SteerSpec 101
Write one rule, publish it, then see strspc reject an edit to it. Seven short steps
for engineers, run in a scratch directory with the strspc CLI.
← home · all how-tos · concepts · markdown
TL;DR
- A rule is one constraint. Rules live in an entity, entities in a realm.
- A rule starts as Draft. Once Published,
strspc diffrejects any edit to its body; by default CI fails only on Implemented rules. - Install the CLI, run
strspc init, then create a realm and add a rule. - Lint it, promote it to Published, then edit the body:
strspc diffreportsRD002. - Next: put the same checks in CI, and sync config to your repos with strspc-sync.
Output below is copied as is from a real run. The hint lines that follow
Next steps: are left out to keep the blocks short.
// 1. Concepts in 60 seconds
A rule is one behavioral constraint with an id, a revision and a lifecycle
state. Rules belong to an entity, and a realm is a versioned
collection of entities. States run forward only: D (Draft) is the only editable
state, P (Published) fixes the text (strspc diff rejects edits; nothing locks the file), I (Implemented) is enforced:
violations fail strspc check. Full glossary: concepts. The core realm:
spec.
// 2. Install
On macOS, with Homebrew. Homebrew may refuse a third-party tap until you trust it:
brew trust SteerSpec/tap, then retry. For other platforms, download an archive from
GitHub Releases.
brew install --cask SteerSpec/tap/strspc
// 3. Start a project
strspc init writes .strspc/config.yaml, the project configuration
(SPCFG): which rule sources you use and how they are enforced. The default evaluator is Claude and
needs ANTHROPIC_API_KEY; strspc init --provider null writes a config for
static checks only. The steps below do not call an evaluator.
$ git init -q -b main $ strspc init Initialized SteerSpec in .strspc
// 4. Make a realm and a rule
Create a realm in rules/, add an entity DEMO, then add a rule to it.
New rules start as Draft. Use your own GitHub login for --added-by.
$ strspc realm init --id com.example.demo --title "Demo realm" --dir rules Initialized Realm "com.example.demo" in rules $ strspc realm add DEMO --title "Demo entity" --dir rules Created entity "DEMO" (Demo entity) in rules/DEMO.json $ strspc rule add DEMO --body "The system MUST log every login attempt." --added-by github:alice --dir rules Added rule DEMO-001 (Draft, revision 0) Entity version: 0.1.0 → 0.1.1
// 5. Check it and publish it
Lint validates the entity files against the schema. Promoting moves
DEMO-001 from Draft to Published, which fixes its text (strspc diff rejects edits to it, as step 6 shows; nothing locks the file). Change rules with
strspc rule add and strspc rule promote, not a text editor, so the
entity version and hash stay valid.
$ strspc lint rules No errors or warnings found $ strspc rule promote DEMO-001 --dir rules Promoted rule DEMO-001: Draft → Published Entity version: 0.1.1 → 0.2.0
What is on disk is plain JSON, not a database or an opaque state: you can read it, diff it and review it in a pull request,
and other tools can read it too. The commands above also created a
_schema/ folder next to these files, which the $schema fields point to. The two files in
rules/ after the commands above, in full:
rules/realm.json, the realm:
{
"$schema": "./_schema/realm.v1.schema.json",
"realm": {
"id": "com.example.demo",
"title": "Demo realm",
"version": "0.1.0"
},
"dependencies": [],
"rule_identifier_format": null
}
rules/DEMO.json, the entity with its rule, now Published ("state": "P"):
{
"$schema": "./_schema/entity.v1.schema.json",
"entity": {
"id": "DEMO",
"title": "Demo entity"
},
"rule_set": {
"version": "0.2.0",
"timestamp": "2026-11-09T17:18:05Z",
"hash": "blake3:37f419d5509a6e493ab55dd8c47481baa6ea05b5a9c3ae8befa3d39a578093f1"
},
"rules": [
{
"id": "DEMO-001",
"revision": 0,
"state": "P",
"body": "The system MUST log every login attempt.",
"added_by": "github:alice",
"added_at": "2026-11-09",
"supersedes": null
}
],
"notes": []
}
rule_set.version, timestamp and hash are written by the CLI, which is why step 6's
hand edit fails on them as well as on the rule body. Your timestamp, hash and date will differ.
// 6. See a Published rule resist change
Commit the Published rule, then rewrite its body by hand. strspc diff compares the
working tree with a base commit and exits 1. RD002 is the rejection that matters:
a Published body is immutable, so you supersede the rule instead of editing it. That rejection comes from strspc diff; the default config fails CI only on Implemented rules (fail_on: [I]). The other
three errors appear because a hand edit leaves the version, timestamp and hash unchanged.
The diagnostic codes page explains each one.
$ git add rules .strspc && git commit -qm "publish DEMO-001" $ sed -i.bak 's/MUST log every login attempt/MAY log some login attempts/' rules/DEMO.json $ strspc diff rules/DEMO.json --base HEAD [error] RD007: rule_set.version must be a valid semver and strictly higher than "0.2.0", got "0.2.0" (rules/DEMO.json: DEMO/rule_set.version) [error] RD009: rule_set.timestamp must be updated (rules/DEMO.json: DEMO/rule_set.timestamp) [error] RD002: rule body is immutable in state "P": supersede the rule to change its body (rules/DEMO.json: DEMO/DEMO-001) [error] RD008: rule_set.hash mismatch: computed "blake3:ead641ecde88b141c6b467f8372e08907c79879998e7f3645c5c13b180429161", file has "blake3:37f419d5509a6e493ab55dd8c47481baa6ea05b5a9c3ae8befa3d39a578093f1" (rules/DEMO.json: DEMO/rule_set.hash) 4 error(s), 0 warning(s) Error: diff found 4 error(s)
The hashes above are from one run; yours differ.
// 7. Next: CI and sync
strspc ci init writes the GitHub Actions workflow that runs these checks on pull
requests. --dry-run prints it without writing. To distribute CLAUDE.md, agents, skills and
settings from one central repo to the repos in your GitHub org by pull request, use the
strspc-sync GitHub Action; see
companions.
$ strspc ci init --dry-run
Would write .github/workflows/strspc-lint.yml
name: strspc lint
on:
push:
branches: [main]
pull_request:
branches: [main]
permissions:
contents: read
jobs:
rules:
uses: SteerSpec/.github/.github/workflows/strspc-lint.yml@v1
permissions:
contents: read
pull-requests: read
with:
path: rules/
strict: true
Where next: concepts, the core realm, companions, mapping rules to a standard and the CLI README.