Overview

Spec 1.0: This page reflects the current stable portable core release.

Spec Led Development gives a repo a small current-truth layer plus a verification loop. It keeps intent, code, tests, docs, and review pointed at the same contract. At the core, the repo keeps authored specs in .spec/specs/*.spec.md and derived state in .spec/state.json. If you are new, start with Why for the motivation, Getting Started for the first pass, and Tooling for the package repos and commands.

​

The problem

Software changes faster than shared understanding. That gap shows up as drift:

• code that technically passes but misses the point
• tests that only cover part of the behavior
• docs that go stale
• agent output with weak context

​

The answer

Spec Led Development keeps four things tied together:

1. intent
2. code
3. tests and docs
4. verification

The spec is not the whole system. It is the small contract layer that keeps those pieces aligned.

​

The loop

1. Write current truth in the repo.
2. Build code, tests, and docs against it.
3. Verify that the effects match the spec.
4. Keep the same check in CI so drift does not stay hidden.

​

What stays in the repo

At the core, the repo keeps:

• authored spec files in .spec/specs/*.spec.md
• derived verification state in .spec/state.json

Some implementations also scaffold local workspace guides and ADRs. The public model stays intentionally small.

​

Who it is for

• teams using AI coding agents
• teams that want clearer engineering back pressure
• projects that need a language-agnostic method
• engineers who want something simple enough to teach and strong enough to verify

​

Start Here