agent-wave git:20260907.f8592d5A

Immutable. This exact content never changes and is served at /api/v1/blob/223203cdb4601c3f.

---
name: agent-wave
description: Orchestrate a wave of parallel agents over the plan/todo queue in a documentation-led repo — asks how many agents, the budget (items/waves, with hours as a soft cap), and whether to checkpoint after each wave or run continuously. Spawns isolated worktree subagents, assigns one queue item each, collects results. Use when the user says "spawn a wave of agents", "run the queue in parallel", "fan out the work", or "agent wave".
---

# agent-wave

Drive the implementation queue with parallel subagents, in waves.

## Honest scope (read first)

In-session subagents are bounded by **this session**, not by wall-clock
hours. So this skill measures budget reliably in **items and waves**,
with hours as a *soft cap* (stop starting new waves once elapsed time
passes it). For a true multi-hour unsupervised fleet that outlives a
session, use remote agents or a scheduled run of
`_agent/prompts/autonomous.md` instead — this skill points you there
rather than pretending to be it.

## Step 0 — Preconditions and context

1. Confirm the repo is bootstrapped with a `plan/` queue and that
   `_agent/prompts/autonomous.md` exists (a real verify gate is
   required — see the **bootstrap** skill, Q8).
2. Read `CONVENTIONS.md` for the **multi-agent mode** and **integration
   model**.
   - **Single writer:** refuse. Parallel agents in one checkout
     clobber each other. Tell the user to re-bootstrap for several
     writers, or run the autonomous prompt sequentially instead.
   - **Several writers, shared checkout:** allowed but warn — file
     contention is real; `_agent/LOCKS.md` must be respected and wave
     width kept low.
   - **Several writers, separate worktrees:** the intended mode. Each
     subagent works in its own isolated worktree.

## Step 0.5 — Assessment (run first)

Run the shared assessment protocol before spawning anything:

- **Depth selector first.** Ask how deep this assessment should go:
  **express** — every choice takes its recommended default; only
  questions with no derivable default (the free-text essentials) are
  still asked; **guided** — only the questions marked high-impact
  below, plus the free-text essentials; **full** — every question
  below. If the repo's `CONVENTIONS.md` records an `Assessment depth:`,
  pre-select it as the recommended option — the selector always
  appears; a recorded depth is never applied silently. Otherwise
  recommend **full** when the request arrived with little or no
  context and **express** when it is already fully specified. At any
  question the operator may answer "defaults from here" or "go
  deeper"; honour the switch immediately.

- The Step 1 parameters **are** the assessment questions: ask them **one
  at a time**, each with a **recommended option** and a one-line reason;
  wait for each answer. **Budget** and **supervision** are the
  high-impact parameters (asked in guided); width and merge strategy
  take their recommended defaults.
- Use **structured selection** (single- or multiple-choice). If the host
  exposes a structured single-/multi-select question tool, use it and
  mark the recommended option; otherwise list options A/B/C in plain text
  and name the recommended one. Use free text only where unavoidable.
- **The operator decides.** Never spawn a wave without confirmed
  parameters, and never guess when invoked with no context.

## Step 1 — Ask the wave parameters (one at a time, recommend)

1. **Wave width N** — how many agents per wave.
   *Recommended: min(queue depth, 3)* — modest, keeps review tractable.
2. **Budget** — total items (or waves) to attempt this run.
   *Recommended: one wave, then reassess.* Optionally a soft hours cap.
3. **Supervision** — **checkpoint** (review after each wave, then
   continue) or **continuous** (run wave after wave until budget/queue
   exhausted).
   *Recommended: checkpoint* for the first run on a repo.
4. **Merge / integration strategy** — how each shipped item lands.
   *Recommended: follow the repo's integration model* (read it from
   `CONVENTIONS.md`). Override options: **local fast-forward**,
   **PR-based**, or **other**. This sets how each subagent integrates in
   Step 3 and what "shipped" means for the wave.

Cross-check: **continuous + direct-to-main** is risky — nothing gates
each merge. If the repo is direct-to-main, recommend either switching
this run to checkpoint, or that the repo move to PR-based so CI gates
every merge.

