Download the exact captured file
---
name: swarm
description: Use when executing a superlite plan that has a %% taskgraph. Runs a ready-queue scheduler over an idle agent pool, with scripts for the mechanical steps, selective reviews, and a packet-only final review.
---
# Swarm
You are the coordinator. You decide, dispatch and rule; scripts do everything with a definite answer; agents design, write, review and fix. Read each script's one-line output; one narration line per tool call.
Shorthand (every agent brief states `SUPERLITE=<path>`):
`SUPERLITE` = the plugin root, two levels above this skill's "Base directory for this skill: ..." path: `SUPERLITE="$(cd "<base dir>/../.." && pwd)"`, passing the base dir through `cygpath -u` first when that exists. `CLI="$SUPERLITE/skills/swarm/scripts/superlite-cli"`; always run it as `bash "$CLI" ...`. `PLAN` = the plan file; pass `--plan $PLAN` everywhere. Exit 3 means no Python: `bash "$CLI" incident add` it and continue.
**You never edit code or run raw `pytest`; fixes go to fixer agents: tiers, escalation and contract in `fixing.md` (Fixing). Never pass `model`.**
**Rulings, not stalls.** Decide conflicts and plan defects yourself (**spec** binds when present: done+why outranks the plan's how; `superlite-cli agent_specs status`). Append `Ruling: <decision> - <why> - <cost if wrong>` to `.superlite/progress.md`.
## Setup
- **One feature, one worktree**: a feature (or colliding multi-file build) works only in its own worktree on `superlite/<topic>`: `superlite-cli session create --slug <topic> --worktree` if missing, then enter it (`session: create` / `enter` line; else `cd`). Write the start SHA to `.superlite/progress.md` (`- start <sha>`).
- Wave 0 is never yours: when the machine plan is written, run `bash "$CLI" wave0 --plan $PLAN` and send Wave 0 in the same message as `lint --stable`. Lint skips START FIRST once the brief exists; `STUB UPDATE:` means refresh stubs. `wave0 --plan` reprints the line. Then `checkpoint T0` (tasks never wait for it) and `bash "$CLI" plan_tools adapter --plan $PLAN`.
- Prime now: `bash "$CLI" build_prime --plan $PLAN` prints `hash size` and writes the slim `.superlite/prime.md` (rules, header, constraints, stable interfaces; `--prime full --spec SPEC --sections "1,3"` = whole plan). Start ready tasks now.
- Incidents: `.superlite/incidents.jsonl` (agents call `bash "$CLI" incident add`); you log BLOCKED and NEEDS_CONTEXT with `--agent coordinator`.
- Graphify: `bash "$CLI" graphify_gate` prints JSON; `use` false: skip. Installed: `graphify update .`. `needs_install` and `allowed`: `uv tool install graphifyy`, `graphify extract . --code-only`. You alone run `graphify update .` after each package is checkpointed.
## Planning check
`widget:` from lint or finish: show that file verbatim with your inline widget tool (e.g. `show_widget`).
Fixed order: write plan -> `bash "$CLI" plan_tools lint --plan $PLAN --spec SPEC --stable` (show the body of its `GRAPH` block to the user as a ```mermaid block; lists STABLE and FIX tasks, writes `.superlite/stable.json`; prints `SEND BEFORE ANY PLAN EDIT:`, ends with `DISPATCH NOW: T2 T4` or `none`) -> `dispatch` and start every task on that line in the same turn -> only then patch the FIX tasks (edits or a rewrite) -> re-lint -> dispatch the newly stable tasks -> repeat until lint passes. Never patch, rewrite or re-lint while a `DISPATCH NOW` task is unsent.
Each dispatch round, in the same message as the Agent calls, run the `THEN LOG` line lint prints (it appends `unblocked: dispatched T2 T4 at HH:MM:SS; waiting on fixes: T1 T3` to progress.md). `finish` checks it against `lint-log.jsonl`.
Dispatched tasks are frozen: a rewrite keeps their blocks byte-identical, else lint says `FROZEN:` (restore it; a real change is a follow-up fix task). `**Status:** draft` is an optional manual hold. `MISSED TARGET: ... critical path T1 -> T5` is a warning: split or stub the named tasks, or `Ruling: accept predicted <N> min - <why sequential> - <cost>`. `NOTE:` is advice.
## The scheduling loop
```mermaid
flowchart TB
N[dispatch] --> A{per batch}
A -- agent=ID --> M[task message]
A -- poll IDS --> Q[relevance poll] --> M
A -- fresh --> P[prime verbatim] -- READY --> M
M --> D[DONE reports] --> C[checkpoint T.. --dispatch] --> A
C -. background .-> PR[probe_run --checkpoint]
C -. both sides in .-> SM[pt_review contract seam]
```
Keep `.superlite/pool.json`: `{"agents":[{"id","tasks":[...],"files":[...],"context_k":N,"idle_min":N,"busy":false,"current":"Tn","tier":"haiku|sonnet"}]}` (`tier` = the line's; T0's is `haiku`). Sending a line or spawning its agent sets `busy: true` and `current: Tn` (a batch: `Tn,Tm`); `checkpoint` clears each task it records. The ledger and `current` are the state: keep no lists.
1. `bash "$CLI" dispatch --plan $PLAN --cap 10` prints one line per batch (`Tn` or `Tn,Tm`) from packing that minimizes max(B+A, F/T), longest first: `Tn agent=ID tier=T`, `Tn poll ID,ID tier=T` or `Tn fresh tier=T agent=TYPE`. Tiers come from lint (`config/routing.json`); never override or cross them. Start exactly those. Compact every 30 min (`compact_due`).
2. Per line: `agent=ID`: SendMessage the task to that idle agent. `poll ID,ID`: one SendMessage to each listed agent, "Relevance 0-10 for Tn (files, consumes)? Reply `score: N - reason`"; use the replies present at your next turn, highest wins, tie to the smallest `context_k`. `fresh tier=T agent=TYPE`: Agent TYPE with its tier's prime file pasted verbatim (`.superlite/prime.md`; haiku: `build_prime --tier haiku` writes `prime-haiku.md`), and send its task only after its reply `READY`. `evict=ID` (stderr): drop it. `dispatch` never offers a busy agent or one past its tier's limits.
3. Task message (a batch: one message, in line order): heading and `PLAN`, "your task text: `bash "$CLI" task Tn --plan $PLAN`" (current plan, never retyped), Owns and files not to touch, the Review Focus categories for its files, rulings and interface names (a fake returns the producer's `e.g.` examples), `SUPERLITE=<path>`, the verify command (`bash "$CLI" run_tests --affected --files <owned files> --background`, then `--wait --run <id>` from its `wait:` line; `--fast PATHS` is the manual fallback), append `bash "$CLI" lessons brief --task Tn --plan $PLAN` output, and "reply in at most 200 words per task: status DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED, files, `tests: <passed> <failed> <skipped> run <id>`, open questions".
4. Mark reporters `busy: false`. Verify each DONE task with `--wait --run <id>` (its reported run id; own file, exit 0 green); a missing or mismatched id is unverified. Then record all DONE tasks in one call (hidden): `bash "$CLI" checkpoint T3 T5 --plan $PLAN --dispatch` saves each task's own files, prints `Tn <sha>` or `Tn FAILED`, then `next:` and dispatch lines. A FAILED task lists unowned files or syntax/import problems: send it back. DONE_WITH_CONCERNS: fix correctness ones first. NEEDS_CONTEXT: always answer the same implementer; if the plan is silent, add a `Ruling:` and answer with it; resume with the answered task first (`--question` / `--answered`). BLOCKED: log (`checkpoint --blocked T --tier X`); fixer one tier up (Fixing). A haiku miss: `bash "$CLI" routing miss --task Tn --plan $PLAN`; never retried on Haiku. Act on the `next:` lines. On `Learned: tag: text`: `bash "$CLI" learn note --task Tn --tag tag --text "…"`.
5. Each checkpoint has already started `probe_run --checkpoint` and, for each seam whose two sides are now both checkpointed, `pt_review contract --seam` in the background. Pass: `verified`; mismatch: incident. Route the fix per `fixing.md`.
6. Probe failures: `incident hotspots --files <task files>` before the next work; open failures go to fixers (`fixing.md`). `checkpoint` accepts generated `tests/regression/` files from any task.
## Reviews (D16)
```mermaid
flowchart LR
C[checkpoint] --> T{seam, Complexity >= 5, Review Focus risk, open incident?}
T -- yes --> R1[package-reviewer on that task]
T -- no --> W[wait for the package] --> R2[one package-reviewer, all its diffs]
R1 & R2 --> X[fixes + regression tests] --> K[checkpoint again]
```
- Matching tasks get `superlite:package-reviewer` on checkpoint, in the same message as the next dispatches; others, one review per checkpointed package. In the last package, review each task at checkpoint.
- Brief: `SUPERLITE=<path>`, checkpoint or range, spec slice, `PLAN`, files in scope, `incident hotspots` output, adapter path. It reviews, fixes with regression tests, logs; you checkpoint its fixes; its files are off limits meanwhile.
## Coordinator batching
- One message per turn: all dispatches, reviews, background starts.
- Every test run is `run_tests ... --background`; the coordinator never waits on a test run mid-build; only agents wait, on their own. The one blocking run is at finish (`superlite:shipping`).
## Final review
```mermaid
flowchart TB
G[all reviewed + saved] --> PK[packet from existing summary]
G --> ST[run_tests --affected, background]
PK --> FR[fresh final-reviewer, findings only]
FR --> V{findings, suite red?}
ST --> V
V -- yes --> FX[fixers by tier] --> ST2[run_tests --affected --background]
V -- no --> Z[freeze, checkpoint]
```
1. Gate: every task checkpointed, every review reported and checkpointed, every seam `verified`.
2. Build the packet now: `bash "$CLI" plan_tools packet --plan $PLAN --base <start-sha>` uses `.superlite/tests/summary.json`, probe results and incidents, and writes `.superlite/review-packet.md`. Its header says `FAST PATH` or `REVIEW REQUIRED`. In the same message start `bash "$CLI" run_tests --affected --background`; do not wait for it.
3. Start `superlite:final-reviewer` at the same moment, fresh, brief = `SUPERLITE=<path>` and "read .superlite/review-packet.md", nothing more. The tree stays frozen. It answers in one turn from the packet only: `Verdict: APPROVED` or `CHANGES_REQUESTED` plus `file:line - problem - fix - tier N` lines. Pipe its reply into `bash "$CLI" review_findings record`.
4. Red suite lines are findings too. Send all to fixers (`fixing.md`: tier by understanding, split by file), then `checkpoint Tn` per owning task and one more `run_tests --affected --background`. Leftovers: a `Ruling:`.
5. Freeze and checkpoint without waiting on tests. Shipping runs the one blocking run (`run_tests --full --reuse` when the plan says `**Full suite:** yes`, else `run_tests --affected --base <start sha>`); red blocks merge and PR.
## Measure and budget
Hooks write `.superlite/metrics.jsonl` (see `metrics.md`). `lint` and `dispatch` print `budget:` lines when they change (`**Budget-usd:**` in the plan header is the cap). At `WARN` finish what is in flight; at `OVER CAP` start no extra review rounds and no fix rounds beyond the first, then `checkpoint` and finish. `LATE: critical path ...` names the task to unblock first.
## Freeze, rulings, finish
Green suite: freeze. `finish` moves the run's files into `.superlite/runs/<id>/`. Run `bash "$CLI" finish --plan $PLAN`; print its rulings in your closing message under "Rulings I made", each with its cost, then its last block (the report summary) before any merge or PR option; full: `<plan>.report.md`. Then invoke `superlite:shipping`.
## Stop conditions
Stop and ask only for: an irreversible or destructive operation; a security-sensitive action; an outward side effect (merge, push, publish); a plan so broken every path is a guess.
**AI orchestrator** (`superlite-cli orchestrator status`; also user away, "decide yourself"): never end your turn to wait. Take the safe path: defer the outward or destructive action, read a broken plan conservatively, record the ruling; list what you deferred. **Human orchestrator**: nothing is built, dispatched or written but the review plan before the human's approving reply; ask in plain text, end the turn, then if you understand their answer as approval send `bash "$CLI" orchestrator approve --review PATH` and the machine plan. Do not pass their words through. `lint --stable`, `dispatch`, `wave0`, `build_prime` refuse before (`orchestrator.md`).
## Red flags
| Thought or act | Do instead |
|---|---|
| Typing the prime or a task before READY | `build_prime`, paste verbatim, wait for READY |
| Work to a busy agent, or "after T3" | `dispatch` |
| Editing code, raw `pytest`, or a foreground suite | Fixer agent; `run_tests --background` |
| `git commit` by hand | `checkpoint T3 T5 --dispatch` |