# 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.

## 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](https://github.com/SteerSpec/strspc-sync/releases/tag/v0.4.5) 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: https://steerspec.dev/how-to/ai-config-drift.md

## 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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/README.md)). 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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/configuration.md#writing-the-deployment-state)).
- 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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/configuration.md#authentication), since [v0.4.3](https://github.com/SteerSpec/strspc-sync/releases/tag/v0.4.3)).
- strspc-sync is [Apache 2.0](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/LICENSE) licensed. Its behaviour is specified by the `dev.steerspec.sync` realm, whose rules are Draft ([rules](https://github.com/SteerSpec/strspc-sync/tree/v0.4.5/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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/quickstart/templates/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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/quickstart/steerspec-sync.yml) 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.

```yaml
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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/configuration.md#authentication)). An App is confined to the repos it is installed on ([quickstart config](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/quickstart/steerspec-sync.yml)).

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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/configuration.md#writing-the-deployment-state)). 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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/quickstart/workflows/steerspec-sync.yml) with its comments removed and the action pin moved from `v0.4.1`, which the docs still show, to the [v0.4.5](https://github.com/SteerSpec/strspc-sync/releases/tag/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.

```yaml
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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/how-it-works.md)). 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](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/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 (https://steerspec.dev/how-to/ai-config-drift.md), and `conflict` flags contradictions between AI config files across the fleet ([commands](https://github.com/SteerSpec/strspc-sync/blob/v0.4.5/docs/commands.md)). strspc-sync works without the rest of SteerSpec; SteerSpec 101 (https://steerspec.dev/how-to/101.md) covers rules and realms, and concepts (https://steerspec.dev/concepts.md) defines sync and drift. Listing: [GitHub Marketplace](https://github.com/marketplace/actions/steerspec-sync), companions: https://steerspec.dev/companions.md
