wave-execution-planner

Wave Execution Planner

Groups tasks into dependency-ordered waves so multiple subagents can work concurrently in isolated git worktrees.

Core Principles

• Waves enforce ordering, not scheduling — a wave boundary exists only where a real dependency forces sequential execution. Parallel is the default.
• One branch per parallel workstream — each phase in a parallel wave gets its own branch and worktree; agents never share a working tree.
• The wave document is the source of truth — status lives in the wave plan, not scattered across individual task files.
• Gates before advancing — ALWAYS verify the current wave fully passes before starting the next one. A broken wave in production is harder to debug than a delayed start.
• Every wave boundary must be a safe deploy point — after any wave merges, all functionality outside the scope of this plan must continue to work. Three patterns break this: a stranded consumer (code that depends on something removed in a prior wave), a premature consumer (code that requires something not yet deployed), and a breaking contract change (interface change that invalidates existing consumers before they are updated). All three require must land together grouping or explicit expand-contract sequencing.

Quick Start

1. Provide requirements, a PRD, or an existing plan.
2. Invoke Mode A to generate the wave document at:

   .context/plans/<plan-slug>.md
   

3. Work waves in order; run Mode B after each wave to tick off statuses.

When to use

When not to use

• The plan has only 1–2 tasks with no parallelism — a plain checklist is simpler.
• Tasks are all sequential with no independent workstreams — a single branch is enough.
• The caller has explicitly structured their own wave plan and only needs status updates (use Mode B directly).