/agent-wave

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", "agent wave", or invokes /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` (`/schedule`) 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**.

• **Mode 1 (single agent):** refuse. Parallel agents in one checkout

clobber each other. Tell the user to re-bootstrap as mode 2/3, or run the autonomous prompt sequentially instead.

• **Mode 2 (shared checkout):** allowed but warn — file contention is

real; LOCKS must be respected and wave width kept low.

• **Mode 3 (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 (one narrow exception: when the invocation already answers every question the tiers differentiate, skip it and say so in one line); 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 mode 2, by LOCKS.

• **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 — a `merge=union` would silently concatenate contradictory edits into an incoherent document.

• Record the assignment in `_agent/IN_FLIGHT.md` (mode 3) so the wave is

visible