v-epic

You are running /v:epic — the epic driver of Compound V. A v1.0 run executes ONE plan (one feature). An epic chains several: an ordered set of features, each run through the full v1.0 pipeline, in dependency order, accumulating onto one branch. "Build a whole app." It is the same discipline one level up — resumable, topological, no daemon.

The epic spec is {{args}} (a path to an epic brief, or a described feature set).

The epic model, run-dir layout, the final integration review, and the honesty boundary are defined in skills/compound-v/epic-mode.md — read it; it is the authority. The deterministic state spine is scripts/compound-v-epic-state.py (one level up from state-machine.md). Each per-feature run is a normal v1.0 run materialized per execution-manifest.md.

Steps

1. Resolve the epic spec. From {{args}}: if it is a path to an epic brief, read it; if it is a described feature set, work from the description. If {{args}} is empty, ask the user for the epic brief (or list existing epics under docs/superpowers/execution/epics/ to resume one). Pick an <epic-id> (convention: YYYY-MM-DD-<slug>) and an epic title, and capture the epic's acceptance criteria (used by the final integration review). Agree an autonomy budget with the user — MAX_FEATURES per /v:epic invocation. Seed the default from .claude/compound-v.json epic.max_features if set (written by /v:init Step 3c), else 1: build one feature, then checkpoint; raise it only when the user wants more autonomy per run. An epic is N full v1.0 runs, so this is the human checkpoint cadence — a driver policy, not a script-enforced token meter: by default the loop builds one feature, reports --stats, and stops for you to review and re-run.

   Marathon gate (opt-in, v2.10). If .claude/compound-v.json epic.autonomy.stance == "marathon" (written by /v:init Step 3c) or the user explicitly asks for the autonomous/marathon loop for this invocation, this epic runs the Autonomous marathon loop below instead of steps 4–7 — MAX_FEATURES does not apply there (marathon is bounded by global breaker caps, not a per-invocation feature count). Otherwise (the default, unconfigured case) continue with the checkpoint loop in steps 4–7 exactly as documented — nothing below changes for you.

2. Decompose + spec every feature UP FRONT — the one interactive phase. Decompose the product into independent-ish features, each a vertical slice (auth, api, ui), not a layer; capture cross-feature dependencies in depends_on (api depends_on auth). Then, for each feature, run superpowers:brainstorming to produce a real per-feature spec file (with feature-level Acceptance Criteria), saved to docs/superpowers/execution/epics/<epic-id>/specs/<feature-id>.md. Trigger 0 applies to each of these brainstorms: before each per-feature brainstorm, run the pre-brainstorm recon gate sequence from phase-0-recon.md (plumbing-skip → KB-hit → config); later features in the same epic increasingly skip via the KB-hit gate as earlier recon/audit docs accumulate — designed behavior, not a bypass. This is the only human-interactive phase: every spec is written and approved here, before the autonomous loop — so the loop never pauses to brainstorm. That batching is what makes the epic genuinely autonomous and keeps a real spec per feature (the central tension, resolved). Write features.json = a JSON array of {id, title, depends_on, spec_path}, each spec_path pointing at its spec file.

3. Review the decomposition, then init (specs enforced).

   • Gate the feature DAG before building (one level up from partition-review): python3 scripts/compound-v-epic-state.py --lint --features docs/superpowers/execution/epics/<epic-id>/features.json flags structural smells (an ISLAND feature with no deps and no dependents = a likely missed dependency; an over-coupled feature depending on most others = a layer, not a slice) plus any hard validation error. Then critique it yourself: are these real vertical slices, are depends_on correct and complete? A missing edge means a feature builds before its prerequisite. Fix features.json until lint is clean and the split is sound — a weak decomposition is the #1 way an epic fails downstream.
   • Resume-aware init. The epic lives at docs/superpowers/execution/epics/<epic-id>/epic-state.json. If it already exists → CONTINUE (read it; first run python3 scripts/compound-v-epic-state.py --check-specs --state <epic-state.json> to confirm every non-done feature still has an existing, contained spec_path — this guards an old or hand-made state from entering the loop spec-less — then go to the loop). Else initialize:

     python3 scripts/compound-v-epic-state.py --init --require-specs \
       --features docs/superpowers/execution/epics/<epic-id>/features.json \
       --epic-id <epic-id> --title "<title>" \
       --out docs/superpowers/execution/epics/<epic-id>/epic-state.json
     

     --require-specs refuses to start unless every feature has an existing spec_path — the deterministic enforcement that no feature enters the autonomous loop without an approved spec. It also validates ids/refs/cycles/dups. A non-zero exit ⇒ fix and re-init; never hand-edit the state.
   • Marathon init (only for a NEW epic, gated by step 1). If the marathon gate applies and epic-state.json does not exist yet, add --stance marathon plus the agreed breaker caps to the --init command above: --stance marathon --max-attempts-per-feature <N> --max-no-progress-cycles <N> --max-wall-clock-hours <H> --start-sha <sha> (leave --max-total-attempts unset to take the script's feature-count-derived default, max(6, 3×features), unless the user wants a specific number). Capture <sha> with git rev-parse HEAD at this init moment and pass it — it is stored as autonomy.start_sha and is the baseline the halt-page's accumulated-diff command (§7) and the final integration review (§8) diff against. Marathon has no in-place upgrade. An existing checkpoint epic-state.json (no autonomy block) cannot be flipped to marathon after the fact — build_state/--init only ever writes the marathon fields at creation time. If the epic already exists as a checkpoint state and the user now wants marathon, the options are: (a) keep finishing it in checkpoint mode (steps 4–7), or (b) start a fresh --epic-id with --stance marathon, reusing the same features.json/spec files under a new epic id. Never hand-edit an existing epic-state.json to inject an autonomy block.
     • Watch opt-in (v2.11, additive to this same --init call). If .claude/compound-v.json epic.autonomy.watch == true (written by /v:init Step 3c), add --watch [--max-resume-count <N>] to the SAME --init command above — this is what activates auto-resurrection: config intent alone never arms anything, only the autonomy.watch this call PERSISTS into epic-state.json does (every watch-gated command below — --liveness, --claim-resume, --renew-lease, --record-watcher-armed/-disarmed, --list-watchers — reads and requires the persisted value, exactly like autonomy.stance itself). The persisted autonomy.watch is the sole authority once the epic exists — the config key epic.autonomy.watch only ever gates THIS one --init --watch call for a NEW epic; a config-only "yes" on an epic whose --init omitted --watch never retroactively arms it (no in-place upgrade, same rule as marathon itself), and a later config flip does not retroactively turn watch on or off for an already-initialized epic. Leave --max-resume-count unset to take the script's default (20) unless the user wants a specific cap. The exact arming/disarming sequence is Autonomous marathon loop §0c below.
   • Commit the epic-level files right after init: features.json and the freshly-created epic-state.json are new, uncommitted files. Two separate commands, checking each exit code — never chain with &&: git add docs/superpowers/execution/epics/<epic-id>/features.json docs/superpowers/execution/epics/<epic-id>/epic-state.json, then git commit -m "chore(v-epic): init epic <epic-id>". (Per-feature spec files are committed by superpowers:brainstorming itself when each spec is approved, in step 2 — no separate action needed for those.)