Skip to main content
Spec 1.0: This example uses the current stable portable core release.
Use this when you are starting from zero and want clear intent from day one without turning the repo into a planning exercise.

​
Goal

Get one working loop in place early:
  • one current-truth subject
  • one set of requirements
  • one real verification path
  • one CI check that keeps drift visible

​
Smallest good starting point

Pick one user-visible behavior. Good examples:
  • one endpoint
  • one workflow
  • one core module contract
Keep the first subject small enough that one engineer can hold the whole thing in their head. For example, start with one endpoint that has one clear success path and one important boundary case.
  1. Add the .spec workspace for your stack.
  2. Write one subject spec in .spec/specs/.
  3. Keep the first spec narrow:
    • two or three requirements
    • one or two scenarios
    • one verification target
  4. Implement the code, tests, and docs from that contract.
  5. Run the local verification command and keep the same check in CI.

​
Prompt you can give an agent

Draft one small current-truth subject spec for the first user-visible behavior in this repo.

Keep it narrow.
Write two or three requirements, one or two scenarios, and one real verification target.
Do not model the whole project.
End by pointing at the smallest proof we can run in this stack.

​
What success looks like

By the end of the first pass, the repo should have:
  • one clear subject spec
  • tests or commands that prove the key requirements
  • a local verification command that passes
  • a CI check that will fail when code and intent drift apart
That is enough to establish the method.

​
Avoid

  • modeling the whole project on day one
  • writing specs for things nobody understands yet
  • adding a large governance layer before the first verification loop works
  • treating the spec as a substitute for tests

​
Next step

Once the first subject is stable, add the next subject right beside it. That keeps the adoption curve shallow and the method teachable.

​
What to skip

Do not start with:
  • heavy traceability
  • proposal records
  • ADR workflows
  • conformance matrices
  • pre-commit hooks
Those can come later.