Skip to main content
command CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/speckit.companion.living-drift.md
Open on GitHub

What 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.md

Call it with /speckit.companion.living-drift. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set83

The whole set →
speckit.plan speckit.plan runs an implementation planning workflow from a feature spec, generating research.md, data models, and API contracts. CX Codex GP ChatGPT ★ 110repo stars sandbox This command builds throwaway SpecKit sandboxes from recipes or lists available recipes and existing folders. It works with Claude Code and Codex. CX Codex +1 ★ 110repo stars release-qa release-qa is a Claude Code command that checks code before release. It compares the last version tag, runs automated and manual checks, and blocks /publish until all checks pass. CX Codex +1 ★ 110repo stars install-local The install-local command for Claude Code builds and installs local speckit-companion VS Code and spec-kit extensions, bumping the patch version to trigger an editor reload banner. CX Codex +1 ★ 110repo stars speckit.companion.resume speckit.companion.resume is a command for Claude Code that resumes spec-driven development after a pause. It carries recorded decisions forward and starts the next pipeline step. CX Codex +1 ★ 110repo stars speckit.git.commit speckit.git.commit is a Claude Code command that stages and commits changes after Spec Kit commands, according to project configuration. CX Codex +1 ★ 110repo stars speckit-git-commit The speckit-git-commit skill stages and commits project changes around Spec Kit commands. Use it when Git history should be updated from the project’s Spec Kit settings. CX Codex +1 ★ 110repo stars bench-capture bench-capture — a command for Claude Code and Codex that captures benchmark scores after a size runs through three cells, appends them to history, regenerates the report, and resets the cells for the next round. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open