# Project Spine Drift

> Use when the user mentions drift, says AGENTS.md / CLAUDE.md / copilot-instructions / Cursor rules are "stale" or "out of date", asks about CI catching docs drift, or says "check if my spine is still current". Runs `spine drift check`, interprets each drift category, and guides resolution. For initial setup use project-spine-kickoff.

- Skill: `tomevault-io/project-spine-drift` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/project-spine-drift`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/project-spine-drift/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/project-spine-drift

---


# Drift detection and resolution

**Goal:** determine whether the generated files still match the current inputs, and if not, help the user pick the right fix for each drift category.

## Prerequisites

- `.project-spine/export-manifest.json` exists. If not, the project was never compiled — switch to project-spine-kickoff.
- CLI ≥ 0.8.1.

## Step 1 — run the check

From the project root:

```bash
spine drift check
```

Exit codes:

- `0` — clean; nothing to do.
- `1` — drift detected; continue.
- `2` — can't check (missing manifest, unreadable inputs); investigate before proceeding.

The command prints a summary with three counters and writes `drift-report.md` + `drift-report.json` under `.project-spine/`.

## Step 2 — interpret each drift category

### Input drift

One or more of: `brief.md`, `design-rules.md`, `tokens.json`, repo profile, or the spine hash itself changed.

**Fix:** `spine compile --brief ./brief.md --repo .` (add the same `--template`, `--design`, or `--tokens` the project uses). This regenerates all exports from the new inputs.

The `[input:tokens]` drift kind fires specifically when the design tokens JSON file (DTCG or Tokens Studio) changed — typical when the design team re-exports from Figma.

### Export hand-edits

A generated file (e.g. `AGENTS.md`) was edited manually after the last compile.

**Two valid responses — ask the user which they want:**

1. **"Accept my edits as canonical"** → the user wants the hand-edit to survive. They must edit the upstream input (`brief.md`, `design-rules.md`, or the workspace template) so a recompile reproduces the edit. Otherwise the next recompile reverts it.
2. **"Discard my edits, regenerate"** → run `spine export --targets all` to rewrite the exports from the stored `spine.json`.

The second option is only safe if the user confirms they don't need the hand-edited text. Never auto-discard.

### Missing exports

A file listed in the manifest isn't on disk (deleted, moved, gitignored).

**Fix:** `spine export --targets all` to regenerate.

## Step 3 — resolve and verify

After applying fixes, run `spine drift check` again. It should report clean.

## CI usage (for automation conversations)

If the user is setting this up in CI:

```yaml
# .github/workflows/spine-drift.yml
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with: { node-version: 20 }
      - run: npm install -g project-spine
      - run: spine drift check --fail-on any
```

`--fail-on` levels: `none`, `any`, `inputs` (only fail on brief/design changes), `exports` (only hand-edits + missing files). Do not use `--push`; it is not routed in the public OSS CLI.

## What to tell the user after resolving

If drift was caused by **input** changes, emphasise: *"This is normal — you changed the brief or repo, so the generated files need to regenerate. The new `spine.json` hash is `<hash>`; keep that visible in commit messages."*

If drift was caused by **hand-edits**, emphasise: *"Hand-edits get overwritten on recompile. The fix is to edit the upstream `brief.md` / `design-rules.md` / template so the content regenerates naturally."*

## What NOT to do

- Do not manually edit `spine.json` to "fix" a hash mismatch. It's content-addressable — any edit desyncs everything.
- Do not suggest ignoring drift. The whole point is early detection.
- Do not recompile as a reflex. Run the drift check first and tell the user what it found before applying any changes.

---
> Source: [PetriLahdelma/project-spine](https://github.com/PetriLahdelma/project-spine) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->