Skip to main content
Spec 1.0: This page reflects the current stable portable core release.
Start smaller than you think. Do not begin by trying to specify the whole repo. The best first step is one subject, one small reconcile loop, and one clear piece of behavior that matters. A good first pass looks like this: choose one subject, make one small change, tie it to real evidence, reconcile the current truth, and run the check before you widen the scope.

​
The shortest path

  1. Choose one important subject.
  2. Add the .spec workspace with the tooling for your stack.
  3. If you are entering an existing repo or branch, get context first. In specled_ex, run mix spec.prime --base HEAD.
  4. Make the smallest code, docs, or test change that matters.
  5. Add or tighten the smallest proof when behavior changed.
  6. Run the guided reconcile step for your stack. In specled_ex, that is mix spec.next.
  7. Update one current-truth subject if needed, then run the strict check. In specled_ex, that is mix spec.check --base HEAD.
That is enough to learn the method. If the change affects behavior, the pull request should usually include the spec update in the same change.

​
Choose your starting point

Greenfield

Start with one feature and one subject instead of modeling the whole system.

Brownfield

Retrofit one critical area first and use current behavior as the baseline.

Bug Fix

Lock the regression into the spec, tests, and checks together.

New Feature

Define the feature boundary first, then implement only what the spec calls for.

​
A good first subject

Pick something that is:
  • user-visible
  • important enough to matter
  • small enough to understand in one sitting
  • already covered by at least some code or tests
Good first candidates:
  • one endpoint
  • one module contract
  • one workflow
  • one package-level behavior

​
A very small example

You do not need much to start. 
---
subject:
  id: checkout.total
  title: Checkout Total
---

## Requirement

`checkout.total.includes_tax`

The checkout total must include tax before payment is requested.
And then tie it to one real proof: 
## Verification

`checkout.total.proof`

- kind: command
- command: run the smallest checkout total test for your stack
That is enough to learn the loop.

​
What not to do first

Avoid these traps:
  • modeling the whole repo on day one
  • writing aspirational specs that do not match shipped behavior
  • adding a lot of process before you have one working reconcile loop
  • treating the spec as a replacement for tests

​
Next steps

Once the first subject is stable:
  • add the next subject near the same surface
  • tighten weak verification
  • add ADRs only when cross-cutting decisions actually need them
  • keep the loop in CI so drift stays visible
If you need command details for your stack, start with Tooling.