| name | swarm-execute |
| description | 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. |
| user-invocable | true |
| disable-model-invocation | false |
| argument-hint | [tier] <plan-artifact-or-task> [--flags] |
| triggers | ["execute this plan","execute the plan","implement this plan","implement the plan","run the plan"] |
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 (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
loads repo context (AGENTS.md when present) 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 → plan-status.md.
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
