Skip to main content
Spec 1.0: This page reflects the current stable portable core release.
Spec Led Development is not just “write a spec.” It is a working loop:
  1. make the change
  2. add or tighten the proof
  3. reconcile the current truth
  4. verify that the effects still match the spec
  5. keep the same check in CI
Without that loop, the spec is just another document.

​
1. Make the change

Start small. Change one feature, one bug, one workflow step, or one subject boundary. That keeps the next reconciliation step manageable.

​
2. Add or tighten the proof

Once the change is clear enough, add or tighten the smallest test, guide, or command that proves it. Tests are not peer truth with the spec. They are evidence that helps the repo prove the current truth.

​
3. Reconcile current truth

Start with the smallest subject that matters. That might be:
  • one endpoint
  • one module
  • one workflow
  • one package-level contract
Author current truth in .spec/specs/*.spec.md. The portable core keeps five claim types:
  • subject
  • requirement
  • scenario
  • verification
  • exception
The authored layer says what must stay true. Once the change is clear enough, implement code, tests, and docs against it. Humans and agents can both work in this step. The spec gives both of them the same target. That is important. The value is not that an agent can read a spec. The value is that humans and agents now have one shared contract to work from. In a mature workflow, this is where a guided step helps. For example, specled_ex provides mix spec.prime for session-start context and mix spec.next to point at the next subject, proof, or ADR update for the current Git change set.

​
4. Verify the result

Verification turns the spec into something operational. The repo checks whether the implementation still matches the authored claims. That check can point at:
  • source files
  • tests
  • guides
  • commands
The exact command depends on the implementation for your stack.

​
5. Keep the loop live

The same check should run locally and in CI. That is how the repo creates back pressure when code changes but intent, tests, or docs do not move with it. This is how drift gets caught early instead of staying hidden.

​
How this helps review

This loop also makes pull requests easier to review. When a behavior-changing pull request includes the spec update, the reviewer gets three clear things:
  1. the spec states the intended current truth
  2. the code shows the implementation
  3. CI shows whether the repo can prove the co-change
That is better than asking a reviewer to infer intent from code and tests alone. The spec is not a replacement for the pull request description. The pull request description still explains scope, risk, and rollout. The spec explains what should now be true in the repository.

​
How this relates to TDD

There is overlap, but they are not the same thing. TDD focuses on executable behavior through tests. Spec Led Development adds a repo-level current-truth contract that code, tests, docs, review, and CI can all point at. It is not a replacement for TDD. It is a wider coordination layer around behavior and proof.

​
Current truth versus derived state

Spec Led Development keeps authored and derived information separate. Authored current truth:
  • .spec/specs/*.spec.md
Derived state:
  • .spec/state.json
The authored files describe the intended state. The derived state records what the tooling found on the last run. That separation matters. It keeps the source contract stable while findings and coverage details change over time.

​
The practical workspace

The portable core is intentionally small. At minimum, a workspace centers on: 
.spec/
  specs/
    *.spec.md
  state.json
Some implementations also scaffold:
  • .spec/README.md
  • .spec/AGENTS.md
  • .spec/decisions/*.md
Those extras help real teams, but the core model stays small. Supporting docs may help humans and agents plan work, but the spec is still the contract the repo verifies.

​
Where humans and agents fit

Humans still lead. Humans decide:
  • what the system is for
  • what must stay true
  • where ambiguity needs to be resolved
Agents can help:
  • draft specs
  • implement code
  • update tests
  • repair drift
But they should work inside the loop, not outside it. That is the operating model.

​
Proven lessons, tighter loop

This is built on proven software engineering lessons. Fred Brooks argued for conceptual integrity. Martin Fowler pushed teams toward small, evolutionary design and concrete behavioral examples. Spec Led Development keeps those lessons, but gives the repo a tighter reconcile loop for local work, review, and CI.