Keep CLAUDE.md, AGENTS.md and .cursor/rules in sync

Add agentsmesh check and agentsmesh lint to your CI pipeline to catch config drift and validation errors in every pull request.

What drift is

Drift happens when:

Someone edits .agentsmesh/ but forgets to run agentsmesh generate
Someone edits a generated file (.claude/, .cursor/, etc.) directly
Someone adds an unexpected file under a managed generated-output location
A PR merges canonical changes without regenerating
An extends source changes and the project hasn’t refreshed

agentsmesh check detects all of these. It verifies two things against the stored lock: canonical-source drift (the .agentsmesh/ sources vs. the recorded checksums) and generated-output drift (recorded files are re-hashed to catch hand-edits or deletions, and managed output locations are scanned for stale files absent from the lock). Either kind of drift exits with code 1.

Basic CI setup

name: CI

on: [push, pull_request]

jobs:
  agentsmesh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - name: Lint AgentsMesh config
        run: agentsmesh lint

      - name: Check AgentsMesh sync
        run: agentsmesh check

What each step catches

`agentsmesh lint`

Validates canonical config files:

Invalid YAML frontmatter
Missing required fields
Unknown target names
Invalid hook event types
MCP server schema errors
Duplicate rule/command/agent names

Fails with exit code 1 if any lint errors are found.

`agentsmesh check`

Verifies that both canonical sources and generated tool directories match the lock:

Re-hashes .agentsmesh/ sources against the lock’s checksums (canonical drift)
Re-hashes each generated file recorded in the lock’s outputs map (generated-output drift)
Scans configured targets’ managed output locations for stale files absent from the lock
Fails with exit code 1 if either has drifted

Locks written before generated-output tracking existed have no outputs map; check skips output verification and prints a note until you run agentsmesh generate once to upgrade the lock. Pass --no-outputs to skip output verification deliberately — for example, in CI setups that gitignore generated outputs, where every output would otherwise report as removed after checkout.

Automated fix comment

Add a comment to failing PRs explaining how to fix drift:

- name: Check AgentsMesh sync
  run: agentsmesh check
  id: check

- name: Comment on drift
  if: failure() && steps.check.outcome == 'failure'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '**AgentsMesh drift detected.**\n\nRun `agentsmesh generate` and commit the updated files.'
      })

Full example with caching

name: CI

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Lint AgentsMesh config
        run: agentsmesh lint

      - name: Verify AI config is in sync
        run: agentsmesh check

Manual fix workflow

When CI fails with drift:

# 1. Pull the branch
git checkout feature/my-changes
git pull

# 2. Regenerate
agentsmesh generate

# 3. Review what changed
git diff

# 4. Commit
git add .agentsmesh/ .claude/ .cursor/
git commit -m "chore: sync generated AI config"
git push