agentleFS
grimoire-rsgrimoire-rs/grimoire-vscode/.claude/skills/swarm-plan/SKILL.md

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

  • Other versions4 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 4

    1. ZaxbyHub/opencode-swarm★ 531same name
    2. zaxbysauce/opencode-swarm★ 519same name
    3. dralgorhythm/claude-agentic-framework★ 118same name
    4. 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.

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
  1. Very specific:

    Read classify.md. Apply tier signals + overlay triggers to prompt plus any fetched GitHub body/labels.

    line 63
  2. Very specific:

    Default: EnterPlanMode with meta-plan path.

    line 88
  3. Distinctive:

    Never sequential prompts. Form IS preview — do not also fire markdown gate.

    line 93
  4. Distinctive:

    NO tasks without testable acceptance criteria.

    line 152
  5. Distinctive:

    NO assuming context — Discover run every tier

    line 153
  6. Distinctive:

    NO skipping Review; NO >8 parallel workers

    line 154
  7. Very specific:

    NO mid-flow AskUserQuestion during classification — ambiguity always resolve at meta-plan gate

    line 155
  8. Very specific:

    ALWAYS store artifacts in .claude/artifacts/.

    line 157
  9. Distinctive:

    ALWAYS include component contracts (with expected behavior and edge cases) and user experience scenarios (with error cases)

    line 159
  10. Very specific:

    ALWAYS announce final config, even post-approval, hand off to /swarm-execute with explicit next-step

    line 161
  11. Very specific:

    ALWAYS init plan with ## Status block (Step /swarm-plan → plan-approved) and write .claude/state/current_plan.md pointer — schema + …

    line 163

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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. Default auto.
  • 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 URL https://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 (--form use AskUserQuestion; imply --dry-run)

Workflow

1. Parse arguments and detect GitHub target

Detect GitHub refs (ordered, first match win):

  1. Full https://github.com/<owner>/<repo>/(pull|issues)/<N> URL
  2. PR <N> / pull/<N> / pulls/<N> → PR
  3. issue <N> / issues/<N> → issue
  4. #<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: EnterPlanMode with meta-plan path; resume on approve. If skill resume after ExitPlanMode unreliable in practice, fall back to AskUserQuestion with Approve / Edit / Cancel options.
  • --form: ONE AskUserQuestion call 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.

PhaseWorkerCountRole
Discoverworker-architecture-explorer0–1Current-state mapping
Discoverworker-explorer1–4Subsystem deep-dive
Researchworker-researcher0–3Technology landscape
Design (complex)worker-architect0–1ADR / system design
Reviewworker-reviewer (spec-compliance)1Plan consistency
Review (One-Way Door)worker-architect0–1Trade-off honesty
Reviewworker-researcher0–1SOTA gap check
Cross-modelcodex-adversary (plan-artifact)0–1Cross-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 AskUserQuestion during classification — ambiguity always resolve at meta-plan gate
  • ALWAYS store artifacts in .claude/artifacts/; ALWAYS persist substantial research as research_[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-execute with explicit next-step
  • ALWAYS init plan with ## Status block (Step /swarm-plan → plan-approved) and write .claude/state/current_plan.md pointer — 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].md

Consumers: /swarm-execute (plan artifact); Human (deferred findings).

$ARGUMENTS

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.