speckit.companion.living-drift — Claude Code command for spec drift
speckit.companion.living-drift finds capability files that changed after their living spec was last committed. Use it to spot project changes that have not made it back into the spec.
MIT ★ 110 updated 2026-10-19
.claude/commands/speckit.companion.living-drift.mdWhat speckit.companion.living-drift does
The command compares each capability’s files from living-specs.yml with the last commit of its spec, then labels the drift. tracked marks a change that passed through Companion but missed the living spec; unspeced marks a file changed outside that process. Paths covered by the registry’s exempt list are filtered out.
This is a read-only report, and the command always exits with code 0. By default it checks committed history; --working includes uncommitted edits, deletions, and untracked files, while --json returns machine-readable output. If living specs are disabled or there is no config, it reports nothing. Python 3 is required; without python3, the check is skipped, so verify it is available first.
What it helps with
- Find files changed since their capability spec was committed
- Separate missed syncs from changes made outside Companion
- Include uncommitted edits in a drift check
- Pass drift results to tooling or CI as JSON
Example prompts for the agent
- Check which files have drifted from the living specs.
- Include uncommitted changes in the drift report.
- Return the living-spec drift report as JSON.
How to install speckit.companion.living-drift
Manually: put the files in place
.claude/commands/speckit.companion.living-drift.mdCall it with /speckit.companion.living-drift. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/speckit.companion.living-drift.mdCall it with /prompts:speckit.companion.living-drift. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/speckit.companion.living-drift.prompt.mdManually: put the files in place
.gemini/commands/speckit.companion.living-drift.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about speckit.companion.living-drift
How do I install speckit.companion.living-drift in Claude Code?
Add the command file at .claude/commands/speckit.companion.living-drift.md.
What does speckit.companion.living-drift do?
It reports changed files for each living-spec capability and labels how they drifted. It does not edit files or halt the workflow.
Does the command need Python?
Yes, it requires python3. If Python is unavailable, the check is skipped and the host command does not fail.
Source text
speckit.companion.living-drift.md · MIT
--- description: "Report living-spec drift — per capability, the source files changed since the spec was last committed (opt-in, never halts)" --- # Spec Drift Show, for each living-spec capability, the source files that changed since that capability's spec was last committed — and **how** each one slipped. A living spec only stays honest if changes to its area flow back into it; this command surfaces the ones that didn't. **Read-only** — it never edits anything, and it **never fails** (always exits success). A surrounding workflow or CI may treat findings as a gate; the command itself does not. This is **opt-in**. With living specs disabled (or no config), it reports nothing and exits clean. ## Prerequisites - Verify Python is available by running `python3 --version`. - If `python3` is not available, warn the user and skip: `[companion] Warning: python3 not detected; skipped drift`. Do not fail the host command. ## Execution Run the drift detector from the repository root: ```bash python3 .specify/extensions/companion/scripts/drift.py ``` The script reads the capability registry (`living-specs.yml`), reuses the resolver for capability membership, and uses git to find what changed since each capability's `capabilities/<name>/<name>.spec.md` was last committed. Each drifted file is classified: - **`tracked`** — the file went through the Companion pipeline (it appears in a `specs/*/.spec-context.json` changed set) but was never folded back into the living spec → a missed sync. - **`unspeced`** — the file changed entirely outside the pipeline; the living spec never saw it. The more concerning of the two. Files matching any glob in the registry's `exempt` list (default `*.config.*`, `*.test.*`, `**/migrations/**`) are filtered out. A capability whose spec is not yet committed is skipped with an informational note, and the run ends on a counts line — e.g. `0 checked, 2 skipped (spec.md not yet committed)` — so a check that examined nothing never reads as clean. The `✓ All N checked capabilities in sync.` line is reserved for a run that checked at least one capability and found it clean. Add `--working` (opt-in) to also see the **working tree**: uncommitted edits, deletions, and untracked files then count as drift alongside the committed history. The contract is unchanged — same checked/skipped counts semantics, same never-fails exit `0` — and without the flag the report reads committed history only, exactly as before: ```bash python3 .specify/extensions/companion/scripts/drift.py --working ``` Add `--json` for a machine-readable object (used by tooling/CI). It carries a `checked` count alongside the `capabilities` and `skipped` lists, so a caller can tell "clean" from "did not run" — the exit code stays `0` either way — plus a `working` boolean naming which mode produced it: ```bash python3 .specify/extensions/companion/scripts/drift.py --json ``` ## What to do with the report Drift is a signal, not an error. To fold the reported changes back in one pass, run `speckit.companion.living-sync` — the write-side twin of this report (it consumes the same `--working` computation). Otherwise, for each `unspeced` or `tracked` row, either fold the change into the living spec by hand (e.g. run `speckit.companion.living-adopt` for the area, or write a delta spec) or add the path to the registry's `exempt` list if it shouldn't be tracked. The command never blocks the pipeline on its own.
© alfredoperez · MIT · alfredoperez/speckit-companion