Swarm execute

Skill grimoire-rs/grimoire/.claude/skills/swarm-execute

Package manager for AI-agent config. grim installs, updates, and publishes skills, rules, agents, MCP servers, and bundles into Claude Code, Copilot, Cursor, Codex, Gemini, Zed, Amp, Kiro, Junie, and opencode — pinned by digest in a lockfile. Storage is any OCI registry; there is no service to run.

Install

npx -y skills add grimoire-rs/grimoire --skill swarm-execute

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use to implement a plan artifact from `/swarm-plan`, or a free-text implementation task with contract-first TDD + Review-Fix Loop. Tier (`low | auto | high | max`) scales builder model, loop rounds, review breadth, and Codex code-diff gate.

SKILL.md

7.9 KB, as published. Nobody here has run it

Execution Orchestrator — Tiered

Thin dispatch layer. Phase plans 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, hand off to matching tier file. Shared content (worker table, loop design principles, constraints, handoff) stay here — phase-by-phase execution in tier files.

Argument syntax

/swarm-execute [tier] <plan-artifact-or-task> [--flags]

tier (optional): low | auto | high | max. Default auto.
target (one of): plan artifact path (.claude/state/plans/plan_*.md); free-text task description.
flags (Grimoire convention: flags before positional):
- --builder=sonnet|opus
- --tester=sonnet|opus
- --reviewer=haiku|sonnet|opus
- --doc-reviewer=haiku|sonnet
- --loop-rounds=1|2|3
- --review=minimal|full|adversarial
- --codex / --no-codex
- --dry-run / --form — meta-plan preview (--form use AskUserQuestion; imply --dry-run)

Workflow

1. Parse arguments and detect plan artifact

Detect target type:

Path ending .md (typically under .claude/state/plans/) → plan-artifact mode
Else → free-text mode

When plan present, read and parse handoff block for Tier, Scope, Reversibility, Overlays; parse phase definitions; extract "Subsystems Touched" from plan body.

2. Classify (only when tier=`auto`)

Read classify.md. Apply plan-header signals first (primary); fall back to free-text signals (pointer to /swarm-plan's classify.md when no plan artifact) only for axes plan header miss. Produce candidate tier + confidence flag + overlay set.

3. Resolve overlays

Final config = tier defaults (overlays.md per-tier table) + classifier overlays + user flag overrides. User flags always win (except tier=max's mandatory --builder=opus).

4. Meta-plan gate (single consolidated approval point)

Fire when ANY of: --dry-run, --form, tier resolved to max, or classification marked low-confidence. Only user-prompt point — no mid-flow AskUserQuestion during classification.

Write .claude/state/plans/meta-plan_execute_[feature].md with: Classification (tier + rationale + plan-header source), Overlays (+ rationale), Workers per phase, loop-rounds budget, Estimated cost, Whether Codex fires, Not Doing (push, 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 / Builder / Loop-rounds / Codex), first option "Recommended".

On reject: re-draft meta-plan with rejection rationale and re-present once.

5. Announce final config (always)

Print before loading tier file:

Swarm execute
  Tier:        high                                (from plan header)
  Target:      .claude/state/plans/plan_foo.md
  Overlays:    builder=sonnet, loop-rounds=3       (tier default)
               codex=on                            (signal: plan Reversibility=One-Way Door Medium)
  Workers:     stub/impl sonnet, 1 arch reviewer,
               3 review rounds (full breadth)
  Codex diff review: on (after loop converges)
  Proceed? (Ctrl+C to abort; re-run with explicit tier to override)

6. Dispatch to tier file

Read matching tier-{low,high,max}.md and execute its phase plan. No phase content duplicated here.

Review-Fix Loop

Protocol: see canonical Review-Fix Loop in workflow-swarm.md. Protocol auto-load for swarm-skill contexts via workflow-swarm.md path-scoping. Per-tier loop config (rounds, perspectives) set in each tier file.

Cross-Model Adversarial Pass — shared protocol

See overlays.md "codex axis" for when fires per tier. Use codex-adversary skill with scope code-diff against branch diff after Claude loop converges.

Preconditions: loop exited, task verify green, working tree clean except intended diff.
Invocation: delegate to codex-adversary with --scope code-diff --base main --model <tier model> (high→terra, max→sol; --codex-model=luna|terra|sol overrides — see overlays.md). Codex load AGENTS.md automatically — do not inject project context.
Triage: Actionable → one-shot worker-builder fix pass, gate task verify. Deferred → summary. Stated-convention / trivia → dropped with count.
One-shot only: never re-enter Review-Fix Loop — prevent two-family thrash. If one-shot fix fails task verify, revert and promote findings to deferred.
Unavailable path: CLAUDE_PLUGIN_ROOT unset / companion non-zero / empty output → log Cross-model gate skipped: <reason> and continue. Gate, not blocker (at tier=max, surface skip prominently).

Worker assignment (shared across tiers)

See .claude/rules/workflow-swarm.md for worker types, models, tools, focus modes.

Phase	Worker	Model
Stub	`worker-builder` (focus: `stubbing`)	sonnet / opus
Verify arch (high/max)	`worker-reviewer` (focus: `spec-compliance`, phase: `post-stub`)	sonnet
Verify arch (max)	`worker-architect`	opus
Specify	`worker-tester` (focus: `specification`)	sonnet
Implement	`worker-builder` (focus: `implementation`)	sonnet / opus
Review Stage 1	`worker-reviewer` (spec-compliance + test-coverage)	sonnet
Review Stage 2	`worker-reviewer` / `worker-doc-reviewer` / `worker-architect` / `worker-researcher`	per role
Cross-model	`codex-adversary` (code-diff)	—

Max concurrent workers: 8 (per workflow-swarm.md).

Quality Gates & Git Protocol

task --list to discover workflows; task verify is final gate (subsystem verify runs during review loop)
Stage and commit with conventional commit message; never push
Use task checkpoint for work-in-progress saves

Living Design Records

Plan artifacts = living documents. When implementation reveal behavior or edge case not in design record: update plan artifact first, write corresponding test, then implement.

Plan Status block (mutate on phase entry + advance)

Mutate the ## Status block in the plan referenced by .claude/state/current_plan.md: flip Step on phase entry / Stub→Specify→Implement→Review-Fix transitions; increment Active phase on plan-phase advance; set Step: awaiting /swarm-review when the final phase completes (don't clear current_plan.md — /finalize does that). Skip silently when no current_plan.md / no Status block. Full mutation table → meta-ai-config.md "Plan Status Protocol".

Constraints

NO completing tasks without passing quality gates
NO leaving work uncommitted locally
NO exceeding 8 parallel workers
NO pushing to remote
NO running stub and test phases concurrently (sequential only)
NO mid-flow AskUserQuestion during classification — ambiguity resolve at meta-plan gate
ALWAYS report blockers immediately
ALWAYS validate git status shows clean before commit
ALWAYS update design record before adding tests for unspecified behaviors

Handoff

To /swarm-review: after implementation complete, for adversarial review
To /qa-engineer: for acceptance testing

Next Step — copy-paste to continue:

/swarm-review

$ARGUMENTS