Add agent-swarm skill
This commit is contained in:
Emil Shanaty
@@ -0,0 +1,188 @@
|
||||
# Swarm playbook
|
||||
|
||||
Detailed runbook for `agent-swarm`. Read this after the fit check passes. Keep `.swarm/state.json` current; it is the resume point if the session restarts.
|
||||
|
||||
## 0. Fit check and budget
|
||||
|
||||
Answer these before spawning:
|
||||
- **Units.** Can you list 8+ deliverables that different agents can finish without waiting for each other?
|
||||
- **Writes.** Can every unit get a disjoint write scope? Name the shared files now.
|
||||
- **Checks.** Does every unit have a command or criterion a verifier can re-run?
|
||||
- **Interfaces.** Can you freeze signatures, data shapes, and file names before dispatch?
|
||||
- **Breadth.** Is the time dominated by many independent pieces, not one deep chain?
|
||||
|
||||
Budget:
|
||||
- `agents ≈ units + ceil(units / 5) verifiers + 1–2 integrators + 2–4 recon`; add retries and re-verifications explicitly.
|
||||
- Tokens ≈ `agents × 20k` (10–40k per agent depending on code reads).
|
||||
- Waves ≈ `ceil(units / batch_size)` + verify + integrate, where `batch_size` comes from the **real** active-child cap, not from a documented default.
|
||||
- Stop at `max_agents` or `max_waves`, whichever comes first. Record both, plus `slot_cap`, `active_at_dispatch`, `batch_size`, retries and re-verifications in `state.json`.
|
||||
|
||||
Go: a 40-file migration with per-module tests, a 30-source research report, a 20-section document with a style guide.
|
||||
No-go: one failing test, one architectural decision, a refactor where every file imports the same core module.
|
||||
|
||||
## 1. Recon (2–4 agents)
|
||||
|
||||
Give each recon agent one question, not the whole task:
|
||||
- Structure: entry points, modules, build/test commands.
|
||||
- Conventions: naming, error handling, test style, formatting.
|
||||
- Hazards: generated files, migrations, flaky tests, shared caches, secrets.
|
||||
- Prior work: existing branches, TODOs, partial implementations.
|
||||
|
||||
Require findings as `path:line — fact`, no proposals. Merge into `.swarm/brief.md` and `.swarm/map.md`. Cap recon at ~10% of the budget and **10–15 minutes per recon agent**; on a small repo, do it yourself.
|
||||
|
||||
Recon lifecycle matters: each recon agent writes its report and stops. It must kill GUI/probe processes it started, must not run the full test suite, and must not keep a slot while the build wave starts. If a recon agent is still active after its report exists, interrupt it; otherwise it silently consumes one of the active-child slots.
|
||||
|
||||
## 2. Plan gate
|
||||
|
||||
Resolve `<skill>` to the base directory reported by the skill loader. If the workspace is a git repository, add `.swarm/` to `.gitignore` before the baseline so coordination files never reach the diff. Bootstrap once:
|
||||
|
||||
```sh
|
||||
mkdir -p .swarm/tasks .swarm/reports .swarm/reviews .swarm/tmp
|
||||
cp <skill>/assets/brief.md.tmpl .swarm/brief.md
|
||||
cp <skill>/assets/report.schema.json .swarm/report.schema.json
|
||||
cp <skill>/assets/verdict.schema.json .swarm/verdict.schema.json
|
||||
node <skill>/scripts/audit-scope.mjs --init
|
||||
```
|
||||
|
||||
Write the plan before any worker starts.
|
||||
|
||||
**Decomposition.** One task = one deliverable, one writer, one acceptance check, at most one page. Budget **5–25 minutes for S/M** and **40–60 minutes for L**; the old blanket 25-minute rule underestimates large UI/refactor files. If a task is expected to produce a single source file over ~1,500 lines, split it by module or accept that it will be a long, integration-heavy task. If it needs two writers, split it; if it needs the whole repo, it is not a task.
|
||||
|
||||
**Ownership.** Every path in exactly one `write` list. Add an explicit `LEAD` task whose `write` list contains lead/integrator-owned shared files, screenshots, licenses and the final report; without it, audit-scope reports the lead's own integration edits as unowned. Shared files are integrator-only: `package.json`, lockfiles, `tsconfig`, CI config, barrel/index files, schemas, migrations, i18n catalogs, snapshots, generated code. If two tasks must touch one file, serialize them with `depends_on` or merge them.
|
||||
|
||||
**Contracts.** Freeze what crosses a boundary: function signatures, types, file names, CLI flags, error behavior, output format. Put them in `.swarm/contracts.md`; workers may not change them without returning `blocked`.
|
||||
|
||||
**Coverage matrix.** Each success criterion → task(s) → check. A criterion with no task is a hole; a task with no criterion is scope creep.
|
||||
|
||||
**Visual acceptance.** For a GUI or visual product, define a deterministic screenshot/artifact command before dispatch (fixed window sizes, output path, clean pointer state) and put it in the acceptance matrix. Do not rely on desktop portal capture; it is unreliable on shared sessions and under Wayland.
|
||||
|
||||
**Waves.** Topologically sort by `depends_on`, then balance effort across batches. Do **not** plan 8–12 workers from a documented default: discover the runtime active-child cap first. Compute `batch_size = clamp(slot_cap - active_children - 1, 2, 8)`; recon and any other subagents count as active children. If the cap is unknown, use 6. Put foundational or risky tasks in batch 1; verify after the last build batch.
|
||||
|
||||
**Gate checklist:**
|
||||
- [ ] 8+ tasks, each with objective, inputs, write scope, acceptance, stop condition.
|
||||
- [ ] No path in two write scopes.
|
||||
- [ ] Contracts frozen for every cross-task interface.
|
||||
- [ ] Coverage matrix complete.
|
||||
- [ ] `slot_cap`, `active_at_dispatch`, and `batch_size` are recorded and `batch_size` fits the available slots.
|
||||
- [ ] Recon agents have stopped (or have been interrupted); no extra children hold slots.
|
||||
- [ ] A `LEAD`/`INTEGRATOR` task owns shared files, screenshots, licenses and the final report.
|
||||
- [ ] For a visual/GUI product, a deterministic screenshot command and sizes are in the acceptance matrix.
|
||||
- [ ] `.swarm/brief.md`, `plan.json`, `plan.md`, `ownership.md`, `contracts.md`, `tasks/*.md` exist.
|
||||
- [ ] `audit-scope.mjs --init` recorded the baseline.
|
||||
|
||||
If any box is empty, fix the plan; do not dispatch.
|
||||
|
||||
Minimal `plan.json` shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"goal": "one line",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "LEAD",
|
||||
"title": "lead-owned shared files, screenshots, licenses, final report",
|
||||
"wave": 0,
|
||||
"status": "in_progress",
|
||||
"depends_on": [],
|
||||
"write": ["package.json", "docs/**", "LICENSE*"],
|
||||
"read": []
|
||||
},
|
||||
{
|
||||
"id": "T01",
|
||||
"title": "short title",
|
||||
"wave": 1,
|
||||
"status": "pending",
|
||||
"depends_on": [],
|
||||
"write": ["src/feature/**"],
|
||||
"read": ["src/types.ts"],
|
||||
"acceptance": ["pnpm vitest run src/feature"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`audit-scope.mjs` reads only `id` and `write`. Keep those accurate. Use `path/**` for directories, including directories the task will create.
|
||||
|
||||
## 3. Build wave
|
||||
|
||||
Dispatch one `workflow` call per build wave (see `references/orchestration.md`). Use `assets/wave.workflow.js`, which splits tasks into batches, catches spawn errors instead of discarding the whole wave, and carries `args.concurrency`.
|
||||
|
||||
Before the call:
|
||||
- [ ] Task cards are on disk and reference real paths.
|
||||
- [ ] `args.tasks` carries `{id, write}` for each task.
|
||||
- [ ] The report schema is passed as `args.schema`, and `args.concurrency` is at most the free slot count.
|
||||
- [ ] Every task has a stop condition.
|
||||
- [ ] Baseline exists and `state.json` records the cap.
|
||||
|
||||
After the call:
|
||||
- [ ] Triage structured reports: done / partial / blocked / failed.
|
||||
- [ ] Treat `spawn/runtime error` and `active child limit` results as scheduling failures, not worker failures: keep completed results and dispatch only the unstarted remainder in a smaller batch.
|
||||
- [ ] Run `node <skill>/scripts/audit-scope.mjs` (the lead runs it; workers do not); revert or reassign out-of-scope changes.
|
||||
- [ ] Run the build/test gate yourself; do not ask workers to fix shared breakage.
|
||||
- [ ] Update `plan.json` and `state.json`.
|
||||
- [ ] Decide: continue, answer blocked, re-scope, or stop.
|
||||
|
||||
Do not paste reports into the next prompt. Summarize decisions into the brief or contracts. Open a full report only for `blocked` and `failed`.
|
||||
|
||||
### Answering a blocked task
|
||||
|
||||
A `blocked` report is a request for a lead decision, not a failure. Fast path:
|
||||
1. Read the exact `blocked_question` and the relevant contract section.
|
||||
2. Make the smallest possible shared/contract change yourself (or via the integrator), and update `.swarm/contracts.md` and `state.json`.
|
||||
3. `send_message` to the **same** worker with the decision and any exact signatures; ask it to continue under the same write scope.
|
||||
4. Do not spawn a replacement until the original worker cannot continue, and do not retry a blocked task with the same unanswered prompt.
|
||||
|
||||
If the block reveals an underspecified interface shared by several tasks, update the contract once and message all affected workers. If two blocked tasks need conflicting contracts, stop and re-plan.
|
||||
|
||||
## 4. Verify wave
|
||||
|
||||
Choose verifiers by risk cluster, not one per task: 4–6 verifiers for 8–12 tasks. A verifier gets the task cards, the changed files (or diff), and the acceptance commands. It does not get the worker's rationale and does not fix anything.
|
||||
|
||||
**Freeze before verify.** Once you start this wave, do not edit source, tests or docs. If you already started and then fixed something, mark the in-flight review stale and re-run that verifier on the new build. A verifier's verdict is only valid for the exact tree it saw.
|
||||
|
||||
Use `assets/verify.workflow.js` and `assets/verdict.schema.json`, not the full worker report schema. The verifier's detailed review **must be written to `.swarm/reviews/Vxx.md` before it returns**; the workflow return is only `{task_id, verdict, summary, review_file}`. Do not treat a workflow `null`/`no usable verdict` as a product failure if the review file exists — read the file, then re-run with the minimal schema if needed.
|
||||
|
||||
Evidence standard: for every criterion, a command and its observed result. `pass` without evidence is `not_run`. Accept `pass_with_risks` only with named risks and a follow-up task. Verifiers should copy or hash-check generated files rather than rewriting the tree; if a required gate script rewrites generated artifacts, report the hash delta.
|
||||
|
||||
On failure, create a fix task with the verifier's repro; do not send the verifier back to fix its own finding. After fixes, re-run the affected verifier and mark the previous review stale; repeat until the remaining findings are minor/documented. Then run a final integrated verification pass.
|
||||
|
||||
## 5. Integrate
|
||||
|
||||
One integrator (two only for disjoint areas) owns:
|
||||
- shared files and cross-cutting edits;
|
||||
- merge conflicts and import/barrel fixes;
|
||||
- one formatting/lint pass over changed files;
|
||||
- the full acceptance suite.
|
||||
|
||||
No parallel workers during integration. The integrator may read all task cards and reviews; it writes `.swarm/integration.md` with what changed and why. Freeze the tree while the final verification runs; any post-verification edit invalidates the affected evidence.
|
||||
|
||||
## 6. Close
|
||||
|
||||
Final review is against the **original request**, not the plan: a fresh agent checks the success criteria, the diff, and the evidence. Then the lead writes `.swarm/final-report.md` with these sections:
|
||||
|
||||
- Shipped — what exists now, with paths.
|
||||
- Not shipped / deferred — and why.
|
||||
- Evidence — commands and observed results.
|
||||
- Risks and open questions.
|
||||
- Cost — agents, waves, wall-clock.
|
||||
- Artifacts — `.swarm/...` paths.
|
||||
|
||||
## Failure recovery
|
||||
|
||||
| Signal | Likely cause | Action |
|
||||
|---|---|---|
|
||||
| Workers edit the same file | ownership map missed a shared file | stop, reassign, serialize, re-audit |
|
||||
| Many `blocked` on the same interface | contract underspecified | answer once in `contracts.md`, retry those tasks only |
|
||||
| Many schema `null`s | schema too strict or prompt unclear | loosen schema, add one example to the task card |
|
||||
| Wave slower than serial | units too small or too coupled | merge units, reduce batch size |
|
||||
| Workflow dies with `active child limit reached` | batch sized from wrong cap; recon still active | shrink batch, interrupt finished recon, dispatch only unstarted tasks |
|
||||
| `no usable verdict` but review files exist | verifier schema miss / prose return | read review files; switch to `verdict.schema.json`; re-run if stale |
|
||||
| Verifier reviewed an older build | source edited during verify | freeze, re-run affected verifier, mark old review stale |
|
||||
| `blocked` task with a shared-file need | contract omits an integration point | lead applies the change, messages the same worker, no replacement |
|
||||
| Verifiers find the same defect | brief missing a convention | fix the brief, add a check, re-run affected tasks |
|
||||
| Lead context filling up | reading full reports | read summary + evidence; open only exceptions |
|
||||
| A worker hangs | no per-agent timeout exists | kill the job, split the task, add a tighter stop condition |
|
||||
|
||||
## Time and cost
|
||||
|
||||
Parallel speedup is bounded by the sequential share and by the real slot cap, not by the number of tasks. Push sequential work down: recon once, contracts before dispatch, verification in parallel. A 36-unit task with 10-minute units and a 6-slot batch is ~6 batches × 10 min ≈ 60 min of agent work, plus plan, verify and integration; do not promise a 3× speedup when the host caps active children at 8 or fewer.
|
||||
Reference in New Issue
Block a user