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.

Install the CLI ↓

TL;DR

  • A rule is one constraint. Rules live in an entity, entities in a realm.
  • A rule starts as Draft. Once Published, strspc diff rejects 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 diff reports RD002.
  • 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.