create-prd

Author a 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.

/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] [--docs <path>] (default --hybrid, or --full on the BRD route — Phase 0 step 2; the one --no-* switch turns off the one grounding source — see Phase 1). --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.

Phase 0 — Resolve inputs

1. Flags. Strip every recognised flag from $ARGUMENTS before step 1 classifies the address or any @idea.md: --from-prd <PRD-KEY|path> and --docs <path> each together with the token after it, plus the booleans --no-docs and --lean / --hybrid / --full. Steps 2 and 2a then read the values this step set aside.

   Every value-taking flag, not only the docs pair. --from-prd takes a <PRD-KEY|path>, and an unstripped one puts two stray tokens in front of step 1 — the flag, which is read as the address, and its value, which is read as @idea.md. That is the same defect as the docs flags and it was missed once by scoping the sweep to "a flag with no parsing site" rather than to "a value not consumed before positionals are read": step 2a does discuss --from-prd, so a parsing-site test passes it, and step 2a runs after step 1. It is step 0 and not 1a: step 1 is what parses the address, so a rung numbered after it runs after the damage. Both are carried to Phase 1's resolve-docs-grounding call and change nothing else. Without this rung the flag is a token like any other and lands in that classification: --docs is read as the address, or its path is read as the @idea.md argument. They were named in the Usage line and parsed nowhere, the same defect /create-ard, /specify and /release-notes were found to have.

2. The address (mandatory). Parse the first token that is neither a flag nor a flag's value — --from-prd and --docs each consume the token after them (step 0), and a value skipped as "non-flag" would be read as the key and validate it with key-valid (workflows-core:addressing §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 '/product-workflows:create-prd <ADDRESS>'.