steerspec@github:~$

SteerSpec

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

RFC-2119 compliant Apache 2.0

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 — 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, drift is detected rather than discovered, and agents behave the same way everywhere — which is what makes their output reliable enough to scale on.

// How it fits together

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

Rules are validated against a published schema and released as an immutable, hashed rule set. 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 rule set on top of the core one, pinned and verifiable by hash.

Step one, from the strspc-sync README:

name: SteerSpec Sync
on:
  push:
    branches: [main]
    paths: ['templates/**', 'steerspec-sync.yml']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SteerSpec/strspc-sync/sync@v0.2.1
        with:
          token: ${{ secrets.STEERSPEC_TOKEN }}

// 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 rule set. The core rule set 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 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

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

// Implementation status

strspc-sync v0.2.1 was proven end to end (sync, monitor, conflict detection) against a test organization on 2026-10-20. The CLI evaluates pull-request diffs with Claude in the CI of strspc-CLI, strspc-manager and strspc-sync.