project-scaffold

Scaffolds a complete project spec folder for any new software project. Produces a docs/ folder and a root CLAUDE.md that together act as persistent project memory across Claude Code sessions.

---

What It Creates

CLAUDE.md                   ← Auto-read by Claude Code every session
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
├── 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        ← Copy this for every new feature

---

Installation

1. Download project-scaffold.skill
2. Place it in your Claude Code skills folder:

   ~/.claude/skills/project-scaffold.skill
   

3. Restart Claude Code — the skill is now available automatically

---

Usage in Claude Code

Starting a new project from scratch

Just describe your project. Claude Code will extract what it can and ask only about what's genuinely missing:

scaffold this project — it's a time tracking tool for freelancers,
using Next.js and Supabase

Or with no context at all:

scaffold my project

Claude Code will ask four questions and generate the full folder from your answers.

---

Starting with an existing brief

If you already have a project brief — a PRD, a one-pager, an idea doc, notes from a planning session — drop it into your project root and reference it when running the skill. Claude Code will read it, extract all relevant context, and pre-populate the spec files with as little back-and-forth as possible.

scaffold my project — use brief.md as the source

Any filename works (brief.md, product-brief.md, spec.md, notes.md). Just point Claude Code at it.

---

Recommended Workflow

Before your first build session

Fill in at minimum:

• docs/stack.md — define your tech stack before any code is written
• docs/design.md — define your UI conventions before any components are built

These two files prevent the most common drift in Claude Code sessions — the model making stack and style decisions you didn't intend.

Starting each session

Claude Code reads CLAUDE.md automatically. To give it full context before starting work on a feature, say:

Read the docs/ folder. We're starting on [feature name].
The spec is in docs/features/[feature-name].md.

Adding a new feature

1. Copy docs/features/_template.md
2. Rename it to match your feature (e.g. docs/features/auth.md)
3. Fill in the goal and acceptance criteria
4. Add it to the registry in docs/features.md
5. Then start the build session

Always create the feature file before the session — not during.

Using with Superpowers

If you have Superpowers installed, run writing-plans after scaffolding and before building. It reads your feature file and breaks it into a concrete implementation plan.

If a brief is already in the project root, Superpowers can treat it as a completed design document and skip its brainstorming phase — jumping straight to planning.

---

How CLAUDE.md Works

The generated CLAUDE.md contains standing behavioral rules that Claude Code follows automatically every session:

• Updates session-log.md at the end of every session
• Logs architectural decisions to decisions.md as they're made
• Fills in feature documentation when a feature is marked done
• Keeps data-models.md in sync with schema changes
• Tracks feature status (planned → in-progress → done)
• Documents deploy dependencies in deploy.md and the relevant feature file

You never have to remind Claude Code to do these things. The rules are always there.

---

Where It Fits

Typical flow:

brief (any source) → project-scaffold → build

The skill works standalone. Run it whether you have a brief in hand or are starting from a one-line description.