Skip to main content
command CX Codex

speckit.companion.living-validate — Claude Code command

speckit.companion.living-validate is a command for Claude Code that checks living specs and feature deltas without editing files. It flags missing scenarios, unlinked headings, and syntax issues.

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

What speckit.companion.living-validate does

This command runs python3 .specify/extensions/companion/scripts/living_validate.py from the project root. It inspects living specs and delta blocks against structural rules: flags requirements exceeding 120 words, sections packing more than 4 SHALL, MUST, or SHOULD directives, and scenarios missing WHEN or THEN clauses. Passing --capability <name> limits checking to a single target spec.

Validation runs strictly read-only and never fails with an exit code error. It only reports findings with line numbers, stable rule codes, and recommended fixes, leaving the spec files untouched for the author to review.

Execution depends on Python 3 being present in the environment. If python3 is missing, the checker prints a warning and skips execution. If living specs are disabled in configuration, it reports nothing and exits clean.

What it helps with

  • find requirements lacking verification scenarios
  • catch scenarios missing WHEN conditions or THEN outcomes
  • detect duplicate requirement headings inside a capability
  • flag deltas pointing to missing specification sections
  • locate unclosed markdown code fences

Example prompts for the agent

  • Run speckit.companion.living-validate to check living spec shape
  • Validate spec deltas for capability billing using --json

How to install speckit.companion.living-validate

Manually: put the files in place

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

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

Questions about speckit.companion.living-validate

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

Add the command definition file at .claude/commands/speckit.companion.living-validate.md in your repository.

What does speckit.companion.living-validate check?

It scans living specs for missing scenarios, broken headings, unclosed code fences, and deltas targeting nonexistent sections.

Does this command halt workflows on errors?

No, it always exits clean and never halts execution on its own. It only reports findings, leaving spec modifications entirely to you.

Source text

speckit.companion.living-validate.md · MIT
---
description: "Check the shape of living specs and a feature spec's deltas — a requirement with no scenario, a scenario missing WHEN or THEN, a duplicate heading, a delta pointing at nothing (opt-in, read-only, never halts)"
---

# Spec Shape

Check that every living spec, and every active feature spec's delta sections, are shaped the way every reader of them assumes. A living spec is only worth keeping if what gets folded into it is trustworthy, and until something checked, a requirement with no scenario or a delta pointing at a heading that does not exist landed silently and was found weeks later by a person reading the file.

**Read-only** — it never edits anything, and it **never fails** (always exits success). The fold consumes the same checks and refuses to write on an error; this command only reports. A surrounding workflow 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 the spec shape check`.

## Execution

Run the checker from the repository root. When the invocation names a capability, add `--capability <name>` so only that capability's spec is checked:

```bash
python3 .specify/extensions/companion/scripts/living_validate.py
```

Add `--json` when a caller needs the machine-readable object rather than the list. Each finding carries a severity, a stable code, the path, the line, a sentence saying what is wrong, and a one-line fix.

## What it reports

| Code | Severity | Raised when |
|---|---|---|
| `requirement-without-scenario` | warning | A requirement states a rule and never says how anyone would know it held. |
| `requirement-bundles-rules` | warning | A requirement states more than 4 SHALL, MUST or SHOULD sentences under one heading. Split it: one requirement per rule, each with its own heading and scenario. |
| `requirement-too-wordy` | warning | A requirement takes more than 120 words to state its rule. Cut it to the rule and the one reason that stops someone breaking it. |
| `scenario-missing-half` | error | A scenario has a condition and no outcome, or an outcome and no condition. The keywords are recognised with or without emphasis, so `- WHEN …` counts exactly as `- **WHEN** …` does. |
| `duplicate-requirement` | error | Two requirements in one capability share a heading, which is the join key fold-back and coverage use. |
| `unknown-capability` | error | A delta block is marked for a capability the registry does not list. |
| `delta-heading-not-found` | warning | A MODIFIED or REMOVED entry names a heading the target spec does not carry. The fold promotes an unmatched modification into an addition, so this is a defined outcome rather than damage. |
| `unmatched-touches-glob` | warning | A file marker names a pattern matching nothing on disk. |
- `requirements-outside-capability` — every file marker names code the capability does not claim, so nothing resolves for that behaviour.
- `capability-claims-undescribed-code` — the capability claims code no requirement describes, so a change there is briefed with nothing.
| `unbalanced-fence` | warning | A code fence is opened and never closed, so everything after it is invisible to every reader. |

Severity answers exactly one question: whether the fold stops. An error means the durable record would be damaged; a warning means it would be untidy.

## Report

Relay the checker's own output. Where it reports findings, say how many are errors and how many are warnings, and name the file and line for each. Where it reports skipped files, list them with their reasons verbatim — a clean report must never be readable as a verdict on files that were never examined.

Do **not** edit any spec to satisfy a finding as part of this command. Fixing is the author's decision, made with the finding in front of them.

© alfredoperez · MIT · alfredoperez/speckit-companion

Similar slash commands

All slash commands for Writing and docs →

From the same set83

The whole set →
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 publish The publish command guides a VS Code extension release, from QA checks and changelog updates to versioning and pushing a tagged commit. A separate file is available for Codex. CX Codex +1 ★ 110repo stars 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

Project sponsors

Companies that keep this analytics open