/v-epic

description: Drive an EPIC — chain several features into one autonomous, resumable, dependency-ordered build on a single branch. Each feature runs through the FULL v1.0 pipeline (recon-gated spec → 3 pre-flights → writing-plans + partition → manifest → dispatch → 3-pass review) in topological order, accumulating onto the current branch. Resume-aware via epic-state.json; ends with a cross-feature integration review and finishing-a-development-branch.

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`](../skills/compound-v/epic-mode.md) — read it; it is the authority. The deterministic state spine is [`scripts/compound-v-epic-state.py`](../scripts/compound-v-epic-state.py) (one level up from [`state-machine.md`](../skills/compound-v/state-machine.md)). Each per-feature run is a normal v1.0 run materialized per [`execution-manifest.md`](../skills/compound-v/execution-manifest.md).

Resolving the plugin root

The `scripts/` this command calls ship with the plugin — they are not files in your own repository. Resolve the plugin root once per session before calling any of them:

CV="${CLAUDE_PLUGIN_ROOT:-$(ls -d "$HOME"/.claude/plugins/cache/*/superpowers-v/*/ 2>/dev/null | sort -V | tail -1)}"
CV="${CV:-$PWD}"; CV="${CV%/}"

`CLAUDE_PLUGIN_ROOT` is set for hooks but is not set in this Bash environment, so treat it as a hint, never the whole answer — the fallback line covers an installed plugin cache or a checkout of this repo. Paths under `docs/superpowers/` stay relative; only the plugin's own `scripts/` get `$CV`.

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`](v-init.md) 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`](v-init.md) Step 3c) or the user explicitly asks for the autonomous/marathon loop for this invocation, this epic runs the **[Autonomous marathon loop](#autonomous-marathon-loop-opt-in-v210)** 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`](../skills/compound-v/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 "$CV/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 "$CV/scripts/compound-v-epic-state.py" --check-specs