create-prd

Author a Product Requirements Document: $ARGUMENTS

/create-prd is sub-project 2 of the PRD-creation flow (PM phase) — it consumes the idea.md from /idea and a user-supplied address and authors a high-quality Product Requirements Document that feeds the downstream pipeline. The PRD is product-level (a PRD): what / why / for-whom, not how. Zero external calls — the PRD is authored as markdown in the specs repo, which is where every downstream command reads it from.

Usage: /create-prd <ADDRESS> [@idea.md] [--from-prd <PRD-KEY|path>] [--lean|--hybrid|--full] [--no-docs] (default --hybrid, or --full on the BRD route — Phase 0 step 2; the two --no-* switches each turn off one grounding source — see Phase 1).

---

Phase 0 — Resolve inputs

1. The address (mandatory). Parse the first non-flag token and validate it with key-valid (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §1). If absent or malformed, stop gracefully with the one CREATE_PRD_NEEDS_KEY text below — there is one stop for this code, not two. (Shape only, and never checked against anything: the key is the operator's own and names a folder in $SPECS_PATH; nothing mints it and nothing verifies it.)

   The BRD route is detected, not declared. A folder carrying brd-link.md was produced by /brd-split and holds the seeds this command reads; the operator restates nothing on the command line, and there is no flag that could disagree with the folder it names. Detection therefore waits on resolution. The address is resolved once, with resolve-address (step 5), and that resolution is taken as soon as step 2b has settled $SPECS_PATH — ahead of step 2's profile default and step 3's ladder, both of which read the route. Print which route the run entered at that point, before any other work. Where the address resolves to nothing there is no folder and no brd-link.md to read one off, so the run is on the idea route; step 5 says what happens then, and it is not a stop. A key that fails §1's grammar stops with CREATE_PRD_NEEDS_KEY: /create-prd needs an address (^[A-Z][A-Z0-9_]*(-\d+)+$, e.g. EPIC-008 or the slice EPIC-008-01) — re-run '/dev-workflows:create-prd <ADDRESS>'.

2. Profile. --lean | --hybrid | --full; default --hybrid — or --full when the BRD route is present and no profile flag was given, per the design's Profile default section (§7.4): that profile is the one carrying ## Functional requirements ([FR#N]), ## API specification, ## UX prototype / UI mockups and the full ## Assumptions & open questions Contradictions Log, so considerably more BRD-derived content has a legitimate product-altitude home than --hybrid allows. An explicit --lean/--hybrid still wins: the default is a default, not an override. 2a. --from-prd <PRD-KEY|path> (optional seed). When present, this run authors a new PRD (the positional <KEY>) seeded read-only by another PRD. Resolve the seed via resolve-address (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §3) and read that folder's prd.md for a key, or read the given path directly. The seed is grounding, not content (Phase 3 adapts it; it is never copied wholesale).

2b. $SPECS_PATH, then the specs-repo preflight — both before step 3's gate. If $SPECS_PATH is unset, stop naming it (choices: ["Set SPECS_PATH (enter the path)", "Cancel"]). Then cite ${CLAUDE_PLUGIN_ROOT}/references/specs-repo-git.md and execute its specs-preflight entry point (§3) inline: flush any leftover session artifacts from an earlier run, retry an artifact commit that failed to push, and settle the branch. Prompt-free and silent when the specs repo is clean and on its default branch. If a guard fires, emit its §5 notice; if it returns specs_git: blocked (§3.3 G0), carry that flag for the whole run — the terminal commit-artifacts step skips on it.

**The ordering is the point, not the tidiness.** Step 3's `require-on-main` performs no fetch of
its own (`${CLAUDE_PLUGIN_ROOT}/references/phase-handoff.md` §3), so without the preflight's
best-effort fetch ahead of it a merged `idea.md` reads as "on a branch and never handed off" and
the run hard-stops on work that is already on the default branch. This command was for a time the
only one of the twenty-four `commit-artifacts` callers running no preflight — deleted as
collateral with an adjacent paragraph — which also left `specs_git: blocked` unset, so the G0
guard in both `commit-artifacts` and `handoff-to-main` was inert here and a detached-HEAD specs
repo would take this command's commits to an unreachable place and report success.