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
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
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.
Instead of silently skipping research based on the config toggle,
plan-phase now asks the user whether to research before planning
(when no explicit --research or --skip-research flag is provided).
The prompt includes a contextual recommendation:
- 'Research first (Recommended)' for new features, integrations, etc.
- 'Skip research' for bug fixes, refactors, well-understood tasks
The --research and --skip-research flags still work as silent overrides
for automation. Auto mode (--auto) respects the config toggle silently.
Fixes#846
The settings UI description for the 'balanced' profile said 'Opus for
planning, Sonnet for execution/verification' — omitting that research
also uses Sonnet. Users assumed research was included in 'planning'
and expected Opus for the researcher agent.
Updated to: 'Opus for planning, Sonnet for research/execution/verification'
This matches model-profiles.md and the actual MODEL_PROFILES mapping.
Fixes#680
After committing task changes, the executor now checks for untracked
files (git status --short | grep '^??') and handles them: commit if
intentional, add to .gitignore if generated/runtime output.
This prevents generated artifacts (build outputs, .env files, cache
files) from being silently left untracked in the working tree.
Changes:
- execute-plan.md: Add step 6 to task commit protocol
- gsd-executor.md: Add step 6 to task commit protocol
Fixes#957
Add hooks.context_warnings config option (default: true) that allows
users to disable the context monitor hook's advisory messages. When
set to false, the hook exits silently, allowing Claude Code to reach
auto-compact naturally without being interrupted.
This is useful for long unattended runs where users prefer Claude to
auto-compact and continue rather than stopping to warn about context.
Changes:
- hooks/gsd-context-monitor.js: Check config before emitting warnings
- get-shit-done/templates/config.json: Add hooks.context_warnings default
- get-shit-done/workflows/settings.md: Add UI for the new setting
Fixes#976
When the discuss-phase workflow asks 'More questions about [area], or
move to next?', it now also lists the remaining unvisited areas so the
user can see what's still ahead and make an informed decision about
whether to go deeper or move on.
Example: 'More questions about Layout, or move to next?
(Remaining: Loading behavior, Content ordering)'
Fixes#992
Add composable --research flag to /gsd:quick that spawns a focused
gsd-phase-researcher before planning. Investigates implementation
approaches, library options, and pitfalls for the task.
Addresses the middle-ground gap between quick (no quality agents) and
full milestone workflows. All three flags are composable:
--discuss --research --full gives the complete quality pipeline.
Made-with: Cursor
Co-authored-by: ralberts3 <ralberts3@gatech.edu>
* perf: make `/gsd:set-profile`'s implementation more programmatic
* perf: run the set-profile script without Claude needing to invoke it
- inject the script's output as dynamic context into the set-profile skill, so that Claude doesn't
need to invoke it and can simply read + print the output to the user
- reference: https://code.claude.com/docs/en/skills#inject-dynamic-context
* feat: improve output message for case where model profile wasn't changed
* feat: specify haiku model for set-profile command since it's so simple
* fix: remove ' (default)' from previousProfile to avoid false negative for didChange
* chore: add docstring to MODEL_PROFILES with note about the analogous markdown reference table
* chore: delete set-profile workflow file that's no longer needed
Two bugs caused workflow.research to silently reset to false:
1. new-milestone.md unconditionally overwrote workflow.research via
config-set after asking about research — coupling a per-milestone
decision to a persistent user preference. Now the research question
is per-invocation only; persistent config changes via /gsd:settings.
2. verify.cjs health repair (createConfig/resetConfig) used flat keys
(research, plan_checker, verifier) instead of the canonical nested
workflow object from config.cjs, also missing branch templates,
nyquist_validation, and brave_search fields.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Add a new `/gsd:stats` command that displays comprehensive project
statistics including phase progress, plan execution metrics, requirements
completion, git history, and timeline information.
- New command definition: commands/gsd/stats.md
- New workflow: get-shit-done/workflows/stats.md
- CLI handler: `gsd-tools stats [json|table]`
- Stats function in commands.cjs with JSON and table output formats
- 5 new tests covering empty project, phase/plan counting, requirements
counting, last activity, and table format rendering
Co-authored-by: ashanuoc <ashanuoc@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Add pre-planning design contract generation and post-execution visual audit
for frontend phases. Closes the gap where execute-phase runs without a visual
contract, producing inconsistent spacing, color, and typography across components.
New agents: gsd-ui-researcher (UI-SPEC.md), gsd-ui-checker (6-dimension
validation), gsd-ui-auditor (6-pillar scored audit + registry re-vetting).
Third-party shadcn registry blocks are machine-vetted at contract time,
verification time, and audit time — three enforcement points, not a checkbox.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix: plan-phase Nyquist validation when research is disabled (#980)
plan-phase step 5.5 required Nyquist artifacts even when research was
disabled, creating an impossible state: no RESEARCH.md to extract
Validation Architecture from. Step 7.5 then told Claude to "disable
Nyquist in config" without specifying the exact key, causing Claude to
guess wrong keys that config-set silently accepted.
Three fixes:
- plan-phase step 5.5: skip when research_enabled is false
- plan-phase step 7.5: specify exact config-set command for disabling
- config-set: reject unknown keys with whitelist validation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test: update config-set tests for key whitelist validation
Tests that used arbitrary keys (some_number, some_string, a.b.c) now
use valid config keys to test the same coercion and nesting behavior.
Adds new test asserting unknown keys are rejected with error.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Quick task IDs were sequential integers (001, 002...) computed by reading
the local .planning/quick/ directory max value. Two users running /gsd:quick
simultaneously would get the same number, causing directory collisions on git.
Replace with a collision-resistant format: YYMMDD-xxx where xxx is the
number of 2-second blocks elapsed since midnight, encoded as 3 lowercase
Base36 characters (000–xbz). Practical collision window is ~2 seconds per
user — effectively zero for any realistic team workflow.
- init.cjs: remove nextNum scan logic, generate quickId from wall clock
- quick.md: rename all next_num refs to quick_id, update directory patterns
- init.test.cjs: rewrite cmdInitQuick tests for new ID format
Co-authored-by: yanbing <yanbing@corp.netease.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Executor agents often produce shallow work because plans say "align X with Y"
without specifying what the aligned result looks like. The executor changes one
value and calls it done.
This adds three mandatory fields to every task:
- `<read_first>`: Files the executor MUST read before editing. Ensures ground
truth is loaded, not assumed.
- `<acceptance_criteria>`: Grep-verifiable conditions checked after each task.
No subjective language ("looks consistent"), only concrete checks
("file contains 'exact string'").
- `<action>` guidance: Must include concrete values (identifiers, signatures,
config keys), never vague references like "update to match production".
Adds `<deep_work_rules>` to planner instructions with mandatory quality gate
checks. Executor workflow enforces both gates: read before edit, verify after
edit. Adds generic pre-commit hook failure handling guidance.
Co-authored-by: Dammerzone <dammerzone@users.noreply.github.com>
When a task fails verification, the executor now attempts structured
repair before interrupting the user:
- RETRY: adjusts approach and re-attempts
- DECOMPOSE: splits the task into smaller verifiable sub-tasks
- PRUNE: skips with justification when infeasible
Only escalates to the user when the repair budget is exhausted or an
architectural decision is required (Rule 4). Configurable via
workflow.node_repair (bool) and workflow.node_repair_budget (int).
Defaults to enabled with budget=2.
Inspired by the NODE_REPAIR operator in STRUCTUREDAGENT (arXiv:2603.05294).
Co-authored-by: buftar <buftar@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: add mandatory canonical_refs section to CONTEXT.md
CONTEXT.md is the bridge between user decisions and downstream agents
(researcher, planner). When projects have external specs, ADRs, or
design docs, these references were being silently dropped — mentioned
inline as "see ADR-019" but never collected into a section that agents
could find and read. This caused agents to plan and implement without
reading the specs they were supposed to follow.
Changes:
- templates/context.md: Add <canonical_refs> section to file template,
all 3 examples, and guidelines (marked MANDATORY)
- workflows/discuss-phase.md: Add step 1b (extract canonical refs),
add section to write_context template, add to success criteria
- workflows/plan-phase.md: Add canonical ref extraction to PRD express
path and its CONTEXT.md template
- workflows/quick.md: Add lightweight canonical_refs to --discuss mode
The section is mandatory but gracefully handles projects without external
docs ("No external specs — requirements fully captured in decisions above").
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: make canonical refs an accumulator across entire discussion
Refs come from 4 sources, not just ROADMAP.md:
1. ROADMAP.md Canonical refs line (initial seed)
2. REQUIREMENTS.md/PROJECT.md referenced specs
3. Codebase scout (code comments citing ADRs)
4. User during discussion ("read adr-014", "check the MCP spec")
Source 4 is often the MOST important — these are docs the user
specifically wants downstream agents to follow. The previous
version only handled source 1 and silently dropped the rest.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
When gsd-tools init output exceeds 50KB, core.cjs writes to a temp file
and outputs @file:<path>. No workflow handled this prefix, causing agents
to hallucinate /tmp paths that fail on Windows (C:\tmp doesn't exist).
Add @file: resolution line after every INIT=$(node ...) call across all
32 workflow, agent, and reference files.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Surfaces gray areas and captures user decisions in CONTEXT.md before
planning, reducing hallucination risk for ambiguous quick tasks.
Composable with --full for discussion + plan-checking + verification.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
