# Plan Swarm

> >

- **Type:** Skill
- **Install:** `agentstack add skill-alexio777-plan-swarm-plan-swarm`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [alexio777](https://agentstack.voostack.com/s/alexio777)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [alexio777](https://github.com/alexio777)
- **Source:** https://github.com/alexio777/plan-swarm/tree/main/skills/plan-swarm

## Install

```sh
agentstack add skill-alexio777-plan-swarm-plan-swarm
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Plan Swarm

Turn one goal into a **mechanically checked recursive plan**, then execute it.
The root agent owns the plan, shared workspace, integration, Git, and final
verdict. Workers own only bounded leaves.

This is **not** a plan-only handoff skill (those produce a prompt file and stop).
Plan-swarm plans with the current agent and continues into implementation unless
`--plan-only` is set.

## 1. Parse the invocation

```text
/plan-swarm [--plan-only] [--resume PATH]
            [--max-depth N] [--max-leaves N] [--repair-rounds N] 
```

Defaults: `max-depth=4`, `max-leaves=24`, `repair-rounds=2`. Default mode is
end-to-end execution. Cap concurrency at the host's available subagent slots
minus the root, at most **three** workers. Bounds are safety limits, not targets.

`--resume` makes the artifact's original goal authoritative. Reject a conflicting
new goal. Reconcile every stale `RUNNING` node against the real workspace and
evidence before scheduling.

## 2. Establish the safe baseline

1. Read repository instructions; inspect real code, tests, and existing behavior.
2. Inspect `git status --short`, `git diff --name-only`, and worktrees. Existing
   dirty files belong to the user — record the baseline; never assign an overlapping
   dirty file to a worker.
3. Choose a durable artifact path (`plan-swarm-.md` at repo root, or an
   existing plans directory). Do not overwrite an unrelated file.
4. Write exactly one fenced `json plan-swarm` manifest in the Markdown artifact.
   The manifest is the only mutable source of truth for phase/node state.
5. Resolve the validator next to this skill:

```bash
# from this package (clone)
python3 skills/plan-swarm/scripts/plan_swarm_check.py --check 

# after npx skills install (typical)
python3 ~/.agents/skills/plan-swarm/scripts/plan_swarm_check.py --check 
```

Also works as `~/.claude/skills/plan-swarm/scripts/…` when that tree is used.

## 3. Build the recursive plan

Phases, in order:

```text
PLAN -> PROBE -> IMPLEMENT -> INTEGRATE -> VERIFY -> DONE
```

Create one root `group`. Recursively split every broad child. A node is an
implementation leaf only when **all** of these are explicit:

- one owner
- concrete inputs and outputs
- exact repository-relative file paths (no globs, no directory ownership)
- dependencies by node ID
- acceptance command/observable + what success means
- rollback boundary
- `decisions_resolved: true`

If a node fails the leaf gate, split it. If that would exceed `max_depth` or
`max_leaves`, stop and ask whether to raise a bound or narrow the goal.

Unknown facts become `probe` leaves: one question, evidence target, `read_only:
true`, no write files. Complete probes first, revise dependents, re-validate.

Manifest shape and field rules: [references/manifest.md](references/manifest.md).

After every write/change to the manifest:

```bash
python3 /scripts/plan_swarm_check.py --check 
```

Exit `2` = not safe to schedule. Fix structural errors; never waive the gate in prose.

## 4. Execute probes and implementation waves

```bash
python3 /scripts/plan_swarm_check.py --ready  --workers 3
```

Before each wave, re-snapshot changed files. Launch only returned nodes whose
write files are clean vs the user baseline. Probes are read-only. Implementation
workers may run concurrently **only** with disjoint write sets.

Worker contract (give each worker only what it needs):

```text
Implement leaf : .
Allowed writes: .
Inputs: . Required outputs: .
Dependencies already established: .
Acceptance:  — .
Rollback boundary: .
Do not edit other files. Do not run git commands. Do not spawn or delegate.
Preserve pre-existing user changes. Return: outcome; files touched; checks;
assumptions; blockers.
```

Workers never update the artifact. The root alone waits for the wave, diffs
ownership, rejects undeclared writes / overlap, runs leaf acceptance, records
evidence, repairs within bounds, checkpoints the manifest, and journals the wave.

**Publication is not authorized by plan-swarm.** Scoped workspace edits and tests
yes; commit/push/PR/merge/deploy only if the user separately authorizes them.

## 5. Integrate and verify

After all implementation leaves are `DONE`, run root-owned `integration` nodes
serially with the same evidence rules.

Then run repository-level acceptance from the manifest. Spawn one **fresh
read-only verifier** with only: original goal, artifact, workspace, check
permission. It maps every requested outcome to observed evidence; it cannot edit,
delegate, or trust worker self-reports.

Turn gaps into bounded repair leaves under `repair_rounds`. Advance to `DONE`
only when every non-group node is evidence-backed `DONE`, a verification node
passed, `final_evidence` matches successful repo acceptance, the fresh verifier
finds no goal-level gap, and:

```bash
python3 /scripts/plan_swarm_check.py --check 
```

## 6. Deliver

Report: artifact path, waves and leaf IDs, files changed, checks, verifier
verdict, blocked nodes. Distinguish workspace completion from publish actions.

## Safety summary

| Rule | Why |
|------|-----|
| Structural gate before schedule | Bad plans must not spawn workers |
| Exact write_files, no globs | Conflict waves stay auditable |
| Root owns Git and artifact | Workers cannot rewrite the plan |
| Diff baseline every wave | Silent cross-leaf edits are rejected |
| Fresh verifier at the end | Worker reports are not the verdict |
| Bounds are hard | Honesty over fake completeness |

See also: [references/phases.md](references/phases.md) for phase/state machine detail.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [alexio777](https://github.com/alexio777)
- **Source:** [alexio777/plan-swarm](https://github.com/alexio777/plan-swarm)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-alexio777-plan-swarm-plan-swarm
- Seller: https://agentstack.voostack.com/s/alexio777
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.