# SteerSpec 101

All how-to guides: https://steerspec.dev/how-to.md

Write one rule, publish it, then see strspc reject an edit to it. Commands and output come from a [real run](https://github.com/SteerSpec/strspc-CLI/releases/tag/v1.40.0) in a scratch directory. Hint lines after "Next steps:" are left out.

## 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.

## 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; 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`. Glossary: https://steerspec.dev/concepts.md. Core realm: https://steerspec.dev/spec.md

## 2. Install
On macOS, with Homebrew. Homebrew may refuse a third-party tap until you trust it (`brew trust SteerSpec/tap`), then retry. Other platforms: archives at https://github.com/SteerSpec/strspc-CLI/releases

```
brew install --cask SteerSpec/tap/strspc
```

## 3. Start a project
`strspc init` writes `.strspc/config.yaml` (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` enforces that, as step 6 shows. 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:

```json
{
  "$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"`):

```json
{
  "$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. The other three errors appear because a hand edit leaves the version, timestamp and hash unchanged. Diagnostic codes: https://steerspec.dev/docs/diagnostics.md

```
$ 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. The default config fails CI only on Implemented rules (`fail_on: [I]`); `strspc diff` is what guards a Published body.

## 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](https://github.com/SteerSpec/strspc-sync/releases/tag/v0.4.5) GitHub Action: https://steerspec.dev/companions.md

```
$ 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: https://steerspec.dev/concepts.md, https://steerspec.dev/spec.md, https://steerspec.dev/companions.md, https://steerspec.dev/how-to/standards.md, https://steerspec.dev/how-to.md (all how-tos), https://github.com/SteerSpec/strspc-CLI/blob/v1.40.0/README.md
