swarm-plan
Skill0 starsChanged 4 months agoApache-2.0View on GitHub
Use for feature planning, task decomposition, multi-perspective research, or ADR scaffolding. Tier (`low | auto | high | max`) scales research depth, architect model, and review breadth. Canonical research primitive for AI config / ADR work.
4 other projects use a version of this.
Adopted by
Most recently taken up by
- ZaxbyHub/opencode-swarmtheir own version, first seen Nov 15, 2026
- zaxbysauce/opencode-swarmtheir own version, first seen Oct 8, 2026
- dralgorhythm/claude-agentic-frameworktheir own version, first seen Jul 24, 2026
- MaxGzLi/claudeorctheir own version, first seen Mar 8, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- ZaxbyHub/opencode-swarm★ 531same name
- zaxbysauce/opencode-swarm★ 519same name
- dralgorhythm/claude-agentic-framework★ 118same name
- MaxGzLi/claudeorc★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- finalizeSkill
- swarm-executeSkill
- swarm-reviewSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 5 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 63
Read classify.md. Apply tier signals + overlay triggers to prompt plus any fetched GitHub body/labels.
- Very specific: line 88
Default: EnterPlanMode with meta-plan path.
- Distinctive: line 93
Never sequential prompts. Form IS preview — do not also fire markdown gate.
- Distinctive: line 152
NO tasks without testable acceptance criteria.
- Distinctive: line 153
NO assuming context — Discover run every tier
- Distinctive: line 154
NO skipping Review; NO >8 parallel workers
- Very specific: line 155
NO mid-flow AskUserQuestion during classification — ambiguity always resolve at meta-plan gate
- Very specific: line 157
ALWAYS store artifacts in .claude/artifacts/.
- Distinctive: line 159
ALWAYS include component contracts (with expected behavior and edge cases) and user experience scenarios (with error cases)
- Very specific: line 161
ALWAYS announce final config, even post-approval, hand off to /swarm-execute with explicit next-step
- Very specific: line 163
ALWAYS init plan with ## Status block (Step /swarm-plan → plan-approved) and write .claude/state/current_plan.md pointer — schema + …
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Planning Orchestrator — Tiered
Thin dispatch layer. Phase plans live in sibling tier files
(tier-low.md, tier-high.md, tier-max.md). This file parse args,
classify target (classify.md), resolve overlays (overlays.md),
optional gate on meta-plan approval, then hand off to matching tier
file. Shared content (worker assignment, subsystem context,
constraints, handoff format, research-primitive contract) stay here —
never duplicated across tier files.
Argument syntax
/swarm-plan [tier] <target> [--flags]- tier (optional):
low | auto | high | max. Defaultauto. - target (one of): free-text prompt;
<N>or#<N>(auto-probe PR then issue);PR <N>/pull/<N>(explicit PR);issue <N>/issues/<N>(explicit issue); full GitHub URLhttps://github.com/<owner>/<repo>/(pull|issues)/<N>. - flags (convention: flags before positional):
--architect=inline|sonnet|opus--research=skip|1|3--researcher=haiku|sonnet--codex/--no-codex— force plan-artifact Codex pass on/off--dry-run/--form— meta-plan preview (--formuseAskUserQuestion; imply--dry-run)
Workflow
1. Parse arguments and detect GitHub target
Detect GitHub refs (ordered, first match win):
- Full
https://github.com/<owner>/<repo>/(pull|issues)/<N>URL PR <N>/pull/<N>/pulls/<N>→ PRissue <N>/issues/<N>→ issue#<N>or bare integer<N>→ probe PR first, fall back to issue
Fetch via mcp__github__pull_request_read /
mcp__github__issue_read (preferred); gh pr view / gh issue view
with --json title,body,comments,labels,files as fallback. PRs and
issues equal-class targets — probe order implementation detail.
On fetch fail, treat input as free text (ask via AskUserQuestion
only if disambiguation needed).
2. Classify (only when tier=auto)
Read classify.md. Apply tier signals + overlay triggers to prompt
plus any fetched GitHub body/labels. Produce candidate tier +
confidence flag + overlay set. Labels map direct (e.g.,
breaking-change → --codex). PR file list feed Discover scope (not
classification).
3. Resolve overlays
Final config = tier defaults (overlays.md per-tier table) +
classifier overlays + user flag overrides. User flags always win.
4. Meta-plan gate (single consolidated approval point)
Fire when ANY of: --dry-run, --form, tier resolve to max, or
classification marked low-confidence. Only user-prompt point — no
mid-flow AskUserQuestion during classification.
Write .claude/state/plans/meta-plan_[feature].md with:
Classification (tier + rationale + overlays), GitHub context, Workers
I Would Launch (per phase), Artifacts I Would Produce, Estimated Cost
(parallel worker count, heaviest call, Codex presence), Not Doing
(implementation, PR creation).
Approval UI (always single interaction):
- Default:
EnterPlanModewith meta-plan path; resume on approve. If skill resume afterExitPlanModeunreliable in practice, fall back toAskUserQuestionwith Approve / Edit / Cancel options. --form: ONEAskUserQuestioncall with ≤4 batched axis questions (Tier / Architect / Research / Codex), first option "Recommended". Never sequential prompts. Form IS preview — do not also fire markdown gate.
On reject: re-draft meta-plan with rejection rationale (free-text or explicit axis answers), re-present once.
5. Announce final config (always)
Print before loading tier file:
Swarm plan
Tier: high (auto)
Overlays: architect=opus (signal: new trait hierarchy)
Workers: 3 explorers, 1 researcher, 1 architect (opus), 1 reviewer
Artifacts: plan_[feature].md, research_[topic].md, adr_[decision].md
Codex plan review: off
Proceed? (Ctrl+C to abort; re-run with explicit tier to override)6. Dispatch to tier file
Read matching tier-{low,high,max}.md, execute its phase plan. No
phase content duplicated here.
Worker assignment (shared across tiers)
See workflow-swarm.md for worker types, models, tools, focus modes.
| Phase | Worker | Count | Role |
| Discover | worker-architecture-explorer | 0–1 | Current-state mapping |
| Discover | worker-explorer | 1–4 | Subsystem deep-dive |
| Research | worker-researcher | 0–3 | Technology landscape |
| Design (complex) | worker-architect | 0–1 | ADR / system design |
| Review | worker-reviewer (spec-compliance) | 1 | Plan consistency |
| Review (One-Way Door) | worker-architect | 0–1 | Trade-off honesty |
| Review | worker-researcher | 0–1 | SOTA gap check |
| Cross-model | codex-adversary (plan-artifact) | 0–1 | Cross-family review |
Max concurrent workers: 8 (per workflow-swarm.md).
Subsystem context rules (shared)
Identify involved modules, read the Architecture section of
CLAUDE.md for the involved areas.
Research as a Reusable Primitive
Discover + Research phases = canonical multi-agent research pattern
for project. Reused by /architect, /meta-maintain-config
(create/research modes), /swarm-plan. Consumers SHOULD: launch
workers in parallel; split researchers by axis (tech / patterns /
domain) when research non-trivial; persist substantial findings as
research_[topic].md; pair at least one explorer with researchers to
ground external findings in local code.
Constraints
- NO tasks without testable acceptance criteria; NO vague behaviors
- NO assuming context — Discover run every tier
- NO skipping Review; NO >8 parallel workers
- NO mid-flow
AskUserQuestionduring classification — ambiguity always resolve at meta-plan gate - ALWAYS store artifacts in
.claude/artifacts/; ALWAYS persist substantial research asresearch_[topic].md - ALWAYS include component contracts (with expected behavior and edge cases) and user experience scenarios (with error cases)
- ALWAYS announce final config, even post-approval, hand off to
/swarm-executewith explicit next-step - ALWAYS init plan with
## Statusblock (Step/swarm-plan → plan-approved) and write.claude/state/current_plan.mdpointer — schema + mutation table →plan-status.md
Handoff format
## Plan Complete: [Feature or "Resolves #N"]
### Classification
- **Scope**: Small | Medium | Large
- **Reversibility**: Two-Way | One-Way Medium | One-Way High
- **Tier**: low | high | max
- **Overlays**: architect=X, research=Y, codex=Z
### Artifacts
- `.claude/state/plans/plan_[feature].md` (with `## Status` block initialized)
- `.claude/state/current_plan.md` (pointer)
- `.claude/artifacts/research_[topic].md`
- `.claude/artifacts/adr_[decision].md` (One-Way Door High)
### Executable Phases (for /swarm-execute)
- **Stub**: components to create with `throw new Error('unimplemented')`
- **Specify**: tests to write from the design record
- **Implement**: stub bodies to fill
- **Review**: perspectives to run
### Deferred Findings (require human judgment)
- Claude panel: ...
- Codex plan review: ...
### Next Step
/swarm-execute .claude/state/plans/plan_[feature].mdConsumers: /swarm-execute (plan artifact); Human (deferred findings).
$ARGUMENTS
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

