---
name: swarm
description: "Fan out N parallel workers, drain them, and return one report. Use for /swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration."
disable-model-invocation: true
---

# 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.
4. Pick the worker seat from the `swarm workers` line in `~/.config/pstack/models.md`, else the default in `<pstack>/docs/models.md`. A `session` seat runs the workers on the lead's own model. When the seat is unavailable, apply the fallback rule in `docs/models.md` and say which seat you substituted. For a model race, name each arm's seat up front. Pick each subagent's effort for the job, per the Subagents section of the **poteto-mode** skill.
5. 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, in the background, with the tool [`<pstack>/docs/t3.md`](../../docs/t3.md) names for the seat's provider: native `Agent` with `subagent_type: "general-purpose"` for a Claude seat when the lead is Claude Code, `delegate_task` otherwise. Give each worker `isolation: "worktree"`. Omit it only when the worker must share the lead's checkout. Keep every `taskId`, then end your turn. Each completion wakes you. Use `task_status` only when you need a result mid-turn.

A worktree starts from the lead's local commit. Commit first, since uncommitted edits are not copied. When a worker must start from another pushed branch, name the exact ref in the brief and have the worker check it out inside its worktree.

Every brief stands alone, since a `delegate_task` child has no parent history. 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 the table, issue one-liners, gaps or dropouts, and the race rule when used.