Skip to content

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 ## Gates ledger on every MR, including the completeness-check result.
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)
/wave 0.1 feature

The 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:

  1. Drops issues that are already claimed (the status::wip label, an open MR, or a worktree in scripts/wt list), is labeled waits::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.
  2. Sequences issues that would edit the same file: the first goes in this wave, the other waits for the next.
  3. Runs scripts/wave-preflight.py on each survivor to see whether it is already done on main (ships in 0.8). Only open issues get an agent.
  4. 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.

Planned. Starting from a plain-language description is not supported by /wave today. It is tracked in macrodream/blueprint#273, with architect first. 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 /wave files 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 (committed or uncommitted) 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 Unplanned in make status, and the next /dotplanning sweeps them into a milestone.

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.

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:

  1. It implements the issue, with tests and docs in the same commit.
  2. It runs make pre-push-checks.
  3. 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:

  1. Rebases the branch onto origin/main, so the audit sees the merged tree.
  2. Spawns completeness-check, a fresh agent that did not write the branch, once, on Opus or Sonnet by the branch’s risk tier.
  3. 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 --harness when 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.
  4. Runs at most one more pass, never a loop. Round 2 runs only when round 1 names a class-missed or collateral blocker. 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.
  5. Checks once more for a stale base, runs make pre-push-checks in 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.

  • 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 prune runs first. Going past it is a deliberate choice: set WT_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.

An agent saying “done” is not evidence. /wave checks each branch, and you can too:

Terminal window
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.

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

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:

  1. scripts/wt list shows each worktree, its age, and whether it was pushed.
  2. Each issue the wave started carries a status::wip label and a 🔒 checked out comment naming its branch and worktree. Commits on a worktree branch survive.
  3. To continue an issue, cd into its worktree and work there.
  4. To give an issue up, scripts/wt release <issue> clears its claim.
  5. After MRs merge, scripts/wt prune removes the worktrees. Nothing does it for you.

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