wave-executor

Wave Executor

Execute a wave document by spawning parallel agents per wave, pausing at merge gates, and verifying each wave before advancing.

When to Use

• User says "run the plan", "execute the plan", "start wave N", "launch the agents"
• A wave document exists at .context/plans/<slug>.md
• The plan was produced by wave-execution-planner (or follows the same format)

When Not to Use

• No wave document exists — run wave-execution-planner (Mode A) first
• The user wants to update wave status only — use wave-execution-planner (Mode B) instead
• The plan has only 1–2 sequential tasks with no parallelism — just run them directly

Workflow

1. Locate the plan

Ask for the plan slug if not provided. Load .context/plans/<slug>.md.

Read the full document. Identify all waves in order and their current status. Skip waves already marked — DONE.

2. For each pending wave — execute the loop

Repeat steps 2a–2g for every wave that is not — DONE, in order.

2a. Check the gate

Read the > Gate: blockquote at the top of the wave. If it requires a prior wave to be verified, confirm that wave's Verification: checklist is fully ticked ([x]). If not, stop and report the unmet gate to the user.

2b. Extract phases

Parse the wave table or inline task list. For each row / item capture:

• branch — the branch name. In phase tables: the phase identifier (use as branch if no explicit branch). In inline tasks: the value after — branch.
• focus — the task description (Focus column, or phase file content if linked).
• model — the Model column value, or — model: suffix on inline tasks. Default: standard if absent.
• writes — if a Writes column or — writes: annotation is present, capture it. Otherwise derive from the phase file, or leave unspecified and let the agent determine scope from the focus.

2b.5. Resolve tiers to model IDs

Read references/model-map.yaml. For each extracted model tier value, look up the corresponding concrete model ID. If a tier is absent from the map, use the standard entry.