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

| File | Purpose | |---|---| | ./spec/project_overview.md | ~5-page narrative spec, no tech, 8 sections | | ./spec/user_flow.md | Mermaid flow + complete page hierarchy with states + per-page descriptions | | ./spec/design_prompts.md | Copy-paste-ready text for Claude Design's design system creation form (2 fields) |

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 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 userflow.md and designprompts.md, mermaid that doesn't render, length way off the 5-page target.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MichaelTheMay
• Source: MichaelTheMay/claude-scaffold-spec
• License: MIT

Install and usage instructions live in the source repository linked above.