/agent-wave

name: agent-wave
description: Run a bounded wave over the plan/todo queue in a documentation-led repo, using available parallel agents or sequential execution. Establishes width, budget and supervision; isolates work and collects verified outcomes. Use for "spawn a wave of agents", "run the queue in parallel", "fan out the work", or "agent wave", not for authoring a decision or queuing a new item.

agent-wave

Run a declared batch of accepted queue items using the capabilities this host actually exposes. Budgets count items or waves. An optional hours cap stops new waves, never a running item. Long-lived automation uses the host's scheduling facility (see README); this session does not promise to outlive itself.

Preconditions and host capability

Before asking parameters, read the repository's entry point, conventions, queue and autonomous prompt. Resolve all artefact paths, including `_agent/`, against the recorded root. Require a real gate and the queue it walks.

| Recorded mode | Execution | |---|---| | Single writer | Stop and direct the operator to the sequential autonomous prompt, at every requested width. | | Shared checkout, direct integration | One executor at a time in that checkout, using item status and lock rows. No claim branch or integration worktree. | | Shared checkout, PR integration | Stop before claiming; require separate worktrees for PR waves. | | Separate worktrees | Each executor uses its own worktree; integration follows the recorded model. |

Fetch/prune the recorded remote and require its integration branch. Print the fetched base SHA. Compare the local integration ref: report unpushed commits or divergence before proceeding, never silently discard them. A behind, clean checkout may be fast-forwarded when it is safe; otherwise leave it alone. The wave's state and probe come from the fetched base, not uncommitted files in the operator's checkout. If the remote queue is empty but the local queue differs, explain that difference.

Derive whether the host can delegate, isolate checkouts, run concurrently, use an orchestration facility **already enabled by the operator**, and require shaped results. Choose the highest available rung:

1. Enabled orchestration facility: one fan-out for this wave only. Keep wave loops, clock checks and questions in the orchestrator. 2. Plain subagents: parallel if available, sequential otherwise. Use host worktree isolation only if its starting head equals the declared base; otherwise explicitly create each worktree at that base. 3. The orchestrator executes one item at a time, in its own worktree or the shared checkout as the recorded mode permits.

Report `Execution: rung N — reason`. The operator can lower this choice; never raise it beyond observed capability or solicit enablement. A skill mentioning a facility is not operator opt-in. The same canonical brief below is used at every rung. Without a proved concurrency ceiling, use one.

Assessment and declaration

Reuse answers already given. Otherwise ask one question at a time with a recommended answer and reason, using a structured selector if available. Offer express (defaults), guided (budget/supervision) or full depth, with the recorded depth preselected. Honour defaults-from-here or go-deeper.

1. Requested width: recommend min(eligible queue depth, 3, host ceiling). 2. Budget: items or waves; recommend one wave. Optionally a soft hours cap. 3. Supervision: checkpoint after each wave (recommended), or continuous. 4. Integration: use the repository profile unless explicitly overridden. Direct integration is legitimate with recorded concurrency guardrails; its integration is serial. An override cannot make an unsupported mode valid.

Declare and confirm the resulting specification before execution (explicit invocation parameters already constitute confirmation). Include:

• Wave name, date, remote, integration branch and fetched base SHA.
• Requested/effective width, rung/reason, host ceiling and any token limit.
• Budget, supervision and soft cap; never convert token limits to item counts.
• Each item's key, owning decisions, dependencies, claim variant, exact

owned artefacts, reserved identifiers with their sequences, and Continue flag.

• Isolation and integration profile; integration/merge actions actually granted.
• Grant: "Attended wave: the operator confirmed these parameters and this

item on <date>; implement only the named item, never pick another."

Reserve only identifiers an item will create, in finite disjoint blocks. Include existing live reservations; continued items keep their original ones. Never assign two writers the same decision or plan body. INDEX is derived: an executor changes only its own rows, and integration regenerates the whole table. Exhausted reservations stop the item; no stealing slots.

After confirmation, create a detached integration/probe worktree at the base for separate-worktree mode, outside the operator's tree. Reuse a leftover only after proving it clean and owned. Probe the exact gate there with tracked files and existing environment only. On environmental failure, stop before dispatch and report the command, output and exit; do not install missing dependencies or imply that selecting rung three repairs the gate. Report effective hooks path and the origin of the signing setting.

Collect before every wave

Fetch/prune again; read item status, claim tips, worktrees and PR state. Use this precedence, resolving each item at the base and claim tip:

| Class | Evidence and action | |---|---| | Unverifiable | Required remote/PR evidence unavailable or contradictory: stop the run. | | Shipped | Done entry on the integration branch with reachable footer commit or confirmed merged PR. Exclude. | | Merged but unshipped | Work/PR merged but item still queued on the base. Exclude and request reconciliation. | | Stopped | Stopped field on the base or claim tip. Exclude unless explicitly continued. | | Live