educlopez/sddesign

<!-- HARNESS MIRROR — do not edit here. Canonical source: skills/ or commands/. After editing source, copy into cli/assets/<harness>/ and repo-root harness mirrors. -->

Context: this sub-skill is one lens of the broader ui-craft skill. If the ui-craft skill is also installed, read its SKILL.md first for Discovery + Anti-Slop + Craft Test, then apply the specific lens below.

Run the spec-driven design pipeline for $ARGUMENTS. Load the ui-craft skill.

---

ORCHESTRATE-ONLY RULE

This command sequences existing phase commands. It MUST NOT re-implement or duplicate any logic from them. Every composition rule, wireframe algorithm, craft rule, and convergence engine lives in the phase commands. This command contributes only:

1. Gate detection (does the artifact exist?)
2. Offer prompts (run phase X or skip?)
3. Progress reporting (the checklist)
4. Degraded-mode honesty (what was skipped and what that costs)

When in doubt: call the phase command, don't inline its steps.

---

Progress Checklist

Print this at the start and update it after each gate resolves:

[ ] brief   [ ] tokens   [ ] shape (spec)   [ ] craft (build)   [ ] converge   [ ] ship

Use [✓] for completed/skipped-with-artifact, [>] for the current gate, [–] for skipped-without-artifact (degraded).

---

Pipeline Gates

Gate 1 — Brief

Check: does .ui-craft/brief.md exist?

If yes: mark [✓] brief. Note that brief §6 learned constraints and the a11y/correctness floor are in effect for all downstream gates — they take precedence over any spec.md composition choice.

If no: offer to run /brief now.

• User confirms → run /brief. When it completes, mark [✓] brief.
• User declines → mark [–] brief. Note downstream impact: "no brief → craft will use skill defaults; composition will not be anchored to project principles."

Gate 2 — Tokens

Check: does a token spine exist? (Look for CSS variables --color-*, --font-*, --accent-*, a Tailwind theme.extend with tokens, or a token file.)

If yes: mark [✓] tokens.

If no: offer to run /tokens now.

• User confirms → run /tokens. When it completes, mark [✓] tokens.
• User declines → mark [–] tokens. Note downstream impact: "no token spine → craft will establish a minimal inline token set; it won't match an existing system."

Gate 3 — Shape (spec)

Existing-surface guard: Before running /shape, check if .ui-craft/spec.md already contains a ## Surface: <name> block for this surface. If it does, do NOT re-run shape and blindly append a duplicate section — offer to update the existing section or skip shape (the spec already exists).

Run /shape for the surface described in $ARGUMENTS. Shape produces its full five-step output (content inventory, ASCII layout, state list, open questions).

Persist in pipeline (default): Inside the /sddesign pipeline, shape's Step 6 spec persist is the default — it is auto-confirmed unless the user explicitly opts out of the spec gate. The persist writes .ui-craft/spec.md (or appends the surface section). This is the whole point of the pipeline.

• Persist completes → .ui-craft/spec.md is written (or the surface section is appended). Mark [✓] shape (spec).
• User explicitly opts out of persist → mark [–] shape (spec, unsaved). Note downstream impact: "no spec.md → craft (build) will build against shape's printed output; acceptance bar will not be persisted."

Gate 4 — Craft (build)

Run /craft <surface> where <surface> matches the description in $ARGUMENTS.

/craft declares the Craft Read (references/craft-intent.md) before building — surface kind, audience, theme/accent, DESIGN_VARIANCE, and the one signature bet. The signature bet is built inside this gate, not deferred to converge or polish. If the spec section names a composition, the Craft Read must be consistent with it.

/craft loads .ui-craft/spec.md before building. If [✓] shape (spec) was set, the spec's chosen composition, component inventory, state lattice, and acceptance bar take precedence over recipe defaults — every acceptance bar item from the spec must be green before craft reports done.

If [–] shape (spec, unsaved), craft builds against the shape output printed to the terminal. Note in the checklist.

Mark [✓] craft (build) when the build completes.

Gate 5 — Converge

Run the visual-anti-slop preset from ../skills/ui-craft/references/loops.md. This iterates — evaluate → fix one → re-evaluate — until the zero-critical gate passes or the budget is exhausted (default budget: 3 iterations).

• If the loop gate passes (zero critical findings) → mark [✓] converge.
• If budget exhausted with open findings → mark [>] converge (open findings). List unresolved findings from the loop report.

Gate 6 — Ship

Run /finalize verdict. Finalize reports READY / NOT READY / BLOCKED based on the 10-pass finish bar and the brief/token gate.

Print the final verdict and the complete resolved checklist:

[✓] brief   [✓] tokens   [✓] shape (spec)   [✓] craft (build)   [✓] converge   [✓] ship

Degraded-mode honesty. If any gate was marked [–], list them in the ship verdict with their downstream impacts:

"Skipped gates: tokens (skipped) → token spine not validated; shape (spec, unsaved) → acceptance bar not persisted. These gaps reduce the ship verdict's confidence."

---

Precedence

Brief §6 learned constraints and the a11y/correctness floor take precedence over spec.md composition choices at every gate. If a constraint conflicts with a spec.md decision, the constraint wins — update the spec section to reflect the winning choice and note the brief §6 reference.

Next step: Ship. The pipeline already walked rungs 1 to 3; .ui-craft/spec.md is the record for the next session.