# SteerSpec (full)

One source of truth for AI configuration, from one repo to the whole organization. Specs-driven AI configuration synchronization for GitHub organizations.

One person with one CLAUDE.md is easy. Keeping hundreds of repos, teams and agents consistent is the hard part. SteerSpec treats AI configuration (CLAUDE.md, .claude/agents/, skills, settings) as versioned, schema-validated data: rules are released as an immutable, hashed rule set; the Sync GitHub Action turns them into reviewable pull requests in every repo; the monitor reports drift.

Adoption ladder: 1) drop in the Sync Action, 2) centralize templates, 3) write rules as versioned specs, 4) run a realm.

## Key concepts

- Rule: A single-phrase behavioral constraint or property definition attached to an entity. Rules have an id, a revision, a lifecycle state and a body written with RFC-2119 (https://www.rfc-editor.org/rfc/rfc2119) keywords. https://steerspec.dev/spec/#RUL
- Entity: An object with a unique identity and lifecycle. The unit of organization; every rule belongs to one entity. https://steerspec.dev/spec/#ENT
- Rule Set: All rules of one entity, versioned as a unit. Each entity file carries its own `rule_set` version, timestamp and hash. https://steerspec.dev/spec/#RST
- Note: A supplemental annotation attached to a specific rule. https://steerspec.dev/spec/#NTE
- Realm: A published, versioned collection of entity files plus a manifest. The core realm is `dev.steerspec.core`. An organization can define its own realm on top of it. https://steerspec.dev/spec/#RLM
- Manifest: `rules/latest/index.json`. Lists the realm version and every entity file with a blake3 hash, so consumers can pin and verify. Every release is also served immutably at `/rules/v<version>/index.json`.
- Schema: JSON Schema files that validate entities, realms and the consumer config. Every entity file declares the schema it conforms to.
- Lifecycle state: D (Draft, the only editable state), P (Published), I (Implemented, in force), R (Retired), T (Terminated), A (Abandoned). Transitions are forward-only. https://steerspec.dev/spec/#RULST
- Keywords: Rule bodies use RFC-2119 (https://www.rfc-editor.org/rfc/rfc2119) keywords, extended with `HAS`, `IS` and `DEFINE` (defined by `KWRD-002`, itself a rule in the set). https://steerspec.dev/spec/#KWRD
- SPCFG: The consumer-side configuration, a `.strspc/config.yaml` at the root of a project. It declares which rule sources the project subscribes to and how they are enforced (evaluator settings, fail conditions). https://steerspec.dev/spec/#SPCFG
- Sync: The `strspc-sync` GitHub Action. Pushes central CLAUDE.md, agents, skills and settings into repos as reviewable pull requests. Nothing is force-pushed or auto-merged.
- Drift: A repository's AI configuration diverging from the central definition. The monitor reports it on a schedule; sync reverses it by pull request.
- Two kinds of rules: Rules in the config you sync (what your agents are told) are different from rules about rules (how SteerSpec's own format is specified, published at `/spec/`). The second kind is the spec; the first is what you apply it to.

## Endpoints
- Manifest: https://steerspec.dev/rules/latest/index.json
- Immutable release: https://steerspec.dev/rules/v<version>/index.json
- Entity schema: https://steerspec.dev/schemas/entity/v1.json
- Bootstrap schema: https://steerspec.dev/schemas/entity/bootstrap.json
- Config schema: https://steerspec.dev/schemas/config/v1.json
- Realm schema: https://steerspec.dev/schemas/realm/v1.json
- Reading the rules as an agent: https://steerspec.dev/spec.md
- Changelog: https://steerspec.dev/changelog/

## Components
- strspc-rules (Python): canonical rule format. https://github.com/SteerSpec/strspc-rules
- strspc-manager (Go): lint, diff, eval, resolve. https://github.com/SteerSpec/strspc-manager
- strspc-CLI (Go): rule authoring and checking. Install: brew install --cask SteerSpec/tap/strspc. https://github.com/SteerSpec/strspc-CLI
- strspc-spec: the dev.steerspec.platform realm, six cross-cutting rules (STRSPC-001 to 006): dependencies point downward only, releases land upstream first, every repo owns a realm, CI validates each realm, published rules are superseded not edited, rule logic lives in strspc-manager. https://github.com/SteerSpec/strspc-spec
- strspc-sync: GitHub Action that syncs AI config by pull request. https://github.com/SteerSpec/strspc-sync
- strspc-pr-review: GitHub Action that auto-approves on green checks plus a Copilot verdict. https://github.com/SteerSpec/strspc-pr-review

License: Apache 2.0.