brd-intake

Intake the customer-supplied business requirements document: $ARGUMENTS

/brd-intake is the entry point of the BRD-to-PRD flow (PM phase) — the first of the /brd-* commands, which between them turn a long, often internally contradictory customer BRD into requirements a PRD can be built from. It copies the customer's source into the specs repo verbatim and immutably, extracts a [BR#n] requirement inventory via the brd-reader agent, classifies the document's defects with a human rather than on the agent's say-so alone, and writes a coverage ledger in which every requirement starts life unallocated — the state /brd-split, the route's third command, cannot complete past until each row has been given a fate.

Usage: /brd-intake <BRD-KEY> @<brd-file> [--sort-existing <dir>] [--no-docs]

Phase 0 — Resolve inputs

1. <BRD-KEY> (mandatory). Parse the first non-flag token; validate it with key-valid (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §1's key-valid — shape only, never checked against a tracker). If absent or invalid, stop gracefully: BRD_INTAKE_NEEDS_KEY: /brd-intake needs a BRD key (shape ^[A-Z][A-Z0-9_]*(-\d+)+$, e.g. ACME-001) — pick a short stable identifier for this business requirements document, then re-run '/dev-workflows:brd-intake <KEY> @<brd-file>'.
2. @<brd-file> (mandatory). The customer's source file argument. If absent, stop: BRD_INTAKE_NEEDS_SOURCE: /brd-intake needs the customer's source as an @-argument — re-run '/dev-workflows:brd-intake <KEY> @<path-to-brd>'.
3. Reject a PDF — do not convert it. If the resolved source does not end in .md/.markdown (a PDF, a Word document, a slide deck, any non-markdown source), stop: BRD_INTAKE_NEEDS_MARKDOWN: the source must be markdown — convert it first, and check the conversion. It becomes the immutable record every [BR#n] anchors into. The reason this is a hard stop rather than a best-effort conversion: once intaken, brd/source/ is never edited again (${CLAUDE_PLUGIN_ROOT}/references/brd-format.md §1), and every [BR#n] locates itself inside that text by source_anchor. An unchecked machine conversion — a dropped clause, a misplaced heading, a table read out of row order — would silently become the record of what the customer asked for, with no later step positioned to catch it. Converting is the operator's own step, done where they can eyeball the result against the original before handing it back to this command.
4. Optional flags. --sort-existing <dir> — if present, validate <dir> exists and carry it forward to Phase 6. --no-docs — boolean; turns documentation grounding off for this run, carried to Phase 1's resolve-docs-grounding call. Neither changes anything else about Phase 0: the BRD source is still required and still gated by step 3.
5. $SPECS_PATH (required). If unset, stop naming SPECS_PATH, per the Required path environment variable unset rule in ${CLAUDE_PLUGIN_ROOT}/references/escalation-rules.md:

   choices: ["Set SPECS_PATH (enter the path)", "Cancel"]
   

6. Specs-repo preflight. Cite ${CLAUDE_PLUGIN_ROOT}/references/specs-repo-git.md and execute its specs-preflight entry point (§3) inline. 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.
7. Resolve or derive the BRD folder via resolve-address <BRD-KEY> (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §3). Found → this is an existing BRD folder and this invocation is a re-run over it; use it. A slice is never a legitimate target here — it has no source document of its own to intake, and its inventory and ledger are the parent's /brd-split to write (${CLAUDE_PLUGIN_ROOT}/references/brd-format.md §2.1, ${CLAUDE_PLUGIN_ROOT}/references/coverage-ledger-format.md §3) — so a resolved folder whose brd-link.md carries a parent: field is a mis-keyed invocation: say so and confirm before Phase 2 copies anything into it. Absent → this is a brand-new BRD: derive <slug> from the source file's first heading (kebab-cased), falling back to a kebab of the source filename when no heading is found, and prepare to create specifications/BRD-<BRD-KEY>-<slug>/ — the BRD- kind prefix is part of the name (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §2), never optional and never derived from the key. The directory is not actually created until Phase 2's first write.