Skip to main content
command CX Codex

speckit.companion.living-move — Claude Code command: setup and use

speckit.companion.living-move relocates Speckit living specs between central storage and colocated code folders while updating the project registry.

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-move.md
Open on GitHub

What speckit.companion.living-move does

This command switches living specs between centralized storage under capabilities/ and colocated folders right next to source code. It leaves requirement text untouched. Because item identity relies on ### headings inside each file, external links do not break.

The operation follows four stages. First, the agent resolves candidate paths and pauses for user confirmation. Next, it executes the Python helper relocate-capability.py, which shifts the spec, moves tier files, and updates living-specs.yml. Finally, it verifies the new tree via resolve-spec-paths.py.

Never move these files by hand. If the filesystem and living-specs.yml fall out of sync, the path resolver fails the entire configuration rather than a single capability.

What it helps with

  • relocate a capability spec from central storage to a colocated code directory
  • switch all repository living specs to the central folder
  • update living-specs.yml atomically alongside spec files on disk
  • verify resolved spec locations after structural directory moves

Example prompts for the agent

  • Move billing to colocated
  • Move everything to central
  • Relocate the tax capability to colocated and show the target paths

How to install speckit.companion.living-move

Manually: put the files in place

.claude/commands/speckit.companion.living-move.md

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

Questions about speckit.companion.living-move

How to install speckit.companion.living-move in Claude Code?

Save the command file to .claude/commands/speckit.companion.living-move.md inside your project root.

What does speckit.companion.living-move do?

It migrates living spec files between capabilities/ and colocated folders while keeping living-specs.yml in sync.

Why should spec files not be moved manually?

Manual moving desynchronizes disk paths from living-specs.yml. When they diverge, the resolver fails the entire spec configuration across the project.

Source text

speckit.companion.living-move.md · MIT
---
description: "Move a living spec between central and colocated storage — file, tiers, and registry together (opt-in, reversible)"
---

# Relocate a Living Spec

Move a capability's living spec between the two storage layouts, without hand-editing config or moving files yourself.

- **central** — `capabilities/<capability>/<name>.spec.md`. One folder per capability, holding one spec or several granular ones. A legacy `capabilities/<name>/spec.md` still reads, and moving it centrally renames it to the new shape.
- **colocated** — `<area root>/<name>.spec.md`, sitting next to the code it describes.

Neither is more correct. Colocating makes ownership obvious and the spec travels with the code when it moves; centralizing keeps the whole record readable in one place and survives code being reorganized. Repos commonly end up mixed, and that is a fine outcome.

The move is reversible and loses nothing. A requirement's identity is its `###` heading text *inside* the spec, so nothing outside the file points at its location — there is no id to renumber, no link to fix, no index to rebuild.

## Input

```text
$ARGUMENTS
```

The argument names what to move and where — a capability name and a target layout (`billing to colocated`), or a repo-wide instruction (`everything to central`).

If either is missing, ask. List the capabilities with their current layout so the developer can see what they are choosing between, and never guess at a target layout.

## What to do

### 1. Show what will move, and pause

Resolve the current layout of each named capability and the exact path each spec will land at. Show that before touching anything:

```text
billing        capabilities/billing/billing.spec.md  →  src/billing/billing.spec.md
billing-tax    capabilities/billing/tax.spec.md  →  src/billing/tax/billing-tax.spec.md
```

Add one line only where something would surprise them: a display name that changes (colocated names come from the file stem), a capability that stays central because its globs cover several folders or the whole area, and any `.rules.md` or `.coverage.md` that travels with the spec.

Then ask. One question, one word back. This is the only pause.

### 2. Run the relocation

Use the deterministic helper — it moves the spec and every tier sibling, rewrites the registry, and keeps the two in step:

```bash
python3 .specify/extensions/companion/scripts/relocate-capability.py --name <name> --to <central|colocated> [--spec <path>] [--root .]
```

For a repo-wide move, `--all --to <layout>`.

Pass `--spec` when the derived path was wrong or ambiguous, using the path confirmed at the gate.

Do **not** move files yourself and do **not** hand-edit `living-specs.yml`. The file and the registry must change together: the resolver raises `capability "<name>" is colocated but has no resolvable spec path` and fails the **entire** living-specs config — not just that capability — if they disagree. The helper is atomic and rolls back on failure; a hand-rolled move is not.

Re-running against a capability already in the target layout is a safe no-op.

### 3. Verify

Confirm the resolver agrees with what you just did:

```bash
python3 .specify/extensions/companion/scripts/resolve-spec-paths.py --root . --all --json
```

Each moved capability should report the new `spec` path and the expected location. Then resolve a real file from the capability's area and check it still matches — most-specific-first ordering must be unchanged, since relocation moves the spec, not the globs:

```bash
python3 .specify/extensions/companion/scripts/resolve-spec-paths.py --root . --changed <a file under the area> --json
```

If a capability vanished from the listing, or the config now fails to load, the move and the registry are out of step — report it plainly rather than patching around it.

### 4. Report

Say which capabilities moved and where, which were already in the target layout and skipped, which were left alone because their area root was ambiguous, any display name that changed, and whether the resolver confirmed the result. If tier files moved, list them.

## Boundaries

- **Move, never rewrite.** Spec content is not touched. If a spec needs reshaping, that is a separate job.
- **The registry and the disk move together.** Never leave them disagreeing; a partial move breaks the whole config, not one capability.
- **Only what was named.** Do not opportunistically relocate a capability the developer did not ask about, even when its layout looks inconsistent with the rest.
- **Reversible by construction.** Every move can be run in the opposite direction, and re-running is a no-op.
- **Never fail the host.** A missing capability, an unparseable config, or an ambiguous area root is reported and skipped, not crashed through.

© alfredoperez · MIT · alfredoperez/speckit-companion

Similar slash commands

All slash commands for Writing and docs →

From the same set83

The whole set →
release-loop release-loop is a command for Claude Code and Codex that moves a batch of changes through fixes, QA, and release. It prepares a report and waits for approval before publishing. CX Codex +1 ★ 110repo stars bench-wave bench-wave runs an end-to-end benchmark round for a pipeline-diet wave across two Companion cells and logs the metrics into a markdown plan. Useful for measuring speed, token counts, and driver feedback. CX Codex +1 ★ 110repo stars speckit.git.feature The speckit.git.feature command creates and checks out a Git feature branch from a specification. Configure sequential or timestamp numbering and shape branch names with a template. CX Codex +1 ★ 110repo stars speckit-git-feature speckit-git-feature is a Claude Code skill that creates a Git branch from a task description within a Spec Kit project and reads its configuration. CX Codex +1 ★ 110repo stars publish-mod publish-mod releases the Claude Code mod through the repository marketplace and prepares the Anthropic directory handoff for the user. CX Codex +1 ★ 110repo stars speckit.companion.mark-complete speckit.companion.mark-complete marks the active spec as completed via write-context.py. Handy when you want to close a spec by hand instead of running a full converge. CX Codex +1 ★ 110repo stars speckit.constitution speckit.constitution updates the project constitution template in .specify/memory/constitution.md and aligns dependent specification templates. CX Codex GP ChatGPT ★ 110repo stars bench-run-all The bench-run-all command runs one benchmark size across three cells, drives the agent steps, then judges and captures the results. It is built for Speckit pipeline comparisons. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open