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
Updates all docs to reflect v1.26.0 features and changes:
README.md:
- Add /gsd:ship and /gsd:next to command tables
- Add /gsd:session-report to Session section
- Update workflow to show ship step and auto-advance
- Update inherit profile description for non-Anthropic providers
docs/COMMANDS.md:
- Add /gsd:next command reference with full state detection logic
- Add /gsd:session-report command reference with report contents
docs/FEATURES.md:
- Add Auto-Advance (Next) feature (#14)
- Add Cross-Phase Regression Gate feature (#20)
- Add Requirements Coverage Gate feature (#21)
- Add Session Reporting feature (#24)
- Fix all section numbering (was broken with duplicates)
- Update inherit profile to mention non-Anthropic providers
- Renumber all 39 features consistently
docs/USER-GUIDE.md:
- Add /gsd:ship to workflow diagram
- Add /gsd:next and /gsd:session-report to command tables
- Add HANDOFF.json and reports/ to file structure
- Add troubleshooting for non-Anthropic model providers
- Add recovery entries for session-report and next
- Update example workflow to include ship and session-report
docs/CONFIGURATION.md:
- Update inherit profile to mention non-Anthropic providers
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
When GSD hits a blocking decision point (AskUserQuestion, next action prompt),
external watchers have no way to detect it. Users monitoring multiple auto
sessions must visually check each terminal.
Added:
- state signal-waiting: writes .planning/WAITING.json (or .gsd/WAITING.json)
with type, question, options, timestamp, and phase info
- state signal-resume: removes WAITING.json when user answers
Signal file format:
{ status, type, question, options[], since, phase }
External tools can watch for this file via fswatch, polling, or inotify.
Complements the existing remote-questions extension (Slack/Discord).
Fixes#1034
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
Claude Code's Task tool sometimes doesn't resolve short aliases (opus,
sonnet, haiku) and passes them directly to the API, causing 404s. Tasks
then inherit the parent session's model instead of the configured one.
Added:
- MODEL_ALIAS_MAP in core.cjs mapping aliases to full model IDs
- resolve_model_ids config option (default: false for backward compat)
- resolveModelInternal() maps aliases when resolve_model_ids is true
Usage:
{ "resolve_model_ids": true }
This causes gsd-tools resolve-model to return 'claude-sonnet-4-5' instead
of 'sonnet', which the Task tool passes to the API without needing alias
resolution on Claude Code's side.
The alias map is maintained per release. Users can also use model_overrides
for full control.
All 755 tests pass.
Fixes#991
stripShippedMilestones() uses a negative heuristic: strip all <details>
blocks, assume what remains is the current milestone. This breaks when
agents accidentally wrap the current milestone in <details> for
collapsibility — all downstream consumers then see an empty milestone.
Observed failure: cmdPhaseComplete() returns is_last_phase: true and
next_phase: null for non-final phases because the current milestone's
phases were stripped along with shipped ones.
Added extractCurrentMilestone(content, cwd) — a positive lookup that:
1. Reads the current milestone version from STATE.md frontmatter
2. Falls back to 🚧 in-progress marker in ROADMAP.md
3. Finds the section heading matching that version
4. Returns only that section's content
5. Falls back to stripShippedMilestones() if version can't be determined
Updated 12 call sites across 6 files to use extractCurrentMilestone:
- core.cjs: getRoadmapPhaseInternal(), getMilestonePhaseFilter()
- phase.cjs: cmdPhaseAdd(), cmdPhaseInsert(), cmdPhaseComplete() (2 sites)
- roadmap.cjs: cmdRoadmapGetPhase(), cmdRoadmapAnalyze()
- commands.cjs: stats/progress display
- verify.cjs: phase verification (2 sites)
- init.cjs: project initialization
Kept stripShippedMilestones() for:
- getMilestoneInfo() — determines the version itself, can't use positive lookup
- replaceInCurrentMilestone() — write operations, conservative boundary
- extractCurrentMilestone() fallback — when no version available
All 755 tests pass.
Fixes#1145
* 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
Prevents shipping hooks with JavaScript SyntaxError (like the duplicate
const cwd declaration that caused PostToolUse errors for all users in
v1.25.1).
The build script now validates each hook file's syntax via vm.Script
before copying to dist/. If any hook has a SyntaxError, the build fails
with a clear error message and exits non-zero, blocking npm publish.
Refs #1107, #1109, #1125, #1161
MSYS curl on Windows has SSL/TLS failures and path mangling issues.
Replaced curl references in checkpoint and phase-prompt templates with
Node.js fetch() which works cross-platform.
Changes:
- checkpoints.md: server readiness check uses fetch() instead of curl
- checkpoints.md: added cross-platform note about curl vs fetch
- checkpoints.md: verify tags use fetch instead of curl
- phase-prompt.md: verify tags use fetch instead of curl
Partially addresses #899 (patch 1 of 6)
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
Previously, calling `mark-complete` on already-completed requirements
reported them as `not_found`, since the regex only matched unchecked
`[ ]` checkboxes and `Pending` table cells.
Now detects `[x]` checkboxes and `Complete` table cells and returns
them in a new `already_complete` array instead of `not_found`.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
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.
Three bugs preventing /gsd:profile-user from generating complete profiles:
1. Template path resolves to bin/templates/ (doesn't exist) instead of
templates/ — __dirname is bin/lib/, needs two levels up not one
2. write-profile reads analysis.projects_list and analysis.message_count
but the profiler agent outputs projects_analyzed and messages_analyzed
3. Evidence block checks dim.evidence but profiler outputs evidence_quotes
Fixes all three with fallback patterns (accepts both old and new field
names) so existing and future analysis formats both work.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
PR #1084 added profile-user command and gsd-user-profiler agent but
didn't bump the hardcoded count assertions in copilot-install tests.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
The researcher agent now verifies each recommended package version
using 'npm view [package] version' before writing the Standard Stack
section. This prevents recommending stale versions from training data.
Addresses patch 5 from #899
