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 — including each agent's reserved identifier block.

Step 3 — Spawn the wave

Spawn N subagents in parallel, each in an isolated worktree (isolation: worktree). Brief each with: its assigned queue item, the instruction to follow _agent/prompts/autonomous.md end-to-end for that one item (orient → 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 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. Update _agent/IN_FLIGHT.md (remove finished rows). 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, record the outcome in the WORKLOG, and report.