--- 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=`): `SUPERLITE` = the plugin root, two levels above this skill's "Base directory for this skill: ..." path: `SUPERLITE="$(cd "/../.." && 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: - - ` to `.superlite/progress.md`. ## Setup - **One feature, one worktree**: a feature (or colliding multi-file build) works only in its own worktree on `superlite/`: `superlite-cli session create --slug --worktree` if missing, then enter it (`session: create` / `enter` line; else `cd`). Write the start SHA to `.superlite/progress.md` (`- start `). - 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 min - - `. `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=`, the verify command (`bash "$CLI" run_tests --affected --files --background`, then `--wait --run ` 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: run `, open questions". 4. Mark reporters `busy: false`. Verify each DONE task with `--wait --run ` (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 ` 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 ` 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=`, 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 ` 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=` 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 `); 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//`. 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: `.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` |