speckit-companion-capture

name	speckit-companion-capture
description	Capture the current spec-kit step into .spec-context.json for the Companion GUI
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"companion:commands/speckit.companion.capture.md"}

Capture Spec Context

Record the active feature's current pipeline step into .spec-context.json so the SpecKit Companion GUI re-renders with the correct step and status. This command runs as the after_specify lifecycle hook — state-writing only; the spec directory and files are created by the core /speckit.specify workflow.

Prerequisites

• Verify Python is available by running python3 --version.
• If python3 is not available, warn the user and skip the capture: [companion] Warning: python3 not detected; skipped .spec-context.json capture. Do not fail the host command.

Execution

Run the writer script from the repository root:

python3 speckit-extension/scripts/write-context.py --step specify --status specified --by extension

The script resolves the active feature directory on its own, in this order: --feature-dir → SPECIFY_FEATURE_DIRECTORY env → SPECIFY_FEATURE env → .specify/feature.json → current git branch prefix.

If you already know the feature directory (e.g. the one /speckit.specify just created), pass it explicitly so resolution is unambiguous:

python3 speckit-extension/scripts/write-context.py --feature-dir specs/<NNN>-<slug> --step specify --status specified --by extension

Graceful Degradation

The script is best-effort and never fails the host command:

• If python3 is missing, skip with the warning above.
• If the active feature directory cannot be resolved, the script prints a warning to stderr and exits 0 without writing.

Output

On success the script prints the path it updated and the values written, e.g.: [companion] Updated specs/<NNN>-<slug>/.spec-context.json (currentStep=specify, status=specified, by=extension). The write is atomic (temp file + rename) and appends to transitions without rewriting existing history.