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).

Recognition examples

Input that triggers Mode A:

"Create a wave plan for this refactor. Tasks: extract lib (no deps),
scaffold CLI (needs lib), add commands A/B/C (needs CLI), cleanup (needs all commands)."

Expected output skeleton:

Wave 1 (parallel): extract-lib
Wave 2 (sequential): scaffold-cli  ← depends on Wave 1
Wave 3 (parallel): command-A, command-B, command-C  ← depend on Wave 2
Wave 4 (sequential): cleanup  ← depends on Wave 3

Mode A — Create Wave Plan

See references/wave-format.md for output format and full examples.

Steps

1. Read inputs — requirements doc, PRD, or existing plan file.
2. Extract tasks — list every task with an ID, description, and explicit dependencies. If none are stated, infer from logical ordering (a test task depends on the implementation task).
3. Build dependency DAG — see references/dependency-analysis.md.
4. Assign waves — Wave 1 = tasks with no dependencies; Wave N = tasks whose all dependencies are in waves 1..N-1.
5. Decide execution mode — a wave with >1 independent task is parallel; a wave with 1 task (or tasks that must run in order) is sequential. Then apply the safe intermediate state check to every wave boundary: "If this wave deploys and the next has not landed yet, does any existing functionality break?" If yes, merge the tasks on both sides of that boundary into a single must land together wave — see references/dependency-analysis.md for patterns and detection guidance.
6. Write output: emit <plan-slug>.md to the plans location shown in Quick Start, using the format in references/wave-format.md.
7. Validate — every task appears in exactly one wave; no wave contains tasks that depend on each other.

Mode B — Update Wave Status

See references/status-tracking.md for the full update protocol.

Steps

1. Read wave document: load the current wave document for the plan slug (see Quick Start for its location).
2. Run verification gate — execute the commands listed in the completed wave's Verification: checklist:

   # example gate for a test-coverage wave
   bun run test --coverage
   bun run typecheck
   git log --oneline main..HEAD

3. Update statuses — tick checkboxes or update Status column cells.
4. Mark wave — append — DONE to the wave heading when all verifications pass.
5. Announce next wave — state which wave is now unblocked and whether it is parallel or sequential.
6. Save — write the updated document back.

Status transitions

Pending  →  In Progress  →  Done
                          ↓
                       Blocked  (add a > BLOCKED: note)

Anti-patterns

Each entry gives the rule, WHY it exists, then a BAD and GOOD example.

NEVER put dependent tasks in the same wave

WHY: agents working in parallel worktrees assume no ordering, so placing dependent tasks together causes undefined behaviour or overwrite conflicts.

BAD: Wave 2 (parallel): scaffold-cli, add-commands where the commands need the scaffold.

GOOD: Wave 2: scaffold-cli, then Wave 3 (parallel): command-A, command-B, command-C.

NEVER label a wave parallel if it contains only one task

WHY: parallel signals subagent tooling to spin up worktrees; a single-task wave wastes setup overhead and misleads reviewers.

BAD: Wave 1 (parallel): extract-lib.

GOOD: Wave 1 (sequential): extract-lib.

NEVER advance to Wave N+1 before Wave N verification passes

WHY: a broken merge point in production compounds into every parallel branch; early detection is always cheaper.

BAD: mark Wave 2 in progress while one Wave 1 verification check is still unticked.

GOOD: name the failing check, hold Wave 2 as pending, and tell the user what must pass first.

NEVER track status inside individual task files

WHY: distributed status creates stale reads and coordination failures when multiple agents update concurrently.

BAD: add a status: done line to each phase file and treat those as the record.

GOOD: update checkboxes or the Status column in the single wave document.

NEVER invent dependencies that are not stated in the requirements

WHY: fabricated ordering reduces parallelism, slows execution, and breaks the contract between the plan and the actual work.

BAD: serialise two unrelated documentation tasks because they "feel" related.

GOOD: infer only logical ordering (a test task depends on its implementation task) and leave the rest parallel.

NEVER create an unsafe intermediate deploy state at a wave boundary

WHY: each wave merge is a potential release point. Runtime dependencies (config values, API contracts, schema columns, env vars, permission grants, event topics) are invisible to the code-level DAG but fatal when missequenced. Three failure modes: (1) stranded consumer, a resource is removed before all code that uses it is also removed or updated; (2) premature consumer, code that requires a resource (new env var, schema column, endpoint) deploys before that resource exists; (3) breaking contract change, an interface changes incompatibly before all consumers are updated.

BAD: Wave 1 removes an SDK-backed infrastructure resource and Wave 2 updates the services that still call it.

GOOD: group tasks that must deploy atomically into a single must land together wave, or use explicit expand-contract sequencing across waves. See references/dependency-analysis.md.

NEVER share a working tree between parallel agents

WHY: agents editing the same tree overwrite each other and leave no clean merge point per workstream.

BAD: two phases in a parallel wave both commit to the same branch checkout.

GOOD: each phase in a parallel wave gets its own branch and worktree, listed in the Branch Strategy table.

NEVER declare a wave done without running its verification checklist

WHY: "it looks right" is not a gate, and an unverified wave hides defects until the next merge.

BAD: append — DONE to the wave heading after reading the diff.

GOOD: run every command in the wave's Verification: list, tick each item, and only then mark the wave done.

NEVER leave a task missing from, or duplicated across, the waves

WHY: a task absent from every wave is never executed, and one present in two waves is built twice.

BAD: a plan with nine tasks whose waves list eight, or list one task twice.

GOOD: validate that every task appears in exactly one wave before writing the output.

References

• references/wave-format.md — Wave document format, sections, and worked examples
• references/dependency-analysis.md — Building the DAG and assigning wave numbers
• references/status-tracking.md — Status update protocol and verification gates
• references/wave-document.yaml — Copy-paste template for a new wave document