source-of-truth · Spec-Driven Development for Claude Code

The whole idea in one picture

Every change goes through the same loop

Problem

Four ways AI quietly wrecks a codebase

Without a reference the AI trusts, long-running projects hit these four failures. Each one is blocked by a specific part of the catalog.

Failure 1Rebuilds what already exists

Session #12 doesn't remember session #3 — so it writes a second, slightly different version.

Blocked by READ → "Already exists?"

Failure 2Silently deletes a feature

A refactor drops a capability nobody intended to remove — noticed weeks later.

Blocked by specs + changelog

Failure 3Breaks a contract

Changes behavior without knowing what callers depend on ("improves" a 404 into a 200).

Blocked by Invariants in each spec

Failure 4Drifts off-track

Builds something that violates project principles or was never planned.

Blocked by constitution + roadmap gates

Operation · interactive

Three modes, selected automatically

▸ Click a situation to see which mode fires:

No mode picker, no flags — the skill infers the mode from what's on disk and what you just said.

Run once

BOOTSTRAP

docs/overview.md not yet present

Auto-detect stack, test runner, design system (no prompts)
One interview pass: quality rules, perf budget, mission
Confirm → write catalog + update CLAUDE.md

Before editing code

READ

write / modify / delete — bug fixes included

Read overview → constitution → roadmap → spec + check the record folders
Print the "Catalog check" for you to review
STOP on conflict; proceed only after you approve

After shipping

SYNC

"done" · "merge" · "shipped" · before commit

Read the diff (not the whole repo) → classify changes
Update specs, remove shipped entries from roadmap
Record removals / renames / contract changes as changelog entry files + decision/debugging records when triggered

RE-BOOTSTRAP: catalog exists but constitution.md / mission.md missing → rebuild that file before any code edit. Updating CLAUDE.md during BOOTSTRAP is the highest-leverage step: every future session then reads the catalog automatically.

Mechanism · interactive

Gate chain: each layer guards the one below

▸ Click any layer in the diagram to see what it does:

constitution.md — the rules of the house

Answers: “Are we allowed to build it this way?”

Example: constitution says "stateless API tier" → a session-based login plan is rejected at the gate; JWT gets chosen instead. Changing this file requires your explicit approval + a changelog entry + a decision record.

mission.md — why the project exists

Answers: “Does this actually serve our users?”

Example: problem, target users, value proposition, success metrics. A feature idea that serves nobody in Users shouldn't reach the roadmap. Content comes from you — never invented by the AI.

roadmap.md — what we're doing, in order

Answers: “Is this planned — Now, Next, or Later?”

Example: work not on the roadmap → NOT TRACKED → STOP, add a one-line entry first (takes seconds). Shipped entries leave the roadmap — it shrinks as you ship.

spec-<feature>.md — the contract of each feature

Answers: “What must not break when we touch this?”

Example: "wrong password → 401 with empty body". Any change that breaks a documented invariant stops for your confirmation and gets a changelog entry.

src/ — code, the only place that says “how”

Answers: “How is it implemented?”

Example: algorithms, libraries, file structure live here only. If a spec starts describing how (bcrypt, Redis, class names), that content is in the wrong layer — it belongs in code or spec Notes.

principles gate plans → mission gates roadmap → roadmap gates specs → specs gate code.

Live demo · interactive

Watch READ mode stop a duplicate feature

A real session, step by step. You ask for something that already exists — see how the catalog catches it before a single line is written.

claude — READ modedemo session

$ you: Add an endpoint to search users by their email address. claude: Before touching code I'll check the catalog. (READ mode fires — automatic, code edit requested)

claude: Reading the catalog… ✓ docs/overview.md → index lists a feature: email-search ✓ docs/constitution.md → stack: NestJS + PostgreSQL, no conflicts ✓ docs/roadmap.md → not in Now/Next/Later… because it already shipped

claude: Reading the matching spec… ✓ docs/specs/spec-email-search.md Surface: GET /api/users/search?email= Invariants: case-insensitive match · soft-deleted users excluded · 404 when not found (never 200 + null)

claude: Catalog check: - Constitution: no conflict - Roadmap status: shipped (off-roadmap) - Invariants: 3 documented contracts - Already exists? YES → spec-email-search STOP. Feature already exists at docs/specs/spec-email-search.md. Modify it, or is this genuinely different?

