Swarm Wave
Orchestrate multi-agent development sprints using the swarm wave pattern: group
file-disjoint work into waves, launch parallel task agents per wave, enforce a
blocking quality gate before committing, and track sprint state in SWARM-NN.md
files.
File isolation is the primary safety mechanism — agents within a wave each own
distinct files, preventing merge conflicts without relying on worktrees.
This skill does not create beads issues (use /backlog-groomer), write
retrospectives (use /retrospective), or gate sprint closure (the
sprint-review agent handles that). It orchestrates the execution phase
between backlog grooming and sprint close.
SWARM Files
Sprint state is tracked in SWARM-NN.md files in the project root (NN =
sprint number). These are gitignored — they are ephemeral working documents,
not committed artifacts.
Structure:
# SWARM-NN — Sprint Theme
Waves: N | Issues: N | Started: YYYY-MM-DD
## Wave 1 — [Theme]
Status: pending | running | gate-pending | gate-passed | committed
Issues: id1, id2, id3
### Agent Assignments
- Agent A: [file1, file2] -> issue-id
- Agent B: [file3] -> issue-id
- Research: [topic]
### Item Status
| Item | State |
| ----------- | ---------------------------------- |
| id1 | pending / claimed / done / carried |
| id2 | pending / claimed / done / carried |
## Wave 2 — [Theme]
...
Item Status is the run-state table. When beads is available, bd is the
source of truth (claim/close) and this table mirrors it for at-a-glance status.
When beads is unavailable (ROADMAP or manual source), this table is the
source of truth: the orchestrator owns all writes to it — pending at plan
time, claimed when an agent launches, done when the agent reports complete,
carried when an item is deferred to a later wave. Item is a beads id when
beads is used, otherwise a short slug for the work item.
Workflows
Determine which workflow the user needs based on their request. If ambiguous,
default to workflow 1 (Plan a swarm sprint) when the user mentions planning or
starting a sprint, workflow 2 (Execute a wave) when a SWARM plan already exists,
and workflow 3 (Post-wave gate) when a wave has completed and needs review.
1. Plan a swarm sprint
Plan which issues go in which wave, optimizing for file-disjoint parallelism.
Steps:
Determine the work source (Tier A — require-or-fallback). Beads is
available iff a .beads/ directory exists and command -v bd succeeds;
this component is Tier A per CLAUDE.md ### Beads-availability convention. Select the wave source by precedence — beads wins when both
beads and a ROADMAP.md exist:
- Beads available — run
bd ready and bd list --status open to load
the candidate issue set.
- No beads,
ROADMAP.md present — interpret it as the work source
following references/roadmap-interpretation.md (read it in its own
idiom; never reformat it). If that interpretation declines the ROADMAP
(it is not a parallelizable work plan), fall through to the manual path.
- No beads and no usable ROADMAP — manual path: ask the user for the
work items and their file scopes, reusing the workflow 4 (Map file
contention) step-1 prompt (item titles + descriptions + the files each
touches).
Downstream steps operate on the resulting item list regardless of source.
Issue creation and bd claim/close are beads-only; for a beadless source
the SWARM-NN.md Item Status table is the run-state equivalent (see
## SWARM Files).
Read the project structure to understand the codebase layout. Use Glob for
key source directories and Read for package.json and relevant config files.
This builds the mental model for file contention analysis.
Build the file contention map using the procedure from workflow 4 (Map file
contention). Identify HIGH contention files (3+ issues touching the same
file). See references/file-contention-and-clustering.md for threshold rules.
Cluster issues into waves. Apply these rules in order:
- 4a. Issues sharing HIGH contention files must go into separate waves.
- 4b. Within a wave, each agent owns 1-3 files; no file appears in more
than one agent's scope.
- 4c. P0/P1 issues form earlier waves. P2 fills remaining slots. P3/P4 go
to later waves. See
references/file-contention-and-clustering.md for
priority ordering.
- 4d. Wave size: 4-6 task agents per wave. Check RAM constraints in
references/agent-concurrency-limits.md and reduce if needed.
- 4e. Each wave gets one background research agent slot if research
questions exist for the sprint.
- 4f. Issues that block other issues (check with
bd blocked) must go in
an earlier wave than their dependents.
- 4g. Single owner per issue. When an issue's scope spans files that
would otherwise be split across multiple agents, assign the whole issue
to one agent — issue narrative coherence beats wave-level file balance.
Precedent: RETRO-10 (Sprint 10's
vp-beads-0e9.6, which spanned skill
code, CLAUDE.md, and MEMORY.md). See
references/file-contention-and-clustering.md "Single owner per issue"
for the trade-off.
Draft the wave execution plan in the SWARM file format shown above. Include
per-agent file ownership and the research topic for each wave.
Write the plan to SWARM-NN.md in the project root. Collision detection:
pick the next free SWARM-NN (glob existing SWARM-*.md, including
-suffix variants, and choose the lowest unused number) rather than
overwriting an active plan; append if deliberately replanning the same
sprint mid-flight. If any SWARM-*.md is git-tracked, warn the user —
these are ephemeral run-state and should be gitignored (a tracked SWARM file
usually means .gitignore is missing the entry).
Present the plan to the user. No wave execution begins without explicit
approval. After approval, suggest: "Run /swarm-wave execute-wave 1 to
start Wave 1."
Note: GitHub-mirrored beads sync via bd github sync runs post-wave (or
post-sprint), not as part of swarm-wave — the bd v1.0.0 Integration Charter
(gastownhall/beads@5d524cf7:docs/INTEGRATION_CHARTER.md) explicitly punts
cross-tracker orchestration out of bd's scope, and swarm-wave follows the same
boundary.
2. Execute a wave
Launch parallel task agents for a specific wave. Takes the wave number as
argument.
Steps:
Read the active SWARM-NN.md file. Find the wave matching the requested
wave number. Verify status is pending — if committed, report it is
done; if gate-pending or gate-passed, redirect to workflow 3
(Post-wave gate).
Run git status — if there are uncommitted changes, stop and report.
Stale staged files get swept into agent commits.
Run the backpressure sequence from
references/agent-concurrency-limits.md — Phase 1 (kill orphans),
Phase 2 (GC cooldown — skip for waves with fewer than 5 agents), and
Phase 3 (pressure check). If memory pressure is HIGH, reduce agent
count and note the reduction. If CRITICAL, stop and report.
Claim all wave issues: run bd update <id> --claim for each issue ID in
the wave. Report the claimed IDs. Beadless source: set each item's row
in the wave's ### Item Status table to claimed instead (the orchestrator
owns these writes).
Update the wave status to running in the SWARM file.
Launch task agents in parallel. For each agent slot in the wave plan,
use the Agent tool with a prompt built from the canonical template in
references/command-patterns.md. Key elements:
- Issue title and ID (from
bd show <id>)
- Exhaustive file scope list (files this agent may modify — never globs)
- Isolation constraint: "Do not modify any file outside your scope list."
- Validation: "Run
npm run check before finishing."
- Completion: "Run
bd close <id> when the issue is done." (Beadless
source: omit this line — the agent reports completion in its final
message and the orchestrator marks the Item Status row done.)
If a background research agent is planned for this wave, include it in
the same parallel launch batch. Research agents write findings to a
separate file and do not modify source files.
All agent launches go in a single response (parallel execution).
Wait for all agents to complete. As each agent reports done, log it.
Verify closures: run bd list --status in_progress to check for unclosed
issues. Any issue still in_progress means the agent did not complete —
note it for the user (carry forward or retry in the next wave). Beadless
source: the equivalent check is the wave's ### Item Status table — any
row still claimed (not done) is the unclosed-item signal; mark deferred
items carried.
Update wave status to gate-pending in the SWARM file.
Suggest: "Wave N agents complete. Run /swarm-wave post-wave-gate N to
run the quality gate."
3. Post-wave gate
Run the blocking quality gate after a wave completes. Takes the wave number
as argument.
This is a hard blocking gate — no commit happens until all steps pass.
See references/wave-planning-checklist.md for the full gate sequence and
references/review-gate-protocol.md for reviewer details.
Steps:
- Read the active SWARM file. Find the wave. Verify status is
gate-pending or gate-passed.
- Launch two review agents and
npm run check in parallel (Agent tool
calls + Bash in a single response):
- Code reviewer: reads all files modified by the wave (derive from
the file ownership map in the SWARM file). Reviews for correctness,
edge cases, error handling, type safety.
- Domain reviewer: specialized by wave theme. See
references/review-gate-protocol.md for the domain specialization
table. If the wave theme is unclear, use a second code reviewer.
npm run check: via Bash (not an agent — fast and synchronous).
Capture pass/fail.
- Wait for both review agents and the check to complete. Read findings.
- Tally the gate:
npm run check must pass (P0 — gate fails immediately on check errors).
- Code reviewer confidence must be 80+.
- Domain reviewer confidence must be 60+ (80+ for security-adjacent).
See
references/review-gate-protocol.md for threshold details and
severity handling.
- If the gate passes:
- 5a. Run tests sequentially (workspace-first, root-last if applicable).
- 5b. If tests pass: commit all wave changes with
git commit --no-gpg-sign -m "feat: wave N — [theme] (N issues)".
- 5c. Close any remaining wave issues with
bd close.
- 5d. Update wave status to
committed in the SWARM file.
- 5e. Report: "Wave N passed gate and committed. N issues closed."
- 5f. If this is the final wave: offer the retrospective handoff.
"All waves committed. Run
/retrospective to generate the sprint
retro?" If the user confirms, invoke /retrospective via the Skill
tool.
- If the gate fails:
- 6a. List specific failures (check errors, review concerns).
- 6b. For
npm run check failures: fix inline (mechanical fixes).
- 6c. For HIGH-severity review findings: launch a targeted fix agent
scoped to the specific concern and affected files. After the fix
agent completes, re-gate from step 1. If fix iterations exceed 2
within a single wave, halt and escalate to the user instead of
launching a third fix agent. Scope is per-wave: a wave with
multiple HIGH findings dispatches one fix agent that addresses all
of them, and the count increments once per re-gate cycle (not once
per finding). The iteration count covers fix-agent dispatches
only — inline orchestrator fixes (step 6b) do not consume
iteration budget, while user-directed MEDIUM fix-agent dispatches
(step 6d) DO consume the same budget as HIGH-driven dispatches
(same dispatch path). This is a preventive cap — Sprint 10 ran one
fix iteration per wave; the budget exists to bound runaway gate
failures in future runs where reviewers and fix agents disagree.
- 6d. For MEDIUM/LOW findings: present to the user — accept risk and
commit, or fix first. See
references/review-gate-protocol.md for
the severity handling table.
- 6e. Never commit with an open HIGH-severity concern.
4. Map file contention
Standalone utility: build a file-to-issue matrix to identify contention
before planning waves. Also called inline by workflow 1 (Plan a swarm
sprint).
Steps:
Run bd ready to get all open issues. If beads is unavailable, ask the
user to provide issue titles and descriptions — the same manual path
workflow 1 (Plan a swarm sprint) Tier A falls back to.
For each issue, identify which files it is likely to touch:
- 2a. Read the issue description (
bd show <id>) — look for explicit
file mentions.
- 2b. Grep/Glob: search for function names, class names, or keywords
mentioned in the description against the codebase. Map matches to
files.
Build the file-to-issue matrix:
File Issues Contention
src/foo.ts id1, id2, id3 HIGH (3)
src/bar.ts id1, id2 MEDIUM (2)
src/baz.ts id3 LOW (1)
HIGH = 3+ issues. MEDIUM = 2 issues. LOW = 1 issue.
For HIGH contention files with 500+ lines, run a section-level analysis:
Grep for function or class boundaries to identify which sections each
issue touches. If issues touch different sections, they may be compatible
in the same wave — assign explicit line-range ownership. See
references/file-contention-and-clustering.md for the two-tier
contention model.
Present the map to the user. For HIGH contention files, recommend
strategies from references/file-contention-and-clustering.md (sequence,
split, refactor, consolidate).
5. Research wave
Orchestrate parallel research agents. Takes a topic or domain as argument.
Delegates issue creation to /backlog-groomer — this workflow only handles
the parallelism and deduplication.
Steps:
- Identify the research domain from the user's request. Classify by intent:
explore, deepen, validate, audit, or bm-enrichment. See
references/command-patterns.md for the intent-matching table.
- Determine agent count based on intent and RAM. Hard caps: 3-15 write
agents, up to 37 for read-only audit. See
references/agent-concurrency-limits.md for the ceiling table.
- Design agent prompts. Each agent gets a distinct sub-question or domain
slice — no two agents investigate the same question. Research agents
write findings to separate files (one per agent). Research agents do not
modify source files.
- Launch all research agents in parallel (single response, multiple Agent
tool calls).
- Wait for all agents to complete. Read all findings files.
- Dedup pass. Read all findings side by side. Identify duplicate or
overlapping findings across agents. Produce a merged summary.
- Validate against code. For each significant finding, use Grep/Glob
to verify the claim holds in the actual codebase. Flag findings that do
not match reality — research agents have a 15-20% false positive rate.
- Present the merged, validated findings to the user. Suggest: "Run
/backlog-groomer workflow 5 (Create issues from findings) to turn
these into issues." Keep the findings cap at roughly 15 beads — more
suggests the research scope was too broad.
Guidelines
- File isolation is non-negotiable. Every agent in a wave must have an
explicit, exhaustive list of files it may modify. Agents that wander
outside their scope create the same conflict problems as shared-file
agents. When in doubt, give an agent a narrower scope and create a
follow-up issue for the remaining work.
- The gate is a hard block. The post-wave gate (workflow 3 (Post-wave
gate)) must fully pass before the next wave launches. Never commit wave work that has not
passed the gate. "Fix it later" is how parallel agent work produces
cascading failures.
- Beads is preferred, not required (Tier A). swarm-wave needs a work
source, not beads specifically (per CLAUDE.md
### Beads-availability convention). Use beads when available; otherwise source waves from a
ROADMAP.md (workflow 1 (Plan a swarm sprint)) or a manual list, and use the
SWARM-NN.md Item Status table as run-state in place of bd claim/close.
Guard every bd command so a beadless run never errors. Only stop when no
work source can be obtained at all.
- SWARM files are ephemeral.
SWARM-NN.md files are working documents,
not committed artifacts. They should be gitignored.
- No mutations without approval. Wave plans require explicit user
approval before the first agent launches. HIGH-severity gate failures are
described to the user before fix agents launch.
/retrospective is only
invoked via the Skill tool after explicit user confirmation.
- Agent prompts must be complete. Each task agent needs: issue title,
file scope, isolation constraint, validation command, and
bd close
instruction. See references/command-patterns.md for the canonical
template. An incomplete prompt is a gate failure waiting to happen.
- Research agents are read-only for source files. Research agents may
write findings files and may write to Basic Memory (using their own
tool budgets). They must not modify source files.
- Sequential tests, parallel reviews. Reviews run in parallel (two
agents). Tests run sequentially after the gate passes. This is a
correctness requirement, not a performance trade-off.
- RAM ceilings are hard caps. The ceilings in
references/agent-concurrency-limits.md come from empirical sprint
data. Exceeding them produces OOM failures. When in doubt, run fewer
agents.
- Cross-skill boundaries. swarm-wave does not own UPSTREAM, SYNERGY, or
RETRO files. When a wave surfaces upstream friction, suggest
/upstream-tracker workflow 1 (Log a new entry). When the sprint closes,
hand off to /retrospective. Do not replicate logic that belongs in
other skills.
1---2name: swarm-wave3description: "Orchestrate multi-agent development sprints with wave-based parallelism. Use when the user wants to plan a swarm sprint, partition work into file-disjoint waves, map file contention across open issues, run a post-wave quality gate with review agents, manage agent backpressure, run a parallel research wave, or coordinate multiple concurrent agents on a shared codebase. Works with or without beads: sources waves from the beads backlog, from a ROADMAP.md, or from a manually supplied work list. Trigger phrases: 'swarm sprint', 'wave plan', 'launch wave', 'execute wave', 'post-wave gate', 'contention map', 'research wave', 'parallel agents', 'multi-agent sprint', 'agent wave', 'swarm orchestration', 'swarm from ROADMAP', 'wave plan without beads', 'swarm with manual list'."4argument-hint: "[workflow] [wave-number|topic]"5user-invocable: true6paths:7 - "SWARM-*.md"8 - ".beads/**"9allowed-tools:10 - Bash11 - Read12 - Write13 - Edit14 - Glob15 - Grep16 - Agent17 - Skill18metadata:19 source: https://skillmd.com/skills/voxpelli/swarm-wave20---2122# Swarm Wave2324Orchestrate multi-agent development sprints using the swarm wave pattern: group25file-disjoint work into waves, launch parallel task agents per wave, enforce a26blocking quality gate before committing, and track sprint state in `SWARM-NN.md`27files.2829File isolation is the primary safety mechanism — agents within a wave each own30distinct files, preventing merge conflicts without relying on worktrees.3132This skill does not create beads issues (use `/backlog-groomer`), write33retrospectives (use `/retrospective`), or gate sprint closure (the34`sprint-review` agent handles that). It orchestrates the execution phase35between backlog grooming and sprint close.3637## SWARM Files3839Sprint state is tracked in `SWARM-NN.md` files in the project root (NN =40sprint number). These are gitignored — they are ephemeral working documents,41not committed artifacts.4243Structure:4445```markdown46# SWARM-NN — Sprint Theme4748Waves: N | Issues: N | Started: YYYY-MM-DD4950## Wave 1 — [Theme]5152Status: pending | running | gate-pending | gate-passed | committed53Issues: id1, id2, id35455### Agent Assignments5657- Agent A: [file1, file2] -> issue-id58- Agent B: [file3] -> issue-id59- Research: [topic]6061### Item Status6263| Item | State |64| ----------- | ---------------------------------- |65| id1 | pending / claimed / done / carried |66| id2 | pending / claimed / done / carried |6768## Wave 2 — [Theme]69...70```7172**Item Status is the run-state table.** When beads is available, `bd` is the73source of truth (claim/close) and this table mirrors it for at-a-glance status.74When beads is **unavailable** (ROADMAP or manual source), this table *is* the75source of truth: the orchestrator owns all writes to it — `pending` at plan76time, `claimed` when an agent launches, `done` when the agent reports complete,77`carried` when an item is deferred to a later wave. `Item` is a beads id when78beads is used, otherwise a short slug for the work item.7980## Workflows8182Determine which workflow the user needs based on their request. If ambiguous,83default to workflow 1 (Plan a swarm sprint) when the user mentions planning or84starting a sprint, workflow 2 (Execute a wave) when a SWARM plan already exists,85and workflow 3 (Post-wave gate) when a wave has completed and needs review.8687### 1. Plan a swarm sprint8889Plan which issues go in which wave, optimizing for file-disjoint parallelism.9091**Steps:**92931. **Determine the work source (Tier A — require-or-fallback).** Beads is94 available iff a `.beads/` directory exists **and** `command -v bd` succeeds;95 this component is **Tier A** per CLAUDE.md `### Beads-availability96 convention`. Select the wave source by precedence — **beads wins when both97 beads and a `ROADMAP.md` exist**:9899 - **Beads available** — run `bd ready` and `bd list --status open` to load100 the candidate issue set.101 - **No beads, `ROADMAP.md` present** — interpret it as the work source102 following `references/roadmap-interpretation.md` (read it in its own103 idiom; never reformat it). If that interpretation declines the ROADMAP104 (it is not a parallelizable work plan), fall through to the manual path.105 - **No beads and no usable ROADMAP** — **manual path**: ask the user for the106 work items and their file scopes, reusing the workflow 4 (Map file107 contention) step-1 prompt (item titles + descriptions + the files each108 touches).109110 Downstream steps operate on the resulting item list regardless of source.111 Issue creation and `bd` claim/close are beads-only; for a beadless source112 the `SWARM-NN.md` Item Status table is the run-state equivalent (see113 `## SWARM Files`).1142. Read the project structure to understand the codebase layout. Use Glob for115 key source directories and Read for `package.json` and relevant config files.116 This builds the mental model for file contention analysis.1173. Build the file contention map using the procedure from workflow 4 (Map file118 contention). Identify HIGH contention files (3+ issues touching the same119 file). See `references/file-contention-and-clustering.md` for threshold rules.1204. Cluster issues into waves. Apply these rules in order:121 - 4a. Issues sharing HIGH contention files must go into separate waves.122 - 4b. Within a wave, each agent owns 1-3 files; no file appears in more123 than one agent's scope.124 - 4c. P0/P1 issues form earlier waves. P2 fills remaining slots. P3/P4 go125 to later waves. See `references/file-contention-and-clustering.md` for126 priority ordering.127 - 4d. Wave size: 4-6 task agents per wave. Check RAM constraints in128 `references/agent-concurrency-limits.md` and reduce if needed.129 - 4e. Each wave gets one background research agent slot if research130 questions exist for the sprint.131 - 4f. Issues that block other issues (check with `bd blocked`) must go in132 an earlier wave than their dependents.133 - 4g. **Single owner per issue.** When an issue's scope spans files that134 would otherwise be split across multiple agents, assign the whole issue135 to one agent — issue narrative coherence beats wave-level file balance.136 Precedent: RETRO-10 (Sprint 10's `vp-beads-0e9.6`, which spanned skill137 code, `CLAUDE.md`, and `MEMORY.md`). See138 `references/file-contention-and-clustering.md` "Single owner per issue"139 for the trade-off.1405. Draft the wave execution plan in the SWARM file format shown above. Include141 per-agent file ownership and the research topic for each wave.1426. Write the plan to `SWARM-NN.md` in the project root. **Collision detection:**143 pick the next free `SWARM-NN` (glob existing `SWARM-*.md`, including144 `-suffix` variants, and choose the lowest unused number) rather than145 overwriting an active plan; append if deliberately replanning the same146 sprint mid-flight. **If any `SWARM-*.md` is git-tracked, warn the user** —147 these are ephemeral run-state and should be gitignored (a tracked SWARM file148 usually means `.gitignore` is missing the entry).1497. Present the plan to the user. **No wave execution begins without explicit150 approval.** After approval, suggest: "Run `/swarm-wave execute-wave 1` to151 start Wave 1."152153**Note:** GitHub-mirrored beads sync via `bd github sync` runs *post-wave* (or154post-sprint), not as part of swarm-wave — the bd v1.0.0 Integration Charter155(`gastownhall/beads@5d524cf7:docs/INTEGRATION_CHARTER.md`) explicitly punts156cross-tracker orchestration out of bd's scope, and swarm-wave follows the same157boundary.158159### 2. Execute a wave160161Launch parallel task agents for a specific wave. Takes the wave number as162argument.163164**Steps:**1651661. Read the active `SWARM-NN.md` file. Find the wave matching the requested167 wave number. Verify status is `pending` — if `committed`, report it is168 done; if `gate-pending` or `gate-passed`, redirect to workflow 3169 (Post-wave gate).1702. Run `git status` — if there are uncommitted changes, stop and report.171 Stale staged files get swept into agent commits.1723. Run the backpressure sequence from173 `references/agent-concurrency-limits.md` — Phase 1 (kill orphans),174 Phase 2 (GC cooldown — skip for waves with fewer than 5 agents), and175 Phase 3 (pressure check). If memory pressure is HIGH, reduce agent176 count and note the reduction. If CRITICAL, stop and report.1774. Claim all wave issues: run `bd update <id> --claim` for each issue ID in178 the wave. Report the claimed IDs. **Beadless source:** set each item's row179 in the wave's `### Item Status` table to `claimed` instead (the orchestrator180 owns these writes).1815. Update the wave status to `running` in the SWARM file.1826. Launch task agents in parallel. For each agent slot in the wave plan,183 use the Agent tool with a prompt built from the canonical template in184 `references/command-patterns.md`. Key elements:185186 - Issue title and ID (from `bd show <id>`)187 - Exhaustive file scope list (files this agent may modify — never globs)188 - Isolation constraint: "Do not modify any file outside your scope list."189 - Validation: "Run `npm run check` before finishing."190 - Completion: "Run `bd close <id>` when the issue is done." (Beadless191 source: omit this line — the agent reports completion in its final192 message and the orchestrator marks the Item Status row `done`.)193194 If a background research agent is planned for this wave, include it in195 the same parallel launch batch. Research agents write findings to a196 separate file and do not modify source files.197198 All agent launches go in a single response (parallel execution).1997. Wait for all agents to complete. As each agent reports done, log it.2008. Verify closures: run `bd list --status in_progress` to check for unclosed201 issues. Any issue still `in_progress` means the agent did not complete —202 note it for the user (carry forward or retry in the next wave). **Beadless203 source:** the equivalent check is the wave's `### Item Status` table — any204 row still `claimed` (not `done`) is the unclosed-item signal; mark deferred205 items `carried`.2069. Update wave status to `gate-pending` in the SWARM file.20710. Suggest: "Wave N agents complete. Run `/swarm-wave post-wave-gate N` to208 run the quality gate."209210### 3. Post-wave gate211212Run the blocking quality gate after a wave completes. Takes the wave number213as argument.214215This is a **hard blocking gate** — no commit happens until all steps pass.216See `references/wave-planning-checklist.md` for the full gate sequence and217`references/review-gate-protocol.md` for reviewer details.218219**Steps:**2202211. Read the active SWARM file. Find the wave. Verify status is222 `gate-pending` or `gate-passed`.2232. Launch two review agents and `npm run check` in parallel (Agent tool224 calls + Bash in a single response):225 - **Code reviewer**: reads all files modified by the wave (derive from226 the file ownership map in the SWARM file). Reviews for correctness,227 edge cases, error handling, type safety.228 - **Domain reviewer**: specialized by wave theme. See229 `references/review-gate-protocol.md` for the domain specialization230 table. If the wave theme is unclear, use a second code reviewer.231 - **`npm run check`**: via Bash (not an agent — fast and synchronous).232 Capture pass/fail.2333. Wait for both review agents and the check to complete. Read findings.2344. Tally the gate:235 - `npm run check` must pass (P0 — gate fails immediately on check errors).236 - Code reviewer confidence must be 80+.237 - Domain reviewer confidence must be 60+ (80+ for security-adjacent).238 See `references/review-gate-protocol.md` for threshold details and239 severity handling.2405. If the gate passes:241 - 5a. Run tests sequentially (workspace-first, root-last if applicable).242 - 5b. If tests pass: commit all wave changes with243 `git commit --no-gpg-sign -m "feat: wave N — [theme] (N issues)"`.244 - 5c. Close any remaining wave issues with `bd close`.245 - 5d. Update wave status to `committed` in the SWARM file.246 - 5e. Report: "Wave N passed gate and committed. N issues closed."247 - 5f. **If this is the final wave**: offer the retrospective handoff.248 "All waves committed. Run `/retrospective` to generate the sprint249 retro?" If the user confirms, invoke `/retrospective` via the Skill250 tool.2516. If the gate fails:252 - 6a. List specific failures (check errors, review concerns).253 - 6b. For `npm run check` failures: fix inline (mechanical fixes).254 - 6c. For HIGH-severity review findings: launch a targeted fix agent255 scoped to the specific concern and affected files. After the fix256 agent completes, re-gate from step 1. **If fix iterations exceed 2257 within a single wave, halt and escalate to the user instead of258 launching a third fix agent.** Scope is per-wave: a wave with259 multiple HIGH findings dispatches one fix agent that addresses all260 of them, and the count increments once per re-gate cycle (not once261 per finding). The iteration count covers fix-agent dispatches262 only — inline orchestrator fixes (step 6b) do not consume263 iteration budget, while user-directed MEDIUM fix-agent dispatches264 (step 6d) DO consume the same budget as HIGH-driven dispatches265 (same dispatch path). This is a preventive cap — Sprint 10 ran one266 fix iteration per wave; the budget exists to bound runaway gate267 failures in future runs where reviewers and fix agents disagree.268 - 6d. For MEDIUM/LOW findings: present to the user — accept risk and269 commit, or fix first. See `references/review-gate-protocol.md` for270 the severity handling table.271 - 6e. Never commit with an open HIGH-severity concern.272273### 4. Map file contention274275Standalone utility: build a file-to-issue matrix to identify contention276before planning waves. Also called inline by workflow 1 (Plan a swarm277sprint).278279**Steps:**2802811. Run `bd ready` to get all open issues. If beads is unavailable, ask the282 user to provide issue titles and descriptions — the same manual path283 workflow 1 (Plan a swarm sprint) Tier A falls back to.2842. For each issue, identify which files it is likely to touch:285 - 2a. Read the issue description (`bd show <id>`) — look for explicit286 file mentions.287 - 2b. Grep/Glob: search for function names, class names, or keywords288 mentioned in the description against the codebase. Map matches to289 files.2903. Build the file-to-issue matrix:291292 ```293 File Issues Contention294 src/foo.ts id1, id2, id3 HIGH (3)295 src/bar.ts id1, id2 MEDIUM (2)296 src/baz.ts id3 LOW (1)297 ```298299 HIGH = 3+ issues. MEDIUM = 2 issues. LOW = 1 issue.3004. For HIGH contention files with 500+ lines, run a section-level analysis:301 Grep for function or class boundaries to identify which sections each302 issue touches. If issues touch different sections, they may be compatible303 in the same wave — assign explicit line-range ownership. See304 `references/file-contention-and-clustering.md` for the two-tier305 contention model.3065. Present the map to the user. For HIGH contention files, recommend307 strategies from `references/file-contention-and-clustering.md` (sequence,308 split, refactor, consolidate).309310### 5. Research wave311312Orchestrate parallel research agents. Takes a topic or domain as argument.313Delegates issue creation to `/backlog-groomer` — this workflow only handles314the parallelism and deduplication.315316**Steps:**3173181. Identify the research domain from the user's request. Classify by intent:319 `explore`, `deepen`, `validate`, `audit`, or `bm-enrichment`. See320 `references/command-patterns.md` for the intent-matching table.3212. Determine agent count based on intent and RAM. Hard caps: 3-15 write322 agents, up to 37 for read-only audit. See323 `references/agent-concurrency-limits.md` for the ceiling table.3243. Design agent prompts. Each agent gets a distinct sub-question or domain325 slice — no two agents investigate the same question. Research agents326 write findings to separate files (one per agent). Research agents do not327 modify source files.3284. Launch all research agents in parallel (single response, multiple Agent329 tool calls).3305. Wait for all agents to complete. Read all findings files.3316. **Dedup pass.** Read all findings side by side. Identify duplicate or332 overlapping findings across agents. Produce a merged summary.3337. **Validate against code.** For each significant finding, use Grep/Glob334 to verify the claim holds in the actual codebase. Flag findings that do335 not match reality — research agents have a 15-20% false positive rate.3368. Present the merged, validated findings to the user. Suggest: "Run337 `/backlog-groomer workflow 5 (Create issues from findings)` to turn338 these into issues." Keep the findings cap at roughly 15 beads — more339 suggests the research scope was too broad.340341## Guidelines342343- **File isolation is non-negotiable.** Every agent in a wave must have an344 explicit, exhaustive list of files it may modify. Agents that wander345 outside their scope create the same conflict problems as shared-file346 agents. When in doubt, give an agent a narrower scope and create a347 follow-up issue for the remaining work.348- **The gate is a hard block.** The post-wave gate (workflow 3 (Post-wave349 gate)) must fully pass before the next wave launches. Never commit wave work that has not350 passed the gate. "Fix it later" is how parallel agent work produces351 cascading failures.352- **Beads is preferred, not required (Tier A).** swarm-wave needs a *work353 source*, not beads specifically (per CLAUDE.md `### Beads-availability354 convention`). Use beads when available; otherwise source waves from a355 `ROADMAP.md` (workflow 1 (Plan a swarm sprint)) or a manual list, and use the356 `SWARM-NN.md` Item Status table as run-state in place of `bd` claim/close.357 Guard every `bd` command so a beadless run never errors. Only stop when no358 work source can be obtained at all.359- **SWARM files are ephemeral.** `SWARM-NN.md` files are working documents,360 not committed artifacts. They should be gitignored.361- **No mutations without approval.** Wave plans require explicit user362 approval before the first agent launches. HIGH-severity gate failures are363 described to the user before fix agents launch. `/retrospective` is only364 invoked via the Skill tool after explicit user confirmation.365- **Agent prompts must be complete.** Each task agent needs: issue title,366 file scope, isolation constraint, validation command, and `bd close`367 instruction. See `references/command-patterns.md` for the canonical368 template. An incomplete prompt is a gate failure waiting to happen.369- **Research agents are read-only for source files.** Research agents may370 write findings files and may write to Basic Memory (using their own371 tool budgets). They must not modify source files.372- **Sequential tests, parallel reviews.** Reviews run in parallel (two373 agents). Tests run sequentially after the gate passes. This is a374 correctness requirement, not a performance trade-off.375- **RAM ceilings are hard caps.** The ceilings in376 `references/agent-concurrency-limits.md` come from empirical sprint377 data. Exceeding them produces OOM failures. When in doubt, run fewer378 agents.379- **Cross-skill boundaries.** swarm-wave does not own UPSTREAM, SYNERGY, or380 RETRO files. When a wave surfaces upstream friction, suggest381 `/upstream-tracker workflow 1 (Log a new entry)`. When the sprint closes,382 hand off to `/retrospective`. Do not replicate logic that belongs in383 other skills.