epics

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

Core references. A citation of the form workflows-core:<name> names a shared reference in the workflows-core plugin. Load it with Skill(skill: "workflows-core:reference", args: "<name>") — never by path: ${CLAUDE_PLUGIN_ROOT} resolves to this plugin, which does not carry it.

/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 is no implementation record and no commit 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 holding its epic.md that has a PRD above it, which it re-refines. A stand-alone EPIC- folder, an EPIC- folder holding no epic.md and a BRD- container are all 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 workflows-core:specs-repo-git; 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 (workflows-core:specs-repo-git §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 (workflows-core:specs-repo-git §2.2); it creates none).

Phase 0 — Load

1. Flags. --no-docs — boolean; turns documentation grounding off for this run (Phase 2). --docs <path> — points documentation grounding at that root for this run instead of ${DOCS_PATH:-/workspace/docs}; strip the flag and its value together before any remaining-argument classification, or the path is read as part of the address. Declared for every consumer by workflows-core:docs-grounding Procedure step 1 (Flags first), which resolves it; this command only has to recognise it and pass the invocation through. Strip both, and --docs's value, from $ARGUMENTS before step 1 classifies what remains.
2. 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 (Skill(skill: "workflows-core:reference", args: "addressing resolve-address"), §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 (workflows-core:addressing §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 /product-workflows:idea <KEY> or /product-workflows:create-prd <KEY> on the idea route, and by /product-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.