Detect drift in AI agent config files across GitHub repos
For platform and engineering teams that distribute CLAUDE.md, agents, skills and settings
to many repos: find the repos whose copy no longer matches the central standard, on a schedule, with one
issue per drifted repo and template.
← home · all how-tos · concepts · companions · markdown
TL;DR
- Sync writes to target repos only through pull requests, and the monitor opens and updates drift issues and, by default, closes them.
- Drift is a repo's AI config file differing from what the central repo last deployed to it.
- To detect it you need two things: a record of what was deployed, and a hash of what is in the repo now.
- The strspc-sync
monitoraction compares the two on a schedule and opens a GitHub issue for each drifted repo and template. - For files with managed sections, only those sections count, so local notes are not drift.
- To undo drift, re-run sync with
force(the fix still arrives as a pull request; nothing is force-pushed); to keep the local change, copy it into the template.
// What the monitor touches
- The monitor opens a GitHub issue for each drifted repo and template, updates it while the drift lasts and,
with
auto-close: true(the default), closes it once the drift is resolved. Its token therefore needs to read the target repos and open issues; the quickstart workflow and App permissions list Issues read and write. In the sources of the release linked here, the rule MNRACT-006 says the issues open in the central repo and the quickstart monitor workflow comment says the target repos, so grant Issues read and write on both until you have checked a run; the central repo also needs contents read for the deployment state (quickstart config). Its outputs are counts of repos in sync, repos drifted, issues created and issues closed, plus a JSON summary (monitor action). - Sync only ever changes target repos through pull requests that it opens (configuration).
- strspc-sync is Apache 2.0 licensed. The monitor's behaviour is specified by the
MNRACTentity of thedev.steerspec.syncrealm; the MNRACT rules are still Draft (MNRACT).
// Why you cannot detect drift from the file alone
Reading a repo's CLAUDE.md tells you what it says, not whether it was changed after it was
deployed. Detection needs a baseline. strspc-sync keeps one: after every sync it writes
.steerspec/deployment-state.json to the central repo, with each repo's deployed version,
timestamp, pull request number and status, and a BLAKE3 hash for integrity checks. For a template that uses managed sections,
the record holds the section names and the hash of those sections only
(DPLYST,
Draft). The monitor reads that record, hashes the current file in each target repo, and compares
(MNRACT, Draft).
A file shared word for word is easy to compare. A CLAUDE.md usually is not: each repo adds its
own notes. With the marker strategy, the comparison covers only the sections between
STEERSPEC:BEGIN and STEERSPEC:END markers, so an edit outside them is the
repo's business and raises nothing
(since v0.4.4). Setting up the
template and markers is covered in
keep CLAUDE.md consistent across repos.
// 1. Start from a working sync
The monitor compares against the deployment state, so a sync must have run first. If you have not set one up, follow keep CLAUDE.md consistent across repos.
// 2. Configure the monitor
Add a monitor section to steerspec-sync.yml. These values are from the
quickstart config
and match the defaults in
SYNCCFG (Draft): weekly on Monday at 08:00 UTC, the steerspec-drift label, and
issues closed when the drift is resolved. GitHub runs the monitor from the on.schedule cron in the workflow
(step 3), not from monitor.schedule, so change both together.
monitor: schedule: "0 8 * * 1" issue-label: steerspec-drift auto-close: true
// 3. Add the monitor workflow
This is the
quickstart monitor workflow
with its comment removed and the pin moved from v0.4.1, which that workflow still shows, to
v0.4.5. The token must be
able to read the target repos and open issues; the workflow's own GITHUB_TOKEN reaches only
the current repo. workflow_dispatch lets you run it by hand.
name: SteerSpec Monitor
on:
schedule:
- cron: '0 8 * * 1'
workflow_dispatch:
jobs:
monitor:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: SteerSpec/strspc-sync/monitor@v0.4.5
with:
token: ${{ secrets.STEERSPEC_TOKEN }}
// 4. Read the drift issues
Each drift issue names the repository and template, the expected version, the actual version or hash, the related sync pull request and how long ago the drift was first detected. While the drift lasts, the monitor updates the same issue rather than opening another (MNRACT, Draft; the strspc-sync release keeps the first-detected time across updates).
// 5. Resolve it one of two ways
Restore the standard. A plain sync run skips a repo when the rendered template has not
changed since the last deployment, even if the repo's copy has
(how it works). Set
the sync action's force input to true to bypass that check, and narrow it with
target-filter and template-filter. The fix still arrives as a pull request.
- uses: SteerSpec/strspc-sync/sync@v0.4.5
with:
force: true
target-filter: 'acme-corp/api-server'
template-filter: claude-md
token: ${{ secrets.STEERSPEC_TOKEN }}
Adopt the change. If the repo's edit should become the standard, copy it into the central template and push. The next sync proposes it to the other repos.
// Where SteerSpec fits
The monitor is one of three strspc-sync commands, each with its own sub-action: sync opens the pull requests,
monitor reports drift, and conflict flags contradictions between AI config files
across the fleet (commands).
They work without the rest of SteerSpec. The SteerSpec 101 covers rules and realms,
concepts defines sync and drift, and companions lists
the action. Listing: GitHub Marketplace.