Keep CLAUDE.md consistent across repos in a GitHub org

For platform and engineering teams: write the shared part of CLAUDE.md once, in a central repo, and have it proposed to every repo as a pull request. Each repo keeps its own notes outside the managed sections.

Set up the central repo ↓

TL;DR

  • Every change reaches a target repo as a pull request that its owners review. Nothing is force-pushed or merged for you.
  • Split CLAUDE.md into managed sections (the org standard) and local notes (owned by each repo).
  • Keep the managed sections in one central repo as a template, with a steerspec-sync.yml that lists the target repos.
  • A GitHub Actions workflow runs the strspc-sync action on every push to the template and opens one pull request per template, per repo.
  • A render that has not changed opens no pull request.
  • Next: detect drift when a repo edits its copy afterwards.

// What changes in your repos, and what does not

  • Every change to a target repo lands as a pull request. Sync never force-pushes a git ref and never merges (README). The force option only bypasses the recorded hash check; it does not force-push.
  • The central repo is the exception: after every run, sync commits .steerspec/deployment-state.json straight to the central repo's default branch. If that branch requires pull requests, the identity running sync must be allowed to bypass the ruleset, or the run fails and records nothing (configuration).
  • Commits go through GitHub's createCommitOnBranch mutation, which GitHub signs, so they pass rulesets that require verified signatures with a token or an App (authentication, since v0.4.3).
  • strspc-sync is Apache 2.0 licensed. Its behaviour is specified by the dev.steerspec.sync realm, whose rules are Draft (rules).

// Why copies drift apart

A CLAUDE.md copied into each repo by hand becomes many files with one history each. A fix to the shared standard has to be repeated in every repo, and an edit in one repo is invisible to the others. Two things make the problem tractable: decide which lines are the org's and which are the repo's, and make a single place the source of the org's lines.

// 1. Create a central repo

One repo in your org holds the templates and the configuration, for example your-org/steerspec-config. It also receives the deployment state, the record of what was proposed to which repo.

// 2. Write the template with managed sections

With the marker strategy, sync replaces only the sections between STEERSPEC:BEGIN and STEERSPEC:END markers and leaves the rest of the target file alone. The template below is the quickstart file (CLAUDE.md.mustache); {{org_name}} and the other placeholders are Mustache variables from the configuration.

# {{org_name}} Project Standards

<!-- STEERSPEC:BEGIN:project-standards -->
## Project Standards

- Use {{default_model}} as the default AI model
- Follow coding standards at {{coding_standards_url}}
- Write tests for all new functionality
- Use conventional commits
<!-- STEERSPEC:END:project-standards -->

<!-- STEERSPEC:BEGIN:coding-conventions -->
## Coding Conventions

- Follow the language-specific style guide
- Maximum function length: 50 lines
- All public APIs must have documentation
<!-- STEERSPEC:END:coding-conventions -->

## Local Project Notes

Add project-specific notes below. This section is not managed by SteerSpec.

// 3. List the template and the target repos

steerspec-sync.yml sits at the root of the central repo. This excerpt of the quickstart config keeps the CLAUDE.md template and drops the other templates, the target overrides, the monitor and conflicts sections, and the comments. targets selects repos by name pattern and topic; overrides (in the full file) sets per-repo variables or skips a template for one repo.

version: "1.0.0"

central-repo: acme-corp/steerspec-config

auth:
  method: github-token

variables:
  org_name: "acme-corp"
  default_model: "claude-sonnet-4-6"
  coding_standards_url: "https://acme-corp.dev/standards"

templates:
  - id: claude-md
    version: "1.0.0"
    type: claude-md
    source: templates/CLAUDE.md.mustache
    destination: CLAUDE.md
    strategy: marker

targets:
  include:
    - "acme-corp/*"
  exclude:
    - "acme-corp/archived-*"
    - "acme-corp/.github"
    - "acme-corp/steerspec-config"
  topics:
    - claude-managed

sync:
  concurrency: 5
  pr-label: steerspec-sync
  close-stale-prs: true

// 4. Give sync a token that reaches the other repos

The workflow's own GITHUB_TOKEN is scoped to the central repo and cannot open pull requests anywhere else. Store a PAT, or use a GitHub App installation, with contents and pull_requests write on every target repo (authentication). An App is confined to the repos it is installed on (quickstart config).

Sync also commits .steerspec/deployment-state.json straight to the central repo's default branch after every run, so the same credential needs contents write there too. If a ruleset or branch protection on that branch requires pull requests or status checks, the identity running sync must be allowed to bypass it; otherwise the run fails with deployment state not saved (configuration). The quickstart's App permissions are Contents, Pull requests and Issues, each read and write.

// 5. Add the sync workflow

This is the quickstart workflow with its comments removed and the action pin moved from v0.4.1, which the docs still show, to the v0.4.5 release. Pin an exact tag, never a branch. For a first run, set dry-run: true to preview the changes without opening pull requests.

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

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: SteerSpec/strspc-sync/sync@v0.4.5
        with:
          dry-run: false
          token: ${{ secrets.STEERSPEC_TOKEN }}

// 6. Review the pull requests

Each target repo gets one pull request per template, titled chore(steerspec-sync): update <template-id> to <version>; the type and scope are configurable for repos with stricter commit rules (how it works). The repo's owners review and merge it like any other change. To change the standard later, edit the template, raise its version (it appears in the pull request title) and push: the workflow proposes the new text to every target whose copy differs from it.

// Where SteerSpec fits

strspc-sync is the SteerSpec GitHub Action for this job, and SteerSpec uses it on its own repos: the org-standards section of strspc-sync's CLAUDE.md is a managed section synced from a central repo. The quickstart configuration also distributes .claude/agents/, .claude/skills/ and .claude/settings.json. Two companion commands run after sync: monitor reports files that have drifted from their template (see detect drift), and conflict flags contradictions between AI config files across the fleet (commands). strspc-sync works without the rest of SteerSpec; the SteerSpec 101 covers rules and realms, and concepts defines sync and drift. Listing: GitHub Marketplace, companions.