## Step 2 — Plan the wave

- Read `plan/todo/`; take the lowest-numbered N items with no unmet
  dependencies. Two agents must never get the same item or items that
  edit the same files — partition by item and, in a shared checkout, by
  `_agent/LOCKS.md`.
- **Reserve identifiers before spawning.** Parallel worktrees that each
  author an ADR or a `plan/` item will otherwise collide on the same
  next number — each worktree computes "next" against its own checkout,
  so two will pick the same one and break the contiguous-numbering
  invariant at merge. Before the wave:
  - Compute the current highest ADR number and `plan/todo` slot.
  - Hand each agent a **disjoint reserved block** — e.g. agent A may
    create ADRs `0042+` and plan slots `0007+`, agent B `0043+` /
    `0008+`, interleaved so no two blocks overlap. Most queue items
    implement an existing ADR and need none — reserve only for items
    that will author new ADRs/plans.
  - An agent uses only its reserved identifiers; if it needs more than
    reserved, it stops and reports rather than guessing.
- **Single writer per artefact.** An ADR body (or a given `plan/` item)
  is edited by at most one worktree per wave. Never put two items that
  both edit the same ADR in one wave — the merge would concatenate
  contradictory edits into an incoherent document.
- Show the assignment — item, agent, reserved identifier block — in the
  wave specification you put to the operator before spawning, and hand
  each agent its own block there. **Require each agent to restate its
  block, and the artefacts it is the single writer of, in its
  pull-request description** — or in the first commit on its branch
  under direct-to-main. Write it to no file under `_agent/`: no
  coordination mode prescribes one, the reservation is orchestrator
  state that expires with the wave, and the branch each agent pushes is
  the visible claim. There is nothing to clean up when the wave ends.

## Step 3 — Spawn the wave

Spawn N subagents in parallel, each in an isolated worktree
(`isolation: worktree`). Brief each with: its assigned queue item, its
reserved identifier block, the instruction to follow
`_agent/prompts/autonomous.md` end-to-end for that
one item (orient → **claim** → implement → verify → **check before
merge (G2)** → integrate per the repo's model → ship), and to report
back a structured result (item, pass/fail, HEAD or PR link, any
blocker). The claim step: commit, then push `claim/<item-key>` for the
assigned item — the queue file name without its extension — and open a
draft pull request from it where integration is pull-request based. A
**rejected push means another writer already holds that item**: the
agent stops and reports rather than working it anyway, and the wave
re-plans around it. The G2 step:
before integrating, sync onto the current `main` and run the **audit**
skill; if the item's new ADR/plan number now clashes with what landed,
renumber locally
before merging. (Reservation in Step 2 makes this rare; G2 catches what
slips through, e.g. an out-of-band ADR landing mid-wave.)

## Step 4 — Collect and checkpoint

When the wave returns, summarise: shipped, failed, blocked, with links.
Then:
- **Checkpoint mode:** present the summary and ask whether to launch the
  next wave.
- **Continuous mode:** launch the next wave with the next N items,
  unless a stop condition fired.

## Stop conditions

Stop the run (do not start another wave) when any holds:
- Queue empty, or budget (items/waves) reached, or soft hours cap passed.
- Failure rate exceeds a sane threshold (e.g. >½ the wave failed) —
  something systemic is wrong; surface it.
- Repeated merge conflicts on the same files — the queue partition is
  wrong; re-plan.
- An item's ADR is not `Accepted`, or its acceptance criteria are
  ambiguous.

On stop, leave every worktree in a committed or cleanly-abandoned state
and report the outcome to the operator in the wave summary. Ensure each
item's outcome is visible in its own commit or pull request; shipped
items are recorded by their commits, pull requests, and `plan/done/`.
There is **no dashboard to write and no reservation to release** — the
reservation was orchestrator state and expires with the wave. An
abandoned item's claim branch is the one loose end: say in the summary
which claim branches are still standing without work behind them, so
the operator can delete them and free the item.