# Spec-First Development

This folder contains design documents for features in development. Claude reads these to understand what to build and track progress.

## How It Works

1. **Before implementing a feature**, create a spec folder with design docs
2. **Claude reads the design** before writing any code
3. **Progress is tracked** in implementation.md for session continuity
4. **Decisions are recorded** in decisions.md for future reference
5. **Docs are generated** with screenshots when feature is complete

## Starting a New Feature

```bash
cp -r specs/_templates specs/{feature-name}
```

Then tell Claude:
```
"I want to build {feature}. Here's my idea: [description].
Review the codebase and fill in specs/{feature}/design.md"
```

## File Structure

Each feature has:

| File/Folder | Purpose |
|-------------|---------|
| `CLAUDE.md` | Instructions for Claude when working on this feature |
| `design.md` | Source of truth - what to build and how |
| `implementation.md` | Progress tracking - what's done, in progress, blocked |
| `decisions.md` | Architecture Decision Records (ADRs) |
| `prompts.md` | Reusable prompts for common tasks |
| `future-work.md` | Deferred ideas and enhancements |
| `docs/` | Internal documentation with screenshots |
| `docs/screenshots/` | Screenshots captured during development |

## Session Continuity

When starting a new Claude session:
```
"Continue working on {feature}"
```

Claude will read `implementation.md` to pick up where it left off.

## Generating Documentation

When a feature is ready for documentation:
```
"Generate docs with screenshots for {feature}"
```

Claude will:
1. Open the feature in browser
2. Take screenshots of key UI states
3. Save to `specs/{feature}/docs/screenshots/`
4. Update `specs/{feature}/docs/README.md`

## Promoting to Public Docs

When internal docs are ready for customers:
```
"Promote {feature} docs to public"
```

Claude will:
1. Copy content to `docs/{feature}.mdx` (Mintlify format)
2. Move screenshots to `docs/images/{feature}/`
3. Update `docs/mint.json` navigation
4. Adjust language for customer audience

## The Most Important Rule

Every PR must be reviewable in under 10 minutes:
- Max 5-7 files changed (excluding tests)
- Max 500 lines changed
- One focused change per PR

If your change is bigger, split it into multiple PRs.