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

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:

---
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

Spec Body Structure

## 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 for all planned work, organized by priority.