Spec-First Development

## How We Build Features

Every feature follows a **spec-first** workflow. The spec starts as a design document, gets refined, guides implementation, and then becomes the feature's documentation when complete. No separate "write the docs after" step — the spec evolves into the doc.

### The Lifecycle

```
idea → draft → approved → in-progress → completed
```

| Stage | What happens | Where it lives |
|-------|-------------|----------------|
| **Idea** | One-liner in the backlog with priority | `content/docs/roadmap/backlog.mdx` |
| **Draft** | Design spec written with architecture, API, trade-offs | `content/docs/roadmap/specs/{name}.mdx` |
| **Approved** | Reviewed and ready for implementation | Same file, `status: approved` |
| **In Progress** | Claimed by an agent or person, branch created | Same file, `status: in-progress`, `assigned-to` set |
| **Completed** | Built, tested, merged. Spec content promoted to feature doc | Feature doc updated, spec gets `status: completed` |

### Why Spec-First

1. **Agents need context.** Before building, the spec tells the agent what to build, why, and how it fits with existing systems. Without a spec, agents make assumptions.
2. **The spec becomes the doc.** When a feature is done, the documentarian promotes the spec's content (architecture, API, design decisions) into the feature doc. The spec stays as a historical record of what was decided and why.
3. **Multi-agent coordination.** When multiple agents work in parallel, specs with file ownership declarations prevent conflicts. The backlog tells agents what to work on; the spec tells them how.
4. **No stale docs.** Because the spec IS the doc-in-progress, documentation can never fall behind implementation.

## Spec Format

Every spec is an MDX file in `content/docs/roadmap/specs/` with this frontmatter:

```yaml
---
title: Feature Name
description: One-line summary.
status: draft | approved | in-progress | completed
priority: P0 | P1 | P2 | P3
created: 2026-03-20
assigned-to: ""
branch: ""
target-doc: /docs/features/entity-system
files-touched:
  - features/entities/server/actions.ts
  - features/entities/types.ts
---
```

### Frontmatter Fields

| Field | Purpose |
|-------|---------|
| `status` | Lifecycle stage. Agents check this before claiming work. |
| `priority` | P0 = blocking/security, P1 = high-value, P2 = quality, P3 = nice-to-have |
| `assigned-to` | Who is working on this (agent session ID, person name, or empty) |
| `branch` | Git branch where implementation is happening |
| `target-doc` | Which feature doc gets updated when this spec completes |
| `files-touched` | Files this spec will modify. Two specs must not overlap without coordination. |

### Spec Body Structure

```markdown
## Problem

What is broken, missing, or suboptimal? Who is affected?

## Solution

What are we building? High-level approach.

## Design

### Architecture
How it fits into existing systems. Key types, data flow, module boundaries.

### API
New functions, endpoints, or tools. Signatures and behavior.

### Migration
What changes for existing data or behavior.

## Trade-offs

What alternatives were considered and why this approach was chosen.

## Acceptance Criteria

- [ ] Specific, testable criteria
- [ ] That an agent can verify

## Files

### New
- `path/to/new/file.ts` — purpose

### Modified
- `path/to/existing/file.ts` — what changes
```

## For Agents

### Before Starting Work

1. Read `content/docs/roadmap/backlog.mdx` to see what needs to be done
2. Check `content/docs/roadmap/specs/` for existing specs with `status: approved`
3. If a spec exists and is approved, claim it by setting `status: in-progress` and `assigned-to`
4. If no spec exists, write one first — do not start coding without a spec
5. Check `files-touched` to avoid conflicts with other in-progress specs

### During Implementation

1. The spec is your source of truth for what to build
2. Update the spec if the design changes during implementation
3. Check off acceptance criteria as you complete them

### After Completing Work

1. Set `status: completed` on the spec
2. The documentarian will promote spec content into the target feature doc
3. The spec stays as a historical record (like an Architecture Decision Record)

### Claiming and Coordination

- If `assigned-to` is empty and `status` is `approved`, you can claim it
- If `assigned-to` is set, that work is taken — find something else
- If `files-touched` overlaps with another in-progress spec, coordinate or work sequentially
- When working in a worktree, set `branch` to your branch name

## Backlog

See the [full backlog](/docs/roadmap/backlog) for all planned work, organized by priority.