create-ard

Author an Architecture Requirements/Decision Document for the resolved item: $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-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] [--docs <path>], where <ADDRESS> is a key or an @<path>. --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.

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.

   Strip recognised flags before anything counts positional tokens. --no-docs (boolean) and --docs <path> (which consumes the token after it) are removed from $ARGUMENTS first, together with --docs's value; what remains is the positional address, and the one-address refusal below applies to that remainder alone. Without this rung the flags this command documents do not work — a flag is a token, so --no-docs reaches the refusal as a second positional and stops the run, and --docs <path> supplies two. That was the live state: both flags were named in the Usage line and neither was ever parsed, which is the shape workflows-core:docs-grounding Procedure step 1 (Flags first) declares for all nine of its consumers and only /idea had implemented.

   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 (Skill(skill: "workflows-core:reference", args: "addressing resolve-address"), §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 '/product-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 folder the address resolves to sets the altitude by its prefix — 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 — and a legacy folder with no prefix by what it holds. Re-run '/product-workflows:create-ard <ADDRESS>' with the single address you meant.