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.

Add the monitor workflow ↓

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 monitor action 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 MNRACT entity of the dev.steerspec.sync realm; 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.