# Swarm Plan > 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. - Skill: `grimoire-rs/swarm-plan` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add grimoire-rs/swarm-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/grimoire-rs/swarm-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: grimoire-rs (https://skillmd.com/u/grimoire-rs) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/grimoire-rs/swarm-plan --- # 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] [--flags] ``` - **tier** (optional): `low | auto | high | max`. Default `auto`. - **target** (one of): free-text prompt; `` or `#` (auto-probe PR then issue); `PR ` / `pull/` (explicit PR); `issue ` / `issues/` (explicit issue); full GitHub URL `https://github.com///(pull|issues)/`. - **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///(pull|issues)/` URL 2. `PR ` / `pull/` / `pulls/` → PR 3. `issue ` / `issues/` → issue 4. `#` or bare integer `` → 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. | 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 `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`](../../rules/plan-status.md) ## Handoff format ```markdown ## 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