scaffold-spec

scaffold-spec

When to use

Invoke me at project genesis — immediately after scaffolding the repo, before any planning or implementation skill (/plan-ceo-review, /plan-eng-review, /office-hours, /design-consultation, etc.).

I do not block other skills. Skip me if you don't want me. But running planning skills without these artifacts means you're working from your head, not a written spec — and downstream skills will keep re-asking the same scoping questions I'd have nailed down once.

What I produce

Where outputs go. All three files are written to ./spec/ relative to the invoking project's cwd — i.e., inside the repository where the user ran /scaffold-spec. Templates (in this skill's ./templates/ directory) are reused across projects and are NOT outputs. Never write outputs into the skill directory.

Generation is parallel. The three files are generated by 3 parallel subagents (see Step 5). A pre-generation "lock decisions" step (Step 4.5) computes the canonical page list, palette, and voice once so all three agents share the same source-of-truth — this is what previously prevented drift via sequential read-back, now done in-memory.

Step 0: Preconditions

The invoking shell's cwd is the project repo. ./spec/ and all three outputs resolve relative to that cwd, NOT relative to this SKILL.md. Do not pass absolute paths into the skill directory.

mkdir -p ./spec
EXISTING=""
for f in project_overview.md user_flow.md design_prompts.md; do
  [ -f "./spec/$f" ] && EXISTING="$EXISTING $f"
done
[ -n "$EXISTING" ] && echo "EXISTS:$EXISTING" || echo "FRESH"

If EXISTS: AskUserQuestion — overwrite all / abort. Honor the choice. (Append/merge is not supported in v1 — too easy to produce inconsistent artifacts. Delete the old files manually if you want to keep parts.)

If FRESH: proceed.

Intake modalities: The user may include links, pasted documents, or screenshots in their initial dump and follow-up responses. Treat all of these as input — read them, factor them into coverage. You don't need to ask "do you have a screenshot?" — let the user volunteer.

Step 1: Intake

Tell the user, verbatim:

"Tell me about your idea. Anything you have — unstructured is fine. Drop links, screenshots, half-thoughts, voice notes you transcribed. The more context up front, the fewer questions later. Type your dump when ready."

STOP. Wait for the user's response. Do not proceed.

Step 2: Fast-path check (run ONCE, only after intake)

After the user's first response, internally rate coverage across the 15 dimensions in §3 below. If ≥ 12 are well-covered, summarize coverage and ask:

"Thorough brief. Covered: [list]. Missing or thin: [list, if any]. Ship now, or refine first?"

If the user replies with a ship keyword (§4 rules) → jump to Step 4.5 (lock) then Step 5 (parallel generation). Otherwise → enter the loop (Step 4).

If coverage < 12: enter the loop silently, no fast-path mention.

Step 3: The 15 dimensions

Track coverage across these systematically. Each maps to one or more artifacts.

Step 4: The feedback loop

ASK ONE QUESTION AT A TIME AND STOP.

This is the most important rule. Each loop turn:

1. Identify the dimension with lowest coverage that is most blocking the next artifact (in dependency order: overview → flow → design).
2. Ask ONE focused question. (Two only if tightly related, e.g. "primary persona + their main job to be done".) Use AskUserQuestion when the answer space is bounded; use free text when open.
3. Special handling for dimensions 10 & 14: Do not ask "what's the visual mood / color palette?" abstractly. Cover dimension 9 (voice) first — palettes/type proposals derive from it. Then propose 3 concrete palettes (hex values) and 2 typography pairings inline, derived from voice. User picks one or asks for variations. Lock the choice — these locked values flow into the Locked Decisions block in Step 4.5 and are then handed to the design subagent in Step 5.
4. After the user responds, update internal coverage. Then ask the next question. Then STOP.
5. Never preemptively generate artifacts. No matter how much you think you know, the user must explicitly signal ship.
6. Every 3 loop rounds, check in: "Covered: [X]. Want to keep refining, or ship?"

Ship keyword detection

Fire only when the user's message matches one of these patterns (case-insensitive, after stripping whitespace):

1. The whole message is exactly a ship keyword, with optional trailing punctuation:

- ship / Ship! / done. / go / ready? / lgtm / generate

1. The message starts with a ship keyword as the first word, followed by a space or punctuation:

- ship it / ship — let's go / done, generate them / go ahead

Ship keywords: ship, done, generate, go, ready, lgtm

Do NOT fire on substring matches inside longer messages:

• •"this will be ready to ship to QA later" → does not fire
• •"I'm not done with personas" → does not fire
• •"let me go grab the screenshot" → does not fire

When in doubt → keep looping. Ask "ready to ship?" explicitly.

When ship signal detected → proceed to Step 4.5 (lock decisions), then Step 5 (parallel generation).

Step 4.5: Lock decisions (run once, right after ship signal, before Step 5)

Before spawning generation agents, compile a single Locked Decisions block. Every generation subagent receives this same block verbatim — it is the source-of-truth that keeps the three files consistent without serial read-back.

The block MUST contain:

