design-md — visual design-system picker

All paths below: <skill> = this skill's directory, <run> = .design-md/ in the target project root. All generated state lives under <run>; the only file written outside it is the final design.md.

Phase 0 — Run gate

1. If <run>/run.json exists with status != "complete": ask the user — resume this run (keep candidates, re-serve the picker) or clean restart (delete <run>, keep backups/)?
2. If design.md exists at project root: warn that finishing this run will replace it (a timestamped backup is made in <run>/backups/). Confirm before continuing.

Phase 1 — Interview

Follow <skill>/reference/interview.md. Write <run>/brief.md.

Phase 2 — Directions & fixture

1. Pick 4-6 divergent directions per <skill>/reference/directions.md.
2. Write <run>/fixture.md: the canonical content every candidate renders — product name, nav labels (4-5), hero headline + subline, 3 feature blurbs, 3 testimonial-style proof lines, CTA text, a 5-row × 4-col data table, form fields (name, email, one select, one textarea, submit), footer lines. Derive all copy from the brief; never lorem ipsum.
3. Decide the page list from the brief (components is always included and is NOT listed in pages passed to the validator; 2-3 more from: landing, dashboard, form, pricing, docs).
4. Generate a runId: node -e "console.log(crypto.randomUUID())".
5. Write <run>/run.json: { "runId": "<uuid>", "status": "generating", "candidates": ["a","b",...], "createdAt": "<ISO now>" }.

Phase 3 — Generate candidates (parallel)

Dispatch one subagent per candidate, all in a single message so they run concurrently. Each prompt contains, verbatim: the full text of <skill>/reference/candidate-spec.md, the brief, the fixture, the assigned direction row + one-line summary, the page list, and the absolute output directory <run>/candidates/<id>/. Falls back to sequential dispatch if parallel fails — correctness never depends on concurrency.

Phase 4 — Validate

For each candidate: node <skill>/scripts/validate.mjs <run>/candidates/<id> --pages <page,list> (page list WITHOUT components). Regenerate failed candidates once, passing the validator errors into the retry prompt. Proceed with >= 3 valid candidates; below 3, stop and report. Delete invalid leftovers.

Phase 5 — Pick

1. Copy <skill>/assets/picker/ → <run>/picker/.
2. Write <run>/manifest.json: { "runId", "briefSummary" (one line), "pages": ["components", ...], "candidates": [{ "id", "direction", "summary" }] } — valid candidates only.
3. Update run.json status → "picking".
4. Start as a background task: node <skill>/scripts/server.mjs --dir <run> --open.
5. Tell the user the picker is open (URL from the LISTENING <port> line) and that they can also just say their pick in chat.
6. Wait for the background task to exit (server exits after a valid selection), then read <run>/selection.json. If no exit notification within 15 minutes, check for selection.json directly; if absent, ask the user for their pick in chat and write selection.json yourself with the run's runId.

Phase 6 — Distill & finalize

Update run.json status → "distilling", then follow <skill>/reference/distill.md exactly (transactional: tmp file → pinned lint → backup → rename → archive → status "complete").

Phase 7 — Report

Summarize: chosen direction, design.md location, lint status (clean / findings fixed / draft-unlinted), what persists (design.md, <run>/brief.md, <run>/winner/), and that any future agent should read design.md before UI work.

Error handling