project-scaffold

name

project-scaffold

description

Scaffolds a complete project spec folder structure for any new software project. Use this skill at the start of every new project, or when a user wants to set up a structured planning system for Claude Code. Triggers on phrases like "start a new project", "scaffold my project", "set up my spec folder", "create project docs", "new project structure", "set up Claude Code for my project", or any time someone is kicking off a new build and needs a planning framework. Also trigger when someone asks how to keep Claude Code context consistent across sessions. This skill creates all planning files, a features subfolder, and a CLAUDE.md with behavioral rules baked in — so the AI maintains docs automatically.

Project Scaffold Skill

Scaffolds a complete, stack-agnostic project spec system for use with Claude Code. Produces a docs/ folder and a root CLAUDE.md that together act as persistent project memory across sessions.

---

What This Skill Creates

CLAUDE.md                   ← Root behavioral rules file (auto-read by Claude Code)
docs/
├── overview.md             ← Product vision, customer journey, value prop
├── stack.md                ← Tech stack, infra, key dependencies, CI/CD
├── features.md             ← Feature registry with status and priority
├── design.md               ← Design system, UI conventions, aesthetic rules
├── data-models.md          ← Key entities, relationships, field names
├── integrations.md         ← External services, APIs, gotchas
├── decisions.md            ← Architectural decision log (ADR)
├── deploy.md               ← Deploy process, pipeline steps, manual steps
├── session-log.md          ← Per-session log of what was done and what's next
└── features/
    └── _template.md        ← Template to copy for each new feature

---

Process

Step 1: Determine Input Mode

Three ways a user can provide context. Detect which applies and handle accordingly.

---

Mode 1: product-brief.md is present

Check whether a product-brief.md from the idea-validator skill is present — referenced in the conversation, uploaded, or found in the current directory.

If found, extract:

• Project name → "The Idea" section
• One-liner → "The Idea" section
• ICP → "Ideal Customer Profile" section
• Stack → "Technical Design" section if present, otherwise TBD
• First feature(s) → infer from "The Wedge" section
• Early decisions → "Assumptions and Risks" and "Planning Report" sections

Confirm what was extracted in one short message. Ask only about anything genuinely missing. Then proceed.

---

Mode 2: User provides a freeform description

The user writes a description — a sentence, a paragraph, or several. No structured file, just plain text.

Extract everything you can from what they wrote. Then ask only about what is genuinely missing and cannot be inferred. Maximum two follow-up questions.

If stack is unclear, mark it TBD and move on — do not block file generation on it.

Example: if someone writes "I'm building an invoicing tool for freelancers using Next.js and Supabase" — you have everything needed. Generate the files immediately.

---

Mode 3: No context provided

Ask four questions only:

1. Project name — what are we calling this?
2. What it does and who it's for — one sentence
3. Stack — any preferences, or TBD?
4. First feature — what's the first thing being built?

Do not ask more than four questions. Mark anything unanswered as TBD in the files.

---

Step 2: Generate All Files

Use the templates in assets/templates/ as the base for each file. Populate what you know from the interview. Leave clearly marked <!-- TODO --> placeholders for everything else.

Generate files in this order:

1. CLAUDE.md
2. docs/overview.md
3. docs/stack.md
4. docs/features.md
5. docs/design.md
6. docs/data-models.md
7. docs/integrations.md
8. docs/decisions.md
9. docs/deploy.md
10. docs/session-log.md
11. docs/features/_template.md
12. docs/features/<first-feature>.md (if first feature was provided)

---

Step 3: Present, Confirm, and Hand Off

List the files created with a one-line description of each.

Then tell the user:

1. Fill in the TODOs before your first build session At minimum, complete docs/stack.md and docs/design.md before writing any code. These prevent the most common drift — Claude making stack and style decisions you didn't intend.

2. If Superpowers is installed, run writing-plans next Use the writing-plans skill to break your first feature file into a concrete implementation plan before starting the build. If a product-brief.md exists in the project, Superpowers will treat it as a completed design document and skip brainstorming entirely.

3. One feature file per feature, always Copy docs/features/_template.md for each new feature. Fill in the goal and acceptance criteria before the build session starts — not during.

---

Then ask: "Do you want to fill in any of the TODO sections now, or are you ready to start?"

---

CLAUDE.md Behavioral Rules

The generated CLAUDE.md must include these standing instructions:

## Session Rules

At the end of every session:
1. Update `docs/session-log.md` — date, what was completed, what's next, blockers
2. If any architectural decision was made, log it in `docs/decisions.md`
3. If a feature was completed, fill in its `## Documentation` section
4. If a schema or data model changed, update `docs/data-models.md`
5. Keep feature status fields current (planned → in-progress → done)
6. If any new env vars or deploy steps are required, document them in the feature file and `docs/deploy.md`

These rules are non-negotiable — include them verbatim in every generated CLAUDE.md.

---

Template Reference

Read the templates in assets/templates/ before generating each file. They contain the section structure and placeholder patterns to use.