design

Author an engineering design for the resolved item: $ARGUMENTS

/design is the Dev-phase engineering-design workflow — the design step of the PM→PA→PE→Dev pipeline (/specify → specification.md; then /design → design.md). The developer takes over a merged specification.md, grounds in the fully-mounted implementation code, and authors a reviewed engineering design.md through a relentless one-question-at-a-time grill that challenges the spec and designs the implementation. It gates on the Opus design-reviewer and offers to land design.md + the spec's engineering-review edits on the specs repo's main branch (via branch + PR) so /implement can plan and build from it.

Key distinction from /specify: /specify (PE) authors the requirements spec and grounds lightly (soft repo gate); /design (Dev) challenges that spec and designs the implementation, and must see all implementation repos — its repo gate is strict (hard-stop on any unmounted repo).

Flags: --design-twice forces the Phase 5 interface fan-out on the run's load-bearing interface, even when no contested-interface signal fired (references/design-format.md ## Seams).

---

Phase 0 — Resolve input

1. Resolve the address — strip every recognised flag first. --design-twice is removed from $ARGUMENTS before anything else, exactly as commands/idea.md's Phase 1 strips its own: an unstripped flag is read as the positional token and resolution then fails on a token that was never an address.

   Parse the single positional address from the stripped $ARGUMENTS — a <KEY>, or an @<path> naming a folder or a file inside one — and resolve it with resolve-address (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §3). Carry forward:

   • <PRD> — the resolved PRD folder's key: the folder itself when the address named a PRD- folder, its parent when the address named an EPIC- folder.
   • <EPIC> — the resolved EPIC- folder's key, or null when the address named a PRD- folder. The kind decides the altitude, which is what replaces the two-key grammar: the second key was always derivable from the first.

   With no positional address, stop with DESIGN_NEEDS_KEY: /design needs a PRD or Epic address — a key, or an @<path> to its folder. — /design has no direct-prompt behaviour. Resolution supplies the address and nothing else: /design reads no document for content at this step — the requirements source of truth is the merged specification.md in the specs repo.

2. Resolve $SPECS_PATH. /design reads specification.md and writes design.md under $SPECS_PATH/specifications/. If $SPECS_PATH is unset, stop with a clear error naming SPECS_PATH (choices: ["Set SPECS_PATH (enter the path)", "Cancel"]).

Specs-repo preflight. Cite ${CLAUDE_PLUGIN_ROOT}/references/specs-repo-git.md and execute its specs-preflight entry point (§3) inline: flush any leftover session artifacts from an earlier run, retry an artifact commit that failed to push, and settle the branch. 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.

(The preflight runs here, before the gate below, because require-on-main performs no fetch of its own — §3.2 — and relies on this step's best-effort one. Gating first would test never-fetched refs: a just-merged artifact would be missed on origin/<default> while the stale remote-tracking ref for its deleted branch still carries it, producing a false row D/E stop. specs-preflight self-gates on $SPECS_PATH, so it is safe this early.)

1. Map onto the specs repo + require the spec on main. Derive provisional kebab-case slugs from the relevant title(s): <vslug> for <PRD>, and <eslug> for <EPIC> when focus_key is set.
   • Resolve the PRD dir: call resolve-address <PRD> (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §3) and use its path; on ambiguous, stop naming every match and @<path> as the way through. No matching rule is written here — §5 owns it, and it carries the legacy fallback. Use a freshly derived PRD-<PRD>-<vslug> only on status: absent. Every later specifications/<PRD>-<vslug>/ in this command — the Epic-enumeration ref test included — names the dir resolved here.
   • Resolve the feature folder by case:
     • focus_key set → the per-Epic home specifications/<PRD>-<vslug>/EPIC-<EPIC>-<eslug>/ (same honor-existing tolerance on the EPIC-<EPIC>-<eslug> segment); the target is specification.md there.
     • focus_key null → resolved in step 4 (Granularity): either the flat PRD dir (a broad PRD-level spec) or a per-Epic subfolder the picker selects.
   • Gate the resolved target on main (the specs repo's default branch at $SPECS_PATH is the handoff surface, verified against origin/<default> by ref — never a worktree file-existence check). Execute require-on-main (${CLAUDE_PLUGIN_ROOT}/references/phase-handoff.md §3) against the resolved specification.md path — immediately once focus_key is set, or once step 4 resolves the target for focus_key null — and map its §3.7 return value by stopped first, never by on_main alone: any stopping state → stop per §4.4, naming the concrete branch/PR state it reports; otherwise (stopped: false) pass → proceed; pass_amending → proceed, printing §3.3's row-B message (this run's own in-progress branch amends specification.md, so it legitimately differs from <default>) — proceed as-is, never offering a repair here, since that would discard this run's own in-progress amendments; absent (row F) → stop: DESIGN_NO_SPEC: no specification.md on the specs repo's default branch for <ADDRESS> — run '/dev-workflows:specify <ADDRESS>' and land it there first. <ADDRESS> is this run's own resolved address, one address and no second key (D4).; unmanaged → behave exactly as before this feature.