106 lines
9.4 KiB
Markdown
106 lines
9.4 KiB
Markdown
---
|
||
name: agent-swarm
|
||
description: Use for large tasks that split into 8+ independent work units (codebase-wide changes, audits, migrations, multi-source research, multi-section documents) to run dozens of coordinated subagents in waves under one lead, with file ownership, packed context, and independent verification. Not for single-file, sequential, or highly coupled work.
|
||
whenToUse: The task is broad, parallelizable, and has executable acceptance checks; one agent would take hours and separate agents can finish units without touching the same files.
|
||
---
|
||
|
||
# Agent Swarm
|
||
|
||
Run a large task as waves of coordinated subagents. The lead plans and integrates; workers execute one work packet each; verifiers check independently. A swarm is only as fast as its briefs are clear and its write scopes are disjoint.
|
||
|
||
## Fit check — before spawning anything
|
||
|
||
Swarm only when all are true:
|
||
- The task splits into **8+ independent units** with disjoint write scopes.
|
||
- Each unit has an **executable acceptance check** (command, test, or verifiable criterion).
|
||
- Wall-clock is dominated by **breadth**, not by one deep sequential chain.
|
||
- You can state the interfaces between units **before** dispatch.
|
||
|
||
Otherwise: one agent for small work; 2–5 `subagent` calls for a few long-lived roles you need to steer. Never swarm one bug, one design decision, or work where every unit edits the same files.
|
||
|
||
## Roles
|
||
|
||
- **Lead** — you. Owns the plan, packets, contracts, gates, integration, and the final report. Does not implement during waves.
|
||
- **Recon** (2–4) — maps files, commands, conventions, and hazards. Does not design the solution.
|
||
- **Worker** — one task card, one write scope, one structured report.
|
||
- **Verifier** — fresh context; checks the artifact against acceptance criteria, never the worker's summary.
|
||
- **Integrator** (1–2) — owns shared files and cross-cutting fixes after the parallel waves. During a wave, the lead/integrator may make a small contract/shared-file change to unblock a task, then resume that same worker with `send_message`; do not spawn a replacement.
|
||
|
||
## Protocol
|
||
|
||
0. **Fit check & preflight** — go/no-go, budget (`max_agents`, `max_waves`), and **discover the real active-child cap** before sizing a wave (see Sizing). Record the cap, current active children, and planned batch size in `state.json`.
|
||
1. **Recon** — 2–4 parallel agents return findings with paths and line numbers. Timebox them, merge into `.swarm/brief.md` and `.swarm/map.md`, then stop them; recon must not hold slots during the build wave.
|
||
2. **Plan gate** — write `.swarm/plan.json`, `plan.md`, `ownership.md`, `contracts.md`, and one `tasks/Txx.md` per unit. Every success criterion maps to a task and a check. No two tasks write the same path. Include a `LEAD`/`INTEGRATOR` task owning lead-owned shared files, screenshots, licenses and the final report. Freeze interfaces. **Do not dispatch until this gate passes.**
|
||
3. **Build wave** — one `workflow` call per build wave, using the batched runner in `assets/wave.workflow.js`; its `concurrency` must fit the available slots (see Sizing). Retry `null`/`failed` once; if the runtime reports an active-child limit, halve the next batch and dispatch the remaining tasks — never relaunch the same oversubscribed fan-out.
|
||
4. **Audit** — run `scripts/audit-scope.mjs` from the skill base directory; revert or reassign out-of-scope changes. Run the build/test gate.
|
||
5. **Verify wave** — **freeze source changes**, then run 4–6 fresh verifiers by risk cluster. Use `assets/verdict.schema.json` and `assets/verify.workflow.js`; the review file on disk is the source of truth, not the workflow return. Verifiers never fix. If you fix findings, re-run the affected verifier and mark the old review stale.
|
||
6. **Integrate** — one integrator for shared files and cross-cutting fixes; re-run the full acceptance suite; then a final verification pass on the integrated build.
|
||
7. **Close** — freeze the build and run a final independent review against the original request (not the plan), then write `final-report.md`.
|
||
|
||
## Hard rules
|
||
|
||
1. **One writer per path.** A path appears in at most one task's `write` list. Shared files (`package.json`, lockfiles, barrels, schemas, migrations, CI) belong to the integrator only.
|
||
2. **Packet, not transcript.** Each worker reads `.swarm/brief.md`, its `tasks/Txx.md`, and `.swarm/contracts.md`. Never fork the lead's conversation for dozens of workers.
|
||
3. **Structured reports.** Workers return `{task_id, status, summary, files_changed, evidence, acceptance, issues, assumptions}` and write the same object to `.swarm/reports/Txx.json`. Verifiers write the full review to `.swarm/reviews/Vxx.md` and return the minimal `{task_id, verdict, summary, review_file}`. Prose is not a report.
|
||
4. **No self-verification.** The worker's own checks are a smoke test; a different agent verifies the artifact.
|
||
5. **No global side effects.** Workers do not run installs, repo-wide format/lint/codegen, migrations, dev servers, or any git write command. They do not edit other tasks' files or reports. The lead owns git and commits only after the final review.
|
||
6. **Respect the runtime slot cap.** Active children include recon, verifiers, integrators and any other subagents. A spawn-limit error is a scheduling bug, not a worker failure: shrink the batch, keep completed results, and dispatch the remainder.
|
||
7. **Freeze during verification.** Once the verify wave starts, do not edit source/tests/docs except to fix a verified finding. After a fix, re-run the affected verifier; an old review is stale.
|
||
8. **Stop rules.** Two waves with no net progress → stop and re-plan. Verification failure rate > 30% → fix briefs/contracts, not agent count. Budget exhausted → report partial and list unverified areas.
|
||
|
||
## Sizing
|
||
|
||
| Independent units | Batch size | Batches | Agents | Notes |
|
||
|---|---|---|---|---|
|
||
| < 8 | — | — | — | Do not swarm |
|
||
| 8–11 | 6–8 | 1 + verify | ~12–14 | Small swarm; one batch |
|
||
| 12–24 | 6–8 | 2 | ~20 | Default; 2 batches per build wave |
|
||
| 25–48 | 6–8 | 3–4 | ~40 | Large; watch the lead's context |
|
||
| 49+ | 6–8 | 5+ | 60+ | Only if truly independent; the lead becomes the bottleneck |
|
||
|
||
**The wave size is not fixed by this table.** The runtime active-child cap is host/policy-specific and may be as low as 8; do not assume 14 or any default. Discover it before dispatch (runtime diagnostics or a tiny trial), subtract active recon/other children, and leave at least one slot free for retries. If the cap is unknown, start with 6 workers. The batched runner in `assets/wave.workflow.js` starts tasks in chunks, so a failure to spawn one chunk does not discard completed work.
|
||
|
||
## Workspace
|
||
|
||
```
|
||
.swarm/
|
||
brief.md shared context: goal, stack, commands, conventions, hazards
|
||
map.md repository map from recon: paths, entry points, hazards
|
||
contracts.md frozen interfaces between tasks
|
||
plan.json tasks, deps, write scopes, waves, status
|
||
plan.md human-readable plan + coverage matrix
|
||
ownership.md path -> task map
|
||
tasks/T01.md one work packet per task
|
||
reports/T01.json worker report (worker writes)
|
||
reviews/V01.md verifier report (verifier writes)
|
||
baseline.json pre-swarm file manifest (`--init`)
|
||
report.schema.json report contract for workers
|
||
verdict.schema.json minimal contract for verifiers
|
||
state.json wave, budget spent, open issues
|
||
final-report.md
|
||
tmp/T01/ worker scratch, never shared
|
||
```
|
||
|
||
## Coordination loop
|
||
|
||
Between waves the lead does only four things: **continue**, **answer blocked tasks and retry**, **re-scope**, or **stop**. Read structured reports and review files, not raw logs. Keep `state.json` current, including the real slot cap, retries and re-verifications. The lead is the only agent that talks to the user.
|
||
|
||
For a `blocked` task: apply the smallest contract/shared-file change, update `contracts.md`, record it in `state.json`, then `send_message` to the **same** worker with the answer and let it continue. Do not spawn a replacement for a worker that only needed a decision.
|
||
|
||
## References
|
||
|
||
- `references/playbook.md` — phase-by-phase runbook, gates, checklists, failure recovery.
|
||
- `references/packets.md` — how to write briefs, task cards, and verifier cards; examples and common mistakes.
|
||
- `references/orchestration.md` — `workflow` cookbook: script patterns, schema subset, retries, background runs, archetypes (code / research / content).
|
||
- `assets/` — copyable brief, task, and verifier templates; `report.schema.json`, `verdict.schema.json`; `wave.workflow.js` (batched workers), `verify.workflow.js` (frozen verification).
|
||
- `scripts/audit-scope.mjs` — compares changed files to the ownership map.
|
||
|
||
## Signals that the swarm is failing
|
||
|
||
- Workers ask the same question or edit the same file → the plan or contracts are underspecified.
|
||
- Reports are long on prose and short on evidence → the task card lacks executable checks.
|
||
- The lead spends more tokens reading reports than the workers spend working → waves are too large or reports too verbose.
|
||
- Verification finds the same class of defect repeatedly → fix the brief, not the worker.
|
||
- A workflow ends with `no usable verdict` although reviews exist on disk → the verifier schema is too strict; read the review files and switch to `assets/verdict.schema.json`.
|
||
- A wave dies with `active child limit reached` → the batch was sized from the wrong cap; halve it, subtract recon, and dispatch only unstarted tasks.
|