Start work with /wave
The big picture: /wave is how work starts here. You point it at issues, and it gives
each one its own worktree and its own agent, picks the model for each, runs the gates that
issue’s change needs, audits every branch with completeness-check, and opens one MR per
issue. Use it for a wave of five and for a wave of one.
Why it matters: Hand-rolling worktrees and agents works, but each gets whatever model
the main session runs on, and the gates share one expensive context. /wave encodes what
measured waves taught: re-reading context, not writing code, was 95.9% of the spend. So
it defaults to Sonnet, caps the wave at 5, and checks what every agent produced instead of
believing its “done.”
What you get on every wave:
- One worktree and one agent per issue; no two agents share a checkout.
- A wave size of 5 by default.
- Per-agent commit verification (
git log, the MR, its pipeline) before it reports. - A
## Gatesledger on every MR, including thecompleteness-checkresult.
Two ways to start
Section titled “Two ways to start”| Mode | You give it | Status |
|---|---|---|
| Milestone mode (the default) | A milestone and labels to pull issues from | Works today |
| Free-form mode | A plain-language description of the work | Planned (see below) |
Milestone mode
Section titled “Milestone mode”/wave 0.1 featureThe arguments are [milestone] [label ...] [--harness]. Name them and /wave takes them as given. Leave
them out and it asks, in one question, which milestone and which labels to pull from. It
never guesses either answer, and it asks for the wave size too if you did not give one
(default 5). Blueprint tracks intent with plain committed / uncommitted labels rather
than dated milestones, so with no active milestone the milestone question is skipped and
issues are selected by label. See Issues are the unit of work.
--harness is yours to pass, never /wave’s. Without it, each issue runs in a pinned
wave-worker agent that may not change the harness (scripts/, .claude/, Makefile,
hooks, CI config), and /wave drops an issue that would, telling you to rerun with the
flag. With it, the agents are unpinned and every MR notes gate: wave-worker-pin — skipped (harness issue) in ## Gates.
Either way the harness bounds each implementer run. Each one is told its budget and stops
there by its own count, and Claude Code ends a run that passes the expanded budget’s turns
(maxTurns). That ceiling is per run: a resume starts a new count. For implementers, a
lifetime hook also caps the total at 120 tool calls across every run and resume
(WAVE_AGENT_TOOL_CAP overrides it); it blocks the call, stops the agent and writes a marker
the orchestrator reads after each implementer result (ships in 0.8). No agent resumes itself,
so an agent cannot continue past a ceiling on its own. At a stop, /wave reads what is in the
worktree and continues in a fresh agent rather than resuming the large context, once per
issue, and hands back to you if the stop landed in the middle of a git operation. The stop is
recorded in the MR’s budget-exceeded: line.
Then it reads the matching issues and, before it creates any worktree:
- Drops issues that are already claimed (the
status::wiplabel, an open MR, or a worktree inscripts/wt list), is labeledwaits::owner(it waits on a person, a paid run or a tag; the plan lists it as skipped), or is blocked on an unmerged branch or an unanswered question. It prefers issues that name a root cause, because a vague issue is the one that turns into an expensive exploration. - Sequences issues that would edit the same file: the first goes in this wave, the other waits for the next.
- Runs
scripts/wave-preflight.pyon each survivor to see whether it is already done onmain(ships in 0.8). Onlyopenissues get an agent. - Reports the selected list: number, title, the model and effort chosen, and why.
Worked example (illustrative). You type /wave 0.1 feature. It does not ask which milestone or labels, because you named
both; it may still ask for the wave size (default 5) if you did not give one. It lists seven open feature issues in milestone 0.1, drops two (one claimed by
another session, one blocked), and reports five: four on Sonnet, one on Opus because its
root cause is unknown. It starts five worktrees and five agents.
Free-form mode
Section titled “Free-form mode”Planned. Starting from a plain-language description is not supported by
/wavetoday. It is tracked in macrodream/blueprint#273, witharchitectfirst. Until it ships, file the issues yourself (see Issues are the unit of work) and run milestone mode.
The planned shape, which can change when architect has reviewed it:
- You describe the work; the description is split into issues, which
/wavefiles after the search-for-duplicates step. - Each piece is routed to a model and effort by the same table milestone mode uses.
- The commitment label (
committedoruncommitted) stays your call; it is asked, never inferred. - A free-form wave with no milestone needs no plan. Its issues are filed with no milestone,
show as
Unplannedinmake status, and the next/dotplanningsweeps them into a milestone.
The plan check
Section titled “The plan check”Planning is for committing a milestone’s work, not for fixing something. A wave that pulls
from a milestone needs that milestone to have been planned with /dotplanning; otherwise
/wave stops before doing any work and prints Next: /dotplanning <v>. The override,
--anyway "<reason>", is recorded in the ## Gates of every MR the wave opens as
gate: prerequisite/plan — skipped (<reason>). This check ships in 0.8
(macrodream/blueprint#257). See The lifecycle.
What each agent does
Section titled “What each agent does”Each pinned wave-worker agent works in its own worktree (Claude Code creates it under
.claude/worktrees/; /wave only claims the issue) and does three things:
- It implements the issue, with tests and docs in the same commit.
- It runs
make pre-push-checks. - It commits and stops before pushing. It spawns no agents.
/wave then runs the gates for that branch itself: scripts/wt harness-diff, then the
pre-MR gates the diff earns, as one parallel batch, then the schema and UX gates the
change class names (the fast-paths table in
Development workflow). On a --harness
run, the unpinned agent runs its own pre-MR batch instead.
completeness-check runs on every wave branch
Section titled “completeness-check runs on every wave branch”An agent should not grade its own work, and it cannot start the fresh auditor itself. So after the agent commits and stops, the orchestrator:
- Rebases the branch onto
origin/main, so the audit sees the merged tree. - Spawns
completeness-check, a fresh agent that did not write the branch, once, on Opus or Sonnet by the branch’s risk tier. - Sends the implementer back to fix every blocker and gap in a new commit, never an
amend. A fix round goes to a fresh agent under
--harnesswhen the implementer’s context is 150k tokens or more (a provisional threshold) or the round has fewer than 5 findings, including rounds after the MR opens; the implementer is resumed only for design-level rework. On a pinned branch the orchestrator makes the round itself in the worktree. Every resume re-reads the whole context. - Runs at most one more pass, never a loop. Round 2 runs only when round 1 names a
class-missedorcollateralblocker. A narrow fix-diff re-check of the fix commit runs only when the fix changed executable behavior. A branch that touches the rigor floor always gets round 2. - Checks once more for a stale base, runs
make pre-push-checksin the worktree, then pushes and opens the MR.
The audit’s ## Requirements table lands in the MR description, and its ledger lines land
in the MR’s ## Gates section. If the last pass still reports a blocker, the orchestrator
stops and asks you.
What you do while it runs
Section titled “What you do while it runs”- Watch the status table. While the wave runs, it shows one row per agent:
# | Issue | Model | Effort | Status | MR. - A quiet agent is usually stalled, not dead. Check
scripts/wt list, then resume it with a message rather than respawning it and losing its context. - At the cap. The default wave size is 5. The worktree limit is
WT_CAP(default 10); if a wave would exceed it,scripts/wt pruneruns first. Going past it is a deliberate choice: setWT_CAP=<n>and state why. Issues beyond the wave size are not started; run a later wave for them. - Every agent has a budget. Each brief carries a provisional limit in tool calls and minutes. An agent that reaches it stops and reports, and the orchestrator decides whether to expand it once.
Verify the result yourself
Section titled “Verify the result yourself”An agent saying “done” is not evidence. /wave checks each branch, and you can too:
git -C <worktree> log origin/main..HEAD --oneline # are there commits?git -C <worktree> status --porcelain # anything uncommitted?Then open the MR and check that its pipeline ran on the same commit as the branch head. A worktree is not private: another session can commit to it mid-edit.
The final report
Section titled “The final report”When the wave ends you get one table with a row per issue: the model and effort of every
spawn, the MR, its pipeline status, commits, and gate findings, with a row per
completeness-check pass. Below it, in plain words: which issues did not land and why,
measured tokens per branch, whether the worktree cap was raised, any issue another session
had already checked out, how many agents ran on Opus or Fable, any Fable rescue (a rescue: line per issue, rescue: none when none fired; ships in 0.8), which agents hit a budget, and which
branches needed a second audit pass. It closes by pointing to /mass-merge for landing the green MRs (and /fix-mr first for a red one).
Leaving mid-wave
Section titled “Leaving mid-wave”Resume mode ships in 0.8 (macrodream/blueprint#294). Run /wave again and, before it picks
new issues, it lists the claims you hold (Step 1b) and classifies each leftover into one of
five main states (plus merged, waiting and hand-back cases): no commits, committed but not pushed, pushed with no MR, MR open with a red
pipeline, or MR open and green. For each it offers to resume it, hand it back to you, or
release the claim. It never re-spawns an agent on an issue whose MR is open and green, and a
worktree whose agent is live or unknown, or that holds uncommitted changes, is only ever
handed back. A claim with no local worktree (another machine) is classified from the remote
but is hand-back-only: taking it over is your own step. The recorded walkthrough of the
resume sequence is tracked in macrodream/blueprint#314.
To recover by hand instead:
scripts/wt listshows each worktree, its age, and whether it was pushed.- Each issue the wave started carries a
status::wiplabel and a🔒 checked outcomment naming its branch and worktree. Commits on a worktree branch survive. - To continue an issue,
cdinto its worktree and work there. - To give an issue up,
scripts/wt release <issue>clears its claim. - After MRs merge,
scripts/wt pruneremoves the worktrees. Nothing does it for you.
Landing the wave
Section titled “Landing the wave”/wave never merges. When the MRs are green, /mass-merge
stacks them, re-checks, and merges the safe prefix. A red MR goes to
/fix-mr first.
Next: Parallel work for what scripts/wt does underneath, and
the /wave reference entry for the model and budget rules.