Skip to main content
Start small. A Spec Led document is just a short file that says:
  • what this thing is
  • what must stay true
  • what example behavior should look like
  • what evidence should prove it

​
The core parts

​
Subject

The thing you are writing about. Examples:
  • package
  • module
  • feature
  • service
  • API
  • workflow

​
Requirement

A short rule about what must be true. Good style:
  • clear
  • short
  • testable
  • stable over time

​
Scenario

A concrete example. Good style:
  • Given ...
  • When ...
  • Then ...

​
Verification

The evidence you expect to prove the claim. Examples:
  • a test file
  • a docs page
  • a command
  • a CI check

​
Exception

An approved exception. Anything not represented as an exception should be treated as drift by tooling.

​
Starter file shape

The beta starter path aims at small files inside a specs/ folder. Example: 
# User Login API

This API signs in a user and returns a session token.

```spec-meta
{
  "id": "api.user_login",
  "kind": "api",
  "status": "active",
  "surface": ["/api/login"]
}
```

## Requirements

```spec-requirements
[
  {
    "id": "login.valid_credentials",
    "statement": "When a user sends valid email and password values, the API returns a session token."
  }
]
```

## Scenarios

```spec-scenarios
[
  {
    "id": "login.success",
    "given": ["a valid user account"],
    "when": ["the user sends correct credentials"],
    "then": ["the API returns a session token"],
    "covers": ["login.valid_credentials"]
  }
]
```

## Verification

```spec-verification
[
  {
    "kind": "command",
    "target": "npm test -- login",
    "covers": ["login.valid_credentials"]
  }
]
```

​
What tools should derive

The spec is the ideal state. Tools should derive:
  • findings
  • drift
  • coverage reports
  • action history
  • CI summaries
Those should not be written into the spec file itself.