Add swarm skill to pstack

[poteto]

Summary

• add the public-safe /swarm skill for parallel coverage and races
• route swarm through poteto mode without overriding its required subagent type
• require an upfront race rule and one-batch worker fan-out
• configure the default swarm worker model and publish the skill in the README

Testing

• node scripts/validate-plugins.mjs
• git diff --check origin/main...HEAD

  

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for all 3 issues found in the latest run.

• ✅ Fixed: Swarm missing poteto carve-out
  • Added swarm to poteto-mode's routed-workflow-skill carve-out list so its mandated generalPurpose subagent type and cloud environment are respected instead of being overridden to poteto-agent.
• ✅ Fixed: Missing parallel spawn instruction
  • Changed swarm Phase B to "Spawn all N workers in one message", matching the explicit single-message batch instruction used by the sibling fan-out skills (arena, how, why, interrogate, reflect).
• ✅ Fixed: Race rule never framed
  • Frame step 2 now requires declaring the race selection rule up front (first pass, rank all, or best-of) and Aggregate applies the rule declared in Frame, closing the post-hoc winner-criterion hole.

Or push these changes by commenting:

@cursor push a468bbdb17

Preview (a468bbdb17)

diff --git a/pstack/skills/poteto-mode/SKILL.md b/pstack/skills/poteto-mode/SKILL.md
--- a/pstack/skills/poteto-mode/SKILL.md
+++ b/pstack/skills/poteto-mode/SKILL.md
@@ -83,7 +83,7 @@
 
 ## Subagents
 
-**Use `subagent_type: "poteto-agent"` for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers). `/poteto-mode` and `poteto-agent` route through the same wrapper. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`) set their own `subagent_type` for diverse-model review; respect what the skill prescribes, don't override to `poteto-agent`.
+**Use `subagent_type: "poteto-agent"` for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers). `/poteto-mode` and `poteto-agent` route through the same wrapper. Routed workflow skills (`how`, `why`, `swarm`, `interrogate`, `reflect`) set their own `subagent_type` for diverse-model review or cloud fan-out; respect what the skill prescribes, don't override to `poteto-agent`.
 
 **Defaults for every `Task` call.** `run_in_background: true`, agent mode (readonly strips MCP), file pointers not inlined context, explicit model per role (configurable via `/setup-pstack`; defaults `grok-4.5-fast-xhigh` for code, `claude-fable-5-thinking-max` for prose and judgment). Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your strongest judgment model (`claude-fable-5-thinking-max`) when the task needs judgment or the intent is vague, and to your strongest instruction-following model (`gpt-5.6-sol-max`) when the work is a precisely specified sequence of steps to execute to the letter; trivial mechanical edits go to your fast code model. Per-role lines in the `/setup-pstack` rule override these defaults and the model choices in the routed skills (`how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`); a role with no line keeps its default, and a role line of `inherit-parent` or `auto` runs that role on the parent chat model (omit Task `model`).
 

diff --git a/pstack/skills/swarm/SKILL.md b/pstack/skills/swarm/SKILL.md
--- a/pstack/skills/swarm/SKILL.md
+++ b/pstack/skills/swarm/SKILL.md
@@ -20,14 +20,14 @@
 ## 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.
+2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race, declare the selection rule up front: first pass, rank all, or best-of.
 3. Set N from the user or derive it from the shape. N is total workers, not the cloud concurrency limit.
 4. Pick the worker model from `swarm workers` in `~/.cursor/rules/pstack-models.mdc` when present. Otherwise use `grok-4.5-fast-xhigh`. For a model race, name each arm's model up front.
 5. 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 workers with `subagent_type: generalPurpose`, `environment: "cloud"`, `run_in_background: true`, and the configured model. Use `environment: "local"` only when the worker needs access to something on the user's computer.
+Spawn all N workers in one message, each with `subagent_type: generalPurpose`, `environment: "cloud"`, `run_in_background: true`, and the configured model. 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`.
 
@@ -37,7 +37,7 @@
 
 ## 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.
+Read the terminal results. For coverage, every required slice needs a result. For a race, apply the selection rule declared in Frame. Do not paste raw worker dumps.
 
 Keep a compact result table, one-line evidenced issues, and explicit gaps or dropouts.

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

^{Reviewed by Cursor Bugbot for commit 866bab6. Configure here.}

[cursor]

Model race uses one shared model

Medium Severity · Logic Bug

Phase A allows specifying distinct models for each arm in a model race, but Phase B instructs the parent to spawn all workers with 'the configured model'. This overrides the per-arm model selection, causing model races to silently run with identical models and defeating the purpose of the race.

 

^{Reviewed by Cursor Bugbot for commit 866bab6. Configure here.}

[cursor]

Cloud workers get local output paths

Medium Severity · Logic Bug

Frame tells writers to isolate via a worktree or /tmp/swarm-... path, while Fan out defaults workers to environment: "cloud". Cloud subagents run in separate VMs and cannot see the parent's local worktrees or /tmp, so those assigned write paths are unreachable under the default spawn path.

 

^{Reviewed by Cursor Bugbot for commit 866bab6. Configure here.}

[cursor]

Worker briefs omit output paths

Medium Severity · Logic Bug

Phase A assigns each worker its own writable output, but the Phase B stand-alone brief checklist never includes that path. Unlike arena, which passes each candidate its output path at spawn time, swarm workers can miss the assigned worktree, branch, or directory and collide when writing, especially under environment: "local".

 

^{Reviewed by Cursor Bugbot for commit 866bab6. Configure here.}