Drift Doc — Documentation skill for Claude Code

drift-doc

A [Claude Code](https://claude.com/claude-code) skill that audits whether a project's state documentation — `CLAUDE.md`, `AGENTS.md`, `PLAN.md`, skill/agent READMEs, and agent system-prompt files — still matches the current state of the repository.

It never rewrites docs outright and never invents what changed. A deterministic bash pre-pass (`scripts/audit.sh`) checks documented file paths against git history and flags stale header fields; Claude then applies judgment (`references/judgment.md`) to turn raw findings into a short, actionable report.

What it catches

• Renamed/deleted paths — a doc references old/path.md, but git history shows it was renamed or deleted.
• Missing handoff headers — PLAN.md-style docs missing Status / Owner / Last updated fields.
• Staleness pressure — the doc hasn't been touched in a while, but the code/files it describes have changed since.

What it deliberately does not do

• Never edits source code — only documentation/instruction files.
• Never rewrites a whole document — only proposes targeted diffs.
• Never commits or pushes on your behalf.
• Never flags stylistic differences or intentionally-open roadmap items — only factual mismatches with the current repo state.

Modes

• Review mode (default). Reports findings with diffs; nothing is written until you approve each one.
• Auto mode. Only when you explicitly ask for it (e.g. "auto mode", "sync the docs directly"). Even then, only findings that carry ready-made replacement text (confirmed renames) are applied without asking — everything else still requires a decision.

Requirements

• git, bash, awk, grep, sed — all standard on macOS and Linux. No Python, no other runtime dependency.
• A git repository. Outside a git repo, path-history and staleness checks are skipped and the report says so.

Installation

See [INSTALL.md](INSTALL.md).

Usage

Inside a Claude Code session in your project, just ask something t