brd-split

Split the grounded BRD into child BRDs and allocate every requirement: $ARGUMENTS

/brd-split is the third command of the BRD-to-PRD flow (PM phase) — it takes the findings /brd-ground verified and forces every [BR#n] in this BRD's coverage ledger to a recorded fate: built here, built by a named child, deferred, rejected, or superseded. This is the only place that fate is ever decided (${CLAUDE_PLUGIN_ROOT}/references/coverage-ledger-format.md §1) — without this command's gate, a long BRD split across several children could have every child quietly wave a requirement past, and nothing would notice.

Usage: /brd-split <BRD-KEY>

Runs at either of the two levels <BRD-KEY> can name, in one of two modes Phase 0 step 5 resolves from the folder itself:

• split_mode: full — a BRD that owns its source document. Everything below runs: slices are proposed, children are keyed and nested, and the ledger walk offers all five terminal resolutions.
• split_mode: allocate-only — a slice. Nesting is capped at one level (${CLAUDE_PLUGIN_ROOT}/references/brd-addressing.md §3), so no child may be created below a slice: Phases 2 and 3 are skipped entirely and the walk offers four resolutions, without covered-by. That last part is about who writes the disposition, not about whether a slice may carry it: a slice's covered-by names a sibling or the parent and records a provisional claim the parent's walk withdrew, so it is already terminal before this walk reads the ledger (${CLAUDE_PLUGIN_ROOT}/references/coverage-ledger-format.md §2, §3). The cap is on nesting, not on allocation — a slice whose rows could never leave unallocated could never become PRD-eligible (${CLAUDE_PLUGIN_ROOT}/references/coverage-ledger-format.md §5), which would make slicing pointless. The run announces the mode rather than quietly behaving differently.

---

Phase 0 — Resolve inputs and gate on verification

1. <BRD-KEY> (mandatory). Parse the first non-flag token; validate with brd-key-valid (${CLAUDE_PLUGIN_ROOT}/references/brd-addressing.md §1). If absent or invalid, stop: BRD_SPLIT_NEEDS_KEY: /brd-split needs a BRD key (shape ^[A-Z][A-Z0-9_]*(-\d+)+$) — re-run '/dev-workflows:brd-split <KEY>'.
2. $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"]
   

3. 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.
4. Resolve the BRD folder. resolve-brd <BRD-KEY> (brd-addressing.md §2), which searches specifications/ and exactly one level below it (§2 step 2) — the two levels a BRD folder can occupy. Absent → stop, without asserting which command would create it, because nothing on disk says whether this key names a BRD with a source document or a slice of one: BRD_SPLIT_NOT_FOUND: no BRD folder found for <BRD-KEY> under $SPECS_PATH/specifications/ (both levels searched) — check the key. A BRD with a source document of its own is created by /dev-workflows:brd-intake <BRD-KEY> @<brd-file>; a slice is created by /dev-workflows:brd-split on its parent.
5. Resolve the run mode. Read the resolved folder's brd-link.md and branch on its parent: field — the same signal /brd-ground Phase 0 uses to tell a slice from a root, and the only reliable one: a key's segment count is a naming convention, never a depth declaration (brd-addressing.md §1).
   • No brd-link.md, or one with no parent: → this BRD owns its source document. Set split_mode: full; carry it for the whole run. Nothing is announced — this is the ordinary case.
   • parent: <PARENT-KEY> present → this is a slice. Set split_mode: allocate-only, carry it for the whole run, and emit this notice now, and again in the final report — a run that silently skips two phases and drops a resolution from its own picker is worse than one that says so: BRD_SPLIT_ON_SLICE (notice, not a stop): <BRD-KEY> is a slice of <PARENT-KEY>. This run allocates <BRD-KEY>'s ledger but creates no children: nesting is capped at one level, so Phases 2-3 are skipped and no child BRD can exist below a slice. The Phase 4 walk offers four resolutions instead of five: covered-by is not one this walk can choose — on a slice it names a sibling or the parent, records a provisional claim the parent's own walk withdrew, and is written by that walk, so every row carrying it is already terminal here. This is a cap on nesting, not on allocation. A grandchild would inherit brd/source/ and a defect log from a parent that holds neither, so its inventory header would name a path that does not exist (brd-addressing.md §3, ${CLAUDE_PLUGIN_ROOT}/references/brd-format.md §2.1) — that is what child creation is refused for. A slice's own ledger has no such problem: its rows are this BRD's to allocate, and refusing to walk them would leave every one of them unallocated forever, which is the allocation deadlock this command exists to prevent (${CLAUDE_PLUGIN_ROOT}/references/coverage-ledger-format.md §1, §4). The one inheritance the walk itself needs — the defect log a rejected: [DEF#n] cites — resolves in the parent's log in allocate-only mode, and that lookup is exactly one hop because the cap makes a slice's parent always the source-owning root (brd-format.md §4). Phase 4 states it where it is used.
6. Gate the grounding deliverable on main. /brd-split consumes a $SPECS_PATH deliverable it did not write (/brd-ground's findings, and — transitively — /brd-intake's ledger), so per phase-handoff.md §5 rule 2 it executes require-on-main (§3) here in Phase 0, before anything else reads a file. Execute it against the resolved BRD folder's grounding/code-grounding.md — every deliverable a handoff-to-main run stages lands in one commit (§2.3), so this file's presence on origin/<default> implies grounding/design-grounding.md and brd-link.md merged with it; and since /brd-ground Phase 0 step 6 already required coverage-ledger.md on origin/<default> before grounding itself would run, it also implies /brd-intake's ledger was on main before this BRD was ever grounded. Map the §3.7 return by stopped first: any stopping row → stop, naming the concrete branch/PR state it reports; pass → proceed; pass_amending → proceed, printing the §3.3 row-B message; absent (row F — grounding findings are on no ref at all) → split it before stopping, on a test row F cannot make, the way /brd-reconcile splits its own row F. Row F covers two states here, and the message for the second one must not name a command that stops on the same emptiness. Read <BRD-dir>/brd/brd-inventory.md from the worktree and count its [BR#n] rows:
   • One or more rows — grounding simply has not run yet, and running it is the fix: BRD_SPLIT_NEEDS_GROUNDING: no grounding findings on file for <BRD-KEY> — run /dev-workflows:brd-ground <BRD-KEY> first.
   • Zero rows — there is nothing to ground, so /brd-ground stops with BRD_GROUND_EMPTY_INVENTORY rather than producing the findings this gate wants. Naming it here would be the loop, so name the upstream fix instead, by the split_mode step 5 already resolved — full means this BRD owns its source document, allocate-only means it is a slice: BRD_SPLIT_EMPTY_INVENTORY (split_mode: full): <BRD-KEY>'s inventory holds no [BR#n] row, so there is nothing to ground and nothing to allocate — do not run /dev-workflows:brd-ground, which stops on the same emptiness. Re-run '/dev-workflows:brd-intake <BRD-KEY> @<brd-file>' over this same folder with a source whose requirements brd-reader can identify, and merge that pull request; if the source genuinely states no requirement, this BRD has nothing for the route to carry. BRD_SPLIT_EMPTY_INVENTORY (split_mode: allocate-only): <BRD-KEY> is a slice of <PARENT-KEY> and its inventory holds no [BR#n] row — it claims nothing, so there is nothing to ground and nothing to allocate. Do not run /dev-workflows:brd-ground, and do not run /dev-workflows:brd-intake on a slice; it has no source document of its own. Re-run '/dev-workflows:brd-split <PARENT-KEY>': it resolves every standing empty child, so it will offer to remove this slice or to keep it against its recorded reason, and it will offer covered-by against it for any row on the parent's ledger that is still unallocated. If the parent's ledger has no unallocated row left, removal is the only thing that can change this slice's state — /brd-split never re-allocates a row that already carries a fate. unmanaged → proceed as before this feature.
7. Gate on verification. Every [CG#n]/[DG#n] finding carries a verifier outcome (one of the four in ${CLAUDE_PLUGIN_ROOT}/references/grounding-format.md §8 — agree, extend, contradict, unprovable) once /brd-ground Phase 7 has run over it; a finding without one "is not evidence and cannot be recorded as consumed_by anything" (§8), and this command must never propose a slice or offer covered-here against a claim nobody has actually verified. Count every finding on file carrying no recorded outcome. Any count N greater than zero → stop: BRD_SPLIT_UNVERIFIED: N findings have no verifier verdict — run /dev-workflows:brd-ground first.
8. Read the ledger; check for the no-op case. Read <BRD-dir>/coverage-ledger.md and compute its disposition counts (coverage-ledger-format.md §3) — this BRD's own rows, as written, with no child ledger consulted. The no-op test and the §4 gate are both about unallocated on this ledger; what a child did with a row this BRD already delegated cannot make that row unallocated again, and the remedy for a child that is not building it lives in the child's own walk, not here. Child ledgers are read once, in the Final Report, and only to count the line (coverage-ledger-format.md §6.1). Zero rows are unallocated → set unallocated_zero: true.