idea

Refine an idea into idea.md: $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.

/idea is the front door of the PRD-creation flow (PM phase) — upstream of /create-prd and the existing pipeline. It ingests one source, refines it through a grill, and writes a lean one-page idea.md (per ${CLAUDE_PLUGIN_ROOT}/references/idea-format.md) that seeds the Product Requirements Document. It is not a PRD: no code change. Output lands in the PRD folder the key names, on the first write and never relocated. It then vendors what it read into that same folder (Phase 4.5) so the record the specs repo keeps is one whose links resolve for everybody, not only for the operator whose disk the sources came off.

Flags: --deep switches the grill from bounded (≤10 questions) to relentless (until convergence). --no-docs turns off documentation grounding (see Phase 1). --docs <path> points documentation grounding at <path> instead of ${DOCS_PATH:-/workspace/docs} (see Phase 1); the token after it is always its value. --ground-code [<repo>[,<repo>…]] grounds the idea against mounted code (see Phase 2.6) — bare it derives the repo set, with a value it scans exactly those repos. The token after --ground-code is its value only when it contains no whitespace and every comma-separated part matches a top-level directory basename under ${REPOS_PATH:-/workspace}; otherwise the flag is bare and the token is idea text.

Phase 0 — Resolve the address + model routing

1. The address (mandatory). Parse the first token that is neither a flag nor a flag's value — --docs always consumes the token after it, and --ground-code only as the Flags paragraph above conditions it, and a value skipped as "non-flag" would be read as the key and validate it with key-valid (workflows-core:addressing §1). Absent or malformed → stop: IDEA_NEEDS_KEY: /idea needs a PRD key (^[A-Z][A-Z0-9_]*(-\d+)+$, e.g. ACME-77) — it names the folder this idea will live in. Re-run '/product-workflows:idea <PRD-KEY> [<prompt>|@<file>]'.

   The key is an argument because there is nowhere keyless to write. idea.md lands in its final folder on the first write — PRD-<KEY>-<slug>/ under $SPECS_PATH/specifications/. So $SPECS_PATH comes first: if it is unset, stop naming it (choices: ["Set SPECS_PATH (enter the path)", "Cancel"], workflows-core:escalation-rules Required path environment variable unset) — resolution and Phase 4's write both need it, and an empty one would aim idea.md at /specifications/ under the filesystem root. Resolve the folder here with resolve-address (Skill(skill: "workflows-core:reference", args: "addressing resolve-address"), §3): found is the folder this run writes into — where it is an idea-route PRD folder, below — and ambiguous is §3's hard stop. On absent nothing is created here, because Phase 0 holds no slug to name a folder with: the folder is created by Phase 4's first write, as PRD-<KEY>-<candidate_slug>/ (workflows-core:addressing §2), candidate_slug being the one Phase 2's digest returns. Creating it with idea.md, which carries its kind and key, is also what keeps it from ever being keyless (§4). Either way it is never relocated afterwards, and /create-prd <KEY> finds it there.

   A found folder must be an idea-route PRD folder. Test the folder, never the kind it asserts — a BRD-route slice is PRD--prefixed and asserts kind: brd through its brd-link.md (workflows-core:addressing §4) — in this order, stopping on the first that holds. A folder carrying a brd-link.md naming a parent: at its top level is a BRD-route slice, whatever its name. Then, where the resolution record reads legacy: false, test the prefix: BRD- is a BRD container, EPIC- an Epic folder. Where it reads legacy: true there is no prefix to test — §5's unprefixed name starts with the key, and a key may itself begin with a kind token, so BRD-12-checkout/ is a legacy folder keyed BRD-12 and not a BRD container — so place it by positive evidence instead, as workflows-core:addressing §4.1 does: coverage-ledger.md or brd/brd-inventory.md present is a BRD container, a resolved kind: epic an Epic folder. An idea brief seeds the PRD authored beside it, and none of these takes one: a BRD container never holds a PRD, a slice's PRD is seeded from its BRD with no idea ladder, and an Epic folder sits below its PRD: IDEA_NOT_AN_IDEA_FOLDER: <KEY> resolves to <folder path>, <a BRD container | a BRD-route slice | an Epic folder> — /idea writes only into an idea-route PRD folder. <remedy> For a separate idea, give it a key of its own: '/product-workflows:idea <NEW-KEY> [<prompt>|@<file>]'. <remedy> names the run that does take that folder's work, by what the folder is — and, in the slice and Epic rows below, names a run only where that run can itself take the folder, since each command it could name refuses some shape of it. The BRD container row is the exception: it names each slice's /create-prd as where a PRD belongs, not as a run promised to start, and /brd-split with its no-op case said beside it. The slice rows read the gate set ${CLAUDE_PLUGIN_ROOT}/references/coverage-ledger-format.md §5.2 defines — this slice's own coverage-ledger.md rows narrowed by its brd-link.md claims:, read out of the ledger file and never off a ledger: line (§6.1) — exactly as /product-workflows:update-prd Phase 0 step 4 and /product-workflows:epics Phase 0 step 1b read it: