Core Model - Spec Led Development

Spec 1.0: This page reflects the last published portable core release.

The core model is intentionally small. It tries to answer one question: What is the smallest specification model that is still useful for humans, agents, and verification tooling? The answer is five claim types.

The five claims

Claim	Job	Question it answers
`subject`	defines what is being specified	what part of the system is this spec about?
`requirement`	states what must stay true	what is required behavior?
`scenario`	makes a requirement concrete	what does that requirement look like in practice?
`verification`	points at evidence	how do we prove this claim is being followed?
`exception`	records an approved deviation	where is a deliberate gap or temporary deviation allowed?

Why only five?

Because the model needs to stay portable. If the core grows too large, it gets harder to:

teach
maintain
port across languages
keep aligned with real repos

So the core does not try to model every planning or governance need. It focuses on current truth and proof.

How the pieces connect

A typical subject spec works like this:

spec-meta defines the subject
spec-requirements state what must stay true
spec-scenarios illustrate important cases
spec-verification points at the evidence
spec-exceptions records approved deviations when needed

That gives one clear chain:

what this part of the system is
what matters about it
what the important cases look like
where the proof lives

What the model does not try to do

The portable core does not try to be:

a project management system
a design document template
a control plane for every engineering decision
a replacement for tests

Those things may matter in a real repo. They just should not bloat the portable core.

Practical extensions

Real implementations may add a little more around the core. For example:

local workspace guides
agent operating notes
ADRs for cross-cutting decisions

Those extensions can be useful. They should stay outside the smallest portable model.

Boundary of the core

Use the folders for different jobs:

.spec/specs/ for durable current truth
.spec/decisions/ for durable cross-cutting decisions

Roadmap notes, phase plans, and working documents are often useful too. They should live outside the core spec folder in a clearly non-core location.

The design point

The core model is supposed to be:

small enough to teach to junior engineers
structured enough for tools
simple enough to port across languages
strong enough to create real verification pressure

That tradeoff is deliberate.

​The five claims

​Why only five?

​How the pieces connect

​What the model does not try to do

​Practical extensions

​Boundary of the core

​The design point