- Add workflow.text_mode config option (default: false) that replaces
AskUserQuestion TUI menus with plain-text numbered lists
- Document --text flag and config-set workflow.text_mode true as the
fix for /rc remote sessions where the Claude App cannot forward TUI
menu selections
- Update discuss-phase.md with text mode parsing and answer_validation
fallback documentation
- Add text_mode to loadConfig defaults and VALID_CONFIG_KEYS
- Add regression tests for config-set and loadConfig
Prevent silent loss of UAT/verification items when projects advance.
Surfaces outstanding items across all prior phases so nothing is forgotten.
New command:
- /gsd:audit-uat — cross-phase audit with categorized report and test plan
New capabilities:
- Cross-phase health check in /gsd:progress (Step 1.6)
- status: partial for incomplete UAT sessions
- result: blocked with blocked_by tag for dependency-gated tests
- human_needed items persisted as trackable HUMAN-UAT.md files
- Phase completion and transition warnings for verification debt
Files: 4 new, 14 modified (9 feature + 5 docs)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three commands reimplemented from positively-received community PRs:
1. /gsd:review (#925) — Cross-AI peer review
Invoke external AI CLIs (Gemini, Claude, Codex) to independently
review phase plans. Produces REVIEWS.md with per-reviewer feedback
and consensus summary. Feed back into planning via --reviews flag.
Multiple users praised the adversarial review concept.
2. /gsd:plant-seed (#456) — Forward-looking idea capture
Capture ideas with trigger conditions that auto-surface during
/gsd:new-milestone. Seeds preserve WHY, WHEN to surface, and
breadcrumbs to related code. Better than deferred items because
triggers are checked, not forgotten.
3. /gsd:pr-branch (#470) — Clean PR branches
Create a branch for pull requests by filtering out .planning/
commits. Classifies commits as code-only, planning-only, or mixed,
then cherry-picks only code changes. Reviewers see clean diffs.
All three are standalone command+workflow additions with no core code
changes. Help workflow updated. Test skill counts updated.
797/797 tests pass.
Adds workflow.research_questions config toggle (default: false) that
enables web research before asking questions during /gsd:new-project
and /gsd:discuss-phase.
When enabled:
- discuss-phase: searches best practices for each gray area before
presenting questions, showing 2-3 bullet points of findings
- new-project: researches the user's described domain before asking
follow-up questions, weaving findings into the conversation
Added to /gsd:settings as a toggle ('Research Qs' section).
Closes#1186
New opt-in PreToolUse hook that warns when Claude edits files outside
a GSD workflow context (no active /gsd: command or subagent).
Soft guard — advises, does not block. The edit proceeds but Claude
sees a reminder to use /gsd:fast or /gsd:quick for state tracking.
Enable: set hooks.workflow_guard: true in .planning/config.json
Default: disabled (false)
Allows without warning:
- .planning/ files (GSD state management)
- Config files (.gitignore, .env, CLAUDE.md, settings.json)
- Subagent contexts (executor, planner, etc.)
Includes 3s stdin timeout guard and silent fail-safe.
Closes#678
New lightweight command for tasks too small to justify planning overhead:
typo fixes, config changes, forgotten commits, simple additions.
- Runs inline in current context (no subagent spawn)
- No PLAN.md or SUMMARY.md generated
- Scope guard: redirects to /gsd:quick if task needs >3 file edits
- Atomic commit with conventional commit format
- Logs to STATE.md quick tasks table if present
Complements /gsd:quick (which spawns planner+executor) for cases where
the planning overhead exceeds the actual work.
Closes#609
Windows users experience plan-phase freezes due to Claude Code stdio
deadlocks with MCP servers. When a subagent hangs, the orchestrator
blocks indefinitely with no timeout or error.
Adds:
- Windows troubleshooting section to plan-phase.md with:
- Orphaned process cleanup (PowerShell commands)
- Stale task directory cleanup (~/.claude/tasks/)
- MCP server reduction advice
- --skip-research fallback to reduce agent chain
- Stale task directory detection to health.md (I002 diagnostic)
- Reports count of stale dirs on --repair
- Safe cleanup guidance
Closes#732
Adds --analyze flag to /gsd:discuss-phase that provides a trade-off
analysis before each question (or question group in --batch mode).
When active, each question is preceded by:
- 2-3 options with pros/cons based on codebase context
- A recommended approach with reasoning
- Known pitfalls or constraints from prior phases
Composable with existing flags: --batch --analyze gives grouped
questions each with trade-off tables.
Closes#833
The <evolution> block in templates/project.md defined requirement lifecycle
rules (validate, invalidate, add, log decisions) but these instructions
only existed in the template — they never made it into the generated
PROJECT.md that agents actually read during phase transitions.
Changes:
- new-project.md: Add ## Evolution section to generated PROJECT.md with
the phase transition and milestone review checklists
- new-milestone.md: Ensure ## Evolution section exists in PROJECT.md
(backfills for projects created before this feature)
- execute-phase.md: Add .planning/PROJECT.md to executor <files_to_read>
so executors have project context (core value, requirements, evolution)
- templates/project.md: Add comment noting the <evolution> block is
implemented by transition.md and complete-milestone.md
- docs/ARCHITECTURE.md, docs/FEATURES.md: Note evolution rules in
PROJECT.md descriptions
- CHANGELOG.md: Document the new Evolution section and executor context
Fixes#1039
All 755 tests pass.
Add a cross_reference_todos step to discuss-phase that surfaces relevant
backlog items before scope-setting decisions are made.
Implementation:
- New 'todo match-phase <N>' CLI command (commands.cjs) that scores
pending todos against a phase's ROADMAP goal using three heuristics:
keyword overlap, area match, and file path overlap
- New cross_reference_todos step in discuss-phase.md between
load_prior_context and scout_codebase
- CONTEXT.md template gains 'Folded Todos' subsection in <decisions>
and 'Reviewed Todos (not folded)' subsection in <deferred>
Design:
- No AI call for matching — pure keyword/area/file heuristics for speed
- Silent skip when todo_count is 0 or no matches (no workflow slowdown)
- Auto mode folds all todos with score >= 0.4 automatically
- Scoring: keywords (up to 0.6), area match (0.3), file overlap (0.4)
Tests: 5 new tests covering empty state, keyword matching, unrelated
todo exclusion, area matching, and score sorting.
Closes#1111
Add regression_gate step between executor completion and verification
in execute-phase workflow. Runs prior phases' test suites to catch
cross-phase regressions before they compound.
- Discovers prior VERIFICATION.md files and extracts test file paths
- Detects project test runner (jest/vitest/cargo/pytest)
- Reports pass/fail with options to fix, continue, or abort
- Skips silently for first phase or when no prior tests exist
Changes:
- execute-phase.md: New regression_gate step
- CHANGELOG.md: Document regression gate feature
- docs/FEATURES.md: Add REQ-EXEC-09
Fixes#945
Co-authored-by: TÂCHES <afromanguy@me.com>
Add step 13 (Requirements Coverage Gate) to plan-phase workflow.
After plans pass the checker, verifies all phase requirements are
covered by at least one plan before declaring planning complete.
- Extracts REQ-IDs from plan frontmatter and compares against
phase_req_ids from ROADMAP
- Cross-checks CONTEXT.md features against plan objectives to
detect silently dropped scope
- Reports gaps with options: re-plan, defer, or proceed
- Skips when phase_req_ids is null/TBD (no requirements mapped)
Fixes#984
Co-authored-by: TÂCHES <afromanguy@me.com>
Enhance /gsd:pause-work to write .planning/HANDOFF.json alongside
.continue-here.md. The JSON provides machine-readable state that
/gsd:resume-work can parse for precise resumption.
HANDOFF.json includes:
- Task position (phase, plan, task number, status)
- Completed and remaining tasks with commit hashes
- Blockers with type classification (technical/human_action/external)
- Human actions pending (API keys, approvals, manual testing)
- Uncommitted files list
- Context notes for mental model restoration
Resume-work changes:
- HANDOFF.json is primary resumption source (highest priority)
- Surfaces blockers and human actions immediately on session start
- Validates uncommitted files against git status
- Deletes HANDOFF.json after successful resumption
- Falls back to .continue-here.md if no JSON exists
Also checks for placeholder content in SUMMARY.md files to catch
false completions (frontmatter claims complete but body has TBD).
Fixes#940
* feat: /gsd:ship command for PR creation from verified phase work (#829)
New command that bridges local completion → merged PR, closing the
plan → execute → verify → ship loop.
Workflow (workflows/ship.md):
1. Preflight: verification passed, clean tree, correct branch, gh auth
2. Push branch to remote
3. Auto-generate rich PR body from planning artifacts:
- Phase goal from ROADMAP.md
- Changes from SUMMARY.md files
- Requirements addressed (REQ-IDs)
- Verification status
- Key decisions
4. Create PR via gh CLI (supports --draft)
5. Optional code review request
6. Update STATE.md with shipping status
Files:
- commands/gsd/ship.md: New command entry point
- get-shit-done/workflows/ship.md: Full workflow implementation
- get-shit-done/workflows/help.md: Add ship to help output
- docs/COMMANDS.md: Command reference
- docs/FEATURES.md: Feature spec with REQ-SHIP-01 through 05
- docs/USER-GUIDE.md: Add to command table
- CHANGELOG.md: Document new command
Fixes#829
* fix(tests): update expected skill count from 39 to 40 for new ship command
The Copilot install E2E tests hardcode the expected number of skill
directories and manifest entries. Adding commands/gsd/ship.md increased
the count from 39 to 40.
The agent was telling users to run '/gsd:transition' after phase completion,
but this command does not exist. transition.md is an internal workflow invoked
by execute-phase during auto-advance.
Changes:
- Add <internal_workflow> banner to transition.md declaring it is NOT a user command
- Add explicit warning in execute-phase completion section that /gsd:transition
does not exist
- Add 'only suggest commands listed above' guard to prevent hallucination
- Update resume-project.md to avoid ambiguous 'Transition' label
- Replace 'ready for transition' with 'ready for next step' in execute-plan.md
Fixes#1081
Two gaps in the standard workflow cycle caused planning document drift:
1. PROJECT.md was never updated during discuss → plan → execute → verify.
Only transition.md (optional) and complete-milestone evolved it.
Added an 'update_project_md' step to execute-phase.md that evolves
PROJECT.md after phase completion: moves requirements to Validated,
updates Current State, bumps Last Updated timestamp.
2. cmdPhaseComplete() in phase.cjs advanced 'Current Phase' but never
incremented 'Completed Phases' counter or recalculated 'percent'.
Added counter increment and percentage recalculation based on
completed/total phases ratio.
Addresses the workflow-level gaps identified in #956:
- PROJECT.md evolution in execute-phase (gap #2)
- completed_phases counter not incremented (gap #1 table row 3)
- percent never recalculated (gap #1 table row 4)
Fixes#956
Copilot's subagent spawning (Task API) may not properly return completion
signals to the orchestrator, causing it to hang indefinitely waiting for
agents that have already finished their work.
Added <runtime_compatibility> section to execute-phase.md with:
- Runtime-specific subagent spawning guidance (Claude Code, Copilot, others)
- Fallback rule: if agent completes work but orchestrator doesn't get the
signal, treat as success based on spot-checks (SUMMARY.md exists, commits
present)
- Sequential inline execution fallback for runtimes without reliable Task API
Fixes#1128
Adds --interactive flag to /gsd:execute-phase that changes execution from
autonomous subagent delegation to sequential inline execution with user
checkpoints between tasks.
Interactive mode:
- Executes plans sequentially inline (no subagent spawning)
- Presents each plan to user: Execute, Review first, Skip, Stop
- Pauses after each task for user intervention
- Dramatically lower token usage (no subagent overhead)
- Maintains full GSD planning/tracking structure
Changes:
- execute-phase.md: new check_interactive_mode step with full interactive flow
- execute-phase command: documented --interactive flag in argument-hint and context
Use cases:
- Small phases (1-3 plans, no complex dependencies)
- Bug fixes and verification gap closure
- Learning GSD workflow
- When user wants to pair-program with Claude under GSD structure
Fixes#963
GSD executor agents ignore MCP tools (e.g. jCodeMunch) even when CLAUDE.md
explicitly instructs their use. Agents default to Grep/Glob because those
are explicitly referenced in workflow patterns.
Added MCP tool instructions to:
- execute-phase.md: <mcp_tools> section in executor agent prompt telling
agents to prefer MCP tools over Grep/Glob when available
- execute-plan.md: Step 2 in execute section with MCP tool fallback guidance
Agents now:
1. Check if CLAUDE.md references MCP tools
2. Prefer MCP tools for code navigation when accessible
3. Fall back to Grep/Glob if MCP tools are not available
Fixes#973
After /clear, Claude Code sometimes loses awareness of custom agent types
and falls back to 'general-purpose'. This happens because the model doesn't
re-read .claude/agents/ after context reset.
Added <available_agent_types> sections to:
- execute-phase.md: lists all 12 valid GSD agent types with descriptions
- plan-phase.md: lists the 3 agent types used during planning
The explicit listing in workflow instructions ensures the model always has
an unambiguous reference to valid agent types, regardless of whether
.claude/agents/ was re-read after /clear.
Fixes#949
When plan-phase invokes discuss-phase as a nested Skill call,
AskUserQuestion calls auto-resolve with empty answers — the user never
sees the question UI. This is a Claude Code runtime bug with nested
subcontexts.
Made the 'Run discuss-phase first' path explicitly exit the workflow
with a display message instead of risking nested invocation:
- Added explicit warning: do NOT invoke as nested Skill/Task
- Show the command for user to run as top-level
- Exit the plan-phase workflow immediately
Fixes#1009
* fix: hook version tracking, stale hook detection, and stdin timeout increase
- Add gsd-hook-version header to all hook files for version tracking (#1153)
- Install.js now stamps current version into hooks during installation
- gsd-check-update.js detects stale hooks by comparing version headers
- gsd-statusline.js shows warning when stale hooks are detected
- Increase context monitor stdin timeout from 3s to 10s (#1162)
- Set +x permission on hook files during installation (#1162)
Fixes#1153, #1162, #1161
* feat: add /gsd:session-report command for post-session summary generation
Adds a new command that generates SESSION_REPORT.md with:
- Work performed summary (phases touched, commits, files changed)
- Key outcomes and decisions made
- Active blockers and open items
- Estimated resource usage metrics
Reports are written to .planning/reports/ with date-stamped filenames.
Closes#1157
* test: update expected skill count from 39 to 40 for new session-report command
Adds a zero-friction command that detects the current project state and
automatically invokes the next logical workflow step:
- No phases → discuss first phase
- Phase has no context → discuss
- Phase has context but no plans → plan
- Phase has plans but incomplete → execute
- All plans complete → verify and complete phase
- All phases complete → complete milestone
- Paused → resume work
No arguments needed — reads STATE.md, ROADMAP.md, and phase directories
to determine progression. Designed for multi-project workflows.
Closes#927
Runtimes like Antigravity don't have a Task tool for spawning subagents.
When the agent encounters Task() calls, it falls back to browser_subagent
which is meant for web browsing, not code analysis — causing
gsd-map-codebase to fail.
This adds:
1. A detect_runtime_capabilities step before spawn_agents
2. An explicit warning to NEVER use browser_subagent for code analysis
3. A sequential_mapping fallback step that performs all 4 mapping passes
inline using file system tools when Task is unavailable
Closes#1174
The version detection script in update.md used a space-separated string
for RUNTIME_DIRS and iterated with `for entry in $RUNTIME_DIRS`. This
relies on word-splitting which works in bash but fails in zsh (zsh does
not word-split unquoted variables by default), causing the entire string
to be treated as one entry and detection to fall through to UNKNOWN.
Fix: convert RUNTIME_DIRS and ORDERED_RUNTIME_DIRS from space-separated
strings to proper arrays, and iterate with ${array[@]} syntax which
works correctly in both bash and zsh.
Closes#1173
Users on OpenRouter or local models get unexpected API costs because
GSD's default 'balanced' profile spawns specific Anthropic models for
subagents. The 'inherit' profile exists but wasn't well-documented for
this use case.
Changes:
- model-profiles.md: add 'Using Non-Anthropic Models' section explaining
when and how to use inherit profile
- model-profiles.md: update inherit description to mention OpenRouter and
local models
- settings.md: update Inherit option description to mention OpenRouter
and local models (was only mentioning OpenCode)
Closes#1036
Before this PR, Step 5 derived nyquist_validation from depth !== "quick"
(now granularity !== "coarse"). The new config-new-project call omitted
it, silently defaulting to true even when the user selected "Coarse"
granularity.
Adds nyquist_validation back to the Step 5 JSON payload with an explicit
inline rule: false when granularity=coarse, true otherwise.
Add `config-new-project` CLI command that writes a complete,
fully-materialized `.planning/config.json` with sane defaults
instead of the previous partial template (6-7 user-chosen keys
only). Unset keys are no longer silently resolved at read time —
every key GSD reads is written explicitly at project creation.
Previously, missing keys were resolved silently by loadConfig()
defaults, making the effective config non-discoverable. Now every
key that GSD reads is written explicitly at project creation.
- buildNewProjectConfig() — single source of truth for all
defaults; merges hardcoded ← ~/.gsd/defaults.json ← user choices
- ensureConfigFile() refactored to reuse buildNewProjectConfig({})
instead of duplicating default logic (~40 lines removed)
- new-project.md Steps 2a and 5 updated to call config-new-project
instead of writing a hardcoded partial JSON template
- Test coverage for config.cjs: 78.96% → 93.81% statements,
100% functions; adds config-set-model-profile test suite
FIXES:
- VALID_CONFIG_KEYS extended with workflow.auto_advance,
workflow.node_repair, workflow.node_repair_budget,
hooks.context_warnings — these keys had hardcoded defaults
but were not settable via config-set
The workflow spawns 4 background agents but didn't tell Claude how to
wait for them. Without explicit TaskOutput instructions, the orchestrator
displays "Waiting for agents to complete..." indefinitely.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The offer_next step in execute-phase.md suggests /gsd:transition to users
when auto-advance is disabled. This command does not exist as a registered
skill — transition.md is an internal workflow only invoked inline during
auto-advance chains (line 456).
Replace with /gsd:discuss-phase and /gsd:plan-phase which are the actual
user-facing equivalents for transitioning between phases.
No impact on auto-advance path — that invokes transition.md by file path,
not as a slash command.
Co-authored-by: Piyush Rane <piyush.rane@inmobi.com>
- fix(frontmatter): handle CRLF line endings in extractFrontmatter,
spliceFrontmatter, and parseMustHavesBlock — fixes wave parsing on
Windows where all plans reported as wave 1 (#1085)
- fix(hooks): remove duplicate const cwd declaration in
gsd-context-monitor.js that caused SyntaxError on every PostToolUse
invocation (#1091, #1092, #1094)
- feat(state): add 'state begin-phase' command that updates STATUS,
Last Activity, Current focus, Current Position, and plan counts
when a new phase starts executing (#1102, #1103, #1104)
- docs(workflow): add state begin-phase call to execute-phase workflow
validate_phase step so STATE.md is current from the start
Three additive quality improvements to the execution pipeline:
1. Pre-wave dependency check (execute-phase): Before spawning wave N+1,
verify key-links from prior wave artifacts. Catches cross-plan wiring
gaps before they cascade into downstream failures.
2. Cross-Plan Data Contracts dimension (plan-checker): New Dimension 9
checks that plans sharing data pipelines have compatible transformations.
Flags when one plan strips data another plan needs in original form.
3. Export-level spot check (verify-phase): After Level 3 wiring passes,
spot-check individual exports for actual usage. Catches dead stores
that exist in wired files but are never called.
