From agentops
Executes epics autonomously through orchestrated waves, using /swarm for parallel slice implementation with runtime-native spawning and hard wave-validity gates.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agentops:crankThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Quick Ref:** Autonomous epic execution. `/swarm` for each wave with runtime-native spawning. Output: closed issues + phase-2 handoff for `/validate`.
references/best-practices.mdreferences/branch-isolation.mdreferences/claude-code-latest-features.mdreferences/commit-strategies.mdreferences/contract-template.mdreferences/crank.featurereferences/de-sloppify.mdreferences/execution-preflight.mdreferences/external-gate-protocol.mdreferences/failure-recovery.mdreferences/failure-taxonomy.mdreferences/fire.mdreferences/gc-pool-dispatch.mdreferences/isolation-contract.mdreferences/parallel-wave-isolation.mdreferences/phase-data-contracts.mdreferences/plan-mutations.mdreferences/ralph-loop-contract.mdreferences/shared-task-notes.mdreferences/ship-loop-anti-patterns.mdQuick Ref: Autonomous epic execution.
/swarmfor each wave with runtime-native spawning. Output: closed issues + phase-2 handoff for/validate.
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Move 5 (wave execution) of the operating loop. Consumes the slice validation plan; produces wave-by-wave slice completion via /swarm + /implement. Hard gate at wave start: every row of the wave-validity check must pass (distinct write scopes, no shared migration/contract/CLI surface, declared integration order, owner per slice, discard path per slice). Any failed row → run those slices sequential, not parallel. Coupled-chain rule: two slices that both regenerate a shared derived surface (cli-command-surface / registry.json / context-map / codex manifest) collide even with disjoint source files — run them as a sequential chain, each link branched off the freshly-MERGED prior link. Parallelism is explicit ownership, not swarm chaos.
Autonomous execution: implement all issues until the epic is DONE.
Feed the orchestrator's re-plan loop — don't swallow findings into a silent retry. When run under /rpi, surface what a wave proved or broke UP to the orchestrator. A failed or surprising wave is re-plan input, not just a retry target: per the /rpi Agile Re-Plan Loop, the remaining waves may be refactored, inserted, dropped, or reordered before the next one runs. Re-cranking the same objective forever instead of letting the remaining plan change is the waterfall anti-pattern.
CLI dependencies: bd (issue tracking), ao (knowledge flywheel). Both optional — see skills/shared/SKILL.md for fallback table. If bd is unavailable, use TaskList for issue tracking and skip beads sync. If ao is unavailable, skip knowledge injection/extraction.
For Claude runtime feature coverage (agents/hooks/worktree/settings), the shared source of truth is skills/shared/references/claude-code-latest-features.md, mirrored locally at references/claude-code-latest-features.md.
Crank owns orchestration, epic/task lifecycle, and knowledge-flywheel steps. Swarm owns runtime-native worker spawning, fresh-context isolation, per-wave execution, and cleanup. In beads mode Crank gets each wave from bd ready, bridges issues into worker tasks, verifies results, and syncs status back to beads. In TaskList mode the same loop runs over pending unblocked tasks instead of beads issues.
Read references/team-coordination.md for the full per-wave execution model, references/ralph-loop-contract.md for the fresh-context worker contract, and references/worker-specs.md for per-worker model/tool/prompt specs.
| Flag | Default | Description |
|---|---|---|
--test-first | off | Enable spec-first TDD: SPEC WAVE generates contracts, TEST WAVE generates failing tests, IMPL WAVES make tests pass |
--per-task-commits | off | Opt-in per-task commit strategy. Falls back to wave-batch when file boundaries overlap. See references/commit-strategies.md. |
--tier=<name> | (auto) | Force a specific cost tier (quality/balanced/budget) for all council calls. Overrides effort-to-tier auto-mapping. |
--no-lifecycle | off | Skip ALL lifecycle skill auto-invocations (test delegation in TEST WAVE, pre-validation deps/test checks) |
--lifecycle=<tier> | matches complexity | Controls which lifecycle skills fire: minimal (test only), standard (+deps vuln), full (all) |
--no-scope-check | off | Skip scope-completion check before DONE marker (Step 8.7) |
--skip-audit | off | Skip bd-audit pre-flight gate (Step 3a.2) |
MAX_EPIC_WAVES = 50 (hard limit across entire epic)
This prevents infinite loops on circular dependencies or cascading failures. Typical epics use 5–10 waves max.
Not done until you emit an explicit completion marker after each wave:
<promise>DONE</promise> when the epic is truly complete<promise>BLOCKED</promise> when progress cannot continue<promise>PARTIAL</promise> when work remainsNever claim completion without one of these markers.
When a task fails during wave execution, classify as RETRY (transient — re-add with adjustment, max 2), DECOMPOSE (too complex — split into sub-issues, terminal), or PRUNE (blocked — escalate immediately). Budget: 2 per task. Read references/failure-recovery.md for classification signals and recovery commands.
Mutation logging on failure classification:
task_removed for the original task, then task_added for each new sub-task.task_removed with the block reason.Given /crank [epic-id | .agents/rpi/execution-packet.json | plan-file.md | "description"]:
Read references/execution-preflight.md when you need recovery-hook setup, effort/tier mapping, knowledge-context loading (Step 0), tracking-mode detection (0.5), gc-pool detection (0.6), epic identification (Step 1), branch isolation (1.5), wave-counter / mutation-trail / shared-task-notes initialization (1a–1a.2), test-first classification (1b), epic details (Step 2), ready-issue listing (Step 3), and the four pre-flight checks (3a, 3a.1 pre-mortem, 3a.2 bd-audit, 3a.3 changed-string grep).
The Branch Isolation Gate (Step 1.5) has its own dedicated contract — see references/branch-isolation.md for when crank must create or refuse an isolation branch.
Read references/wave-dispatch.md when you need SPEC WAVE / TEST WAVE / RED Gate flow (Steps 3b–3c), context-briefing assembly (3b.1), shared-notes injection (3b.2), parallel-wave isolation (3b.3), or Step 4 wave execution detail — GREEN mode, issue-typing + file manifests, grep-for-existing-functions, validation metadata policy, acceptance-criteria injection, language-standards injection, file-ownership table, wave-counter / 50-cap gate, spec-consistency gate, cross-cutting constraint injection, gc-pool dispatch, and cross-cutting validation.
Read references/wave-completion.md when you need verify-and-sync (Step 5, external-gate protocol), wave acceptance check + CI-policy parity gate (5.5), wave checkpoint + per-criterion verdicts + back-compat fallback (5.7), validation-context checkpoint (5.7b), shared-task-notes harvest (5.7c), plan-mutation logging (5.7d), wave status report (5.8), worktree base-SHA refresh (5.9), check-for-more-work loop (Step 6), de-sloppify pass (6.5), pre-validation lifecycle checks (6.9), final batched validation (Step 7), phase-2 summary (Step 8), learnings extraction (8.5), shared-notes archive (8.6), and the scope-completion pre-close gate (8.7).
Step 5.5 includes the CI-Policy Parity Gate: if a wave diff touches .github/workflows/*.yml, run bash scripts/validate-ci-policy-parity.sh; any non-zero exit fails wave acceptance and surfaces the generated drift report. See references/wave-patterns.md "CI-Policy Parity Gate" for the worked example and trigger pattern.
Tell the user:
/validate to complete closeout and promote learningsOutput completion marker:
<promise>DONE</promise>
Epic: <epic-id>
Issues completed: N
Iterations: M/50
Flywheel: <status from ao metrics flywheel status>
If stopped early:
<promise>BLOCKED</promise>
Reason: <global limit reached | unresolvable blockers>
Issues remaining: N
Iterations: M/50
When crank drives PRs to main itself (orchestrator-merge model), reconcile each PR mechanically:
gh pr checks <pr> until all checks are terminal.claude-review on a usage-limit message is non-blocking; only substantive non-claude-review failures block the merge.correctness (ubuntu-latest) tar-cache-restore exit-2 → gh run rerun once, then believe. registry.json / derived-surface or contracts-sync drift from another PR → make regen-all (scoped via --skills when only some skills changed), commit, push./pre-land-refuters: all refuters CONFIRMED; the pawl's diversity floor met — fresh-context by default (≥1 refuter in a context other than the author's; model-agnostic), or multi-model opt-in (≥2 distinct canonical model families) where the pawl is opted up; real non-empty reviewer evidence, head_sha == the PR's live head) tied to this bead+PR must exist, or the merge is refused (HOLD). REFUTED → AUTO-REDO: the loop re-works the findings and re-gates on its own, no human. A human is escalated to only when a tunable circuit breaker trips (max-attempts / time budget / cost-quota / oscillation), at which point the disposition is ESCALATE/HOLD and the door stays closed (never auto-land on a breaker trip) — see pawls.md "Escalation — the circuit-breaker model". Then gh pr merge --squash --admin.bd close a child bead ONLY after gh pr view <pr> --json state -q .state returns MERGED — never on a log line or batch bd --json query (those flake to null/0).MERGED — re-query gh pr view --json state per child first. One non-merged child aborts the close. (Post-mortem governance checkpoint: this is a hard gate, not advisory.)Enforce steps 4–6 with the committed scripts, not by hand:
scripts/reconcile-pr.sh <pr> <bead> [--epic <epic>](polls checks, reruns the lone correctness-ubuntu flake once, verifies a CONFIRMED, evidence-bound, commit-current pawl verdict (fresh-context default; multi-model opt-in) viascripts/pawl-verdict.sh check <bead> <pr> --head <live-sha>— exit 5/HOLD with no merge if absent/REFUTED/ESCALATE/diversity-floor-unmet/empty-or-stale-head/no-evidence/schema-invalid; also blocks exit 2 on still-PENDING CI (green is strictly necessary), merges--squash --admin, closes the bead only on confirmedMERGED) andscripts/check-epic-children-closed.sh <epic>(the no-epic-close-with-open-child gate). Both are hermetic-tested undertests/scripts/.
Crank repeats FIRE (Find → Ignite → Reap → Vibe → Escalate) for each wave until all issues are CLOSED (beads) or all tasks are completed (TaskList). Read references/wave-patterns.md for the loop model, parallel wave rules, and acceptance check details.
bd first, TaskList fallback) and use the provided epic or plan input directly./swarm for every wave, preserve fresh per-issue context, and refuse to continue past unresolved conflicts or the 50-wave cap.references/wave-patterns.md ("Wave Acceptance Check") — no skill invocations, no cross-family panel, no context explosion. Fix CRITICAL findings before advancing and keep looping until every issue/task is done. The heavy validation (full council, /validate --mixed, /pre-land-refuters) is reserved for the bead-acceptance / merge-to-main pawl — the Final Batched Validation (Step 7) and downstream /validate closeout, NOT per intermediate wave.DONE, BLOCKED, or PARTIAL.burndown + ship-loop route hereburndown → bounded epic mode. Use when you need to drive a finite epic set to all-merged,
then stop — finishing a specific list of tasks, burning down a backlog epic, or executing a
bounded set of beads until done. Crank's per-wave loop with a fixed input set (epic-id or bead
list) and the epic-close gate IS the burndown: no new-work discovery, terminate on all-closed.ship-loop → single-bead fast lane. Use when running the fast-lane internal ship cycle for
one closable bead or small slice: claim, test, implement, push, merge, close. That is a one-issue,
one-wave crank — the Orchestrator-Merge + Reconcile Loop above (confirmed-MERGED before close)
owns the merge/close half.Read references/worker-verb-disambiguation.md for the verb clarification table. Ambiguous verbs (extract, remove, update, consolidate) cause workers to implement wrong operations — always use explicit instructions with wc -l assertions.
User says: /crank ag-m0r — Beads epic: loads learnings, swarm per wave, loops until all closed, final validation.
User says: /crank .agents/plans/auth-refactor.md — Plan file: decomposes into tasks, swarm per wave, final validation.
User says: /crank --test-first ag-xj9 — SPEC → TEST → RED Gate → GREEN IMPL. See references/test-first-mode.md.
Common failure modes: no ready issues, repeated wave gate failures, missing files from workers, bad RED-gate output, or TaskList/beads mismatches. See references/troubleshooting.md for fixes and command-level recovery steps.
Most /crank steps delegate worker execution via /swarm or Skill(). A small number of steps are orchestrator-owned by design — these are inline gates, scans, and bookkeeping that must stay in the orchestrator's context to make a downstream decision. Orchestrator-owned steps are marked with a *(orchestrator-owned: …)* admonition in the body (see STEP 3a.3, STEP 6.5 slop-scan, STEP 8.7).
Do NOT convert orchestrator-owned steps into Skill() or /swarm delegations — they are intentionally inline. Every other step (SPEC wave, TEST wave, IMPL wave, validation, lifecycle checks) should delegate via the documented Skill(...) call or /swarm invocation.
If unsure whether a step is orchestrator-owned or delegatable, the default is delegate. Only steps marked with the admonition above are exempt.
Crank runs as an isolated phase-2 execution context — discovery and validation are sealed off from this skill. See references/isolation-contract.md for the four-lever enforcement model and the compression patterns scripts/check-skill-isolation.sh flags. See references/best-practices.md for the lifecycle principle + anti-pattern citation table (cite by number; do not duplicate body content).
/using-atm — out-of-session ATM substrate for long-running /crank waves over a bead queue.references/crank.feature — Executable spec: wave-validity hard gate, FIRE loop, mandatory completion marker, 50-wave cap (soc-qk4b.2)
references/phase-data-contracts.md — phase artifact data contracts (cited from references/isolation-contract.md)
references/ship-loop-anti-patterns.md — absorbed ship-loop anti-pattern catalog (ag-s43tg)
npx claudepluginhub boshu2/agentops --plugin agentopsCoordinates feature delivery from epic to PR using a 4-phase execution model with 6-tier prompt hierarchy and paired-team fan-out. Useful for multi-step tasks, issues, or epics that benefit from plan→test→implement→review phases.
Coordinates a swarm of AI agents to autonomously handle GitHub issues from creation to merged PR. Start tracked development work with multi-agent orchestration.