Arun Prakash — Reel 2026

· 4 min read · AI Agents · Claude Code · Open Source

Wave Planning, Packaged: The Claude Code Plugin

Wave planning is now a Claude Code plugin. It plans a build into waves, routes each phase to the cheapest adequate model, and runs every wave in parallel git worktrees with a gate before the next one starts.

I’ve written about wave planning twice: first the method itself, then what a wave actually is and why decomposition, not concurrency, is the hard part. Both posts were about a discipline I was running by hand. This one is about the version you can install.

wave-planning is a Claude Code plugin, MIT licensed. It does two things: it helps you write the plan, and then it runs it.

The idea in one minute

  • Step → phase → wave. A phase is one agent’s unit of work. A wave is the largest set of phases that can run at once, because none waits on another and none writes the same files.
  • Waves run one after another. Phases inside a wave run in parallel.
  • A phase gets a shallow gate: format, lint, types, unit tests. A wave gets a functional gate, run on the merged result.
  • The plan is written and approved before any code. You own what the dependency tree misses.

Install

claude plugin marketplace add ArunPrakashG/wave-planning
claude plugin install wave-planning@arunprakashg-plugins

It’s Claude Code only. It depends on subagents, git worktrees and a shell, so it won’t run on claude.ai or Cowork. You also need git (a repository with at least one commit; the plugin offers to git init) and Python 3 on your PATH for the plan validator, standard library only.

Two commands

/wave-planning:wave-plan <your idea> scopes the project, writes one spec per feature, designs the UI if there is one (a mockup, then frozen), and decomposes the work into waves. You approve at each stage. The output is a plan.md at the project root and specs under docs/waves/specs/.

/wave-planning:wave-execute runs that plan wave by wave. It validates the plan, creates a git worktree per phase, dispatches one subagent per phase on the model the plan assigned, gates each phase, merges, runs the wave’s functional gate, and only then moves on. Progress lives in a status block inside plan.md, so you can stop and resume. 

Wave 1   Design tokens │ DB schema │ CLI scaffold     → gate
Wave 2   Editor UI     │ Notes API │ CLI commands     → gate
Wave 3                   Sync engine                  → gate
A notes app in three waves. Every phase in a row runs at once, in its own worktree.

The cheapest model that can do the job

The part I like most is the routing. Running everything on the biggest model is the easy default, and most phases don’t need it. So each phase is scored 0 to 2 on four things: scope, ambiguity, risk and reasoning.

  • A total of 0 to 2 goes to haiku, 3 to 5 to sonnet, and 6 or more to opus.
  • Risk 2 (security, data, money, migrations) forces opus, whatever the total.
  • Ambiguity 2 doesn’t go to a bigger model at all. It goes back to planning. A bigger model guessing at an unclear phase is still guessing.
  • A failed phase retries once, then moves up one tier, then stops and asks you.

Gates, twice

Each phase is checked on its own, cheaply, before it merges: your formatter, linter, type checker and unit tests. That catches the obvious breakage while it’s still isolated in one worktree. But phases that pass alone can still fail together, so after a wave merges, a separate validator runs the wave’s functional gate on the merged result and reports evidence for each acceptance criterion. The next wave doesn’t start until that passes.

Permissions

Workers edit files and run your gate commands. Plugin agents can’t set their own permission mode, so run Claude Code with a mode, or allow rules in your settings, that let subagents edit files and run your format, lint, typecheck and test commands. If a worker gets denied, the orchestrator stops and tells you what’s missing rather than quietly skipping a gate.

What it doesn’t do

  • It saves wall-clock time, not total work. Total tokens and effort come out about the same, or higher. You’re buying parallelism, not a discount.
  • The plan is the product. A plan with a hidden dependency fails at merge or at the wave gate. The validator catches structural problems, not what nobody wrote down.
  • A feature that depends on another waits for all of that feature’s phases. If you want finer parallelism, split features finer.

That last point is the whole argument of the second post, now enforced by a tool: the speed-up you get is exactly as good as the decomposition you write.

The source, evals and docs are on GitHub. If you try it on a real project, I’d like to hear where the plan broke.