| name | swarm |
| description | Fan out N parallel workers, drain them, and return one report. Use for /skill:swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration. |
| disable-model-invocation | true |
Swarm
Fan out N parallel cloud workers. They may cover separate slices, race the same brief, or mix both. The parent waits, aggregates, and returns one report.
Start
Open a todolist with one entry per phase before launching anything.
- Frame
- Fan out
- Aggregate
- Report
Phase A: Frame
- State the done predicate and the artifact or report the swarm must return.
- Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare
first pass, rank all, or best-of before spawning.
- Set N from the user or derive it from the shape. N is total workers, not the cloud concurrency limit.
- Pick the worker model from
swarm workers in ~/.pi/agent/pstack/models.json when present. Otherwise use inherit-parent. For a model race, name each arm's model up front.
- Give each worker its own writable output when it writes. Use a worktree, branch, or
/tmp/swarm-<slug>/worker-<n>/.
Phase B: Fan out
Spawn all N workers in one parallel subagent call using its tasks array. Use agent: "poteto-agent" unless a workflow names another agent, and set role: "swarm workers". Pi child processes run locally with isolated context, so give each task explicit file pointers and prevent concurrent writes to shared paths.
When a worker must start from a non-default pushed branch, pass cloud_base_branch.
Every brief stands alone. Include the goal, scope, exact slice or race arm, how to verify, and what to report. Reports use PASS, ISSUES, or BLOCKED with evidence.
If a worker drops out, proceed with N-1 and note it.
Phase C: Aggregate
Read the terminal results. For coverage, every required slice needs a result. For a race, apply the selection rule declared up front. Use first pass, rank all, or best-of. Do not paste raw worker dumps.
Keep a compact result table, one-line evidenced issues, and explicit gaps or dropouts.
Phase D: Report
Return one consolidated in-chat report with the table, issue one-liners, gaps or dropouts, and the race rule when used.
