Swarm Execute

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]  [--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:

1. Path ending .md (typically under .claude/state/plans/) → plan-artifact mode
2. 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](../../rules/workflow-swarm.md#review-fix-loop). 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 (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: 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](../../rules/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

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
• Source: grimoire-rs/grimoire
• License: Apache-2.0
• Homepage: https://grimoire.rs

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