/pstack:swarm
AutoIn one lineSplits the work into separate pieces, sends one AI per piece, and sums it up in one report.
- When to use
- You need to go through a lot: every package, every feature.
/pstack:swarm Run check.sh for every package under packages/, one agent per package, and give me one report at the end.Just asking vs. using it
The same request, typed plainly or with /pstack:swarm. Here's what changes.
With /pstack:swarmPASS, ISSUES or BLOCKED.What the document says
5 sections, about 550 words, 2 min to read. Click a section to read it.
- 1StartOpens a todolist with one entry each for Frame, Fan out, Aggregate and Report.
- 2Phase A: FrameStates the done test, picks slices or a race, fixes the race rule first, and names SHAs and method for measurements.
- 3Phase B: Fan outSpawns all workers in one message, in the cloud by default. Each brief stands alone: goal, scope, check, report format.
- 4Phase C: AggregateReads final results, respawns once any that skipped the SHAs or method, records a gap after that, applies the race rule.
- 5Phase D: ReportReturns one in-chat report: a result table, one line per issue, gaps and dropouts, and the race rule used.
Wording worth borrowing
A few sentences from the original: what each one makes the AI do, why it works, and how you can borrow it.
Make every brief stand alone
Every brief stands alone.
- Makes the AI
- Each helper AI gets the full goal, scope and way to check, so none goes off track for lack of context.
- Why it works
- Helpers can't see your chat, so this forces the AI to write the context in instead of assuming it.
- Borrow it
- When you hand off work, add: "Write it so a new colleague who missed our discussion could act on it."
Say what a missing result means
A gap does not count as a pass.
- Makes the AI
- When a helper returns nothing, the report names the gap instead of counting it as passed.
- Why it works
- AIs tend to read "no error" as "no problem"; deciding up front what a blank means closes that door.
- Borrow it
- Add to a checklist: "Pages you didn't check count as failed; list them separately."
Set the winning rule first
For a race or mixed shape, declare
first pass,rank all, orbest-ofbefore spawning.- Makes the AI
- When several helpers race on one job, how the winner is picked is fixed before they start, so it can't shift afterward.
- Why it works
- Rules set before the results stop the AI from picking whichever standard suits the outcome.
- Borrow it
- Say before starting: "Of the three versions, we keep whichever loads fastest." Then begin.
Ask for all, not the first
lists every issue it can prove, not only the first
- Makes the AI
- It lists every problem it can prove, instead of stopping at the first.
- Why it works
- AIs tend to stop at the first find; saying "not only the first" breaks that habit.
- Borrow it
- For a contract review: "Find every clause that works against me, not just the first one."
Full text
The SKILL.md the AI reads, as written.
descriptionFan out N parallel workers, drain them, and return one report. Use for /pstack:swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration.
Swarm
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, orbest-ofbefore spawning. - Pick the worker model from the
swarm workersline in the pstack settings file (~/.cursor/rules/pstack-models.mdcin Cursor,~/.claude/rules/pstack-models.mdin Claude Code,~/.agents/pstack-models.mdin other harnesses). If the file or that line is missing, usegrok-4.7-xhigh-fast. Forautoorinherit-parent, omitmodelso the workers run on the parent model. If your subagent tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message or your harness's model list. For a model race, name each arm's model up front. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the poteto-mode skill. - Give each worker its own writable output when it writes. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result.
Phase B: Fan out
Spawn all N workers in one message with subagent_type: generalPurpose, environment: "cloud", run_in_background: true, and the step 3 model, left unset for auto or inherit-parent. Use environment: "local" only when the worker needs access to something on the user's computer.
When a worker must start from a non-default pushed branch, pass cloud_base_branch.
Other harnesses. These parameters belong to Cursor's Task tool, and environment: "cloud" runs a Cursor cloud agent. In another harness, use its subagent tool: Agent in Claude Code (subagent_type: general-purpose), task in OpenCode (subagent_type: general), spawn_agent in Codex. Workers run locally there, so give each one its own worktree or output path. Keep the brief and the model. Drop parameters your tool doesn't have. If your harness has no subagent tool, as in Pi without an extension, run the workers yourself, one after another.
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. A worker that can prove a defect reports ISSUES and lists every issue it can prove, not only the first.
If a worker drops out, proceed with N-1 and note it.
Phase C: Aggregate
Read the terminal results. Drop a result that does not record the SHAs and method its brief names, and respawn that worker once. After a second miss, record a gap. A gap does not count as a pass. 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.
Phase D: Report
Return one consolidated in-chat report with a result table, issue one-liners, gaps or dropouts, and the race rule when used.
Original by Lauren Tan (poteto), MIT license. Checked against the pstack mirror at 97de40d. View on GitHub