skills.rest
whw23
whw23COMMUNITY
Explore all skills by this author →
GitHub

speckit-companion-capture-plan

Writes plan completion state into .spec-context.json for the SpecKit Companion GUI.

Updated May 28, 2026
Search Tags:#python#feature tracking#spec-kit#state capture#plan workflow#companion gui#lifecycle hook
One-click install
npx skills add https://github.com/whw23/PingoGate --skill speckit-companion-capture-plan-whw23
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: speckit-companion-capture-plan
Source: https://github.com/whw23/PingoGate/tree/main/.claude/skills/speckit-companion-capture-plan
Command: npx skills add https://github.com/whw23/PingoGate --skill speckit-companion-capture-plan-whw23

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? After running the /speckit.plan workflow, the SpecKit Companion GUI has no record that the plan step finished, so it displays stale step and status information. This Skill records plan completion (currentStep=plan, status=planned) into .spec-context.json so the GUI re-renders with correct state. ## Core Features & Use Cases - Lifecycle Hook Execution: Runs as the after_plan hook, performing state-writing only while the plan document itself is created by the core /speckit.plan workflow. - Automatic Feature Resolution: The writer script resolves the active feature directory via --feature-dir flag, SPECIFY_FEATURE_DIRECTORY or SPECIFY_FEATURE environment variables, .specify/feature.json, or the current git branch prefix. - Graceful Degradation: Never fails the host command; skips with a warning if python3 is missing and exits 0 if the feature directory cannot be resolved. - Use Case: After /speckit.plan generates a plan for feature specs/042-user-auth, run this hook to atomically update specs/042-user-auth/.spec-context.json and append to its history[] so the Companion GUI shows the plan step as planned. ## Quick Start Run the capture plan hook after /speckit.plan completes so the Companion GUI reflects the planned status for the current feature.

Frequently Asked Questions about speckit-companion-capture-plan

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I update .spec-context.json after running speckit plan?▼

Run python3 .specify/extensions/companion/scripts/write-context.py --step plan --status planned --by extension from the repository root. The script resolves the active feature directory automatically and writes the state atomically.

How does the write-context script find the active feature directory?▼

It resolves in order: the --feature-dir flag, the SPECIFY_FEATURE_DIRECTORY environment variable, the SPECIFY_FEATURE variable, .specify/feature.json, then the current git branch prefix. Passing --feature-dir explicitly makes resolution unambiguous.

What happens if python3 is not installed when the hook runs?▼

The capture is skipped with the warning '[companion] Warning: python3 not detected; skipped .spec-context.json capture'. The host command does not fail, since the hook is best-effort state writing only.

Does this hook create the plan document itself?▼

No. The plan document is created by the core /speckit.plan workflow. This hook only writes state (currentStep=plan, status=planned) into .spec-context.json so the Companion GUI re-renders correctly.

Why does the Companion GUI not update after the capture script runs?▼

If the active feature directory cannot be resolved, the script prints a warning to stderr and exits 0 without writing. Check that you are on a feature branch or pass --feature-dir specs/<NNN>-<slug> explicitly.

Related Skills

Explore More Software Engineering Skills→
refactory-langrefactory-lang

speckit-workflows.enhance

Create a new branch and Markdown document for minor speckit enhancements.

Official
Intermediate
atournayreatournayre

orchestrator:status

Parse a state file to display development workflow phase status and timings.

Community
Basic
reason-healthcarereason-healthcare
12

speckit-clarify

Identify underspecified areas in feature specifications and log clarifications.

Official
Advanced
alfredoperezalfredoperez
80

eval-speckit-extension

Evaluate speckit-extension lifecycle hooks, timing, and task journaling against .spec-context.json.

Community
Advanced