create-ard

Author an Architecture Requirements/Decision Document for the resolved item: $ARGUMENTS

/create-ard is sub-project 3 of the PRD-creation flow — the Product Architect (PA) phase. It grounds on the mounted implementation repos and authors an ARD that establishes the architecture invariants the downstream (/specify, /design, /implement) will later inherit. The ARD is optional (a simple PRD may not need one) and scoped by the kind of the address it is given:

• /create-ard <PRD-KEY> → a PRD-level ARD.
• /create-ard <EPIC-KEY> → an Epic-level ARD (inherits the PRD-level ARD read-only). The Epic's own key is the whole address: it encodes its ancestry, so the PRD is the folder above it and is never typed beside it (D4).
• /create-ard <SLICE-KEY> → an ARD on the BRD route, authored in the PRD- slice folder /brd-split carved and seeded from the reconciled BRD instead of from a PRD. A BRD- container is refused (Phase 0 step 1a). One address on every route: a second positional token is refused (Phase 0 step 1, CREATE_ARD_ONE_ADDRESS).

Usage: /create-ard <ADDRESS> [--no-docs], where <ADDRESS> is a key or an @<path>.

It authors architecture only — no code writing; grounding is architect-driven (there are no PRs at this stage). Zero external calls.

---

Phase 0 — Resolve input

1. Resolve the address.

   One resolution, both routes. Parse the single positional address from $ARGUMENTS — a <KEY>, or an @<path> naming a folder — and resolve it with resolve-address (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §3). A key that fails §1's grammar stops with CREATE_ARD_NEEDS_KEY: /create-ard needs an address (^[A-Z][A-Z0-9_]*(-\d+)+$, e.g. EPIC-008 or the slice EPIC-008-01) — re-run '/dev-workflows:create-ard <ADDRESS>'. Shape only, and never checked against anything (§1) — a key names a folder in $SPECS_PATH.

   A second positional token is refused, on every route (D4). There is no <PRD> <Epic> form to fall back to: an Epic key encodes its own ancestry, so a second argument would be derivable from the first and able to disagree with it, which is the failure class D4 exists to remove. Stop gracefully: CREATE_ARD_ONE_ADDRESS: /create-ard takes one address; <second-token> was given as a second. The kind of the folder the address resolves to is what sets the altitude — an EPIC- folder gives an Epic-level ARD, with its PRD read from the folder above it; a PRD- folder gives a PRD-level one. Re-run '/dev-workflows:create-ard <ADDRESS>' with the single address you meant.

   The resolved kind decides the altitude, which is what replaces the old two-key grammar:

   • a PRD- folder → <PRD> is its key, <EPIC> is null;
   • an EPIC- folder → <EPIC> is its key and <PRD> is its parent's;
   • a PRD- folder holding a brd-link.md → the BRD route. Define <SLICE-KEY> = the resolved folder's key.

   The BRD route is detected, not declared. A folder carrying brd-link.md was produced by /brd-split and holds the seed this command reads; nothing about that needs restating on the command line, and a flag that could disagree with the folder it names is one more disagreement to have. Print which route the run entered before doing anything else.

1a. Refuse a BRD- container — on either route, and the moment the address resolves.

Resolution waits on $SPECS_PATH, and there is exactly one of them. resolve-key globs specifications/**/*-<KEY>-*, so it needs $SPECS_PATH; run step 1's resolution only after step 2 has settled it, and let step 3 reuse that same resolution rather than taking a second one. With the old ordering /create-ard ACME-77 against an unset $SPECS_PATH resolved absent at step 1 — so this refusal did not fire and the route printed as the idea route — then step 2 stopped, the operator supplied the path, and step 3 re-resolved and found the BRD- container with nothing testing it. The run authored ard.md into the container, which is the exact state this step exists to prevent. /create-prd states the same rule for the same reason ("Detection therefore waits on resolution"); the two must not diverge on it. A BRD- folder is not a fourth altitude, and this command used to route one onto the BRD route. This test is not part of the BRD-route branch and must not be folded into it: that route is detected from a brd-link.md, and a root BRD folder need not carry one — /brd-intake writes none, and only /brd-ground, /brd-split and /brd-package ever do — so a route-conditioned refusal would let /create-ard <ROOT-BRD-KEY> fall through and author an ARD into the container. It is a container: the design's §4.1 tree places ard.md only inside a PRD folder, while a BRD- folder holds brd/, grounding/, interview/, coverage-ledger.md, decisions.md and slices.md — and no ARD. Authoring one there writes an artifact the tree has no place for and that ${CLAUDE_PLUGIN_ROOT}/references/ard-resolution.md would then look for one level away.