$ you: Oh right — just add fuzzy matching to the existing one. claude: Adding email-search-fuzzy to roadmap `Now`, then extending the existing endpoint. All 3 invariants preserved.

Outcome: zero duplicate code written, existing contracts intact, roadmap still true. Without the catalog you'd now have two search endpoints slowly drifting apart.

The 5 STOP rules of READ mode

Situation	Response
Feature already exists	STOP. "Already exists at `<path>`. Modify it, or is this genuinely different?"
Breaks a documented invariant	"Breaks invariant `X`. Confirm (goes in the changelog) or rethink?"
Violates the constitution	"Conflicts with `<principle>`. Update the constitution first, or change approach."
Not on the roadmap	STOP. Add a roadmap entry (Now/Next) first — unless you explicitly override.
Spec points to a missing file	"Spec `X` references a missing file — sync first?" Never silently self-corrects.

Structure · interactive

Four docs, four folders. That's the whole system.

▸ Click any file in the tree to preview its exact format:

docs/click a file

docs/
├─ # index — points to everything
├─ # principles & tech stack
├─ # why the project exists
├─ # Now / Next / Later
├─ changelog/ # one file per entry — no conflicts
│ └─ # removals · renames · contracts
├─ decisions/ # why we chose it — created on first entry
├─ debugging/ # how we found that bug — created on first entry
└─ specs/
└─ # one per feature

docs/overview.mdpreview
# Spec catalog — my-project

## Project docs
- [Constitution](constitution.md) — principles, stack
- [Mission](mission.md) — problem, users, value
- [Roadmap](roadmap.md) — delivery plan
- [Changelog](changelog/) — removals, renames
- [Decisions](decisions/) — why, across features
- [Debugging](debugging/) — root causes worth keeping

## Feature specs
- [jwt-authentication](specs/…) — JWT + refresh
- [email-search](specs/…) — search by email

# summaries only — never a detail dump.
# touched only when a feature is added /
# removed / renamed, or a record folder's
# first entry.
# Constitution
_Changes require user approval._

## Tech Stack
- Language: TypeScript on Node 22
- Framework: NestJS 10 · DB: PostgreSQL 16
## Code Quality
- No `any` types in new code
## Testing Standards
- ≥80% coverage on src/, blocking
## UX Consistency  ·  ## Performance
- _TBD: p95 latency budget?_ ← unknown =
  marked, never invented
# Mission

## Problem
Ops teams juggle 6 dashboards to answer
one question.
## Users
- On-call engineer: needs answers in <1 min
## Value proposition
One query instead of six dashboards.
## Success metrics
- Time-to-answer < 60s

# comes from YOU in the bootstrap
# interview. AI never fabricates this.
# Roadmap
_Forward plan only — shipped work leaves._

## Now   (≤3 in flight, each has a spec)
- [ ] email-search-fuzzy — fuzzy match
      — [spec](…) — _started 2026-07-10_
## Next  (spec'd, queued)
- [ ] rate-limiting — per-key limits — [spec](…)
## Later (idea pool, no spec yet)
- [ ] sso-login — SAML for enterprise

# one line per entry. detail → the spec.
# one flat file per (date, feature) —
# parallel sessions never merge-conflict.
# no title / date heading: the filename
# carries both.

### Contract changed
- email-search — Old: 200+null on miss.
  New: 404. Migration: handle 404.

# sibling: 2026-07-08-csv-export.md (### Removed)
# answers ONE question: "was this removed
# on purpose, or did the AI forget it?"
### Feature: email-search
- Status: active · Roadmap: shipped
- Source files: src/users/search.ts
- Last verified: 2026-07-08 @ 8cb70b0

## Plan       # why + chosen approach
## Requirement # surface + invariants
- Invariants: case-insensitive ·
  soft-deleted excluded · 404 on miss
## Validation # checkable by reading
- Given unknown email → 404.

# full anatomy in the next section ↓

Heart of the catalog

Anatomy of a spec

One spec-<feature>.md per feature: header + 3 sections (+ optional Notes). Goal: someone who has never seen the code understands why it exists and which contracts must not break.

docs/specs/spec-jwt-authentication.md

### Feature: jwt-authentication
- Status: active   Roadmap: shipped
- Last verified: 2026-04-30 @ a1b2c3d

## Plan          # why + approach
JWT chosen over sessions — constitution requires
a stateless API tier. Non-goal: SSO.

