swarm-wave

name	swarm-wave
description	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. 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'.
argument-hint	[workflow] [wave-number|topic]
user-invocable	true
paths	["SWARM-*.md",".beads/**"]
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep","Agent","Skill"]

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]

## Wave 2 — [Theme]
...

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:

1. Guard: check .beads/ exists. If absent, report that swarm-wave requires beads and stop. Run bd ready and bd list --status open to load the candidate issue set.
2. 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.
3. 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.
4. 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.
5. Draft the wave execution plan in the SWARM file format shown above. Include per-agent file ownership and the research topic for each wave.
6. Write the plan to SWARM-NN.md in the project root. Create the file if absent; append if replanning mid-sprint.
7. 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:

1. 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).

2. Run git status — if there are uncommitted changes, stop and report. Stale staged files get swept into agent commits.

3. 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.

4. Claim all wave issues: run bd update <id> --claim for each issue ID in the wave. Report the claimed IDs.

5. Update the wave status to running in the SWARM file.

6. 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."

   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).

7. Wait for all agents to complete. As each agent reports done, log it.

8. 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).

9. Update wave status to gate-pending in the SWARM file.

10. 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:

1. Read the active SWARM file. Find the wave. Verify status is gate-pending or gate-passed.
2. 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.
3. Wait for both review agents and the check to complete. Read findings.
4. 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.
5. 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.
6. 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). 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:

1. Run bd ready to get all open issues. If beads is unavailable, ask the user to provide issue titles and descriptions.

2. 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.

3. 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.

4. 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.

5. 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:

1. 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.
2. 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.
3. 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.
4. Launch all research agents in parallel (single response, multiple Agent tool calls).
5. Wait for all agents to complete. Read all findings files.
6. Dedup pass. Read all findings side by side. Identify duplicate or overlapping findings across agents. Produce a merged summary.
7. 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.
8. 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 required. All swarm-wave workflows assume beads is available. Guard all bd commands — if .beads/ is absent, report that swarm-wave requires beads and stop.
• 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.