Skip to content
  1. Skills at a glance
  2. Design and review
  3. /pstack:swarm

/pstack:swarm

Auto

In 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.
Say it like this
/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.

Just askingWith /pstack:swarm
Pastes the raw helper output at you.Merges results into one table, one line per issue, gaps listed apart.
Counts a helper that returned nothing as a pass.Respawns a missing result once, then records a gap. A gap is not a pass.
Stops at the first problem it finds.Lists every issue it can prove and marks results PASS, ISSUES or BLOCKED.

What the document says

5 sections, about 550 words, 2 min to read. Click a section to read it.

  1. 1StartOpens a todolist with one entry each for Frame, Fan out, Aggregate and Report.
  2. 2Phase A: FrameStates the done test, picks slices or a race, fixes the race rule first, and names SHAs and method for measurements.
  3. 3Phase B: Fan outSpawns all workers in one message, in the cloud by default. Each brief stands alone: goal, scope, check, report format.
  4. 4Phase C: AggregateReads final results, respawns once any that skipped the SHAs or method, records a gap after that, applies the race rule.
  5. 5Phase D: ReportReturns one in-chat report: a result table, one line per issue, gaps and dropouts, and the race rule used.

See the wording worth borrowingRead the full text

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.

  1. 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."
  2. 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."
  3. Set the winning rule first

    For a race or mixed shape, declare first pass, rank all, or best-of before 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.
  4. 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.

  1. Frame
  2. Fan out
  3. Aggregate
  4. Report

Phase A: Frame

  1. State the done predicate and the artifact or report the swarm must return.
  2. 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.
  3. Pick the worker model from the swarm workers line in the pstack settings file (~/.cursor/rules/pstack-models.mdc in Cursor, ~/.claude/rules/pstack-models.md in Claude Code, ~/.agents/pstack-models.md in other harnesses). If the file or that line is missing, use grok-4.7-xhigh-fast. For auto or inherit-parent, omit model so 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.
  4. 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

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.