grimoire-rs 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].md
Consumers: /swarm-execute (plan artifact); Human (deferred findings).
$ARGUMENTS