• •Project name — final name to use in titles and §1 of each file.
• •One-liner — final 1-2 sentence product description (drives overview §1 and design Field 1).
• •Surfaces — final list (e.g. "iOS + Android mobile only").
• •Primary persona(s) — final names + one-line each.
• •v1 IN-scope — bullet list.
• •v1 OUT-of-scope — bullet list with reasons.
• •Voice adjectives — 3-5 final adjectives.
• •Voice anti-examples — what it must never sound like.
• •Voice anchors — 2-4 reference brands/people.
• •Visual mood — one-line distilled mood.
• •Color palette — concrete hex values for background, surface, surface-elevated, primary text, secondary text, border, accent primary, accent hover, success/warning/error.
• •Typography — concrete typefaces (display / body / mono), scale, line-heights.
• •Canonical page list — every screen + every modal, grouped by feature area, with per-page state list (from the fixed vocabulary). This is THE list — both user_flow.md Section 2 and design_prompts.md Field 2 §5 must use these names in this order.
• •Mermaid graph decision — single (≤30 screens) or master+zoom (>30 screens), counted from the canonical page list.

Where any dimension is thin (user shipped before fully covering it), use smart defaults derived from what IS locked — and note the assumption in the Locked Decisions block so it's auditable.

Render the Locked Decisions block as a short markdown summary the user can scan, then proceed to Step 5 without waiting for further input.

Step 5: Parallel generation (3 subagents)

Spawn three Agent calls in the same message (multiple tool-use content blocks) so they run concurrently. Each subagent is general-purpose, writes exactly one file to ./spec/, and shares the same Locked Decisions block.

For each agent, the prompt MUST include:

1. The full Locked Decisions block verbatim.
2. Absolute path to the template it must read ({skill_dir}/templates/{template_name}.md).
3. Absolute path to the output file in the invoking project's ./spec/ directory.
4. The strict generation rules (strip all HTML comments, replace every {placeholder}, no {...} remaining, follow the template's format exactly).
5. A self-contained brief so the agent does not need to read the other two output files (the page list is in Locked Decisions; design palette/typography are in Locked Decisions; voice anchors are in Locked Decisions).

The three agents:

Agent A — overview

• •Template: templates/project_overview.md
• •Output: ./spec/project_overview.md
• •Length target: ~5 pages of rendered markdown.
• •Sections: 8 (One-liner, Problem, Solution, Users & Journeys, Capabilities, Boundaries, Success Criteria, Voice & Tone).

Agent B — flow

• •Template: templates/user_flow.md
• •Output: ./spec/user_flow.md
• •Use the Mermaid graph decision (single or master+zoom) from Locked Decisions — DO NOT recompute.
• •Section 2 must enumerate the canonical page list verbatim, with states.
• •Section 3 must have one block per page, same order, same names.

Agent C — design

• •Template: templates/design_prompts.md
• •Output: ./spec/design_prompts.md
• •Field 1: derived from One-liner + Surfaces in Locked Decisions.
• •Field 2 §1 foundations: every value comes from Locked Decisions (palette + typography). Do NOT copy example values from the template — those are shape-only.
• •Field 2 §5: one #### [Page name] block per page in the canonical page list, in the same order, with the same names.

CRITICAL — name consistency: Agents B and C MUST use page names byte-identical to the canonical page list in Locked Decisions. This is why the list is locked upstream and passed in — not generated independently in each agent.

After all three agents return, verify:

# All three files exist and are non-empty.
for f in project_overview.md user_flow.md design_prompts.md; do
  [ -s "./spec/$f" ] || echo "MISSING_OR_EMPTY: $f"
done
# No HTML comments leaked.
grep -l '<!--' ./spec/*.md && echo "COMMENT_LEAK"
# No unfilled placeholders.
grep -lE '\{[a-z_ -]+\}' ./spec/*.md && echo "PLACEHOLDER_LEAK"
# Page name parity between flow §2 and design Field 2 §5.
# (Quick check: extract `#### ` headings from design and compare to Section 2 entries in flow.)

If verification fails, fix the offending file with a follow-up targeted Edit — do not regenerate from scratch.

Print:

✓ ./spec/project_overview.md written (~N words)
✓ ./spec/user_flow.md written (N screens, [single|master+zoom] mermaid)
✓ ./spec/design_prompts.md written (N per-page blocks)

Step 6: Confirm

Print:

DONE — spec scaffolded.

  ./spec/project_overview.md  (~5 pages, 8 sections)
  ./spec/user_flow.md         (N screens, [single|master+zoom] mermaid)
  ./spec/design_prompts.md    (2 fields, N per-page blocks)

Next steps:
  - Review the three files
  - Paste Field 1 + Field 2 from design_prompts.md into Claude Design's design system creation form
  - Or run /plan-ceo-review / /plan-eng-review against the spec

Dry-run before trusting on real projects

Before using this skill on something you care about, run it once against a throwaway:

mkdir -p /tmp/scaffold-spec-test && cd /tmp/scaffold-spec-test
# /scaffold-spec
# Use a fake idea. Ship after ~3 questions. Inspect the three artifacts.

Look for: missing sections, drifted page names between user_flow.md and design_prompts.md, mermaid that doesn't render, length way off the 5-page target.