## Requirement
- Surface: POST /api/auth/login · /refresh
- Invariants:
  - Wrong password → 401 empty body
  - Email comparison is case-insensitive
  - WHEN /refresh with a valid token
    THEN the old token is revoked
    AND a new token is issued in the same transaction

## Validation      # verifiable by reading alone
- Given wrong password → 401 empty body.
- Given refresh token reused → 401.

## Notes         # gotchas code doesn't document
Do not cache decoded JWTs — revocation requires
a DB lookup on every request.

Quiz: Invariant, or implementation detail?

Invariants = only what a caller can observe without reading source. This is the #1 thing people get wrong — try it:

Question 1 / 6Score 0

Litmus test: if rewriting the code in another language would change the bullet → it's implementation detail, move it to Notes. And if you can't prove it from code or tests, don't write it.

Progressive rigor: a short spec is right for ~80% of features. Expand to WHEN/THEN/AND only when: a past regression · race/ordering concern · compliance · ≥2 clients · an AI misread it before. Length is not quality. Every Validation criterion must trace to an Invariants bullet.

SYNC mode

After shipping: reconcile the diff → update the catalog

SYNC reads the diff (never the whole repo), classifies each change, and shows you the catalog diff before writing anything.

Change type	Catalog action
New feature	Create `spec-<name>.md` + remove from roadmap + add to overview
Feature update	Update spec; Requirements changed → changelog entry
Remove feature	`Status: removed` + changelog `### Removed`
Rename feature	Rename spec file + roadmap + changelog `### Renamed`
Internal refactor	Update `Source files` if files moved — don't touch overview/roadmap, unless it embodies a cross-cutting decision → decision record (can touch overview via its first-entry link)
Tech stack change	Surface to you → constitution + changelog only after you confirm

scripts/sync_helpers.shbash

# changed files + commit hash + today's date
bash scripts/sync_helpers.sh diff
# pre-formatted "Last verified" line for a spec
bash scripts/sync_helpers.sh stamp
# find specs pointing to missing files
bash scripts/sync_helpers.sh stale

Commit gate: asking to commit is itself a SYNC trigger — SYNC completes before the commit so code and catalog land together. Automatic, not a question.

The changelog (one file per entry) records only 4 event types: Removed · Renamed · Contract changed · Constitution change. It answers one question: "was this removed intentionally, or did the AI forget it?" New features and safe refactors don't need an entry.

Hard rule

Iron-rule: every unit of work gets a roadmap entry

Every change — feature, refactor, and bug fix — gets a one-line roadmap.md entry before code is written. It exists to stop the AI from rationalizing "too small to record" — untracked small changes are exactly how the roadmap drifts and the gates decay. It is not a way to overrule you: you own the project.

✗ Violation

AI skips it unilaterally because "it seems minor"
Silently shipping something not on the roadmap
Treating urgency as permission to skip

✓ Valid

Add the entry (takes seconds), then move fast
You, knowing the rule, explicitly override (e.g. live hotfix)
→ proceed + retroactive roadmap/changelog entry after

Discipline

No fabrication · No full-repo reads · No silent edits

An AI-maintained catalog is only trustworthy if it refuses to fill in blanks. These are the red flags the skill self-enforces.

Reading the entire codebase. READ reads catalog files; SYNC reads the diff; BOOTSTRAP caps at ~15 files (per package in a monorepo).

Fabricating invariants. Not visible in code or tests → don't assert it. Tests are the best source of invariants.

Inventing constitution/mission content. Must come from you; _TBD:_ is fine, fabrication is not.

Updating overview for every change. It's an index — touch it only on add / remove / rename, or a record folder's first entry.

Silently editing the constitution. Stack changes need your confirmation; principle changes need an explicit request.

Skipping READ for a "simple" bug fix. Bug fixes break invariants more often than features do.

Slug naming: lowercase kebab-case verb-noun (jwt-authentication, email-search) · flat namespace · no abstract names (util, core) · no bare nouns (user → user-creation).

Where it fits

Works well with superpowers & spec-kit

source-of-truth is a catalog, not a workflow engine. The methodology produces the work; the catalog keeps the source of truth honest across sessions.

superpowersDrives how you work — brainstorming → planning → TDD → review. Each cycle READs the catalog before coding and SYNCs after shipping.

spec-kitGenerates specs & plans up front. source-of-truth turns those one-off specs into a living catalog that stays in sync as the project evolves.