AI configuration drifts. A convention agreed in one repo is quietly edited in another, and nobody notices until an agent does the wrong thing. Define CLAUDE.md, agents, skills and settings once, centrally, and they land everywhere as reviewable pull requests — nothing force-pushed, nothing auto-merged. Companion commands report what has drifted since, and flag rules that contradict each other across the fleet.
steerspec@github:~$
SteerSpec
Specs-driven AI configuration synchronization for GitHub organizations.
Your CLAUDE.md drifts. .claude/agents/ mutates. Teams patch configs manually and drift goes undetected until it breaks something. Reconciling AI configuration files across dozens of repos is pure toil.
SteerSpec is a formal specification and toolset that treats AI configuration files the same way you treat infrastructure—as code, versioned, templated, and automatically synchronized. Define once in a central manifest. Propagate everywhere via pull request. Detect drift on a schedule. The toolchain is released and Apache 2.0.
Because vibe coding without a spec is just vibing.
A project by Consulare, Switzerland.
// GitHub Actions standalone — no spec required
A required approving review is standard change management — SOC 2, ISO 27001, or simply your own branch protection rule. It is also what stalls a merge when no second reviewer is free, and what leaves review policy as per-team habit across a large org.
This fills that review slot on evidence rather than on someone clicking approve unread: every check green, and GitHub Copilot’s verdict — a clean review of the current commit, or enough rounds of review. Changes-requested always blocks, and each approval records on the pull request which of the two earned it — the same gate, in every repo.
// Components
- strspc-rules Canonical rule format — Python
- strspc-manager Enforcement engine — lint, diff, eval, resolve · Go
- strspc-CLI Rule authoring and checking — render, lint, diff, check · Go
- SteerSpec/.claude Shared Claude Code agents, skills and settings — plugin marketplace
// The format how to read the JSON
Four concepts, all expressed through a single object type — the Entity.
- EntityAn object with a unique identity and lifecycle. The unit of organization.
- RuleA single-phrase behavioral constraint or property definition attached to an entity.
- Rule SetThe collection of all rules for a given entity, versioned as a unit.
- NoteA supplemental annotation attached to a specific rule.
Rule identifier
The JSON stores id, revision and state as separate
fields. The displayed form is assembled from them:
[ENT-001.0/D]
- ENT-001
"id": "ENT-001" - 0
"revision": 0 - D
"state": "D"
Which brackets and separators to use is itself specified by the RLIFRMT
entity, so the display form is a rendering decision rather than part of the data.
The core realm declares no override, so the documented defaults apply —
that is what /spec renders.
Lifecycle states
Transitions are forward-only. No state is skipped, and each applies at most once.
- DDraftThe only state in which a rule’s body can be edited.
- PPublishedValidated and approved, but not yet enforced.
- IImplementedIn force. The rule is actively enforced.
- RRetiredStill present but scheduled for removal. Superseded by a newer rule.
- TTerminatedNo longer in force. Terminal state.
- AAbandonedTerminal state for rules that never left Draft.
Keywords
Rule bodies use RFC-2119 keywords. SteerSpec extends MUST with
HAS, IS and DEFINE — which is why a rule reads
IS an object that has a unique identity rather than MUST be.
Defined by KWRD-002, itself a rule in the set.
Full definition: SteerSpec Rule Manager — Specification ↗
// Spec endpoints
- /schemas/entity/v1.json Entity schema — full
- /schemas/entity/bootstrap.json Entity schema — bootstrap
- /schemas/realm/v1.json Realm schema
- /schemas/config/v1.json Config schema
- /rules/latest/index.json Rules manifest — current
Every release is also served immutably at
/rules/v<version>/index.json.
For the rules themselves in readable form, see /spec.
// Implementation status
- [✓] Specification — core realm, machine-readable
- [✓] Sync GitHub Action
- [✓] Monitor GitHub Action
- [✓] Conflict detection
- [✓] PR auto-approve Action
- [✓] CLI tool — render, lint, diff, check, realm and rule authoring
- [·] Cloud API