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 in the project’s plans directory
• 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 the wave document from the project’s plans directory (for example .context/plans/<slug>.md in a repo using that convention):

Read(".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.

Carry the resolved model ID (not the tier name) forward to step 2d.

2c. Build per-agent prompts

Read references/per-agent-template.md.

For each phase, fill the template slots with the values from step 2b. Append the model-tier addition from references/model-tier-guide.md matching the phase’s model value.

Do not paraphrase the focus / task description. Copy it verbatim.

If the phase links to a phase file, read that file and include its full content under “Your task” rather than only the Focus cell value.

2d. Spawn agents in parallel

Send a single response containing one Agent tool call per unblocked phase.

Each call must set:

• subagent_type: "general-purpose"
• model: the resolved model ID from step 2b.5 (e.g. "haiku" for a fast-tier phase)
• isolation: "worktree" for all phases that commit to a branch (omit for phases that commit directly to main)
• description: "Wave N: <branch>"
• prompt: the filled per-agent prompt from step 2c

2e. Wait for all agents to complete

Do not proceed until every agent in the wave has returned.

2f. STOP — merge gate

After all agents complete, report to the user:

“Wave N agents done. Please merge the following branches to main before I continue: [list branches]

Then run the Verification checklist for this wave (copied below) and reply ‘verified’ when all checks pass.”

Copy the wave’s Verification: checklist verbatim into your message so the user can run each item.

Wait for the user to reply before continuing.

2g. Update wave status and advance

After the user confirms verification:

1. Run wave-execution-planner Mode B on the wave document to tick the verification checkboxes and mark the wave — DONE.
2. Report which wave is now unblocked.
3. Continue the loop with the next wave.

3. Report completion

After all waves are done:

• Summarise what was executed (waves, branches, agents).
• Confirm the plan’s **Status** field is set to Complete.
• List any decisions or blockers flagged by agents during execution.

Anti-Patterns

NEVER paraphrase the task description

WHY: Information loss — the verbatim focus or phase file contains constraints, tool names, and scope boundaries that summaries drop.

BAD Summarise “Triage Mem0, Zep, MemoryOS, Letta via triage-tool” as “triage memory tools”. GOOD Copy the full text verbatim into the per-agent prompt. ALWAYS paste the focus text unedited, even if it looks redundant with the branch name.

NEVER omit the model parameter on Agent calls

WHY: Omitting it silently defaults to the orchestrator’s model. For fast-tier mechanical tasks, this wastes significant cost with no quality benefit.

BAD Agent(subagent_type="general-purpose", prompt=...) with no model. GOOD Agent(model="haiku", ...) — resolved from the fast tier in model-map.yaml. ALWAYS resolve the tier to a concrete model ID before spawning.

NEVER start the next wave before the gate passes

WHY: Consolidation agents read files written by prior waves. Unmerged branches mean stale reads and incorrect output that is hard to detect.

BAD Proceed to Wave N+1 as soon as Wave N agents return their results. GOOD STOP, ask the user to merge and verify, confirm gate before advancing. ALWAYS treat an un-ticked Verification: checklist item as a blocked gate, never as a formality.

NEVER spawn wave agents sequentially

WHY: Defeats the parallelism that wave planning was designed to achieve.

BAD Spawn one agent, wait for it, then spawn the next. GOOD Send a single response with all parallel agents in one message.

NEVER spawn agents for phases blocked by unmet dependencies

WHY: A phase that needs a prior branch merged will read stale state and produce incorrect output.

BAD Spawn feat/synthesis before feat/rubric is merged (it’s in the Blocked on note). GOOD Check each phase’s gate / blocked-on annotation; skip and report blocked phases.

NEVER trust a merged branch without checking it actually builds

WHY: A merge can succeed with no conflicts and still leave the codebase broken — a renamed export, a missing migration, a config drift between branches. git merge exiting 0 only proves the text merged, not that the result runs.

BAD Accept the user’s “verified” reply at face value with no build evidence attached. GOOD Before ticking the gate, ask for (or run) the project’s own build/test command on main after the merge:

git checkout main && git pull
make build && make test
# or, in a Node project: npm run build && npm test

Consequence: Skipping this means the next wave’s agents branch from a main that looks merged but doesn’t actually compile, and the failure only surfaces several waves later when it’s much harder to trace back.

References

• Per-agent prompt template — fill for every spawned agent
• Model tier guide — when to use fast / standard / smart
• Model map — resolves tier names to concrete model IDs; edit to switch providers
• Wave format spec — defined in the wave-execution-planner skill (wave-execution-planner/references/wave-format.md)
• Status tracking protocol — defined in the wave-execution-planner skill (wave-execution-planner/references/status-tracking.md); used in step 2g

You are working in the {repo} repository.

## Your task

{focus — copy verbatim from the wave document Focus cell or phase file. Do not summarise.}

## Writes scope

{If a Writes column or phase file specifies scope, state it here:}
You may only write to:
{writes}

{If no writes scope is specified, use:}
Limit your changes to files directly related to your task. Do not modify shared
index files, changelogs, or summary documents unless your task explicitly names them.

## Isolation

Other agents may be running in parallel in separate worktrees.
Only touch files within your writes scope.
Do not read files owned by another concurrent agent's worktree — this causes merge conflicts.

## When done

Verify:
1. Every file you created or modified exists and is non-empty.
2. Any script or command named in your task ran without error.
3. No file outside your writes scope was modified — check with: git diff --name-only

Report:
- Files written (exact paths).
- Any decision or assumption you had to make.
- Any blocker that prevented full completion.

{model_tier_addition}

Work mechanically. Follow each step in the task description in order.
Do not infer, expand, or improve beyond the stated scope.
If any step is ambiguous, take the most conservative interpretation and note it in your report.

Use the skill or script named in your task. Follow its output format exactly.
Verify that any file you produced matches the expected structure before reporting done.
If the skill requires a confirmation sub-step, take the default/conservative option and note it.

You may read any existing file in the repo to inform your analysis.
Cite every file you read by path. If evidence is weak, contradictory, or absent, say so
explicitly — do not hedge silently or fill gaps with plausible-sounding inference.
Depth and accuracy matter more than speed.

You are working in the agentic-context repository.

## Your task

Triage Mem0, Zep, MemoryOS, Letta via `triage-tool`

## Writes scope

You may only write to:
references/*.md

Limit your changes to files directly related to your task. Do not modify shared
index files, changelogs, or summary documents unless your task explicitly names them.

## Isolation

Other agents may be running in parallel in separate worktrees.
Only touch files within your writes scope.
Do not read files owned by another concurrent agent's worktree — this causes merge conflicts.

## When done

Verify:
1. Every file you created or modified exists and is non-empty.
2. Any script or command named in your task ran without error.
3. No file outside your writes scope was modified — check with: git diff --name-only

Report:
- Files written (exact paths).
- Any decision or assumption you had to make.
- Any blocker that prevented full completion.

Use the skill or script named in your task. Follow its output format exactly.
Verify that any file you produced matches the expected structure before reporting done.
If the skill requires a confirmation sub-step, take the default/conservative option and note it.

Agent(
  subagent_type="general-purpose",
  model="sonnet",        # resolved from tier 'standard' via model-map.yaml
  isolation="worktree",
  description="Wave 0: feat/triage-memory",
  prompt=<above>
)