Plan Swarm

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

/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.

1. Choose a durable artifact path (plan-swarm-.md at repo root, or an

existing plans directory). Do not overwrite an unrelated file.

1. 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.

1. Resolve the validator next to this skill:

# 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:

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:

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

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):

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:

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
• Source: alexio777/plan-swarm
• License: MIT

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