Plan Swarm

Languages: English · 中文 · 日本語 · 한국어 · العربية · Русский · Deutsch · Français · Español · Italiano · Português · Nederlands · Polski · Čeština · Slovenčina · Slovenščina · Magyar · Română · Български · Hrvatski · Ελληνικά · Dansk · Svenska · Suomi · Eesti · Latviešu · Lietuvių · Gaeilge · Malti · all translations

Agent skill: recursively decompose a repository goal into mechanically gated leaves, then run dependency-safe subagent waves, integrate, and verify the whole result.

Works with any Agent Skills–compatible host (Claude Code, Codex, Cursor, Kimi Code, Grok Build, OpenCode, …). Install via npx skills; discover on skills.sh.

Why this exists

“Make a plan and implement it with subagents” usually fails in predictable ways:

• leaves are vague (“fix auth”) with no acceptance
• workers edit overlapping files
• the plan lives only in chat and cannot be resumed
• success is declared from worker self-reports

Plan Swarm forces a different contract:

1. Structural plan — every write leaf has exact files, deps, acceptance, rollback
2. External gate — plan_swarm_check.py refuses unsafe plans (exit 2)
3. Bounded waves — root owns the artifact; workers get a narrow write set
4. Fresh verifier — goal-level proof is not a worker claim

goal → recursive PLAN → PROBE → IMPLEMENT waves → INTEGRATE → VERIFY → DONE
         │                    │
         └── json plan-swarm  └── stdlib validator + --ready batches

Install

npx skills add alexio777/plan-swarm

Specific / global / list:

npx skills add alexio777/plan-swarm --skill plan-swarm
npx skills add alexio777/plan-swarm -g
npx skills add alexio777/plan-swarm --list
npx skills use alexio777/plan-swarm@plan-swarm

From a clone:

git clone https://github.com/alexio777/plan-swarm.git
npx skills add ./plan-swarm -g -y

Prerequisites

No API keys. No herdr. No monorepo runtime.

Quick start

In an agent session on a real repo:

/plan-swarm Add a healthcheck endpoint with a unit test

Or plan only:

/plan-swarm --plan-only Ship a feature flag for the new checkout path

The agent writes plan-swarm-<slug>.md with one fenced json plan-swarm block, then:

python3 ~/.agents/skills/plan-swarm/scripts/plan_swarm_check.py --check plan-swarm-<slug>.md
python3 ~/.agents/skills/plan-swarm/scripts/plan_swarm_check.py --ready plan-swarm-<slug>.md --workers 3

Flags

Safety (non-negotiable)

• No globs in write_files — exact repo-relative paths only
• Root owns the artifact, Git, integration, and final verdict
• Workers must not run git, spawn agents, or edit outside their write set
• plan-swarm does not authorize commit / push / PR / merge / deploy
• Partial progress is BLOCKED or incomplete phase — never fake DONE

Package layout

skills/plan-swarm/
  SKILL.md                 # agent contract (portable)
  scripts/
    plan_swarm_check.py    # --check | --resume-check | --ready
  references/
    manifest.md            # JSON shape
    phases.md              # phase machine + scheduling
tests/test_plan_swarm.py   # offline validator contracts
examples/                  # sample artifacts (not installed as skills)

Offline checks

python3 skills/plan-swarm/scripts/plan_swarm_check.py --help
python3 -m pytest -q tests/test_plan_swarm.py

CI runs skill-shape validation + the pytest suite (no network, no model calls).

Relation to private monorepos

This repository is the public install surface for skills.sh / npx skills.
Private monorepos may keep ports or wrappers; they are not the install target.

License

MIT — see LICENSE.