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

- **Type:** Skill
- **Install:** `agentstack add skill-grimoire-rs-grimoire-swarm-plan`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [grimoire-rs](https://agentstack.voostack.com/s/grimoire-rs)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [grimoire-rs](https://github.com/grimoire-rs)
- **Source:** https://github.com/grimoire-rs/grimoire/tree/main/.claude/skills/swarm-plan
- **Website:** https://grimoire.rs

## Install

```sh
agentstack add skill-grimoire-rs-grimoire-swarm-plan
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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** (Grimoire 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 subsystems, read matching
`.claude/rules/subsystem-*.md` context rules — full subsystem → rule
table live in `CLAUDE.md` "Subsystem context".

## 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. `meta-ai-config.md`
"Research Protocol" references this contract.

## 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 (template seeds it; Step `/swarm-plan → plan-approved`) and write `.claude/state/current_plan.md` pointer — schema + mutation table → [`meta-ai-config.md`](../../rules/meta-ai-config.md) "Plan Status Protocol"

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [grimoire-rs](https://github.com/grimoire-rs)
- **Source:** [grimoire-rs/grimoire](https://github.com/grimoire-rs/grimoire)
- **License:** Apache-2.0
- **Homepage:** https://grimoire.rs

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-grimoire-rs-grimoire-swarm-plan
- Seller: https://agentstack.voostack.com/s/grimoire-rs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.