speckit.companion.living-sync — Claude Code command
speckit.companion.living-sync updates living specs to match current working-tree changes in a single pass. Modifies existing spec files without regenerating them from scratch.
MIT ★ 110 updated 2026-10-19
.claude/commands/speckit.companion.living-sync.mdWhat speckit.companion.living-sync does
The command collects working-tree diffs, including untracked files and local deletions, groups them by capability, and applies targeted updates to matching spec files. It relies on .specify/extensions/companion/scripts/drift.py --working --json to build an exact execution plan instead of manual git filtering.
Specs are adjusted in place rather than rewritten. It preserves manual context, cleans out requirements removed from the code, expands touches path patterns, and reflects // simplified: limits in the document. All updated files remain uncommitted so they land alongside the matching code changes.
Python 3 must be available in your environment. If python3 is missing or living specs are turned off in repository settings, the command outputs a warning and exits cleanly without breaking the session.
What it helps with
- sync living specs against uncommitted working-tree changes
- widen touches markers when modified code affects existing rules
- prune obsolete spec requirements after removing code
- keep documentation diffs in the same commit as feature edits
Example prompts for the agent
- Sync all drifted living specs from my current working tree
- Run speckit.companion.living-sync to reflect uncommitted code edits
- Update capability specs using living-sync before committing changes
How to install speckit.companion.living-sync
Manually: put the files in place
.claude/commands/speckit.companion.living-sync.mdCall it with /speckit.companion.living-sync. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/speckit.companion.living-sync.mdCall it with /prompts:speckit.companion.living-sync. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/speckit.companion.living-sync.prompt.mdManually: put the files in place
.gemini/commands/speckit.companion.living-sync.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about speckit.companion.living-sync
How to install speckit.companion.living-sync in Claude Code?
Save the command definition file directly to .claude/commands/speckit.companion.living-sync.md in your project.
What does speckit.companion.living-sync do?
It runs drift detection across the current workspace and updates every drifted spec file directly, without wiping untouched sections.
What happens if python3 is missing?
The run emits a skip notice and terminates cleanly instead of failing the parent process.
Source text
speckit.companion.living-sync.md · MIT
--- description: "Sync living specs from your current changes — group working-tree changes (uncommitted included) by capability and update every affected spec in one pass (opt-in, update-not-regenerate, never halts)" --- # Sync Living Specs Bring every affected living spec up to date with the code **as it is right now** — uncommitted edits, deletions, and untracked files included — in a single pass. This is the one-command loop for a developer who codes directly, without running the Companion pipeline: no drift report to read, no capability to hand-pick, no blind spot for work that isn't committed yet. The updated spec files are left as ordinary working-tree edits so they commit **together with the code that caused them**. This is **opt-in**. With living specs disabled (or no config), it reports nothing to do and exits clean. It **never fails** the host run: any miss degrades into a warning and a skip. ## Prerequisites - Verify Python is available by running `python3 --version`. - If `python3` is not available, warn the user and stop here without failing: `[companion] Warning: python3 not detected; skipped living-spec sync`. <!-- speckit-companion:part concise --> ## The smallest thing that works **Before building anything, stop at the first rung that holds:** does it need to exist at all; does this codebase already have it; does the standard library, the platform, or an installed dependency do it; can it be one line; only then, the minimum code that works. Fix the cause where every caller passes through, not the symptom one caller reported. Delete rather than add, boring rather than clever: no interface with one implementation, no factory for one product, no scaffolding for later. Lean governs what you build and write, not how the work is split: sending work to a worker where a step says to is not extra. **Write it the way you would say it.** One idea per sentence. No em-dashes: a full stop, a comma or a colon says it. Say what happens, not what the system "shall be capable of". Never a section that exists to say "N/A": remove it instead. **The same test governs what you write, and again once it is written.** A section nobody acts on is removed, not filled in. No requirement for what a type or a test already enforces. A third scenario has to cover a failure the first two miss. Then reread and cut: the sentence restating the one before it, the example longer than its rule, the clause defending a choice nobody challenged, the prose repeating a table. Each reads as thoroughness and is what makes a body too long to follow. **Never simplify away** validation at a trust boundary, error handling that prevents data loss, security, accessibility, or anything the spec asks for. **A corner cut on purpose** carries `// simplified: <ceiling>, <what to do when it binds>` in the code and one `concerns` entry in this step's capture. <!-- /speckit-companion:part concise --> ## Execution ### 1. Compute the sync plan Run the drift detector in working-tree mode from the repository root: ```bash python3 .specify/extensions/companion/scripts/drift.py --working --json ``` This is the same engine `speckit.companion.living-drift` uses — resolver membership, exempt globs, per-capability baselines, skip reasons — with `--working` widening each capability's changed set to the working tree (baseline→worktree diff plus untracked files). Its JSON output **is** the sync plan; do not regroup the files yourself with ad-hoc git commands. Read the result: - `enabled: false` → report `Living specs are off in this repo; nothing to sync.` and stop (success). - `checked: 0` → nothing could be examined; report the `skipped` list with each reason and stop (success). - Otherwise the plan is `capabilities[]`: each entry with a non-empty `drifted` list is a capability to sync (`name`, its spec at `spec`, and the changed files in `drifted[].file`); entries with `drifted: []` are already in sync and are left untouched. ### 2. Update each affected capability — every one, no hand-picking For **each** capability with drifted files, edit its spec file (the `spec` path) in place, scoped to **that capability's** `drifted[].file` list: > The capability has drifted — the code it describes changed since the spec was last committed (working-tree changes included). **UPDATE, do not regenerate**: keep every requirement, clarification, and acceptance scenario already written, and revise only what the changed files require. Read the listed changed files, work out what behavior was added, changed, or removed, and reflect exactly that. A file deleted from the working tree means its behavior was **removed** — reflect the removal rather than describing the file as if it still existed. Never rewrite untouched sections, never reorder requirements, and never flatten hand-written detail into a fresh draft. **Widen each updated requirement's `touches` marker.** A requirement you revised now also describes the files that caused the revision, so its marker must say so — otherwise a later run narrowing on markers would skip the very requirement this change just made relevant. On the line immediately under the heading: ```markdown ### Pages delegate their chrome to a layout primitive <!-- touches: src/layout/**, src/pages/shell.tsx --> ``` **Widen, never narrow.** Write the union of what the marker already named and the changed files you folded in. A requirement that used to describe a file it no longer touches keeps claiming it until someone edits the marker by hand — that costs a run one extra requirement, where narrowing could cost it a needed one. A requirement carrying no marker is read by every run, so leaving one unmarked is always safe; add one only when the changed files genuinely tell you what that requirement is about. **Remove what the code no longer has.** When the changed files no longer contain what a requirement describes, the requirement is not "stale" — it is gone, and it is deleted from the spec, not softened. A sync that only ever adds produces a spec that is half history. Likewise a `// simplified:` comment that has disappeared from the code takes its `## Known limits` line with it, and a new one adds its line. Work through the capabilities one at a time. If one capability's update fails (unreadable file, unresolvable content), warn, skip it, and continue with the rest — one bad capability never blocks the others. ### 3. Handle the skipped capabilities honestly Report every entry in the plan's `skipped` list with its reason, verbatim. In particular: - `spec.md not yet committed` — the capability has no committed baseline to diff against. Do **not** draft or redraft its spec here; that is bootstrap work, and `speckit.companion.living-adopt` owns it. Say so. - Git/shallow-clone reasons — nothing to do but state them. ### 4. Report — and leave the edits uncommitted End with a short report: - **Synced** — each updated capability, with how many changed files were folded in. - **Skipped** — each skipped capability and its reason. - A closing note that the spec edits are **left uncommitted on purpose** so they can be reviewed and committed alongside the code that caused them. Do **not** run `git add` or `git commit`, and do not tell the user to run the sync again — the next edit session simply runs it once more when they're ready.
© alfredoperez · MIT · alfredoperez/speckit-companion