steerspec@github:~$

SteerSpec

One source of truth for AI configuration — from a single repo to the whole organization.

A session ends and the agent forgets. A new teammate never knew. A spec in one repo says one thing, a CLAUDE.md in another says something else, and the agents follow whichever they read.

SteerSpec gives people and agents a single source to read from: rules in a realm, not recollections. Versioned, checked in CI, distributed by pull request, checked for drift. Apache 2.0.

Because vibe coding without a spec is just vibing — and it stops working the moment there is more than one of you.

A project by Consulare, Switzerland.

// Solo vs. at scale

One developer, one repo

  • A single CLAUDE.md, edited by hand
  • You remember what you told the agent
  • Vibe coding works

Many teams, many repos, many agents

  • Dozens of copies, each slightly different
  • A convention fixed in one repo never reaches the rest
  • Nobody can say which rules an agent was actually given
  • Changes to agent behaviour have no review and no history

SteerSpec is built for the second column. Rules are versioned, schema-validated data, not prose scattered across repos. The same rules reach every repo by reviewable pull request, and drift is detected rather than discovered. People and agents can read the same rules; SteerSpec does not make an agent follow a rule on its own.

// How it fits together

From rules to agent behaviour Rules are validated against a schema and published as a versioned realm. The sync action turns them into pull requests that update CLAUDE.md, agents, skills and settings in each repository, where the agent reads them. A drift monitor feeds back to sync. Rules entities + schema Realm versioned, hashed Sync PR reviewed, not forced Repo config CLAUDE.md, agents… Agent reads the config drift monitor

Rules are validated against a published schema and released as an immutable, hashed realm. The Sync Action renders them into each repository’s agent configuration, one pull request at a time. The monitor compares what is deployed with what is defined and feeds differences back. Vocabulary: key concepts.

// From one Action to a core principle adopt as far as you need

  1. Drop in the Sync ActionOne central repo, one workflow. Standalone — no spec required.
  2. Centralize templatesCLAUDE.md, agents, skills and settings defined once and rendered per repo.
  3. Write rules as versioned specsEntities and rules with lifecycle states, validated by schema and linted in CI.
  4. Run a realmPublish your organization’s realm on top of the core one, pinned and verifiable by hash.

Step one, with the workflow and config quoted from a tagged release: keep CLAUDE.md consistent across repos.

// Core tools the spec and what enforces it

Rules (strspc-rules)

The canonical rule format, in Python. Entities and rules carry an id, a revision and a lifecycle state, are validated against JSON schemas, and are released as an immutable, hashed realm. The core realm is published on this site.

CLI (strspc-CLI)

Rule authoring and static checking, in Go: render, lint, diff and check, where check runs an AI evaluation with Claude.

Install Homebrew (macOS)
brew install --cask SteerSpec/tap/strspc

Recent Homebrew asks you to trust a third-party tap first: brew trust SteerSpec/tap, then retry. Other platforms: GitHub Releases.

Platform spec (strspc-spec)

The rules that span every SteerSpec repository, written as a SteerSpec realm (dev.steerspec.platform). Six rules cover what no single component can own: dependencies point downward only, releases land upstream first, every repository owns a realm validated in CI, published rules are superseded rather than edited, and rule logic lives in the manager.

Also: the GitHub Actions that deliver and gate the config, and shared Claude Code settings — see companion products.

// 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 in force.
  • IImplementedA rule state: the rule is in force. Whether anything checks it depends on the evaluator in use.
  • 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 keywords based on RFC 2119. 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.

// Spec endpoints

Every release is also served immutably at /rules/v<version>/index.json. For the rules themselves in readable form, see /spec.

// Implementation status

Versions link to the tagged release of each component. The cloud API is planned, not available.