epics

Draft child Epics for the resolved Product Requirements Document: $ARGUMENTS

/epics is the keyed Epic-writing workflow. Given a Product Requirements Document key, it reads the PRD plus its existing Epics from the resolved PRD folder, optionally scans code repos to identify reusable capabilities and gaps, drafts child Epic definitions as markdown files under the resolved output directory, and gates the result on an Opus review.

Key distinction from /document (keyed mode): the PRD being Epic-ized is not yet implemented — there are no PRs to diff. Code scanning (when enabled) is a plain filesystem search to understand what exists and what needs to be built.

/epics accepts exactly two shapes and refuses everything else (Phase 0 steps 1a and 1b): a PRD- folder, which it partitions into new Epics, or an EPIC- folder that has a PRD above it, which it re-refines. A stand-alone EPIC- folder and a BRD- container are both refused. Epics come from a PRD only, and /epics is the only command in this plugin that creates an EPIC- folder — /create-ard and /specify refuse an absent one rather than minting it.

/epics never branches and never commits the Epic drafts (still true — the run's git writes are confined to $SPECS_PATH, per ${CLAUDE_PLUGIN_ROOT}/references/specs-repo-git.md; the run does make read-only git calls elsewhere — Phase 4's git remote get-url origin per candidate clone and Phase 8's git diff --stat from project_root — but none of them writes), and writes only inside the resolved PRD folder — one EPIC-<PRD-KEY>-NN-<eslug>/ per Epic, plus _coverage.md beside prd.md. Git hygiene of the write target is the user's responsibility — they may or may not have it under version control. The run commits only inside $SPECS_PATH, and only its bounded session-artifact paths (${CLAUDE_PLUGIN_ROOT}/references/specs-repo-git.md §2.1) — via the specs-preflight flush at run start (§3.4) and the terminal commit-artifacts step (§4); never the drafts, never the write target. It still creates no branch (still true — specs-preflight switches $SPECS_PATH only between branches that already exist, and only plugin-created ones (${CLAUDE_PLUGIN_ROOT}/references/specs-repo-git.md §2.2); it creates none).

---

Phase 0 — Load

1. Resolve the address. Parse the single positional address from $ARGUMENTS — a <KEY>, or an @<path> naming a folder or a file inside one — and resolve it with resolve-address (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §3), with no <KIND> argument: a slice folder is PRD--prefixed while the brd-link.md inside it asserts kind: brd, so narrowing the resolution by kind would refuse on one route the very folder it resolves on the other (addressing.md §3, resolve-key step 1). The kind gate is step 1b's, and it is taken on what the resolved folder holds. status: found → carry its path, kind and key forward; ambiguous → stop, naming every match and @<path> as the way through. absent is a graceful stop, not a folder to create — /epics partitions a PRD folder that exists and creates no PRD folder of its own:

   EPICS_NOT_FOUND: no folder found for <ADDRESS> under $SPECS_PATH/specifications/ (every level addressing.md §3 bounds, plus §5's legacy fallback) — check the address. /epics partitions an existing PRD folder and creates none. A PRD folder is created by /dev-workflows:idea <KEY> or /dev-workflows:create-prd <KEY> on the idea route, and by /dev-workflows:brd-split on its parent BRD on the BRD route; an EPIC- folder is created by this command and by no other, so an Epic address that resolves to nothing was never drafted here.
   

   Every command that stop names creates the folder it claims to, and none of them is a command this one would then refuse: /idea and /create-prd each write PRD-<KEY>-<slug>/ on their first write, and /brd-split carves the PRD- slice — all three PRD- folders that pass step 1a.