ensureConfigFile(): keep our refactored version that delegates to
buildNewProjectConfig({}) instead of upstream's duplicated logic.
buildNewProjectConfig(): add firecrawl and exa_search API key
detection alongside existing brave_search, matching upstream's
new integrations.
Decisions in CONTEXT.md are now numbered (D-01, D-02, etc.) so
downstream agents can reference them and the plan-checker can verify
100% coverage.
Changes:
- templates/context.md: Decisions use **D-XX:** prefix format
- workflows/discuss-phase.md: write_context step numbers decisions
- agents/gsd-planner.md: Self-check verifies decision ID references
in task actions; tasks reference D-XX IDs for traceability
- agents/gsd-plan-checker.md: Dimension 7 (Context Compliance)
extracts D-XX IDs and verifies every decision has a task
Enhanced gsd-verifier's anti-pattern detection to catch:
- Hardcoded empty data props (={[]}, ={{}}, ={null})
- 'not available' and 'not yet implemented' placeholder text
- Data stub classification guidance (only flag when value flows
to rendering without a data-fetching path)
Added stub tracking to gsd-executor's summary creation:
- Before writing SUMMARY, scan files for stub patterns
- Document stubs in a '## Known Stubs' section
- Block plan completion if stubs prevent the plan's goal
The gsd-context-monitor PostToolUse hook was configured without a
matcher or timeout, causing it to fire on every tool use including
Read, Glob, and Grep. When multiple Read calls happen in parallel,
some hook processes failed with errors.
Added matcher: 'Bash|Edit|Write|MultiEdit|Agent|Task' to limit the
hook to tools that actually modify context significantly. Added
timeout: 10 to prevent hangs.
Includes migration logic: existing installations without matcher/timeout
get them added on next /gsd:update.
gsd-workflow-guard.js was missing the // gsd-hook-version: {{GSD_VERSION}}
header that all other hook files have. The stale hook detection in
gsd-check-update.js scans all gsd-*.js files for this header and flags
any without it as stale (hookVersion: 'unknown'). This caused a
persistent '⚠ stale hooks — run /gsd:update' warning in the statusline
even on the latest version.
Added the version header to gsd-workflow-guard.js. Running /gsd:update
will reinstall the hook with the correct version stamp.
loadConfig() defaulted commit_docs to true regardless of whether
.planning/ was gitignored. The documented auto-detection only existed
inside cmdCommit, so init commands returned commit_docs: true even
when .planning/ was in .gitignore. This caused LLM executors to
bypass the cmdCommit gate and re-commit planning files with raw git.
Now loadConfig() checks isGitIgnored(cwd, '.planning/') when no
explicit commit_docs value is set in config.json. If .planning/ is
gitignored, commit_docs defaults to false. An explicit commit_docs
value in config.json is always respected.
Added 5 regression tests covering auto-detection, explicit overrides,
and the no-config-file edge case.
cmdInitPlanPhase, cmdInitExecutePhase, and cmdInitVerifyWork returned
phase_found: false when the phase existed in ROADMAP.md but no phase
directory had been created yet. This caused workflows to fail silently
after /gsd:new-project, producing directories named null-null.
cmdInitPhaseOp (used by discuss-phase) already had a ROADMAP fallback.
Applied the same pattern to the three missing commands: when
findPhaseInternal returns null, fall back to getRoadmapPhaseInternal
and construct phaseInfo from the ROADMAP entry.
Added 5 regression tests covering:
- plan-phase ROADMAP fallback
- execute-phase ROADMAP fallback
- verify-work ROADMAP fallback
- phase_found false when neither directory nor ROADMAP entry exists
- disk directory preferred over ROADMAP fallback
On Windows, os.homedir() reads USERPROFILE instead of HOME. The 6
tests using { HOME: tmpDir } to sandbox ~/.gsd/ lookups failed on
windows-latest because the child process still resolved homedir to
the real user profile.
Pass USERPROFILE alongside HOME in all sandboxed test calls.
Integrate Exa (semantic search) and Firecrawl (deep web scraping) as
MCP-based research tools, following the existing Brave Search pattern.
- Add tool declarations to all 3 researcher agents
- Add tool strategy sections with usage guidance and priority
- Add config detection for FIRECRAWL_API_KEY and EXA_API_KEY env vars
- Add firecrawl/exa_search config keys to core defaults and init output
- Update source priority hierarchy across all researchers
The stats workflow was the only file using $GSD_TOOLS, which is never
defined anywhere. This caused the LLM to improvise the path at runtime,
producing the wrong directory (tools/) and extension (.mjs) instead of
the correct bin/gsd-tools.cjs used by all other workflows.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds an optional advisor mode to discuss-phase that provides research-backed
comparison tables before asking users to make decisions. Activates when
USER-PROFILE.md exists, degrades gracefully otherwise.
New agent: gsd-advisor-researcher -- spawned in parallel per gray area,
returns structured 5-column comparison tables calibrated to the user vendor
philosophy preference (full_maturity/standard/minimal_decisive).
Workflow changes (discuss-phase.md):
- Advisor mode detection in analyze_phase step
- New advisor_research step spawns parallel research agents
- Table-first discussion flow in discuss_areas when advisor mode active
- Standard conversational flow unchanged when advisor mode inactive
VALID_CONFIG_KEYS: merge our additions (workflow.auto_advance,
workflow.node_repair, workflow.node_repair_budget, hooks.context_warnings)
with upstream's additions (workflow.text_mode, git.quick_branch_template).
ensureConfigFile(): keep our refactored version that delegates to
buildNewProjectConfig({}) instead of upstream's duplicated logic.
buildNewProjectConfig(): add git.quick_branch_template: null and
workflow.text_mode: false to match upstream's new keys.
new-project.md: integrate upstream's Step 5.1 Sub-Repo Detection
after our commit block; drop upstream's duplicate Note (ours at
line 493 is more detailed).
1. Gate findProjectRoot to commands that access .planning/ — skip for
pure-utility commands (generate-slug, current-timestamp, template,
frontmatter, verify-path-exists, verify-summary) to avoid unnecessary
filesystem traversal on every invocation.
2. Warn to stderr when commit-to-subrepo encounters files that don't
match any configured sub-repo prefix.
3. Document that loadConfig auto-syncs sub_repos with the filesystem,
so config.json may be rewritten when repos are added or removed.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The workflow set commit_docs to false for multi-repo workspaces then
immediately ran gsd-tools commit on config.json, which would be
skipped. Replace with a note that config changes are local-only.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The hash recording step used `git rev-parse --short HEAD` which fails
when the project root is not a git repo (multi-repo workspaces). Update
the protocol to extract hashes from commit-to-subrepo JSON output and
record all sub-repo hashes in the SUMMARY.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- findProjectRoot: use isInsideGitRepo() to walk up and find .git in
ancestor dirs, fixing nested paths like backend/src/modules/
- Add sub_repos to cmdInitExecutePhase output so execute-plan.md and
gsd-executor.md can route commits correctly
- Align new-project.md sub-repo detection to maxdepth 1 matching
detectSubRepos() behavior
- Add 3 nested path tests for .git heuristic, sub_repos, and multiRepo
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add support for workspaces with multiple independent git repositories.
When configured, GSD routes commits to the correct sub-repo and ensures
.planning/ stays at the project root.
Core features:
- detectSubRepos(): scans child directories for .git to discover repos
- findProjectRoot(): walks up from CWD to find the project root that
owns .planning/, preventing orphaned .planning/ in sub-repos
- loadConfig auto-syncs sub_repos when repos are added or removed
- Migrates legacy "multiRepo: true" to sub_repos array automatically
- All init commands include project_root in output
- cmdCommitToSubrepo: groups files by sub-repo prefix, commits independently
Zero impact on single-repo workflows — sub_repos defaults to empty array.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Refactoring:
- Extract stateReplaceFieldWithFallback() to state.cjs as single source of truth
for the try-primary-then-fallback pattern that was duplicated inline across
phase.cjs, milestone.cjs, and state.cjs
- Replace all inline bold-only regex patterns in cmdPhaseComplete with shared
stateReplaceField/stateExtractField helpers — now supports both **Bold:**
and plain Field: STATE.md formats (fixes the same bug as #924)
- Replace inline bold-only regex patterns in cmdMilestoneComplete with shared helpers
- Replace inline bold-only regex for Completed Phases/Total Phases/Progress
counters in cmdPhaseComplete with stateExtractField/stateReplaceField
- Replace inline bold-only Total Phases regex in cmdPhaseRemove with shared helpers
Security:
- Fix command injection surface in isGitIgnored (core.cjs): replace execSync with
string concatenation with execFileSync using array arguments — prevents shell
interpretation of special characters in file paths
Tests (7 new):
- 5 tests for stateReplaceFieldWithFallback: primary field, fallback, neither,
preference, and plain format
- 1 regression test: phase complete with plain-format STATE.md fields
- 1 regression test: milestone complete with plain-format STATE.md fields
854 tests pass (was 847). No behavioral regressions.
- Add resolveWorktreeRoot() that detects linked worktrees via
git rev-parse --git-common-dir and resolves to the main worktree
where .planning/ lives
- Add withPlanningLock() file-based locking mechanism to prevent
concurrent worktrees from corrupting shared planning files
- Wire worktree root resolution into gsd-tools.cjs main entry point
- Add regression tests for resolveWorktreeRoot (non-git, normal repo)
and withPlanningLock (normal execution, error cleanup, stale lock
recovery)
When check-todos moves a file from pending/ to done/, the commit only
staged the new destination. The deletion of the source was never staged
because `git add` on a non-existent path is a no-op. Now we detect
missing files and use `git rm --cached` to stage the deletion.
Closes#1228
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The regex-based table parser captured a fixed number of columns,
so 5-column tables (Phase | Milestone | Plans | Status | Completed)
had the Milestone column eaten and Status/Date written to wrong cells.
Replaced regex with cell-based `split('|')` parsing that detects
column count (4 or 5) and updates the correct cells by index.
Affects both `cmdRoadmapUpdatePlanProgress` and `cmdPhaseComplete`.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The summary template puts the one-liner as a `**bold**` line after the
`# Phase N` heading, but `cmdSummaryExtract` and `cmdMilestoneComplete`
only checked frontmatter `one-liner` field — which is often empty.
Adds `extractOneLinerFromBody()` to core.cjs as a fallback that parses
the first `**...**` line after the heading.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
`cmdStateAdvancePlan` expected separate `Current Plan` and
`Total Plans in Phase` fields, but the current STATE.md template
uses a single compound field: `Plan: X of Y in current phase`.
Now tries legacy separate fields first, then falls back to parsing
the compound format. Preserves the compound format when writing back
(replaces only the plan number). Also handles `Last activity`
(lowercase) field name from current template.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Generate {phase_num}-DISCUSSION-LOG.md alongside CONTEXT.md during
discuss-phase sessions
- Log captures all options presented per gray area (not just the
selected one), user's choice, notes, Claude's discretion items,
and deferred ideas
- File is explicitly marked as audit-only — not for agent consumption
- Add discussion-log.md template with format specification
- Track Q&A data accumulation instruction in discuss_areas step
- Commit discussion log alongside CONTEXT.md in same git commit
- Add regression tests for workflow reference and template existence
- 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
The summary template writes task count as `**Tasks:** N` in the
Performance section, but `cmdMilestoneComplete` only counted
`## Task N` markdown headers — which don't exist in that format.
Now checks three patterns in order: `**Tasks:** N` field (primary),
`<task` XML tags, then `## Task N` headers (legacy fallback).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
`cmdRoadmapUpdatePlanProgress` only marked phase-level checkboxes
(e.g. `- [ ] Phase 50: Build`) but skipped plan-level entries
(e.g. `- [ ] 50-01-PLAN.md`). Now iterates phase summaries and
marks matching plan checkboxes as complete.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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.
Node 18 reached EOL April 2025. Node 24 is the current LTS target.
Changes:
- CI matrix: [18, 20, 22] → [20, 22, 24]
- package.json engines: >=16.7.0 → >=20.0.0
- Removed Node 18 conditional in CI (c8 coverage works on all 20+)
- Simplified CI to single test:coverage step for all versions
797/797 tests pass on Node 24.
Consolidates repeated path.join(cwd, '.planning', ...) patterns into
calls to the shared planningPaths() helper from core.cjs.
Modules updated:
- state.cjs: 16 → planningPaths() (2 remain for non-standard paths)
- commands.cjs: 8 → planningPaths() (4 remain for todos dir)
- milestone.cjs: 5 → planningPaths() (3 remain for archive/milestones)
- roadmap.cjs: 4 → planningPaths()
Benefits:
- Single source of truth for .planning/ directory structure
- Easier to change planning dir location in the future
- Consistent path construction across the codebase
- No behavioral changes — pure refactor
797/797 tests pass.
When GSD installs codex_hooks = true under [features], any non-boolean
keys already in that section (e.g. model = "gpt-5.4") cause Codex's
TOML parser to fail with 'invalid type: string, expected a boolean'.
Root cause: TOML sections extend until the next [section] header. If
the user placed model/model_reasoning_effort under [features] (common
since Codex's own config format encourages this), GSD's installer
didn't detect or correct the structural issue.
Fix: After injecting codex_hooks, scan the [features] section for
non-boolean values and move them above [features] to the top level.
This preserves the user's keys while keeping [features] clean for
Codex's strict boolean parser.
Includes 2 regression tests:
- Detects non-boolean keys under [features] (model, model_reasoning_effort)
- Confirms boolean keys (codex_hooks, multi_agent) are not flagged
Closes#1202
gsd-check-update.js scanned ALL .js files in the hooks directory and
flagged any without a gsd-hook-version header as stale. This incorrectly
flagged user-created hooks (e.g. guard-edits-outside-project.js),
producing a persistent 'stale hooks' warning that /gsd:update couldn't
resolve.
Fix: filter hookFiles to f.startsWith('gsd-') && f.endsWith('.js')
since all GSD hooks follow the gsd-* naming convention.
Includes regression test validating the filter excludes user hooks.
Closes#1200
Tests expected 39 skill folders but got 42 after adding add-backlog,
review-backlog, and thread commands. Updated both the hardcoded count
and EXPECTED_SKILLS constant.
Three new commands for managing ideas and cross-session context:
/gsd:add-backlog <description>
Adds a 999.x numbered backlog item to ROADMAP.md. Creates phase directory
immediately so /gsd:discuss-phase and /gsd:plan-phase work on them.
No dependencies, no sequencing — pure parking lot.
/gsd:review-backlog
Lists all 999.x items, lets user promote to active milestone, keep, or
remove. Promotion renumbers to next sequential phase with proper deps.
/gsd:thread [name | description]
Three modes:
- No args: list all threads with status
- Existing name: resume thread, load context
- New description: create thread from current conversation context
Threads live in .planning/threads/ as lightweight markdown files with
Goal, Context, References, and Next Steps sections.
Design:
- Self-contained command files, no core changes needed
- 999.x numbering keeps backlog out of active sequence
- Threads are independent of phases — cross-session knowledge stores
- Both features compose with existing GSD commands
Fixes#1005
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
* fix: universal agent name replacement for non-Claude runtimes (#766)
Adds neutralizeAgentReferences() shared function that all non-Claude
runtime converters call to replace Claude-specific references:
- 'Claude' (standalone agent name) → 'the agent'
- 'CLAUDE.md' → runtime-specific file (AGENTS.md, GEMINI.md, COPILOT.md)
- Removes 'Do NOT load full AGENTS.md' (harmful for AGENTS.md runtimes)
Preserves: 'Claude Code' (product), 'Claude Opus/Sonnet/Haiku' (models),
'claude-' prefixes (packages, CSS classes).
Integrated into: OpenCode, Gemini, Copilot, Antigravity, and Codex
converters. Claude Code converter unchanged (references are correct).
Includes 7 new tests covering all replacement rules.
Closes#766
* fix: use copilot-instructions.md instead of COPILOT.md for Copilot runtime
Addresses review from Solvely-Colin: Copilot's actual instruction file
is copilot-instructions.md, not COPILOT.md. The neutralizer was mapping
CLAUDE.md -> COPILOT.md which would reference a non-existent file.
- install.js: pass 'copilot-instructions.md' to neutralizeAgentReferences
- runtime-converters.test.cjs: update test to validate correct filename
The global HOME override in runGsdTools broke tests in verify-health.test.cjs
on Ubuntu CI: git operations fail when HOME points to a tmpDir that lacks
the runner's .gitconfig.
- runGsdTools now accepts an optional third `env` parameter (default: {})
merged on top of process.env — no behavior change for callers that omit it
- Pass { HOME: tmpDir } only in the 6 tests that need ~/.gsd/ isolation:
brave_api_key detection, defaults.json merging (x2), and config-new-project
tests that assert concrete default values (x3)
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
Code review fixes from codebase pattern analysis:
1. state.cjs: Remove duplicate stateExtractField() definition (lines 12 vs 184).
The second definition shadowed the first with identical logic. Keeps the
original that uses escapeRegex() from core.cjs.
2. init.cjs: Replace Unix-only 'find' pipe with cross-platform fs.readdirSync
recursive walk for code file detection. The execSync('find ... | grep ...')
command fails on Windows where these Unix utilities aren't available.
Removes unused child_process import.
3. state.cjs: Add lockfile-based mutual exclusion to writeStateMd() to prevent
parallel executor agents from overwriting each other's STATE.md changes.
Uses O_EXCL atomic file creation for lock acquisition, stale lock detection
(10s timeout), and spin-wait with jitter. Ensures data integrity during
wave-based parallel execution where multiple agents update STATE.md
concurrently.
All 755 existing tests pass.
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
Adds a Runtime State Inventory step that fires when a phase involves
renaming, rebranding, refactoring, or migrating strings across a codebase.
The core problem: grep audits find files. They do NOT find runtime state —
ChromaDB collection names, Mem0 user_ids, n8n workflows in SQLite, Windows
Task Scheduler descriptions, pm2 process names, SOPS key names, pip
egg-info directories, etc. These survive a complete file-level rename and
will break the system silently after the code is "done".
Three additions:
1. Pre-Submission Checklist — adds a reminder item so the checklist gate
catches skipped inventories before RESEARCH.md is committed
2. output_format — adds Runtime State Inventory table to the RESEARCH.md
template so the section appears in every rename/refactor phase's output
3. execution_flow Step 2.5 — structured investigation protocol with the
five categories (stored data, live service config, OS-registered state,
secrets/env vars, build artifacts), explicit examples for each, and the
canonical question that frames the whole exercise
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
Keep `/gsd-*` command examples slash-prefixed during Cursor conversion while still normalizing legacy `gsd:` syntax, and add regression coverage for Next Up markdown output.
Made-with: Cursor
Prevent Cursor from treating frontmatter quotes as part of skill/subagent identifiers by emitting plain name scalars, and add regression tests to lock the conversion behavior.
Made-with: Cursor
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
OpenCode does not recognize 'model: inherit' as a valid model identifier —
it throws ProviderModelNotFoundError when spawning any GSD subagent.
Changes:
- Remove 'model: inherit' injection for OpenCode agents in install.js
- Strip 'model:' field entirely during OpenCode frontmatter conversion
(OpenCode uses its configured default model when no model is specified)
- Update tests to verify model: inherit is NOT added
This fixes all 15 GSD agent definitions and the gsd-set-profile command
for OpenCode users.
Fixes#1156
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
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.
buildNewProjectConfig() merges ~/.gsd/defaults.json when present, so
tests asserting concrete config values (model_profile, commit_docs,
brave_search) would fail on machines with a personal defaults file.
- Pass HOME=cwd as env override in runGsdTools — child process resolves
os.homedir() to the temp directory, which has no .gsd/ subtree
- Update three tests that previously wrote to the real ~/.gsd/ using
fragile save/restore logic; they now write to tmpDir/.gsd/ instead,
which is cleaned up automatically by afterEach
- Remove now-unused `os` import from config.test.cjs
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>
On Windows, install.js resolves $HOME to the absolute path
(e.g. C:/Users/matte/.claude/) in all workflow .md files.
This breaks when ~/.claude is mounted into a Docker container
where the path doesn't exist — Node interprets the Windows path
as relative to CWD, producing paths like:
/workspace/project/C:/Users/matte/.claude/get-shit-done/bin/gsd-tools.cjs
For global installs, replace os.homedir() with ~ in pathPrefix
so that paths like ~/.claude/get-shit-done/bin/gsd-tools.cjs
work correctly across all environments.
Local installs keep using resolved absolute paths since they
may be outside $HOME.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add Cursor as a fifth supported runtime alongside Claude Code, OpenCode,
Gemini, and Codex. Cursor uses skills (~/.cursor/skills/gsd-*/SKILL.md)
like Codex, with tool name mappings (Bash→Shell, Edit→StrReplace),
subagent type conversion, and full Claude-to-Cursor content adaptation
including project conventions (CLAUDE.md→.cursor/rules/, .claude/skills/
→.cursor/skills/) and brand references.
Includes install, uninstall, interactive prompt, help text, manifest
tracking, and .cjs/.js utility script conversion.
Made-with: Cursor
- fix(core): getMilestoneInfo() version regex `\d+\.\d+` only matched
2-segment versions (v1.2). Changed to `\d+(?:\.\d+)+` to support
3+ segments (v1.2.1, v2.0.1). Same fix in roadmap.cjs milestone
extraction pattern.
- fix(state): stripFrontmatter() used `^---\n` (LF-only) which failed
to strip CRLF frontmatter blocks. When STATE.md had dual frontmatter
blocks from prior CRLF corruption, each writeStateMd() call preserved
the stale block and prepended a new wrong one. Now handles CRLF and
strips all stacked frontmatter blocks.
- fix(frontmatter): extractFrontmatter() always used the first ---
block. When dual blocks exist from corruption, the first is stale.
Now uses the last block (most recent sync).
Hook files (gsd-statusline.js, gsd-check-update.js, gsd-context-monitor.js)
are installed during updates but were never included in gsd-file-manifest.json.
This means saveLocalPatches() could not detect user modifications to hooks,
causing them to be silently overwritten on update with no backup.
Add hooks/gsd-*.js to writeManifest() so the existing local patch detection
system automatically backs up modified hooks to gsd-local-patches/ before
overwriting, matching the behavior already in place for workflows, commands,
and agents.
Co-Authored-By: Claude Opus 4.6 (1M context) <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
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
Two fixes to verify.cjs:
1. Add CWD guard to cmdValidateHealth — detects when CWD is the home
directory (likely accidental) and returns error E010 before running
checks that would read the wrong .planning/ directory.
2. Import and apply stripShippedMilestones to both cmdValidateConsistency
and cmdValidateHealth (Check 8) — prevents false warnings when
archived milestones reuse phase numbers.
This PR subsumes #1071 (strip archived milestones) to avoid merge
conflicts on the same import line.
Addresses patch 2 from #899, fixes#1060
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
resolveModelInternal() was converting 'opus' to 'inherit', assuming
the parent process runs on Opus. When the orchestrator runs on Sonnet
(the default), 'inherit' resolves to Sonnet — silently downgrading
quality profile subagents.
Remove the opus→inherit conversion so the resolved model name is
passed through directly. Claude Code's Task tool now supports model
aliases like 'opus', 'sonnet', 'haiku'.
Fixes#695
* feat: add Antigravity runtime support
Add full installation support for the Antigravity AI agent, bringing
get-shit-done capabilities to the new runtime alongside Claude Code,
OpenCode, Gemini, Codex, and Copilot.
- New runtime installation capability in bin/install.js
- Commands natively copied to the unified skills directory
- New test integration suite: tests/antigravity-install.test.cjs
- Refactored copy utility to accommodate Antigravity syntax
- Documentation added into README.md
Co-authored-by: Antigravity <noreply@google.com>
* fix: add missing processAttribution call in copyCommandsAsAntigravitySkills
Antigravity SKILL.md files were written without commit attribution metadata,
inconsistent with the Copilot equivalent (copyCommandsAsCopilotSkills) which
calls processAttribution on each skill's content before writing it.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: update Copilot install test assertions for 3 new UI agents
* docs: update CHANGELOG for Antigravity runtime support
---------
Co-authored-by: Antigravity <noreply@google.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Strip unsupported `skills:` key from gsd-ui-auditor, gsd-ui-checker, and
gsd-ui-researcher agent frontmatter. Update Copilot install test expectations
to 36 skills / 15 agents.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
Local installs wrote $HOME/.claude/get-shit-done/bin/gsd-tools.cjs into
workflow files, which breaks when GSD is installed outside $HOME (e.g.
external drives, symlinked projects) and when spawned subagents have an
empty $HOME environment variable.
- pathPrefix now always resolves to an absolute path via path.resolve()
- All $HOME/.claude/ replacements use the absolute prefix directly
- Codex installer uses absolute path for get-shit-done prefix
- Removed unused toHomePrefix() function
Tested: 535/535 existing tests pass, verified local install produces
correct absolute paths, verified global install unchanged, verified
empty $HOME scenario resolves correctly.
Closes#820
Made-with: Cursor
Co-authored-by: ralberts3 <ralberts3@gatech.edu>
convertClaudeToOpencodeFrontmatter() was designed for commands but is
also called for agents. For agents it incorrectly strips name: (needed
by OpenCode agents), keeps color:/skills:/tools: (should strip), and
doesn't add model: inherit / mode: subagent (required by OpenCode).
Add isAgent option to convertClaudeToOpencodeFrontmatter() so agent
installs get correct frontmatter: name preserved, Claude-only fields
stripped, model/mode injected. Command conversion unchanged (default).
Includes 14 test cases covering agent and command conversion paths.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
When a debug session resolves, append a structured entry to
.planning/debug/knowledge-base.md capturing error patterns,
root cause, and fix approach.
At the start of each new investigation (Phase 0), the debugger
loads the knowledge base and checks for keyword overlap with
current symptoms. Matches surface as hypothesis candidates to
test first — reducing repeat investigation time for known patterns.
The knowledge base is append-only and project-scoped, so it
builds value over the lifetime of a codebase rather than
resetting each session.
Phase numbers reset per milestone (v1.0 Phase 1-26, v1.1 Phase 1-6,
v1.2 Phase 1-6). Functions that searched ROADMAP.md for phase headings
or checkboxes would match archived milestone entries inside <details>
blocks before reaching the current milestone's entries.
This caused:
- roadmap_complete: true for phases that aren't complete (checkbox
regex matched the archived [x] Phase N from a previous milestone)
- phase-complete marking the wrong checkbox (archived instead of current)
- phase-add computing wrong maxPhase from archived headings
- progress not showing phases defined in ROADMAP but not yet on disk
The installer hardcoded `opencode.json` in all OpenCode config paths,
creating a duplicate file when users already had `opencode.jsonc`.
Add `resolveOpencodeConfigPath()` helper that prefers `.jsonc` when it
exists, and use it in all three OpenCode config touchpoints: attribution
check, permission configuration, and uninstall cleanup.
Closes#1053
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Wrap readdirSync and readFileSync calls in try/catch to silently skip
directories and files with restricted ACLs (e.g. Chrome/Gemini certificate
stores on Windows) instead of crashing the installer.
Closes#964
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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>
- Scope phase section regex to prevent cross-phase boundary matching
- Handle 'In Progress' status in traceability table (not just 'Pending')
- Add requirements_updated field to phase complete result object
- Add 3 new tests: result field, In Progress status, cross-boundary safety
Co-authored-by: ashanuoc <ashanuoc@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix: remove deprecated Codex config keys causing UI instability (closes#1037)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: update codex config tests to match simplified config structure
Tests asserted the old config structure ([features] section, multi_agent,
default_mode_request_user_input, [agents] table with max_threads/max_depth)
that was deliberately removed. Tests now verify the new behavior: config
block contains only the GSD marker and per-agent [agents.gsd-*] sections.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: remove dangling skills: from agent frontmatter and strip in Gemini converter (closes#1023, closes#953, closes#930)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: invert skills frontmatter test to assert absence (fixes CI)
The PR deliberately removed skills: from agent frontmatter (breaks
Gemini CLI), but the test still asserted its presence. Inverted the
assertion to ensure skills: stays removed.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When ROADMAP.md marks a phase as [x] complete, trust that over the
disk file structure. Phases completed before GSD tracking started
(or via external tools) may lack PLAN/SUMMARY pairs but are still
done — the roadmap checkbox is the higher-authority signal.
Without this fix, completed phases show as "discussed" or "planned"
in /gsd:progress, causing incorrect routing and progress percentages.
Fixes#977
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>
* fix: change nyquist_validation default to true and harden absent-key skip conditions
new-project.md never wrote the key, so agents reading config directly
treated absent as falsy. Changed all agent skip conditions from "is false"
to "explicitly set to false; absent = enabled". Default changed from false
to true in core.cjs, config.cjs, and templates/config.json.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: enforce VALIDATION.md creation with verification gate and Check 8e
Step 5.5 was narrative markdown that Claude skipped under context pressure.
Now MANDATORY with Write tool requirement and file-existence verification.
Step 7.5 gates planner spawn on VALIDATION.md presence. Check 8e blocks
Dimension 8 if file missing.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add W008/W009 health checks and addNyquistKey repair for Nyquist drift detection
W008 warns when workflow.nyquist_validation key is absent from config.json
(agents may skip validation). W009 warns when RESEARCH.md has Validation
Architecture section but no VALIDATION.md file exists. addNyquistKey repair
adds the missing key with default true value.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add /gsd:validate-phase command and gsd-nyquist-auditor agent
Retroactively applies Nyquist validation to already-executed phases.
Works mid-milestone and post-milestone. Detects existing test coverage,
maps gaps to phase requirements, writes missing tests, debugs failing
ones, and produces {phase}-VALIDATION.md from existing artifacts.
Handles three states: VALIDATION.md exists (audit + update), no
VALIDATION.md (reconstruct from PLAN.md + SUMMARY.md), phase not yet
executed (exit cleanly with guidance).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: audit-milestone reports Nyquist compliance gaps across phases
Adds Nyquist coverage table to audit-milestone output when
workflow.nyquist_validation is true. Identifies phases missing
VALIDATION.md or with nyquist_compliant: false/partial.
Routes to /gsd:validate-phase for resolution. Updates USER-GUIDE
with retroactive validation documentation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: compress Nyquist prompts to match GSD meta-prompt density conventions
Auditor agent: deleted philosophy section (35 lines), compressed execution
flow 60%, removed redundant constraints. Workflow: cut purpose bloat,
collapsed state narrative, compressed auditor spawn template. Command:
removed redundant process section. Plan-phase Steps 5.5/7.5: replaced
hedging language with directives. Audit-milestone Step 5.5: collapsed
sub-steps into inline instructions. Net: -376 lines.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The "depth" setting with values quick/standard/comprehensive implied
investigation thoroughness, but it only controls phase count. Renamed to
"granularity" with values coarse/standard/fine to accurately reflect what
it controls: how finely scope is sliced into phases.
Includes backward-compatible migration in loadConfig and config-ensure
that auto-renames depth→granularity with value mapping in both
.planning/config.json and ~/.gsd/defaults.json.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The installer only replaced ~/.claude/ (tilde form) when rewriting paths
for OpenCode, Gemini, and Codex installs. Source files also use
$HOME/.claude/ in bash code blocks (since ~ doesn't expand inside
double-quoted strings), leaving ~175 unreplaced references that break
gsd-tools.cjs invocations on non-Claude runtimes.
Adds $HOME/.claude/ replacement to all 6 path-rewriting code paths,
a toHomePrefix() utility to keep $HOME as a portable shell variable,
and a post-install scan that warns if any .claude references leak
through.
Closes#905
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When a phase modifies server, database, seed, or startup files, verify-work
now prepends a "Cold Start Smoke Test" that asks the user to kill, wipe state,
and restart from scratch — catching warm-state blind spots.
Closes#904
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Introduce ephemeral `workflow._auto_chain_active` flag to separate chain
propagation from the user's persistent `workflow.auto_advance` preference.
Previously, `workflow.auto_advance` was set to true by --auto chains and
only cleared at milestone completion. If a chain was interrupted (context
limit, crash, user abort), the flag persisted in .planning/config.json
and caused all subsequent manual invocations to auto-advance unexpectedly.
The fix adds a "sync chain flag with intent" step to discuss-phase,
plan-phase, and execute-phase workflows: when --auto is NOT in arguments,
the ephemeral _auto_chain_active flag is cleared. The persistent
auto_advance setting (from /gsd:settings) is never touched, preserving
the user's deliberate preference.
Closes#857
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When running /gsd:update from $HOME, the local path ./.claude/ resolves
to the same directory as $HOME/.claude/. The local branch always wins,
triggering --local reinstall that corrupts all paths in a global install.
This is self-reinforcing — once corrupted, every subsequent update
perpetuates the corruption.
Compare canonical paths (via cd + pwd) and only report LOCAL when the
resolved directories differ. When they're the same, fall through to
GLOBAL detection.
Closes#721
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The context monitor uses imperative language ("STOP new work
immediately. Save state NOW") that overrides user preferences and
causes autonomous state saves in non-GSD sessions. Replace with
advisory messaging that informs the user and respects their control.
- Detect GSD-active sessions via .planning/STATE.md
- GSD sessions: warn user, reference /gsd:pause-work, but don't
command autonomous saves (STATE.md already tracks state)
- Non-GSD sessions: inform user, explicitly say "Do NOT autonomously
save state unless the user asks"
- Remove all imperative language (STOP, NOW, immediately)
Closes#884
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Hooks hardcode ~/.claude/ as the config directory, breaking setups
where Claude Code uses a custom config directory (e.g. multi-account
with CLAUDE_CONFIG_DIR=~/.claude-personal/). The update check hook
shows stale notifications and the statusline reads from wrong paths.
- gsd-check-update.js: check CLAUDE_CONFIG_DIR before filesystem scan
- gsd-statusline.js: use CLAUDE_CONFIG_DIR for todos and cache paths
Closes#870
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The context monitor and statusline hooks wait for stdin 'end' event
before processing. On some platforms (Windows/Git Bash), the stdin pipe
may not close cleanly, causing the script to hang until Claude Code's
hook timeout kills it — surfacing as "PostToolUse:Read hook error" after
every tool call. Add a 3-second timeout that exits silently if stdin
doesn't complete, preventing the noisy error messages.
Closes#775
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Gap closure plans hardcode wave: 1 and depends_on: [], bypassing the
standard wave assignment logic. When multiple gap closure plans have
dependencies between them, they all land in wave 1 and execute in
parallel — ignoring dependency ordering. Add an explicit wave
computation step using the same assign_waves algorithm as standard
planning.
Closes#856
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Two defensive hardening changes:
1. state.cjs: Replace two identical inline extractField closures
(cmdStateSnapshot and buildStateFrontmatter) with a shared
stateExtractField(content, fieldName) helper at module scope.
The helper uses escapeRegex on fieldName before interpolation
into RegExp constructors, preventing breakage if a field name
ever contains regex metacharacters. Net removal of duplicated
logic.
2. gsd-plan-checker.md: Bound the "relevant" definition in the
exhaustive cross-check instruction. A requirement is "relevant"
only if ROADMAP.md explicitly maps it to this phase or the phase
goal directly implies it — prevents false blocker flags for
requirements belonging to other phases.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Two hardening changes to cmdMilestoneComplete:
1. Replace 27 lines of inline isDirInMilestone logic (roadmap parsing,
normalization, and matching) with a single call to the shared
getMilestonePhaseFilter(cwd) from core.cjs. The inline copy was
identical to the core version — deduplicating prevents future drift.
2. Handle empty MILESTONES.md files. Previously, an existing but empty
file would fall into the headerMatch branch and produce malformed
output. Now an empty file is treated the same as a missing one,
writing the standard "# Milestones" header before the entry.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Three files emit path.join or path.relative results directly into
JSON output without normalizing backslashes on Windows. Wrap these
with toPosixPath (already used in core.cjs and init.cjs) so agents
receive consistent forward-slash paths on all platforms.
Files changed:
- phase.cjs: wrap directory path in cmdPhasesFind
- commands.cjs: wrap todo path in cmdListTodos, relPath in cmdScaffold
- template.cjs: wrap relPath in cmdTemplateFill (both exists and
created branches)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
cmdRequirementsMarkComplete interpolates user-supplied reqId strings
directly into RegExp constructors. If a reqId contains regex
metacharacters (e.g. parentheses, brackets, dots), the patterns break
or match unintended content.
Import escapeRegex from core.cjs (already used in state.cjs and
phase.cjs) and apply it to reqId before interpolation into all four
regex patterns in the function.
Same class of fix as gsd-build/get-shit-done#741 (state.cjs).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The statusline uses a hardcoded 80% scaling factor for context usage,
but Claude Code's actual autocompact buffer is 16.5% (usable context is
83.5%). This inflates the displayed percentage and causes the context
monitor's WARNING/CRITICAL thresholds to fire prematurely.
Replace the 80% scaling with proper normalization against the 16.5%
autocompact buffer. Adjust color thresholds to intuitive levels
(50/65/80% of usable context).
Closes#769
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New test suite covering:
- HDOC: anti-heredoc instruction present in all 9 file-writing agents
- SKILL: skills: frontmatter present in all 11 agents
- HOOK: commented hooks pattern in file-writing agents
- SPAWN: no stale workaround patterns, valid agent type references
- AGENT: required frontmatter fields (name, description, tools, color)
509 total tests (462 existing + 47 new), 0 failures.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace general-purpose workaround pattern with named subagent types:
- plan-phase: researcher and planner now spawn as gsd-phase-researcher/gsd-planner
- new-project: 4 researcher spawns now use gsd-project-researcher
- research-phase: researcher spawns now use gsd-phase-researcher
- quick: planner revision now uses gsd-planner
- diagnose-issues: debug agents now use gsd-debugger (matches template spec)
Removes 'First, read agent .md file' prompt prefix — named agent types
auto-load their .md file as system prompt, making the workaround redundant.
Preserves intentional general-purpose orchestrator spawns in discuss-phase
and plan-phase (auto-advance) where the agent runs an entire workflow.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add skills: field to all 11 agent frontmatter files with forward-compatible
GSD workflow skill references (silently ignored until skill files are created).
Add commented hooks: examples to 9 file-writing agents showing PostToolUse
hook syntax for project-specific linting/formatting. Read-only agents
(plan-checker, integration-checker) skip hooks as they cannot modify files.
Per Claude Code docs: subagents don't inherit skills or hooks from the
parent conversation — they must be explicitly listed in frontmatter.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add 'never use heredoc' instruction to 6 agents that were missing it:
gsd-codebase-mapper, gsd-debugger, gsd-phase-researcher,
gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper.
All 9 file-writing agents now consistently prevent settings.local.json
corruption from heredoc permission entries (GSD #526).
Read-only agents (plan-checker, integration-checker) excluded as they
cannot write files.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When users select "Other" to provide freeform input, Claude re-prompts
with another AskUserQuestion instead of dropping to plain text. This
loops 2-3 times before finally accepting freeform input.
Add explicit freeform escape rule to questioning.md reference, and
update new-milestone.md and discuss-phase.md to switch to plain text
when users signal freeform intent.
Closes#778
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phases listed in ROADMAP.md but not yet planned (no directory on disk)
were excluded from total_phases, causing premature milestone completion.
Now uses Math.max(diskDirs, roadmapCount) via filter.phaseCount.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Extract getMilestonePhaseFilter() from milestone.cjs closure into core.cjs
as a shared helper. Apply it in buildStateFrontmatter and cmdPhaseComplete
so multi-milestone projects count only current milestone's phases instead
of all directories on disk.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Prevents re-asking questions already decided in earlier phases by reading
PROJECT.md, REQUIREMENTS.md, STATE.md, and all prior CONTEXT.md files
before generating gray areas. Prior decisions annotate options and skip
already-decided areas.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
zsh's built-in echo interprets \n escape sequences in JSON strings,
converting properly-escaped \\n back into literal newlines. This breaks
jq parsing with "control characters U+0000 through U+001F must be escaped".
printf '%s\n' preserves the JSON verbatim.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The auto-advance chain (discuss → plan → execute) was spawning each
subsequent phase as a Task(subagent_type="general-purpose"), creating
3-4 levels of nested agent sessions. At that nesting depth, the
Claude Code runtime hits resource limits or stdio contention, causing
the execute-phase to freeze or attempt to shell out to `claude` as a
subprocess (which is explicitly blocked).
The fix replaces Task spawns with Skill invocations for phase
transitions:
- discuss-phase auto-advance: Skill("gsd:plan-phase") instead of
Task(general-purpose)
- plan-phase auto-advance: Skill("gsd:execute-phase") instead of
Task(general-purpose)
The Skill tool runs in the same process context as the caller,
keeping the entire auto-advance chain flat at a single nesting level.
Each phase still spawns its own worker agents (gsd-executor,
gsd-planner, etc.) as Tasks, but the orchestration chain itself
no longer creates unnecessary depth.
Closes#686
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Three files had hardcoded `.claude` paths that break OpenCode and
Gemini installations where the config directory is `.config/opencode`,
`.opencode`, or `.gemini` respectively.
Changes:
- hooks/gsd-check-update.js: add detectConfigDir() helper that checks
all runtime directories for get-shit-done/VERSION, falling back to
.claude. Used for cache dir, project VERSION, and global VERSION.
- commands/gsd/reapply-patches.md: detect runtime directory for both
global and local patch directories instead of hardcoding ~/.claude/
and ./.claude/
- workflows/update.md: detect runtime directory for local and global
VERSION/marker files, and clear cache across all runtime directories
Closes#682
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Gemini CLI uses AfterTool as the post-tool hook event name, not
PostToolUse (which is Claude Code's event name). The installer was
registering the context monitor under PostToolUse for all runtimes,
causing Gemini to print "Invalid hook event name" warnings on every
run and silently disabling the context monitor.
Changes:
- install.js: use runtime-aware event name (AfterTool for Gemini,
PostToolUse for others) when registering context monitor hook
- install.js: uninstall cleans up both PostToolUse and AfterTool
entries for backward compatibility with existing installs
- gsd-context-monitor.js: runtime-aware hookEventName in output
- docs/context-monitor.md: document both event names with Gemini
example
Closes#750
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Expand dual-format parsing to cover all 8 field extraction and
replacement locations in state.cjs. The previous fix only covered
cmdStateSnapshot and buildStateFrontmatter (read path), leaving 6
write-path functions with bold-only regex that silently failed on
plain-format STATE.md files.
Functions fixed:
- stateExtractField: shared read helper (cascades to cmdStateAdvancePlan,
cmdStateRecordSession)
- stateReplaceField: shared write helper (cascades to all state mutations)
- cmdStateGet: individual field lookup
- cmdStatePatch: batch field updates
- cmdStateUpdate: single field updates
- cmdStateUpdateProgress: progress bar writes
- cmdStateSnapshot session section: Last Date, Stopped At, Resume File
Each function now tries **Field:** bold format first (preserving
existing behavior), then falls back to plain Field: format. This
eliminates the read/write asymmetry where state-snapshot could read
plain-format fields but state-update/state-patch could not modify them.
Closes#730
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The commit case in the CLI router reads only args[1] for the message,
which captures just the first word when the shell strips quotes before
passing arguments to Node.js. This silently truncates every multi-word
commit message (e.g. "docs(40): create phase plan" becomes "docs(40):").
Collect all positional args between the command name and the first
flag (--files, --amend), then join them. Works correctly whether the
shell preserves quotes (single arg) or strips them (multiple args).
Closes#733
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
extractField in state-snapshot and buildStateFrontmatter only matches
the **Field:** bold markdown format, but STATE.md may use plain
Field: format depending on how it was generated. When all fields
return null, progress routing freezes with no matching condition.
Add dual-format parsing: try **Field:** first, fall back to plain
Field: with line-start anchor. Both instances in cmdStateSnapshot
and buildStateFrontmatter are updated consistently.
Closes#730
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
getMilestoneInfo matches the first version string in ROADMAP.md, which
is typically the oldest shipped milestone. For list-format roadmaps
that use emoji markers (e.g. "🚧 **v2.1 Belgium**"), the function now
checks for the in-progress marker first before falling back to the
heading-based and bare version matching.
Closes#700
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
cmdPhaseComplete determines is_last_phase and next_phase by scanning
.planning/phases/ directories on disk. Phases defined in ROADMAP.md
but not yet planned (no directory created) are invisible to this scan,
causing premature is_last_phase:true when only the first phase has
been scaffolded.
Add a fallback that parses ROADMAP.md phase headings when the
filesystem scan finds no next phase. Uses the existing comparePhaseNum
utility for consistent ordering with letter suffixes and decimals.
Closes#709
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Without --no-index, git check-ignore only reports files as ignored if
they are untracked. Once .planning/ files enter git's index (e.g., from
an initial commit before .gitignore was set up), check-ignore returns
"not ignored" even when .gitignore explicitly lists .planning/.
This means the documented safety net — "if .planning/ is gitignored,
commit_docs is automatically false" — silently fails for any repo where
.planning/ was ever committed. The --no-index flag checks .gitignore
rules regardless of tracking state, matching user expectations.
Closes#703
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Expand Codex adapter with AskUserQuestion → request_user_input parameter
mapping (including multiSelect workaround and Execute mode fallback) and
Task() → spawn_agent mapping (parallel fan-out, result parsing).
Add convertClaudeAgentToCodexAgent() that generates <codex_agent_role>
headers with role/tools/purpose and cleans agent frontmatter.
Generate config.toml with [features] (multi_agent, request_user_input)
and [agents.gsd-*] role sections pointing to per-agent .toml configs
with sandbox_mode (workspace-write/read-only) and developer_instructions.
Config merge handles 3 cases: new file, existing with GSD marker
(truncate + re-append), existing without marker (inject features +
append agents). Uninstall strips all GSD content including injected
feature keys while preserving user settings.
Closes#779
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The SessionStart hook always writes to ~/.claude/cache/ via os.homedir()
regardless of install type. The update workflow previously only cleared
the install-type-specific path, leaving stale cache at the global path
for local installs.
Clear both ./.claude/cache/ and ~/.claude/cache/ unconditionally.
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
The #330 migration that renames `statusline.js` → `gsd-statusline.js`
uses `.includes('statusline.js')` which matches ANY file containing
that substring. For example, a user's custom `ted-statusline.js` gets
silently rewritten to `ted-gsd-statusline.js` (which doesn't exist).
This happens inside `cleanupOrphanedHooks()` which runs before the
interactive "Keep existing / Replace" prompt, so even choosing "Keep
existing" doesn't prevent the damage.
Fix: narrow the regex to only match the specific old GSD path pattern
`hooks/statusline.js` (or `hooks\statusline.js` on Windows).
Co-authored-by: ddungan <sckim@mococo.co.kr>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Claude Code subagents sometimes rewrite ~/. paths to relative paths,
causing MODULE_NOT_FOUND when CWD is the project directory. $HOME is a
shell variable resolved at runtime, immune to model path rewriting.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- gsd-executor: Add <analysis_paralysis_guard> block after deviation_rules.
If executor makes 5+ consecutive Read/Grep/Glob calls without any
Edit/Write/Bash action, it must stop and either write or report blocked.
Prevents infinite analysis loops that stall execution.
- gsd-plan-checker: Add exhaustive cross-check in Step 4 requirement coverage.
Checker now also reads PROJECT.md requirements (not just phase goal) to
verify no relevant requirement is silently dropped. Unmapped requirements
become automatic blockers listed explicitly in issues.
- gsd-planner: Add task-level TDD guidance alongside existing TDD Detection.
For code-producing tasks in standard plans, tdd="true" + <behavior> block
makes test expectations explicit before implementation. Complements the
existing dedicated TDD plan approach — both can coexist.
Co-authored-by: CyPack <GITHUB_EMAIL_ADRESIN>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Add lightweight codebase scanning before gray area identification:
- New scout_codebase step checks for existing maps or does targeted grep
- Gray areas annotated with code context (existing components, patterns)
- Discussion options informed by what already exists in the codebase
- Context7 integration for library-specific questions
- CONTEXT.md template includes code_context section
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix: use `.claude/skills/` instead of `.agents/skills/` in agent and workflow skill references
Claude Code resolves project skills from `.claude/skills/` (project-level)
and `~/.claude/skills/` (user-level). The `.agents/skills/` path is the
universal/IDE-agnostic convention that Claude Code does not resolve, causing
project skills to be silently ignored by all affected agents and workflows.
Fixes#758
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: support both `.claude/skills/` and `.agents/skills/` for cross-IDE compatibility
Instead of replacing `.agents/skills/` with `.claude/skills/`, reference both
paths so GSD works with Claude Code (`.claude/skills/`) and other IDE agents
like OpenCode (`.agents/skills/`).
Addresses review feedback from begna112 on #758.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Stephen Miller <Stephen@betterbox.pw>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
DEBUGGER_MODEL and CHECKER_MODEL used uppercase bash convention but the
Task() calls referenced {debugger_model} and {integration_checker_model}
(lowercase). The mismatch caused Claude to skip substitution and fall back
to the parent session model, ignoring the configured GSD profile.
Co-authored-by: Ethan Hurst <ethan.hurst@outlook.com.au>
stateReplaceField properly escaped fieldName before building the regex,
but stateExtractField did not. Field names containing regex metacharacters
could cause incorrect matches or regex errors.
Co-authored-by: Ethan Hurst <ethan.hurst@outlook.com.au>
loadConfig() never returned model_overrides, so resolveModelInternal()
could never find per-agent overrides — they were silently ignored.
Additionally, cmdResolveModel duplicated model resolution logic but
skipped the override check entirely. Now delegates to resolveModelInternal
so both code paths behave consistently.
Co-authored-by: Ethan Hurst <ethan.hurst@outlook.com.au>
loadConfig() didn't include nyquist_validation in its return object, so
cmdInitPlanPhase always set nyquist_validation_enabled to undefined. The
plan-phase workflow could never detect whether Nyquist validation was
enabled or disabled via config.
Co-authored-by: Ethan Hurst <ethan.hurst@outlook.com.au>
cmdPhasePlanIndex had 3 mismatches with the canonical XML plan format
defined in templates/phase-prompt.md:
- files_modified: looked up fm['files-modified'] (hyphen) but plans use
files_modified (underscore). Now checks underscore first, hyphen fallback.
- objective: read from YAML frontmatter but plans put it in <objective>
XML tag. Now extracts first line from the tag, falls back to frontmatter.
- task_count: matched ## Task N markdown headings but plans use <task>
XML tags. Now counts XML tags first, markdown fallback.
All three fixes preserve backward compat with legacy markdown-style plans.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The source now outputs posix paths; update the test to match instead
of using path.join (which produces backslashes on Windows).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add toPosixPath() helper to normalize output paths to forward slashes
- Use string concatenation for relative base paths instead of path.join()
- Apply toPosixPath() to all user-facing file paths in init.cjs output
- Use array-based execFileSync in test helpers to bypass shell quoting
issues with JSON args and dollar signs on Windows cmd.exe
Fixes 7 test failures on Windows: frontmatter set/merge (3), init
path assertions (2), and state dollar-amount corruption (2).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The run-tests.cjs child process now inherits NODE_V8_COVERAGE from the
parent so c8 collects coverage data. Also restores npm scripts to use
the cross-platform runner for both test and test:coverage commands.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
npm scripts pass `tests/*.test.cjs` to node/c8 as a literal string on
Windows (PowerShell/cmd don't expand globs). Adding `shell: bash` to CI
steps doesn't help because c8 spawns node as a child process using the
system shell. Use a Node script to enumerate test files cross-platform.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Windows PowerShell doesn't expand `tests/*.test.cjs` globs, causing
the test runner to fail with "Could not find" on Windows Node 20.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
cmdMilestoneComplete previously appended new milestone entries at the
end of MILESTONES.md. Over successive milestones this produced
chronological order (oldest first), which is counterintuitive — users
expect the most recent milestone at the top.
This fix detects the file header (h1-h3) and inserts the new entry
immediately after it, pushing older entries down. Files without a
recognizable header get the entry prepended. New files still get a
default '# Milestones' header.
Adds 2 tests: single insertion ordering assertion and three-sequential-
completions verification (v1.2 < v1.1 < v1.0 in file order).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
cmdMilestoneComplete previously iterated ALL phase directories in
.planning/phases/, including phases from prior milestones that remain on
disk. This produced inflated stats, stale accomplishments from old
summaries, and --archive-phases moving directories that belong to
earlier milestones.
This fix parses ROADMAP.md to extract phase numbers for the current
milestone, builds a normalized Set for O(1) lookup, and filters all
phase directory operations through an isDirInMilestone() helper.
The helper handles edge cases: leading zeros (01 -> 1), letter suffixes
(3A), decimal phases (3.1), large numbers (456), and excludes
non-numeric directories (notes/, misc/).
Adds 5 tests covering scoped stats, scoped archive, prefix collision
guard, non-numeric directory exclusion, and large phase numbers.
Complements upstream PRs #756 and #783 which fix getMilestoneInfo()
milestone detection — this fix addresses milestone completion scoping.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Pin actions/checkout and actions/setup-node to SHA for supply chain safety
- Run coverage threshold on all events (not just PRs) so direct pushes to main
are also gated
- Remove .planning/ artifact that was dev bookkeeping
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- branching_strategy assertion changed from strictEqual 'none' to typeof string check
- plan_check and verifier assertions changed from strictEqual true to typeof boolean checks
- Add isolation comments to three tests that touch ~/.gsd/ on real filesystem
- Full test suite passes: 433 tests, all modules above 70% coverage
- Missing phase number error path
- Nonexistent phase error path
- No plans found returns updated:false
- Partial completion updates progress table
- Full completion checks checkbox and adds date
- Missing ROADMAP.md returns updated:false
- 6 new tests (24 total in roadmap suite)
- roadmap.cjs coverage jumps from 71% to 99.32%
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Disk status variants: researched, discussed, empty branches covered
- Milestone extraction: version numbers and headings from ## headings
- Missing phase details: checklist-only phases without detail sections
- Success criteria: array extraction from phase sections
- 7 new tests (18 total in roadmap suite)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Badge shows workflow status for main branch
- Links to test.yml workflow in GitHub Actions
- Uses for-the-badge style matching existing badges
- Placed after npm downloads badge, before Discord badge
- --archive-phases flag moves phase dirs to milestones/vX.Y-phases/
- archived REQUIREMENTS.md contains header with version, SHIPPED, date
- STATE.md status/activity/description updated during milestone complete
- missing ROADMAP.md handled gracefully without crash
- empty phases directory handled with zero counts
- verify references (5): valid refs, missing refs, backtick paths, template skip, not found
- verify commits (3): valid hash, invalid hash, mixed valid+invalid
- verify artifacts (6): all criteria pass, missing file, line count, pattern, export, no artifacts
- verify key-links (6): pattern in source, pattern in target, pattern not found, no-pattern
string inclusion, source not found, no key_links in frontmatter
Notes:
- parseMustHavesBlock requires 4-space indent for block name, 6-space for items,
8-space for sub-keys; helpers use this format explicitly
- @https:// refs are NOT skipped by verify references (only backtick http refs are);
test reflects actual behavior (only template expressions are skipped)
- verify-summary returns not found for nonexistent summary
- verify-summary passes for valid summary with real files and commits
- verify-summary reports missing files mentioned in backticks
- verify-summary detects self-check pass and fail indicators
- REG-03: returns self_check 'not_found' when no section exists (not a failure)
- search(-1) regression: guard on line 79 prevents -1 from content.search()
- respects --check-count parameter to limit file checking
- 16 tests covering all 8 health checks (E001-E005, W001-W007, I001)
- 5 repair tests covering config creation, config reset, STATE regeneration, STATE backup, repairable_count
- Tests overall status logic (healthy/degraded/broken)
- All 21 tests pass with zero failures
- Creates temp dir with .planning/phases structure
- Initializes git repo with user config
- Writes initial PROJECT.md and commits it
- Exports createTempGitProject alongside existing helpers
- spliceFrontmatter: replace existing, add to plain content, exact body preservation
- parseMustHavesBlock: truths as strings, artifacts as objects with min_lines,
key_links with from/to/via/pattern, nested arrays, missing block, no frontmatter
- FRONTMATTER_SCHEMAS: plan/summary/verification required fields, all schema names
loadConfig() never returned model_overrides, so resolveModelInternal()
could never find per-agent overrides — they were silently ignored.
Additionally, cmdResolveModel duplicated model resolution logic but
skipped the override check entirely. Now delegates to resolveModelInternal
so both code paths behave consistently.
The verifier was the only agent missing the <project_context> section
that executor, planner, researcher, and plan-checker all have. This
aligns it with the existing pattern so project skills and CLAUDE.md
instructions are applied during verification and anti-pattern scanning.
Closes discussion from PR #723.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phase number parsing only matched single-decimal (e.g. 03.2) but crashed
on multi-level decimals (e.g. 03.2.1). Requirement IDs with regex
metacharacters (parentheses, dots) were interpolated raw into RegExp
constructors, causing SyntaxError crashes.
- Add escapeRegex() utility for safe regex interpolation
- Update normalizePhaseName/comparePhaseNum for multi-level decimals
- Replace all .replace('.', '\\.') with escapeRegex() across modules
- Escape reqId before regex interpolation in cmdPhaseComplete
- Update all phase dir matching regexes from (?:\.\d+)? to (?:\.\d+)*
- Add regression test for phase complete 03.2.1
Closes#621
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* Fix /gsd:update to pin installer to latest
* Harden /gsd:update install detection with global fallback
---------
Co-authored-by: Colin <colin@solvely.net>
Reduces token overhead of Dimension 8 and related agent additions by ~37%
with no behavioral change. Removes theory explanation, dead XML tags
(<manual>, <sampling_rate>), aspirational execution tracking, and
documentation-density prose from runtime agent bodies.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Add requirements_completed field to summary-extract output, mapping
from SUMMARY frontmatter requirements-completed key. Enables
/gsd:audit-milestone cross-check to receive data from SUMMARY source.
Re-applied from #631 against refactored codebase (commands.cjs + split tests).
Co-authored-by: Colin Johnson <Solvely-Colin@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
When orphaned SUMMARY.md files cause totalSummaries > totalPlans, the
progress percentage exceeds 100%, making String.repeat() throw RangeError
on negative arguments. Clamp percent to Math.min(100, ...) at all three
computation sites (state, commands, roadmap).
Closes#633
Co-authored-by: vinicius-tersi <vinicius-tersi@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Add native Codex support to the installer with a skills-first integration
path (--codex), including Codex-specific install/uninstall/manifest handling.
Closes#449
Records test generation in project state via state-snapshot call,
keeping add-tests consistent with other GSD workflows that track
their operations.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New command that generates unit and E2E tests for completed phases:
- Analyzes implementation files and classifies into TDD/E2E/Skip
- Enforces RED-GREEN gates for both unit and E2E tests
- Uses phase SUMMARY.md, CONTEXT.md, and VERIFICATION.md as test specs
- Presents test plan for user approval before generating
Test classification rules:
- TDD: pure functions where expect(fn(input)).toBe(output) is writable
- E2E: UI behavior verifiable by Playwright (keyboard, navigation, forms)
- Skip: styling, config, glue code, migrations, simple CRUD
Ref: Issue #302
Add --cwd <path> / --cwd=<path> support so sandboxed subagents running
outside the project root can target a specific directory. Invalid paths
return a clear error. Tests ported to tests/state.test.cjs (the old
monolithic test file was split into domain files on main).
Closes#622
Co-Authored-By: Colin Johnson <colin@solvely.net>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The `--auto` flag on discuss-phase and plan-phase chains stages automatically:
discuss → plan → execute, each in a fresh context window. Currently the chain
is broken because auto-advance spawns `Task(prompt="Run /gsd:plan-phase --auto")`
which requires the Skill tool — but Skills don't resolve inside Task subagents.
Result: plan-phase never runs from discuss's auto-advance, execute-phase never
runs from plan's auto-advance, and gsd-executor subagents are never spawned.
Fix: Replace `Task(prompt="Run /gsd:XXX")` with Task calls that tell the
subagent to read the workflow .md file directly via @file references — the same
pattern that already works for gsd-executor spawning in execute-phase.
Changes:
- execute-phase.md: Add --no-transition flag handling so execute-phase can
return status to parent instead of running transition.md when spawned by
plan-phase's auto-advance
- plan-phase.md: Replace Skill-based Task call with direct @file reference
to execute-phase.md, passing --no-transition to prevent transition chaining
- discuss-phase.md: Replace Skill-based Task call with direct @file reference
to plan-phase.md, with richer return status handling (PHASE COMPLETE,
PLANNING COMPLETE, PLANNING INCONCLUSIVE, GAPS FOUND)
Nesting depth: discuss → Task(plan) → Task(execute) → Task(executor) = 3 levels
max. Each level gets clean 200k context.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Break the 5324-line monolith into focused modules:
- core.cjs: shared utilities, constants, internal helpers
- frontmatter.cjs: YAML frontmatter parsing/serialization/CRUD
- state.cjs: STATE.md operations + progression engine
- phase.cjs: phase CRUD, query, and lifecycle
- roadmap.cjs: roadmap parsing and updates
- verify.cjs: verification suite + consistency/health validation
- config.cjs: config ensure/set/get
- template.cjs: template selection and fill
- milestone.cjs: milestone + requirements lifecycle
- commands.cjs: standalone utility commands
- init.cjs: compound init commands for workflow bootstrapping
gsd-tools.cjs is now a thin CLI router (~550 lines including
JSDoc) that imports from lib/ modules. All 81 tests pass.
Also updates package.json test script to point to tests/.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move 81 tests (18 describe blocks) from single monolithic test file
into 7 domain-specific test files under tests/ with shared helpers.
Test parity verified: 81/81 pass before and after split.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds automated feedback architecture research to gsd-phase-researcher,
enforces it as Dimension 8 in gsd-plan-checker, and introduces
{phase}-VALIDATION.md as the per-phase validation contract.
Ensures every phase plan includes automated verify commands before
execution begins. Opt-out via workflow.nyquist_validation: false.
Closes#122 (partial), related #117
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
/gsd:health --repair now creates a timestamped backup
(STATE.md.bak-YYYY-MM-DDTHH-MM-SS) before overwriting STATE.md,
preventing accidental data loss of accumulated context.
Co-Authored-By: Claude <noreply@anthropic.com>
Subagents now read project-level CLAUDE.md if it exists:
- Workflows: execute-phase, plan-phase, quick
- Agents: gsd-executor, gsd-planner, gsd-phase-researcher, gsd-plan-checker
Agents read ./CLAUDE.md in their fresh context, following project-specific
guidelines, security requirements, and coding conventions.
Fixes: #671
Co-Authored-By: Claude <noreply@anthropic.com>
Skills use '$gsd-*' syntax which isn't visible in the '/' command menu.
Adding parallel install to ~/.codex/prompts/gsd_*.md surfaces all GSD
commands as /prompts:gsd_* entries in the Codex UI slash command menu.
- Add installCodexPrompts() to install commands/gsd/*.md as prompts/gsd_*.md
- Add convertClaudeToCodexPrompt() to strip to description/argument-hint only
- Remove cleanupOrphanedFiles() code that was deleting prompts/gsd_*.md
- Both skills (30) and prompts (30) now install side by side
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds convertTaskCallsForCodex() to bin/install.js that transforms
Task(...) orchestration calls in workflow files to codex exec heredoc
invocations during Codex install.
- Paren-depth scanner handles multi-line Task() blocks reliably
- Supports all prompt= forms: literal, concat (+ var), bare var, triple-quoted
- Skips prose Task() references (no prompt= param or empty body)
- Applies only to workflows/ subdirectory, not references/templates/agents
- Sequential AGENT_OUTPUT_N capture vars for return value checks
- Source files unchanged; Claude/OpenCode/Gemini installs unaffected
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
gsd-executor had no instruction to update ROADMAP or REQUIREMENTS after
completing a plan — both stayed unchecked throughout milestone execution.
- Add `roadmap update-plan-progress` call to executor state_updates
- Add `requirements mark-complete` CLI command to gsd-tools
- Wire requirement marking into executor and execute-plan workflows
- Include ROADMAP.md and REQUIREMENTS.md in executor final commit
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fixes phase number handling to support all formats: integers (12),
decimals (12.1), letter-suffix (12A), and hybrids (12A.1).
Changes:
- normalizePhaseName() now handles letter+decimal format
- New comparePhaseNum() helper for correct sort order
- All directory .sort() calls use comparePhaseNum instead of parseFloat
- All phase-matching regexes updated with [A-Z]? for letter support
- cmdPhaseComplete uses comparePhaseNum for next-phase detection
- Export comparePhaseNum and normalizePhaseName for unit testing
- 14 new unit tests for comparePhaseNum (8) and normalizePhaseName (6)
Sort order: 12 → 12.1 → 12.2 → 12A → 12A.1 → 12A.2 → 12B → 13
Fixes#621
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Closes five gaps where requirements could slip through unchecked at milestone
level: audit now cross-references VERIFICATION.md + SUMMARY frontmatter +
REQUIREMENTS.md traceability, integration checker receives req IDs, gap objects
carry plan-level detail, plan-milestone-gaps updates traceability, and
complete-milestone gates on requirements status.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Gemini CLI's templateString() treats all ${word} patterns in agent
system prompts as template variables, throwing "Template validation
failed: Missing required input parameters: PHASE" when GSD agents
contain shell variables like ${PHASE} in bash code blocks.
Convert ${VAR} to $VAR in agent bodies during Gemini installation.
Both forms are equivalent bash; $VAR is invisible to Gemini's
/\$\{(\w+)\}/g template regex. Complex expansions like ${VAR:-default}
are preserved since they don't match the word-only pattern.
Closes#613
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Tighten all requirements references to use MUST/REQUIRED/CRITICAL language
instead of passive suggestions. Close the verification loop by extracting
phase requirement IDs from ROADMAP and passing them through the full chain:
researcher receives IDs → planner writes to PLAN frontmatter → executor
copies to SUMMARY → verifier cross-references against REQUIREMENTS.md with
orphan detection.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Write workflow.auto_advance to config.json so auto-mode survives
context compaction (re-read from disk on every workflow init)
- Auto-approve human-verify and auto-select first option for decision
checkpoints in both executor and orchestrator
- Pass --auto flag from plan-phase to execute-phase spawn
- Clear auto_advance on milestone complete (Route B)
- Document auto-mode checkpoint behavior in golden rules
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Closes#253 — plans were silently created without CONTEXT.md, and
discuss-phase didn't warn when plans already existed.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Auto mode now chains: new-project → discuss-phase 1 → plan → execute → transition
- Accept pasted text OR file reference (not just @ references)
- YOLO mode implicit in --auto (skip that question)
- Config questions (depth, git, agents) asked FIRST in new Step 2a
- Step 5 skipped in auto mode (config already collected)
- Auto-advance banner shown before invoking discuss-phase
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Enables quality guarantees on quick tasks without full milestone ceremony.
--full spawns plan-checker (max 2 iterations) and post-execution verifier,
produces VERIFICATION.md, and adds Status column to STATE.md table.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Wire execute-phase to invoke transition.md inline when --auto flag or
workflow.auto_advance config is set, propagate --auto through transition
to next phase invocations, add config-get command to gsd-tools, and fix
broken "config get" calls to use hyphenated "config-get" subcommand.
Closes#344
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document the #1 but... pattern for users who want a modified version
of an existing AskUserQuestion option without retyping it.
Closes#385
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
OpenCode uses "general" as its built-in general-purpose subagent type,
while Claude Code uses "general-purpose". This caused "Unknown agent type:
general-purpose is not a valid agent type" errors in OpenCode when running
workflows that spawn subagents (plan-phase, new-project, debug, etc.).
Fixes#411
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Strip .planning/ from staging before merge commits when commit_docs is
false. Prevents planning files from being committed during milestone
completion even when using branching strategies.
- Add commit_docs to config extraction in handle_branches step
- Reset .planning/ from staging before squash merge commits
- Use --no-commit flag for --no-ff merges to allow reset before commit
- Document branch merge behavior in planning-config.md
Closes#608
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phase directories created by /gsd:add-phase and /gsd:insert-phase were
empty until planning, causing git to ignore them. This prevented syncing
across machines.
Fixes#427
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Local OpenCode installs were overwriting ~/.config/opencode/opencode.json
instead of ./.opencode/opencode.json. This fix threads the isGlobal flag
through the install/uninstall chain so permissions are written to the
correct location.
Fixes#435
Co-Authored-By: Gary Trakhman <gtrak@users.noreply.github.com>
Adds ASCII diagram showing how plans are grouped into waves based on
dependencies. Independent plans run in parallel within a wave; waves
run sequentially when dependencies exist.
Addresses user confusion in #486 about why phases may not parallelize
(dependencies prevent parallel execution by design).
Add optional phase archival to milestone completion and a standalone
/gsd:cleanup command for retroactive use. Phase dirs move to
.planning/milestones/v{X.Y}-phases/, reducing phases/ clutter after
multiple milestones.
Core changes:
- getArchivedPhaseDirs() and searchPhaseInDir() helpers in gsd-tools
- findPhaseInternal() searches archives when phase not found in current
- cmdPhasesList() accepts --include-archived flag
- cmdHistoryDigest() scans both current and archived phases
- cmdMilestoneComplete() accepts --archive-phases flag
- Workflow globs replaced with find-phase/phases-list CLI calls
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When init commands include many file contents (state, roadmap, requirements,
etc.), the JSON output can exceed Claude Code's Bash tool buffer (~50KB),
causing parse errors. The output() function now auto-detects large payloads
and writes to a tmpfile, returning @file:/path instead. All workflows that
consume init output handle both formats.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Only auto-fix issues directly caused by current task's changes
- Log pre-existing/unrelated issues to deferred-items.md instead of fixing
- Cap auto-fix attempts at 3 per task to prevent infinite build/fix loops
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Multi-milestone roadmaps use #### for phases nested under milestone
headers. Expanded all phase-matching regexes from #{2,3} to #{2,4}.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New projects seed config from ~/.gsd/defaults.json when available,
skipping the 8 setup questions. /gsd:settings offers to save current
settings as global defaults after configuration.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phase insert failed when zero-padding differed between user input and
ROADMAP.md headers (e.g. "9.05" vs "09.05"). Normalize input and use
flexible regex matching with optional leading zeros.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Projects with "type": "module" in package.json cause Node to treat
gsd-tools.js as ESM, crashing on require(). The .cjs extension forces
CommonJS regardless of the host project's module configuration.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Allow overriding specific agent models without changing the entire profile.
Add model_overrides key to config that takes precedence over profile lookup.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Agents (executor, verifier, planner) were writing markdown files via
Bash heredocs. When approved, Claude Code persisted the entire heredoc
as a permission entry, breaking settings.local.json on next launch.
Added explicit "use Write tool" directives to all three agents and
added missing Write tool to gsd-verifier's tool list.
Closes#526Closes#491
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Typing /exec matched plan-phase instead of execute-phase because the
plan-phase description contained "execution plan".
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Three routing fixes:
- transition.md checks for CONTEXT.md before routing — discuss-phase when
missing, plan-phase when present (matches progress.md behavior)
- execute-phase.md offer_next delegates to transition.md instead of emitting
duplicate "Next Up" blocks
- discuss-phase.md adds explicit handling for "Other" free-text responses
Closes#530
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace NL instructions in execute-plan and execute-phase workflows with
deterministic `roadmap update-plan-progress` command that counts PLAN vs
SUMMARY files on disk. Prevents LLM from miscounting plan progress.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add opt-in mechanism to chain discuss → plan → execute automatically
via Task() subagents, eliminating manual /clear + paste overhead.
- Add `--auto` flag to discuss-phase and plan-phase commands
- Add `workflow.auto_advance` config toggle (default: false)
- Add auto_advance step to discuss-phase workflow (spawns plan-phase)
- Add step 14 to plan-phase workflow (spawns execute-phase)
- Add auto_advance toggle to /gsd:settings
Chain stops gracefully on INCONCLUSIVE, CHECKPOINT, or verification
failures. No work lost — artifacts persist at each step.
Closes#541
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The verifier was deriving verification truths from the vague one-line Goal
field, allowing partial implementations to pass. Now extracts Success Criteria
as a structured array from `roadmap get-phase` and uses them directly as truths,
with Goal derivation as fallback for older ROADMAPs without Success Criteria.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
cmdPhaseComplete now updates REQUIREMENTS.md when a phase finishes:
- Checks off requirement checkboxes (- [ ] → - [x])
- Updates traceability table status (Pending → Complete)
Parses Requirements line from ROADMAP.md phase section to find
which REQ-IDs belong to the completing phase.
Fixes#539
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add update_state step to record session info after context gathering,
matching the pattern used by execute-plan, add-todo, and other workflows.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fix hardcoded headers exceeding the 12-character validation limit and
add max-length guidance for dynamically generated headers.
Closes#559
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Claude Code's "opus" alias maps to a specific model version (claude-opus-4-1).
Organizations that block older opus versions while allowing newer ones see
agents silently fall back to Sonnet. By returning "inherit" instead, agents
use whatever opus version the user has configured in their session.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add `close_parent_artifacts` step to execute-phase workflow that resolves
parent UAT gaps and debug sessions when a decimal/polish phase completes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
`init phase-op` only checked disk for phase directories, failing on
phases with Plans: TBD since no directory exists yet. Now falls back
to parsing ROADMAP.md when findPhaseInternal returns null.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Hooks had hardcoded `.claude` paths that broke OpenCode users. The
installer now templates `.js` hooks with runtime-specific config dirs,
same as it already does for `.md` files. Also added `./.claude/`
replacement for local install paths in workflows.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Parser now accepts both `## Phase X:` and `### Phase X:` headers
- `roadmap get-phase` detects when phases exist in summary list but
missing detail sections, returns `error: 'malformed_roadmap'`
- `roadmap analyze` returns `missing_phase_details` array
- Updated gsd-roadmapper instructions with explicit format requirements
- Added 2 tests for new functionality (77 total, all passing)
Closes#598, closes#599
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The verifier agent interpreted {phase} as the full directory slug
(e.g., 01-foundation-target-system) instead of just the padded phase
number (01), producing wrong filenames like
01-foundation-target-system-VERIFICATION.md.
Changed all {phase}-*.md references to {phase_num}-*.md to match the
convention used in gsd-tools.js (${padded}-VERIFICATION.md).
Files: VERIFICATION.md, RESEARCH.md, CONTEXT.md, UAT.md patterns.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Projects with "type": "module" in package.json cause GSD scripts to fail
with "require is not defined" because Node.js walks up the directory tree
and inherits the module type.
Fix: Write {"type":"commonjs"} package.json to the install target (.claude/)
during installation. This stops Node from inheriting the project's ESM config.
- Install: writes package.json after VERSION file
- Uninstall: removes package.json only if it matches our marker
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add X (Twitter) badge linking to @gsd_foundation
- Add $GSD token badge linking to Dexscreener
- Fix Discord badge to show live member count (server ID 1463221958777901349)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Create docs/USER-GUIDE.md as a detailed companion to the README, covering:
- Workflow diagrams (project lifecycle, planning coordination, execution waves, brownfield)
- Command reference with "When to Use" guidance for each command
- Full config.json schema including workflow toggles, git branching, and per-agent model profiles
- Practical usage examples for common scenarios
- Troubleshooting section for common issues
- Recovery quick reference table
Add link from README navigation bar and Configuration section to the User Guide.
Closes#457
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add `websearch` command to gsd-tools.js for Brave API
- Detect BRAVE_API_KEY env var or ~/.gsd/brave_api_key file
- Persist brave_search setting to config.json on project init
- Update researcher agents to check config before calling
Graceful degradation: if brave_search is false, agents use
built-in WebSearch without wasted Bash calls.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Runs research → requirements → roadmap automatically after config
questions. Requires idea document via @ reference. Auto-includes all
table stakes features plus features mentioned in provided document.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
On Windows, child.unref() alone is insufficient for proper process
detachment. The child process remains in the parent's process group,
causing Claude Code to wait for the hook process tree to exit before
accepting input.
Adding detached: true allows the child process to fully detach on
Windows while maintaining existing behavior on Unix.
Closes#466
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- git tag command in complete-milestone.md used HEREDOC syntax
- HEREDOC fails silently on Windows Git Bash
- Literal newlines in quoted strings work cross-platform
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When user selects "Skip research" during /gsd:new-milestone, the choice
was not saved to .planning/config.json. Later, /gsd:plan-phase would
read the default (research: true) and spawn researchers anyway.
- Add `config-set` command to gsd-tools.js for setting nested config values
- Update new-milestone workflow to persist research choice after user decides
Closes#484
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(gsd-tools): add frontmatter CRUD, verification suite, template fill, and state progression
Four new command groups that delegate deterministic operations from AI agents to code:
- frontmatter get/set/merge/validate: Safe YAML frontmatter manipulation with schema validation
- verify plan-structure/phase-completeness/references/commits/artifacts/key-links: Structural checks agents previously burned context on
- template fill summary/plan/verification: Pre-filled document skeletons so agents only fill creative content
- state advance-plan/record-metric/update-progress/add-decision/add-blocker/resolve-blocker/record-session: Automate arithmetic and formatting in STATE.md
Adds reconstructFrontmatter() + spliceFrontmatter() helpers for safe frontmatter roundtripping,
and parseMustHavesBlock() for 3-level YAML parsing of must_haves structures.
20 new functions, ~1037 new lines.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: wire gsd-tools commands into agents and workflows
- gsd-verifier: use `verify artifacts` and `verify key-links` instead of
manual grep patterns for stub detection and wiring verification
- gsd-executor: use `state advance-plan`, `state update-progress`,
`state record-metric`, `state add-decision`, `state record-session`
instead of manual STATE.md manipulation
- gsd-plan-checker: use `verify plan-structure` and `frontmatter get`
for structural validation and must_haves extraction
- gsd-planner: add validation step using `frontmatter validate` and
`verify plan-structure` after writing PLAN.md
- execute-plan.md: use gsd-tools state commands for position/progress updates
- verify-phase.md: use gsd-tools for must_haves extraction and artifact/link verification
This makes the gsd-tools commands from PR #485 actually used by the system.
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Claude Code v2.1.27+ has a bug where all Task tool agents report
"failed" due to `classifyHandoffIfNeeded is not defined` — a function
called but never defined in the cli.js bundle. The error fires AFTER
all agent work completes, so actual work is always done.
This adds spot-check fallback logic to execute-phase, execute-plan,
and quick workflows: when an agent reports this specific failure,
verify artifacts on disk (SUMMARY.md exists, git commits present).
If spot-checks pass, treat as successful.
Tracked upstream: anthropics/claude-code#24181
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
When users modify GSD workflow files (e.g., adding bug workarounds),
those changes get wiped on every /gsd:update. This adds automatic
backup and guided restore:
**install.js changes:**
- Writes `gsd-file-manifest.json` after install with SHA256 hashes
of every installed GSD file
- Before wiping on update, compares current files against manifest
to detect user modifications
- Backs up modified files to `gsd-local-patches/` directory
- Reports backed-up patches after install completes
**New command: /gsd:reapply-patches**
- LLM-guided merge of backed-up modifications into new version
- Handles cases where upstream also changed the same file
- Reports merge status per file (merged/skipped/conflict)
**update.md changes:**
- Warning text now mentions automatic backup instead of manual
- New step after install to check for and report backed-up patches
Flow: modify GSD file → /gsd:update → modifications auto-backed up →
new version installed → /gsd:reapply-patches → modifications merged back
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The workflow showed the prompt content but didn't wrap it in Task()
with the required subagent_type parameter. This caused the orchestrator
to spawn generic task agents instead of the specialized gsd-executor.
Now shows the full Task() call with subagent_type and model parameters.
Fixes#455
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(execute-phase): pass file paths to subagents instead of content
The --include flag added in fa81821 caused orchestrator context bloat
by reading STATE, config, and plan files into the orchestrator's context,
then embedding all content in Task() prompts.
With multiple plans, this consumed 50-60%+ of context before execution.
Fix: Pass file paths only. Subagents read files themselves in their
fresh 200k context. Orchestrator stays lean (~10-15% as intended).
Fixes#479
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: respect commit_docs=false in execute-plan and debugger workflows
Two code paths bypassed the commit_docs configuration check, causing
.planning files to be intermittently committed when commit_docs=false:
1. execute-plan.md: update_codebase_map step ran `git add .planning/codebase/*.md`
unconditionally — now gated behind commit_docs check
2. gsd-debugger.md: used `git add -A` which stages .planning/ files — replaced
with explicit individual file staging and proper commit_docs conditional
Fixes#478https://claude.ai/code/session_013yS1F2VR3Jn2pdwqr5NuDo
* fix: route all .planning commits through gsd-tools.js CLI
Instead of wrapping direct git commands in markdown conditionals,
both bypass paths now use gsd-tools.js commit which has the
commit_docs check built in:
1. execute-plan.md: uses `gsd-tools.js commit --amend` for codebase
map updates (new --amend flag added to CLI)
2. gsd-debugger.md: code commit uses direct git (no .planning files),
planning docs commit uses gsd-tools.js commit
Also added --amend support to gsd-tools.js commit command so the
execute-plan codebase map step can amend the previous metadata commit.
Fixes#478https://claude.ai/code/session_013yS1F2VR3Jn2pdwqr5NuDo
* docs: update reference docs to use gsd-tools.js CLI for all .planning commits
Reference documentation showed direct git add/commit patterns for
.planning files, which agents copy-paste and bypass the commit_docs
check. Updated all three reference files to show gsd-tools.js commit
as the canonical pattern:
- git-planning-commit.md: replaced manual bash conditionals with CLI
- git-integration.md: replaced direct git add/commit in initialization,
plan-completion, and handoff examples
- planning-config.md: replaced conditional git example with CLI call
https://claude.ai/code/session_013yS1F2VR3Jn2pdwqr5NuDo
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
On Windows, path.join(os.homedir(), '.cursor') produces backslash paths (e.g. C:\Users\user\.cursor). When appended with forward slashes to build pathPrefix, this creates mixed-separator paths that break gsd-tools invocations:
Bash(node C:\Users\user\.claude/get-shit-done/bin/gsd-tools.js init map-codebase)
Normalize targetDir and opencodeConfigDir to forward slashes before concatenation so Node.js receives consistent paths on all platforms.
Co-authored-by: Cursor <cursoragent@cursor.com>
Workflows were calling init commands to get parsed JSON metadata, then
immediately reading the same files again with cat to pass raw content
to agents. This wastes context tokens.
Changes:
- Add --include flag to init execute-phase, plan-phase, and progress
- Support includes: state, config, roadmap, requirements, context,
research, verification, uat, project
- Update plan-phase.md to use --include (removes 6 cat calls)
- Update execute-phase.md to use --include (removes 2 cat calls)
- Update execute-plan.md to use --include (removes 2 cat calls)
- Update progress.md to use --include (removes 4 cat calls)
- Add 7 tests for --include functionality
Token savings: ~5,000-10,000 tokens per plan-phase execution,
~1,500-3,000 per other workflow executions.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The installer was using JSON.parse() which fails on JSONC (JSON with
Comments) files. OpenCode supports JSONC via jsonc-parser, so users
may have comments or trailing commas in their config.
Previously, parse failures would reset config to {} and overwrite the
user's file, causing data loss.
Changes:
- Add parseJsonc() to handle comments, trailing commas, and BOM
- On parse failure, skip permission config entirely instead of
overwriting user's file
- Show helpful error message with reason
Fixes#474
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Add three new commands that extract structured data from GSD files,
reducing context usage by returning only parsed fields instead of
raw file content:
- phase-plan-index: Plans grouped by wave with metadata (id, wave,
autonomous, objective, files_modified, task_count, has_summary)
- state-snapshot: Parsed STATE.md fields (current phase, decisions,
blockers, session info)
- summary-extract: Frontmatter extraction with optional --fields filter
Update workflows to use new commands:
- execute-phase: Use phase-plan-index instead of ls + grep loop
- plan-phase: Use state-snapshot for decisions
- research-phase: Use state-snapshot for decisions
- complete-milestone: Use summary-extract for one-liners
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Reverts af7a057 "feat: add GSD Memory cross-project knowledge system"
The memory system needs more work before shipping:
- Workflow integration is incomplete (writes but doesn't query)
- UX requires too much manual intervention
- Setup friction exceeds value for most users
Preserved on branch `memory-wip` for continued development.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements MCP server for semantic search across GSD projects:
MCP Tools:
- gsd_memory_search: Search across all registered projects
- gsd_memory_decisions: Find decisions from SUMMARY/PROJECT.md
- gsd_memory_patterns: Find patterns from SUMMARY.md
- gsd_memory_pitfalls: Find pitfalls from RESEARCH.md
- gsd_memory_stack: Find tech stack entries
- gsd_memory_register: Register project with memory
- gsd_memory_index: Trigger indexing/update
- gsd_memory_status: Show system status
Architecture:
- QMD wrapper with grep fallback when QMD unavailable
- YAML frontmatter extractors for GSD document types
- Project registry at ~/.gsd/projects.json
- Auto-install via bin/install.js for Claude Code
Workflow integrations:
- new-project: Registers project with memory
- plan-phase: Indexes after planning
- execute-phase: Indexes after execution
- complete-milestone: Indexes milestone completion
- Researcher agents query memory before Context7
Tests: 117 passing (66 unit + 51 integration)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
set-profile and settings commands hard-errored when .planning/config.json
did not exist, blocking users from changing model profile before running
new-project. Create config.json with balanced defaults when missing.
Executor self-check after SUMMARY.md creation verifies key-files exist
on disk and commit hashes exist in git log. Orchestrator spot-checks
SUMMARY claims before trusting and proceeding to next wave. Segmented
execution (execute-plan.md) gets the same self-check inline.
Fixes#363
The update command was hardcoded to use --global flag, which would
convert a local installation to a global one during updates.
Changes:
- Detect install type by checking ./.claude/ first, then ~/.claude/
- Use --local flag when updating a local install
- Use --global flag when updating a global install
- Update cache cleanup path to match install location
- Clarify warning message paths to be relative to install location
Fixes#343
The agent was misinterpreting commit_docs=false as 'skip file write'
when it should only skip git commit operations.
Changes:
- Explicitly state Write tool is mandatory in Step 5
- Clarify commit_docs only affects git operations, not file writes
- Rename Step 6 to indicate it's optional
- Make the file-write-then-commit order explicit
When updating GSD, the installer renames statusline.js to gsd-statusline.js
but didn't update existing settings.json references. Users with the old
config would see their status line disappear.
Now cleanupOrphanedHooks() also checks for and updates any statusLine
config pointing to the old path.
Fixes#330
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* prompt(001): map dependencies for new-project command
* fix(#326): enforce context fidelity in planning pipeline
Root cause: User decisions from CONTEXT.md were available but not
enforced throughout the RESEARCH → PLAN → VERIFY chain.
Changes:
- gsd-planner: Add <context_fidelity> section requiring agents to
parse and honor user decisions BEFORE creating tasks. Includes
self-check checklist and conflict handling guidance.
- gsd-phase-researcher: Add User Constraints as FIRST section in
downstream consumer table. Require researcher to copy CONTEXT.md
decisions verbatim to RESEARCH.md so planner sees them even if
it only skims.
- research.md template: Add <user_constraints> section that must
be populated first. Locked decisions, Claude's discretion, and
deferred ideas copied verbatim from CONTEXT.md.
The command file (commands/gsd/plan-phase.md) already passes
CONTEXT_CONTENT to all agents. These changes add the enforcement
layer in the agent instructions.
Fixes#326, #216, #206
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
- Add Character Preservation section to GSD-STYLE.md
- Clarify 'no special chars' applies to FILENAME only in add-todo
- Use 'box-drawing' terminology for tree structure visualization
Co-authored-by: FlightCore Dev <dev@flightcore.pl>
CONTEXT.md from /gsd:discuss-phase now flows through entire pipeline:
- Loaded early in step 4, stored for all agent spawns
- Researcher: constrains research scope (locked decisions vs discretion)
- Planner: explicit guidance to honor locked decisions
- Checker: new Context Compliance dimension to verify plans respect user vision
- Revision: reminder to maintain context compliance during fixes
Adds Dimension 7 (Context Compliance) to gsd-plan-checker:
- Verifies locked decisions have implementing tasks
- Flags if tasks contradict locked decisions
- Flags if deferred ideas included in plans
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add "Squash merge" as recommended option at complete-milestone
- Keep "Merge with history" (--no-ff) as alternative
- Document merge options in planning-config reference
Improves on #298 based on community feedback from @oojacoboo.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Gemini CLI to supported runtimes
- Update install examples with --gemini and --all flags
- Note native Gemini/OpenCode support in Community Ports section
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The if/else branches in copyFlattenedCommands were identical.
This function is only used by OpenCode (Gemini uses copyWithPathReplacement).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Claude Code enforces an 80% context window limit as a safety mechanism.
The statusline was showing the raw percentage, which meant the bar never
reached 100% before Claude ran out of context.
This change scales the percentage so that:
- 0% real usage = 0% displayed
- 80% real usage (the actual limit) = 100% displayed
Color thresholds are adjusted accordingly to maintain the same visual
progression (green -> yellow -> orange -> red with skull).
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Add configurable git branching with three strategies:
- none (default): commit to current branch
- phase: create branch per phase (gsd/phase-{N}-{slug})
- milestone: create branch per milestone (gsd/{version}-{slug})
Changes:
- planning-config.md: add git.branching_strategy and templates
- execute-phase.md: handle branch creation based on strategy
- settings.md: add branching strategy to settings UI
- complete-milestone.md: handle branch merging at milestone end
/gsd:update already shows changelog before updating, with cancel option.
Two commands for nearly the same purpose adds unnecessary cognitive load.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Standardize on *-CONTEXT.md glob pattern to match files like
03-CONTEXT.md across all workflows.
Files updated:
- commands/gsd/plan-phase.md
- commands/gsd/research-phase.md
- get-shit-done/workflows/discuss-phase.md
- get-shit-done/workflows/resume-project.md
Closes#219
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
OpenCode follows XDG Base Directory spec and expects config at
~/.config/opencode/, not ~/.opencode/. This fix:
- Add getOpencodeGlobalDir() to detect correct path via:
- OPENCODE_CONFIG_DIR env var
- OPENCODE_CONFIG env var (uses dirname)
- XDG_CONFIG_HOME/opencode
- ~/.config/opencode (default)
- Use 'command/' (singular) instead of 'commands/' (plural)
- Use flat file structure: command/gsd-help.md instead of
commands/gsd/help.md (invoked as /gsd-help)
- Write permissions to ~/.config/opencode/opencode.json
- Update content conversion to replace ~/.claude with
~/.config/opencode and /gsd: with /gsd-
Fixes OpenCode installation which was previously installing to
~/.opencode/ where OpenCode couldn't find the commands.
Users can now choose to install for Claude Code, OpenCode, or both
when running the installer interactively. New CLI flags:
- --claude: Install for Claude Code only
- --opencode: Install for OpenCode only
- --both: Install for both runtimes
The installer prompts for runtime first, then location. Backward
compatible - existing --global and --local flags still work.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When installing with --opencode, the installer now adds read and
external_directory permissions for ~/.opencode/get-shit-done/* to
~/.opencode.json. This prevents OpenCode from prompting for permission
every time GSD commands access reference docs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove package-lock.json from .gitignore so CI can use npm caching.
This fixes the "Dependencies lock file is not found" error in GitHub Actions.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Trim redundant documentation while preserving actionable instructions.
-173 lines of prose that restated what templates already show.
Kept: size constraints, mandatory fields, security guidance.
Removed: "when to create/read/update" lifecycle prose, section
descriptions that duplicate template structure.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Custom subagents cannot access MCP tools due to Claude Code bug #13898.
This affects gsd-phase-researcher, gsd-project-researcher, and gsd-planner
which need Context7 for documentation lookups.
Fix: Switch to general-purpose agent (which has MCP access) and have it
read the agent instruction file as its first action. The specialized
behavior comes from the prompt, not the agent definition.
Closes#161
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add GitHub Actions CI for cross-platform testing (ubuntu/windows/macos × node 18/20/22)
- Add release workflow that auto-creates GitHub Releases and publishes to npm on tag push
- Add CONTRIBUTING.md with branching strategy (maintainers direct commit, contributors PR)
- Add MAINTAINERS.md with release workflows and recovery procedures
- Add PR template for contributors
Closes#221
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Previously, closing the readline (via Escape, Ctrl+C, or stdin closure)
would default to global install. Now it cancels the installation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace $HOME with actual resolved path in hook command strings.
$HOME is a Unix shell variable that is not expanded by cmd.exe or
PowerShell on Windows, causing hooks to fail with MODULE_NOT_FOUND.
The fix uses a new buildHookCommand() helper that:
- Uses the actual claudeDir path instead of $HOME
- Normalizes backslashes to forward slashes for Node.js compatibility
* docs: enforce automation-first checkpoint verification
Checkpoints should never ask users to run CLI commands that Claude Code
can execute. This update reinforces the automation-first principle:
Key changes:
- Add golden rules: Claude runs CLI, users only visit URLs
- Add dev server automation patterns (start before checkpoint)
- Add environment variable CLI patterns (Convex, Vercel, etc.)
- Add anti-patterns: asking user to run npm, add dashboard env vars
- Update all examples to show Claude starting servers
- Add comprehensive "Never Ask Users To" and "Users Only Do" lists
- Update gsd-executor with pre-checkpoint automation requirements
The core principle: if Claude CAN automate it, Claude MUST automate it.
Users only do what requires human judgment (visual verification, UX).
* refactor: DRY checkpoint automation with server lifecycle and error handling
Changes:
- checkpoints.md is now single source of truth for automation-first patterns
- Added server lifecycle protocol (start, port conflicts, cleanup)
- Added CLI installation handling (auto-install matrix)
- Added pre-checkpoint failure handling (fix before checkpoint)
- Removed ~93 lines of duplication from verification-patterns.md
- Replaced inline examples in phase-prompt.md with references
- Slimmed gsd-executor.md checkpoint section to reference checkpoints.md
Net effect: -23 lines while adding 3 new capabilities (server lifecycle,
CLI install, error handling). Single place to update automation patterns.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Rolled back the intel system due to overengineering concerns:
- 1200+ line hook with SQLite graph database
- 21MB sql.js dependency
- Entity generation spawning additional Claude calls
- Complex system with unclear value
Removed:
- /gsd:analyze-codebase command
- /gsd:query-intel command
- gsd-intel-index.js, gsd-intel-session.js, gsd-intel-prune.js hooks
- gsd-entity-generator, gsd-indexer agents
- entity.md template
- sql.js dependency
Preserved:
- Model profiles feature
- Statusline hook
- All other v1.9.x improvements
-3,065 lines removed
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add model_profile question (balanced/quality/budget) to Round 2
- Add model_profile to config.json schema
- Reword agent questions to be clearer:
- "Spawn Plan Researcher?" → "Research before planning each phase?"
- "Spawn Plan Checker?" → "Verify plans will achieve their goals?"
- "Spawn Execution Verifier?" → "Verify work satisfies requirements after each phase?"
- Update descriptions to explain value, not mechanics
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create indexer agent for Steps 2-3 file indexing
- Uses exact regex patterns from analyze-codebase Step 3
- Writes index.json directly to disk (context preservation)
- Returns statistics only to orchestrator
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 05: Subagent Codebase Analysis
- 05-03: gsd-indexer subagent for file reading and export/import extraction
- 05-04: Refactor analyze-codebase Steps 2-3 to use indexer subagent
Gap closure addresses context exhaustion during indexing phase (Steps 2-3),
not just entity generation (Step 9).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Step 9.3 now spawns gsd-entity-generator subagent instead of Task batches
- Subagent receives file paths only (preserves orchestrator context)
- Subagent reads files in fresh 200k context, writes entities to disk
- Returns statistics only (not entity contents)
- Updated context section to document subagent execution model
- Fixed slug examples to use single hyphen format (matches hook)
- Simplified Steps 9.4-9.5 for new flow
- Add agent for semantic entity generation from source files
- Include entity template with frontmatter, purpose, exports, deps
- Define type heuristics table for module classification
- Specify wiki-link rules for internal vs external dependencies
- Agent writes directly to .planning/intel/entities/
- Returns statistics only (not entity contents)
All GSD hooks now use gsd- prefix. Installer updated to clean up old
statusline.js file and hook registration from previous installs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 05: Subagent Codebase Analysis
- 2 plans in 2 waves
- Plan 05-01: Create gsd-entity-generator subagent (Wave 1)
- Plan 05-02: Refactor analyze-codebase to use subagent (Wave 2)
- Ready for execution
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 5: Subagent Codebase Analysis
- Refactor entity generation from main context to subagent delegation
- Follow gsd-codebase-mapper pattern
- Prevent context exhaustion on 500+ file codebases
- Single subagent with full file list (not multiple batches)
- Subagent writes entities directly, returns statistics only
Exposes graph database queries to users:
- dependents <file> - what depends on this file (blast radius)
- hotspots - most-depended-on files
Closes tech debt item from v1.9.0 audit.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Wrap intel content in <codebase-intel> tags in plan-phase.md
- Use ENTITY_DIR constant in isEntityFile() instead of hardcoded path
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Read .planning/intel/summary.md into INTEL_CONTENT in Step 7
- Add {intel_content} placeholder to planning_context in Step 8
- Planner now receives dependency hotspots, module types at planning time
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add handleQuery() function to route query actions
- Support dependents and hotspots query types
- Route query actions via stdin handler before Write/Edit
- Return JSON results to stdout for Claude consumption
Phase 04-04: Expose orphaned getDependents() function
- Add handleQuery() routing for stdin query actions
- Enable "what uses this file?" queries via CLI
- Closes verification gap for INTEL-05
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- regenerateEntitySummary() now async, prefers graph when available
- Falls back to entity-file-based summary if no graph.db
- Stdin handler properly awaits async regeneration
- SessionStart hook injects graph-backed summary into context
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- generateGraphSummary() queries SQLite graph for rich summary
- Includes dependency hotspots with accurate counts from edges
- Groups nodes by type for module overview
- Tracks total relationships
- Target < 500 tokens for context injection
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- getHotspots() queries top N files by dependent count
- getNodesByType() groups nodes by type with counts
- getDependents() uses recursive CTE for transitive traversal
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add @anthropic-ai/sdk ^0.52.0 for entity generation API calls
- Required for semantic entity file creation in analyze-codebase
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add syncEntityToGraph() to upsert nodes and edges on entity write
- Entity id derived from filename, node body contains metadata as JSON
- Wiki-links [[target]] become edges with depends_on relationship
- Delete old edges before inserting new ones for clean updates
- Graph sync runs before summary regeneration
- Silent failures ensure Claude is never blocked
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add getSQL() for cached sql.js WASM initialization
- Add loadGraphDatabase() to create or load graph.db
- Add persistDatabase() to export in-memory DB to disk
- Singleton pattern avoids repeated WASM init overhead
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add sql.js ^1.12.0 dependency for WASM SQLite
- Add GRAPH_SCHEMA constant with nodes/edges tables
- Nodes use virtual id from JSON body for upserts
- Edges indexed by source and target for relationship queries
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
04-02: Added SessionStart hook wiring verification to Task 3 and
key_links. The hook already exists from Phase 2 - plan now verifies
it correctly injects the new graph-backed summary format.
04-03: Removed embedded JavaScript execution pattern. Commands are
instructions Claude follows, not scripts. Entity generation now uses
Task tool to spawn subagents for batch processing instead of pretending
markdown can execute JS.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds switchable model profiles (quality/balanced/budget) to control
which Claude model each agent uses, balancing quality vs token spend.
New files:
- get-shit-done/references/model-profiles.md - profile lookup table
- commands/gsd/set-profile.md - runtime profile switching
Updated orchestrators to resolve model before spawning agents:
- new-project, new-milestone (7 calls each)
- plan-phase (4 calls)
- execute-phase (3 calls)
- audit-milestone, debug, research-phase, quick (1-2 calls each)
- workflows: execute-phase, execute-plan, verify-work, map-codebase
Profile stored in .planning/config.json as model_profile.
Default: "balanced" (Opus for planning, Sonnet for execution).
Closes#160
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- SessionStart now reads pre-generated summary.md directly
- No more JSON parsing of potentially large index.json
- Added guidance: .planning/intel/ should always be gitignored
(changes constantly, can be regenerated with /gsd:analyze-codebase)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New intel-prune.js hook runs after each Claude response.
Checks if indexed files still exist, removes stale entries.
Fast (only fs.existsSync checks) and silent (never blocks).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Hook now checks if .planning/intel/ exists before indexing.
This prevents polluting non-GSD projects with intel files.
Directory is created by:
- /gsd:new-project (during setup)
- /gsd:analyze-codebase (explicit user action)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Codebase Intelligence section explaining automatic learning
- Document convention detection and context injection
- Add /gsd:analyze-codebase to Brownfield commands table
- List intel files and their purposes
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add load_codebase_intelligence step to gsd-planner.md
- Add load_codebase_intelligence step to gsd-executor.md
- Include .planning/intel/summary.md in plan context template
- Subagents now use detected conventions during planning/execution
- Create .planning/intel/ during Phase 1 setup
- Document intel directory in Creates and Output sections
- Directory prepared for PostToolUse hook population
- Split Phase 5 into two rounds of questions
- Round 1: core settings (mode, depth, parallel, git tracking)
- Round 2: workflow agents (researcher, plan checker, verifier)
- Add explainer table before workflow questions
- Include workflow section in config.json schema
- Note that /gsd:settings can update later
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Read session metadata from stdin
- Check for startup/resume source
- Read index.json and conventions.json from .planning/intel/
- Silent exit if no intel files present
Adds interactive settings command to toggle workflow agents:
- Plan Researcher (workflow.research)
- Plan Checker (workflow.plan_check)
- Execution Verifier (workflow.verifier)
Updates plan-phase.md and execute-phase.md to check config before
spawning these agents. Flags still override config per-invocation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Archived:
- milestones/v1.8.0-ROADMAP.md
- milestones/v1.8.0-REQUIREMENTS.md
Deleted (fresh for next milestone):
- ROADMAP.md
- REQUIREMENTS.md
Updated:
- MILESTONES.md (new entry)
- PROJECT.md (requirements → Validated)
- STATE.md (reset for next milestone)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds 4th question to initial config asking whether to commit planning
docs to git. When user selects "No", sets planning.commit_docs: false
and adds .planning/ to .gitignore.
Builds on #107 (uncommitted planning mode) by surfacing the option
during project initialization.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add uncommitted planning mode
Add config option to keep planning docs local-only (not committed to git).
Useful for OSS contributions, client projects, or keeping planning private.
Config options in .planning/config.json:
- planning.commit_docs: true/false (default: true)
- planning.search_gitignored: true/false (default: false)
When commit_docs=false:
- All git operations for .planning/ files are skipped
- User should add .planning/ to .gitignore
- Planning system works normally, just not tracked
Updated files:
- config.json template: added planning section
- execute-plan.md: conditional git commits
- execute-phase.md: conditional git commits
- create-roadmap.md: conditional git commits
- help.md: documented new config options
- planning-config.md: reference doc for config behavior
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: extend commit_docs check to all agents/commands/workflows
Add COMMIT_PLANNING_DOCS config check to all files that commit
.planning/ artifacts, ensuring consistent behavior when
commit_docs=false is set in config.json.
Updated:
- 5 agents (planner, executor, debugger, phase-researcher, synthesizer)
- 8 commands (add-todo, check-todos, execute-phase, new-milestone,
pause-work, plan-milestone-gaps, remove-phase, research-project)
- 7 workflows (complete-milestone, create-milestone, define-requirements,
diagnose-issues, discuss-phase, map-codebase, verify-work)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(progress): use Bash instead of Glob for .planning/ check
Glob respects .gitignore, so projects with gitignored .planning/
directories would fail with "No planning structure found."
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(new-milestone): integrate full research/requirements/roadmap flow
Previously routed to non-existent /gsd:research-project and
/gsd:define-requirements commands. Now handles the full flow inline
like new-project does:
- Phase 7: Research Decision (spawns 4 milestone-aware researchers)
- Phase 8: Define Requirements (scopes features, creates REQUIREMENTS.md)
- Phase 9: Create Roadmap (continues phase numbering from previous milestone)
- Phase 10: Done
Key adaptations for milestones:
- Research focuses on NEW features only
- Requirements add to existing, don't start fresh
- Phase numbering continues from previous milestone
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Quick tasks now use `{NNN}-PLAN.md` and `{NNN}-SUMMARY.md` naming
(e.g., `001-PLAN.md`, `001-SUMMARY.md`) matching the convention
used by regular phase plans (`01-01-PLAN.md`, `01-01-SUMMARY.md`).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- 383-line HTML with authentic 90s web aesthetic
- Garish lime green checkered background
- Comic Sans, Times New Roman, Courier mixed fonts
- Marquee tags for scrolling headers/footers
- Blink animation via CSS keyframes
- All 25 GSD commands organized in bordered tables
- Fake hit counter, guestbook link, webmaster email
- 'Under construction' banner and Y2K compliance badge
- Best viewed in Netscape Navigator disclaimer
- Add Quick Mode section in How It Works after Repeat section
- Add /gsd:quick entry to Utilities command table
- Document usage examples and output files
- Lists all 25 GSD commands with descriptions
- Organized into logical groups (Setup, Planning, Execution, etc.)
- Mobile-friendly responsive design
- Single-file with inline CSS, no dependencies
- Add Step 7 with table creation/update logic
- Check for existing Quick Tasks Completed section
- Create section after Blockers/Concerns if missing
- Append row with task number, description, date, commit, directory link
- Update Last activity line
- Add Step 6 with gsd-executor Task spawn
- Include plan reference and constraints
- Verify SUMMARY.md creation after executor returns
- Note wave execution support for multi-plan cases
- Add frontmatter with name, description, allowed-tools
- Include objective explaining quick mode purpose
- Add process section with steps 1-7 (orchestration deferred to Plan 02)
- Include success criteria for full quick task flow
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The update check script always looked for VERSION in ~/.claude/get-shit-done/,
but GSD can be installed locally in ./.claude/get-shit-done/. This caused
false "update available" notifications when using local installations.
Changes:
- Check project directory first, then fall back to global
- Remove unused execSync import
On Windows, the detached spawn option creates a visible console window.
Combined with npm (which is a .cmd batch file), this causes a brief
window flash that steals focus from the user's terminal.
- Remove detached: true (not needed, child.unref() handles non-blocking)
- Add windowsHide: true to both spawn() and inner execSync()
Convert inline array format to list format in discuss-phase.md
to match all other command files in the codebase.
Before: allowed-tools: [Read, Write, Bash, ...]
After: allowed-tools:
- Read
- Write
- Bash
...
The heading said gsd-researcher but the actual Task call uses
gsd-phase-researcher. Aligns with PR #180's cleanup.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Researcher agents were using literal "2025" in query template examples,
causing Claude to copy them verbatim instead of using the actual current
year. Changed to [current year] placeholder with explicit instruction to
check today's date.
Fixes#164
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove mentions of non-existent gsd-researcher agent from
discovery-phase.md and fix step numbering.
The agent was removed/renamed but the workflow still referenced
its "verification protocols".
Add proper @-references to three reference files that existed
but were never loaded:
- git-integration.md -> execute-plan.md
- continuation-format.md -> resume-project.md
- verification-patterns.md -> verify-phase.md
Fixes#119 - Installation on WSL2 via npx would report success but
files weren't actually copied due to stdin handling issues.
Changes:
- Detect non-TTY stdin and fall back to global install automatically
- Handle premature readline close events
- Verify each component exists after copying before showing success
- Exit with error if any critical component fails to install
- Show workaround command when installation fails
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Users who installed before the hook was removed have stranded files
and hook registrations. Installer now removes both:
- The orphaned file (hooks/gsd-notify.sh)
- The hook registration in settings.json
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
After verify-work diagnoses issues and creates fix plans, the next
command now explicitly signals intent with --gaps-only. This eliminates
redundant state discovery where execute-phase had to figure out why it
was being asked to run on an already-complete phase.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rewrite "How It Works" with 6 clear steps: init → discuss → plan → execute → verify → complete
- Emphasize discuss-phase as where users shape implementation (feeds research + planning)
- Emphasize verify-work as where users confirm features actually work (auto-diagnoses failures)
- Add brownfield callout at top of How It Works instead of separate section
- Move discuss-phase, verify-work, new-milestone into Core Workflow commands
- Replace "Subagent Execution" with "Multi-Agent Orchestration" explaining thin orchestrator pattern
- Highlight 30-40% context usage even after thousands of lines of code
Phase directories are now created on-demand when discuss-phase or
plan-phase first touches a phase, rather than upfront by roadmapper.
Prevents duplicate folders when roadmapper names phases differently
than what discuss/plan-phase derives from the roadmap.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Wipe commands/gsd/ and get-shit-done/ before copying
- Delete only gsd-*.md agents (preserves user agents)
- Add confirmation step to /gsd:update with changelog preview
- Warn users about clean install behavior before updating
Add structured next-step routing consistent with other GSD commands.
Four routes: pass+continue, pass+milestone, issues+ready, issues+blocked.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Commands with <offer_next> sections were outputting backticks literally
instead of rendering them as inline code. Removed code block wrappers
and added explicit 'Output this markdown directly' instruction.
Affected: plan-phase, execute-phase, audit-milestone
Updated routing in:
- new-project.md
- create-roadmap.md (command and workflow)
- progress.md (routes B and C)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Convert statusline.sh and gsd-check-update.sh to Node.js
- Remove gsd-notify.sh (blocking popups, not true toasts)
- Remove --force-notify and --no-notify flags from installer
- Use `node` command for cross-platform hook execution
Fixes#114
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove useless "None — you decide" skip option
- Generate phase-specific gray areas based on domain analysis
(UI features, CLI tools, APIs, organization tasks, etc.)
- Increase probing depth: 4 questions per area before check
- Make context.md categories flexible (emerge from discussion)
- Add CLI and organization examples to context template
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Commands accept both padded (08) and unpadded (8) phase numbers.
Normalization happens in step 1/2 before any directory lookups.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Support both zero-padded (05-*) and unpadded (5-*) phase folders
- Delete orphaned research-subagent-prompt.md template
- Update resume-project.md to use Task tool resume parameter
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
/gsd:execute-phase handles single and multiple plans.
All references updated to use execute-phase.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Commands load agent expertise directly via Task tool spawning.
Thin orchestrator pattern — agents have methodology baked in.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Orchestrator sometimes makes small fixes between executor completions
(missing imports, wiring fixes). These were left uncommitted. Now
checks for dirty state after all waves complete and commits if needed.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Revision mode was missing git commit step - plans updated based on
checker issues were written to disk but never committed.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
STATE.md reflects project state, not session state. It persists across
sessions and shows misleading info like "Phase complete" from previous
work. Now only uses session-scoped todo list.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Researcher was only checking if CONTEXT.md exists (ls), not
actually reading it (cat). Added mandatory bash command to
read phase context file in step 1.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The hook was grepping for `current_phase:` and `status:` but STATE.md
uses `Phase:` and `Status:`. Now shows actual phase info instead of
always falling back to "Ready for input".
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Planner was only describing that it should use these files,
not explicitly reading them. Added mandatory bash commands
to cat phase-specific context files in gather_phase_context step.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Researcher now reads and respects user decisions from discuss-phase:
- Locked decisions constrain research scope
- Claude's discretion areas get options explored
- Deferred ideas ignored
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Research is now integrated into /gsd:plan-phase by default.
Remove standalone research command from "Also available" sections.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Alerts user when Claude stops (task complete, needs input, etc.)
with context about what completed. Works on Mac (osascript alert),
Linux (notify-send/zenity), and Windows (PowerShell MessageBox).
Follows same optional install pattern as statusline:
- Prompts in interactive mode if existing hook detected
- --force-notify to replace existing
- --no-notify to skip installation
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds SessionStart hook that checks npm in background, caches result.
Statusline shows "⬆ /gsd:update │" when update available.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes#82
When add-phase or insert-phase creates placeholder entries in ROADMAP.md,
plan-phase now finalizes them:
- Goal: derives from CONTEXT.md/RESEARCH.md if placeholder
- Plans: updates count and adds checkbox list of plan files
- Commits ROADMAP.md alongside PLAN.md files
Clarifies that users can run /gsd:discuss-phase first to specify
UI/UX/behavior decisions before planning. Creates CONTEXT.md that
guides the planner. Optional if defaults are acceptable.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
User setup info belongs in plan frontmatter only. The execute-plan
workflow surfaces it at the right time (after automation completes).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Collapse 5-step flow into 4 clear phases
- Show /gsd:new-project as single ~10min initialization flow
- Document research → plan → verify loop in plan-phase
- Document parallel waves + verification in execute-phase
- Remove deprecated commands: execute-plan, research-project,
define-requirements, create-roadmap, research-phase,
list-phase-assumptions
- Reorganize commands table with Core Workflow at top
- Simplify brownfield section
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Closes#106 - Users didn't know what to type when presented with
test expectations. Now uses GSD checkpoint box format with explicit
"Type 'pass' or describe what's wrong" instruction.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Researchers are always spawned in parallel (4 at once). Committing is
now exclusively handled by the orchestrator or synthesizer agent after
all researchers complete.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Researchers now skip commit step when spawned in parallel.
Synthesizer agent commits STACK.md, FEATURES.md, ARCHITECTURE.md,
PITFALLS.md, and SUMMARY.md in one atomic commit.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add ui-brand.md reference with visual patterns:
- Stage banners with GSD ► prefix
- Checkpoint boxes (62-char width)
- Status symbols vocabulary
- Next Up routing blocks
Update orchestrators to use branded output.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Present proposed roadmap nicely inline (table + phase details)
- Use AskUserQuestion to confirm before committing
- Options: Approve, Adjust phases, Review full file
- Loop on adjustments until user approves
Previously, roadmap was committed immediately without user review.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create dedicated synthesizer agent to handle research synthesis
- Move SUMMARY.md creation from main orchestrator to subagent
- Reduces main context usage (~2000+ lines of research output)
- Synthesizer reads 4 research files and produces unified summary
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Consolidates 4 separate commands into one unified flow:
- /gsd:new-project now handles: questioning → research → requirements → roadmap
- Creates gsd-roadmapper agent for heavy lifting (goal-backward, coverage validation)
- Adds atomic commits after each stage for crash recovery
- Deprecates standalone research-project, define-requirements, create-roadmap
(kept for mid-project use)
Fixes from audit:
- Add requirements quality criteria (specific, user-centric, atomic, independent)
- Add milestone context to research prompts (greenfield vs subsequent)
- Add quality gates per research dimension
- Add template references for consistent output format
Removes deprecated gsd-researcher.md (replaced by project/phase researchers)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Research decisions made at roadmap creation time are:
- Premature: Can't know if research is needed before discuss-phase
- Redundant: --skip-research flag exists for explicit control
- Counterproductive: Gives Claude an excuse to skip research entirely
Removed:
- Research: Likely/Unlikely fields from roadmap template
- detect_research_needs step from create-roadmap workflow
- "If roadmap flagged Research: Likely" checks from gsd-planner
Research now always runs during plan-phase unless:
- RESEARCH.md already exists (silent reuse)
- --skip-research flag passed
- --gaps flag passed (gap closure mode)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Analyze phase to identify gray areas by category (UI, UX, Behavior, etc.)
- Present multi-select for user to choose which areas to discuss
- Deep-dive each selected area with focused questioning loop
- Explicit scope guardrail: clarify HOW, never expand WHAT
- Capture deferred ideas without acting on them
- Downstream awareness: CONTEXT.md feeds researcher and planner agents
- Template restructured for decisions (domain, decisions, discretion, deferred)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Split gsd-researcher into two specialized agents:
- gsd-phase-researcher: tailored for phase research before planning
- gsd-project-researcher: tailored for ecosystem research before roadmap
Updated /gsd:plan-phase to auto-research before planning:
- Research runs if no RESEARCH.md exists (silent use if exists)
- --research flag forces re-research
- --skip-research flag bypasses research entirely
- Researchers commit their output
This enables single-command workflow: /gsd:plan-phase does
research → plan → verify in one orchestrated flow.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds back guidance that was lost during consolidation:
- Task sizing heuristic (15-60 min target)
- Signals for too large / too small tasks
- Specificity side-by-side examples table
- "The test" for checking task clarity
Tasks completed: 3/3
- Add revision_mode section with 6-step process
- Update role section for revision mode
- Add REVISION COMPLETE return format
SUMMARY: .planning/phases/16-plan-verification-loop/16-03-SUMMARY.md
- Plans created (PLANNING COMPLETE or CHECKPOINT handled)
- gsd-plan-checker spawned (unless --skip-verify)
- Verification passed OR user override OR max iterations with user decision
- User sees status between agent spawns
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Steps 1-7: Validate, parse, spawn planner (existing flow)
- Step 8: Spawn gsd-plan-checker with verification_context
- Step 9: Handle checker return (passed | issues)
- Step 10: Revision loop (max 3 iterations)
- Step 11: Present final status with verification outcome
User sees ping-pong between planner and checker in main context.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove context: fork (orchestrator stays in main context)
- Add --skip-verify flag to argument-hint
- Add Task tool to allowed-tools for spawning checker
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Tasks completed: 2/2
- Create gsd-plan-checker agent with six verification dimensions
- Examples included for common failure modes
SUMMARY: .planning/phases/16-plan-verification-loop/16-01-SUMMARY.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replaced 868-line workflow with deprecation notice
- Points to agents/gsd-planner.md for methodology
- Documents historical content for reference
- Kept file for git history
Note clarifies relationship with gsd-planner agent:
- Planning methodology is in agents/gsd-planner.md
- This template defines the PLAN.md output format
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- principles.md: redirects to <philosophy> section
- plan-format.md: redirects to <plan_format> section
- scope-estimation.md: redirects to <scope_estimation> section
- goal-backward.md: redirects to <goal_backward> section
All content preserved in agents/gsd-planner.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds context: fork and agent: general-purpose to plan-phase command.
This isolates the heavy discovery/synthesis work in a fresh 200k context
window, keeping the main conversation clean.
Removes AskUserQuestion from allowed-tools (workflow doesn't use it).
This agent was correctly deleted in f3e0e69 (subagents can't spawn
subagents), then accidentally re-added in d07ef33 during install fix.
The command audit-milestone.md is the orchestrator. No agent needed.
- Install statusline.sh to {claudeDir}/hooks/
- Configure statusLine in settings.json automatically
- Skip if statusline already exists (non-interactive)
- Prompt to keep/replace in interactive mode
- Add --force-statusline flag to override
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
research-phase.md:
- Added <key_insight> framing ("what don't I know that I don't know")
- Added <downstream_consumer> explaining plan-phase integration
- Added <quality_gate> checklist
research-project.md:
- Added milestone context (greenfield vs v1.1+)
- Added <downstream_consumer> per dimension
- Added <quality_gate> per agent
- Enhanced roadmap implications guidance
gsd-researcher.md:
- Simplified <gsd_integration> to point to orchestrator-provided context
- Agent is now pure research capability, context is injected
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Reduces context exhaustion during /gsd:map-codebase by having agents
write documents directly instead of returning findings to orchestrator.
- Create gsd-codebase-mapper agent with embedded templates
- Agent understands downstream consumers (plan-phase, execute-plan)
- Parameterized by focus: tech, arch, quality, concerns
- Each focus writes specific documents directly to .planning/codebase/
- Orchestrator receives only confirmation + line counts
Context savings: ~40 lines returned vs potentially thousands of lines
of exploration findings previously transferred back to orchestrator.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Explains why research matters: output directly consumed by plan-phase.
Documents the contract between RESEARCH.md sections and planning workflow.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The context section now includes @.planning/MILESTONE-CONTEXT.md so
Claude actually loads the file from discuss-milestone instead of just
seeing a text mention in the process steps.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Reduce from ~540 lines (command + workflow) to 130 lines
- Delegate research methodology to gsd-researcher agent
- Keep phase validation, context gathering in orchestrator
- Add spawn and continuation patterns for agent
- Replaced 665-line workflow with 14-line redirect
- Points to agents/gsd-debugger.md for debugging expertise
- Preserves git history while marking content as moved
- Reduced from 202 lines to 149 lines
- Removed workflow/reference loading (expertise now in agent)
- Uses subagent_type="gsd-debugger" instead of "general-purpose"
- Keeps symptom gathering and checkpoint handling in orchestrator
The agents folder (gsd-executor, gsd-verifier, gsd-integration-checker,
gsd-milestone-auditor) was not being published to npm because it was
missing from the package.json files array.
Also adds the missing gsd-milestone-auditor.md agent.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Unify gap handling - whether discovered by code verification or user
testing, gaps feed into the same plan-phase --gaps workflow.
Changes:
- Delete commands/gsd/plan-fix.md (redundant)
- Update verify-work to route to plan-phase --gaps
- Update progress Route E to detect UAT gaps
- Change UAT.md "Issues" section to "Gaps" with YAML format
- Extend plan-phase --gaps to read from both VERIFICATION.md and UAT.md
- Update diagnose-issues to output gaps in YAML format
- Update all references (debug, templates, workflows)
One path: gap discovered → diagnosed → plan-phase --gaps → fixed
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Write to file only on: issue found, every 5 passes, or completion.
Eliminates wasteful I/O while maintaining reasonable crash recovery.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Match new-project format — both research-project and define-requirements
shown as equal paths with guidance on when to use each.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When ROADMAP.md is missing but PROJECT.md exists (after complete-milestone),
progress now correctly routes to /gsd:discuss-milestone instead of suggesting
new-project.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Step 0 now explicitly states to skip to Step 3 when in re-verification
mode. Steps 1-2 marked as "Initial Mode Only" to make flow clear.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When VERIFICATION.md already exists with gaps, verifier now:
- Loads previous must-haves instead of re-deriving
- Focuses deep verification on failed items
- Quick regression check on passed items
- Tracks re-verification metadata (gaps_closed, regressions)
Saves tokens by not starting from scratch after gap closure.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase completion commit now stages VERIFICATION.md alongside ROADMAP.md,
STATE.md, and REQUIREMENTS.md so verification results are tracked.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Milestone audit now reads existing VERIFICATION.md files from phases
(already created during execute-phase) rather than spawning verifiers
again. Aggregates tech debt and deferred gaps, then runs integration
checker for cross-phase wiring. Adds tech_debt status for non-blocking
accumulated debt.
Also adds VERIFICATION.md to phase completion commit in execute-phase.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The ~/.claude/skills/expertise/ system was personal tooling
that doesn't exist for other users. Removed from:
- create-roadmap workflow (detect_domain step)
- plan-phase workflow (domain loading)
- roadmap template (Domain Expertise section)
- phase-prompt template (domain frontmatter)
- plan-format reference (domain field)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
These files were committed before .claude/ was added to .gitignore.
Removing from tracking as they're local install artifacts.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sync execute-plan command and workflow with improved checkpoint display:
- Box header with ╔═══╗ for visual prominence
- Progress indicator at top
- Separator line before unmissable "→ YOUR ACTION:" prompt
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Use double-line box for checkpoint headers with clear visual hierarchy:
- Progress and task info at top
- Content details in middle
- Separator line before unmissable "→ YOUR ACTION:" prompt
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The when_to_use section was overly restrictive, refusing research
for "standard" domains. Research benefits any unfamiliar territory,
not just niche technical domains.
Co-Authored-By: Claude <noreply@anthropic.com>
- Add verify_phase_goal step to execute-phase workflow
- Verifier outputs structured gaps: YAML for planner consumption
- Add --gaps flag to plan-phase for gap closure mode
- Route by verification status: passed, gaps_found, human_needed
- Gap closure creates sequential plans (04, 05...) from verification gaps
- User stays in control at each decision point
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When execute-plan completes the last plan in a phase (summaries = plans),
it now spawns gsd-verifier to verify phase goal achievement before
proceeding to next phase.
Same verification flow as execute-phase, ensuring consistent behavior
regardless of which command is used.
Co-Authored-By: Claude <noreply@anthropic.com>
Deleted:
- subagent-task-prompt.md (baked into gsd-executor)
- subagent-verify-prompt.md (baked into gsd-verifier)
- continuation-prompt.md (baked into gsd-executor)
- checkpoint-return.md (baked into gsd-executor)
Co-Authored-By: Claude <noreply@anthropic.com>
- gsd-verifier.md: dedicated verification subagent with all logic baked in
- Goal-backward verification: checks codebase, not SUMMARY claims
- Creates VERIFICATION.md, returns status to orchestrator
- execute-phase spawns gsd-verifier instead of general-purpose
Co-Authored-By: Claude <noreply@anthropic.com>
- execute-plan.md: spawn gsd-executor instead of general-purpose with template
- execute-phase.md: spawn gsd-executor for wave-based parallel execution
- Remove template filling, subagent has all logic baked in
Co-Authored-By: Claude <noreply@anthropic.com>
Moves all plan execution logic into a dedicated subagent:
- Deviation rules, checkpoint protocols, commit formatting
- Summary creation, state updates, TDD execution
- Authentication gate handling, continuation support
Installer now copies agents/ to ~/.claude/agents/
Co-Authored-By: Claude <noreply@anthropic.com>
ROADMAP.md, STATE.md, and REQUIREMENTS.md updates now commit
together as phase completion instead of separate commits.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Split into separate steps: 1, 1.5 (optional), 2, 3, 4, 5
- Research is recommended for quality, skip only for speed
- Define-requirements is required before create-roadmap
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add research & scope step to "How It Works" (optional but recommended)
- Update brownfield section with full optional flow
- Add research-project and define-requirements to commands
- Add research/ and REQUIREMENTS.md to context engineering table
- Split commands into 7 grouped tables for easier scanning
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Research now loads concrete requirements (e.g., "AUTH-02: User receives
email verification") to inform research domains, not just high-level
roadmap descriptions.
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove phantom status.md command (background agent model abandoned)
- Remove agent-history.md template (unused)
- Remove _archive/ directory
- Add narration to execute-phase (describe what's being built before/after waves)
- Update new-project to offer define-requirements as fast path
- Make define-requirements work without research (gather through questioning)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Promote /gsd:whats-new and update command visibility.
GSD evolves fast — users should check periodically.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Subagents can't determine if phase is complete. The orchestrator
(execute-plan and execute-phase commands) runs in main context,
can count plans vs summaries, and updates REQUIREMENTS.md when
phase completes.
- execute-plan: Step 2.5 updates requirements when summaries = plans
- execute-phase: Step 6 updates requirements (phase always complete)
- Removed duplicate from workflow (subagent can't run it anyway)
When all plans in a phase complete:
1. Look up phase's requirements from ROADMAP.md
2. Update REQUIREMENTS.md traceability table (Pending → Complete)
3. Include in metadata commit
Closes the loop on requirement tracking.
- Roadmap template now includes Requirements: field for each phase
- plan-phase loads REQUIREMENTS.md and extracts phase-specific requirements
- define-requirements shows full list inline before commit (not just counts)
Reduce principles.md from 158 to 73 lines:
- Remove duplicates (atomic_commits, tdd, deviation_rules)
- Remove version drag from claude_automates
- Keep core orientation: solo dev model, plans are prompts,
scope control, ship fast, anti-enterprise
Add principles.md to 9 core commands so Claude always
understands what GSD is.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Focus on what to extract, not what to avoid:
- What they're building
- Why it needs to exist
- Who it's for
- What done looks like
Remove version drag and redundant question categories.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Follow threads naturally instead of rigid step order
- Cleaner question techniques in questioning.md
- Background context checklist instead of forced checklist mode
- Updated next steps to show research flow
Adds /gsd:research-project to research domain ecosystem before creating roadmap.
Spawns parallel agents to investigate stack, features, architecture, and pitfalls.
New files:
- commands/gsd/research-project.md
- get-shit-done/workflows/research-project.md
- get-shit-done/templates/research-project/ (5 templates)
Modified:
- new-project.md: offers research vs direct roadmap options
- create-roadmap.md: loads research if exists
- workflows/create-roadmap.md: uses research to inform phases
Co-Authored-By: Claude <noreply@anthropic.com>
Command now references workflow for checkpoint handling details
instead of duplicating logic. Keeps command thin as intended.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- execute-plan.md: Replace broken Task(resume=...) with fresh continuation agent
- execute-phase.md: Expand checkpoint handling with full continuation flow
- checkpoints.md: Restore ~500 lines of detailed examples and anti-patterns
Checkpoint presentation formats now documented for all three types.
Templates referenced: checkpoint-return.md, continuation-prompt.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The orchestrator pattern conversion (8ed6a8f) removed workflow context
loading for context efficiency but inadvertently removed the offer_next
step that presents copy/paste-ready next commands after plan/phase
completion.
Added explicit <offer_next> sections to both commands:
- execute-plan.md: routes to next plan, next phase, or milestone complete
- execute-phase.md: routes to next phase or milestone complete
Both include /clear hints and copy/paste-ready command paths.
Fixes#69
Co-Authored-By: Claude <noreply@anthropic.com>
- Reads installed version from VERSION file
- Fetches remote changelog from GitHub
- Displays version comparison and missed changes
- Provides update instructions when behind
Remove the global ISSUES.md deferred enhancement tracking system.
- Delete /gsd:consider-issues command (never used)
- Delete issues.md template (never instantiated)
- Remove Rule 5 from deviation rules (never triggered)
- Remove all ISSUES.md, ISS-XXX, and "deferred issues" references
- Update STATE.md to track pending todos instead
The ISSUES.md system was designed to capture non-critical enhancements
during plan execution via "Rule 5", but it never fired in practice
across 100+ projects. The system added ~350 lines of dead code.
The /gsd:add-todo and /gsd:check-todos system serves the same purpose
and is actually used.
Note: UAT *-ISSUES.md files (per-plan, created by /gsd:verify-work)
are unaffected - those are a separate, active system.
Closes#56
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Debug command now orchestrates: gather symptoms in main context, spawn
investigation subagent with fresh 200k context
- Subagent template unified for both /gsd:debug (find_and_fix) and
diagnose-issues (find_root_cause_only) flows via goal flag
- Checkpoint behavior enables subagent to pause for user input
(human-verify, human-action, decision) with continuation agents
- Structured return formats: ROOT CAUSE FOUND, DEBUG COMPLETE,
INVESTIGATION INCONCLUSIVE, CHECKPOINT REACHED
- diagnose-issues updated to match new template placeholders and returns
Co-Authored-By: Claude <noreply@anthropic.com>
Define DEBUG_DIR=.planning/debug at top of debug-related files.
Reference ${DEBUG_DIR} throughout to reduce path typo risk.
Co-Authored-By: Claude <noreply@anthropic.com>
- Debug files from UAT use same naming as regular debug (slug only)
- UAT.md tracks link via debug_session field
- plan-fix actually invokes execute-plan when user selects it
Co-Authored-By: Claude <noreply@anthropic.com>
Diagnosis always produces better fixes and runs in parallel anyway.
Removing the prompt reduces cognitive load.
Co-Authored-By: Claude <noreply@anthropic.com>
After UAT finds issues, spawn parallel debug agents to investigate
root causes before planning fixes. Each agent investigates one issue
with symptoms pre-filled from UAT, finds the root cause, and returns
diagnosis.
New files:
- workflows/diagnose-issues.md: Orchestrator for parallel debug agents
- templates/debug-subagent-prompt.md: Prompt template for debug subagents
Modified:
- workflows/debug.md: Add symptoms_prefilled and diagnose-only modes
- workflows/verify-work.md: Offer diagnosis step after issues found
- templates/UAT.md: Add root_cause and debug_session fields
- commands/gsd/plan-fix.md: Use root causes for targeted fix planning
Flow: UAT → diagnose (parallel) → plan-fix (with root causes) → execute
Co-Authored-By: Claude <noreply@anthropic.com>
- One test at a time instead of full checklist upfront
- Plain text responses instead of AskUserQuestion forms
- Severity inferred from description, never asked
- Persistent UAT.md survives /clear (like debug workflow)
- Single file per phase replaces per-plan ISSUES.md
- Updated plan-fix to read from UAT.md
Co-Authored-By: Claude <noreply@anthropic.com>
Wave numbers now computed during plan-phase and stored in PLAN.md
frontmatter. Execute-phase reads wave directly instead of deriving
from depends_on at runtime.
- Add assign_waves step to plan-phase workflow
- Add wave field to frontmatter (plan-format, phase-prompt template)
- Simplify execute-phase: remove analyze_dependencies and group_into_waves
- Replace with group_by_wave that just reads frontmatter integers
Co-Authored-By: Claude <noreply@anthropic.com>
- Fix brownfield example to use execute-phase instead of execute-plan
- Remove /gsd:resume-task command (relies on broken Task resume)
- Checkpoint continuation now uses fresh agents, not resume
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
execute-phase with parallel agents is the recommended path.
execute-plan is for single-plan or interactive checkpoint handling.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Resume fails when subagents use parallel tool calls due to Claude Code
serialization bug (consecutive assistant entries with same message ID).
Solution: Subagents return structured checkpoint state, orchestrator
spawns fresh agent with continuation-prompt template instead of resuming.
New files:
- templates/checkpoint-return.md: Structured format with completed tasks table
- templates/continuation-prompt.md: Template for spawning continuation agent
Updated:
- templates/subagent-task-prompt.md: Reference checkpoint-return, remove resume language
- workflows/execute-phase.md: Replace Task(resume=id) with fresh agent spawn
- workflows/execute-plan.md: Update checkpoint_return_for_orchestrator step
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
execute-plan.md command now spawns subagent instead of executing directly:
- Loads only subagent-task-prompt template (~100 lines vs ~2200)
- Subagent loads full execute-plan workflow, summary, checkpoints, tdd
- Handles checkpoint returns with resume flow
- ~80% context reduction for orchestrator
Also updated subagent-task-prompt.md description to clarify it's used by
both execute-phase (parallel) and execute-plan (single) orchestrators.
Co-Authored-By: Claude <noreply@anthropic.com>
Scope boundaries are implicit from the roadmap. Asking about them
creates the sensation of scope creep and interrogates the user about
constraints they didn't mention.
Co-Authored-By: Claude <noreply@anthropic.com>
Restored context-budget reasoning for why TDD features get dedicated plans:
- TDD requires 2-3 execution cycles consuming 50-60% context
- Test framework setup handled in first TDD plan's RED phase
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- execute-plan.md: Add checkpoint_return_for_orchestrator step
explaining how to return at checkpoints when spawned via Task tool
- subagent-task-prompt.md: Add checkpoint_behavior and completion_format
sections to guide agents on returning for checkpoints
Tested: Task resume works - agent pauses at checkpoint, returns with
details, orchestrator presents to user, resumes with Task(resume=id).
Parallel agents each get unique agent_id for independent resume.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Shows table of all active debug sessions with status/hypothesis/next action
- Reply with number to resume, or describe new issue
- No AskUserQuestion for session selection - inline flow
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Clarified verification instructions for usage.
I was initially trying to get this to work in my PowerShell terminal, but later realized that the /gsd:help command became available inside Claude Code.
2026-01-13 09:45:31 -06:00
299 changed files with 78310 additions and 13068 deletions
description:Report something that is not working correctly
labels:["bug","needs-triage"]
body:
- type:markdown
attributes:
value:|
Thanks for taking the time to report a bug. The more detail you provide, the faster we can fix it.
> **⚠️ Privacy Notice:** Some fields below ask for logs or config files that may contain **personally identifiable information (PII)** such as file paths with your username, API keys, project names, or system details. Before pasting any output, please:
> 1. Review it for sensitive data
> 2. Redact usernames, paths, and API keys (e.g., replace `/Users/yourname/` with `/Users/REDACTED/`)
> 3. Or run your logs through an anonymizer — we recommend **[presidio-anonymizer](https://microsoft.github.io/presidio/)** (open-source, local-only) or **[scrub](https://github.com/dssg/scrub)** before pasting
- type:input
id:version
attributes:
label:GSD Version
description:"Run: `npm list -g get-shit-done-cc` or check `npx get-shit-done-cc --version`"
placeholder:"e.g., 1.18.0"
validations:
required:true
- type:dropdown
id:runtime
attributes:
label:Runtime
description:Which AI coding tool are you using GSD with?
options:
- Claude Code
- Gemini CLI
- OpenCode
- Codex
- Copilot
- Antigravity
- Multiple (specify in description)
validations:
required:true
- type:dropdown
id:os
attributes:
label:Operating System
options:
- macOS
- Windows
- Linux (Ubuntu/Debian)
- Linux (Fedora/RHEL)
- Linux (Arch)
- Linux (Other)
- WSL
validations:
required:true
- type:input
id:node_version
attributes:
label:Node.js Version
description:"Run: `node --version`"
placeholder:"e.g., v20.11.0"
validations:
required:true
- type:input
id:shell
attributes:
label:Shell
description:"Run: `echo $SHELL` (macOS/Linux) or `echo %COMSPEC%` (Windows)"
description:Describe what went wrong. Be specific about which GSD command you were running.
placeholder:|
When I ran `/gsd:plan`, the system...
validations:
required:true
- type:textarea
id:expected
attributes:
label:What did you expect?
description:Describe what you expected to happen instead.
validations:
required:true
- type:textarea
id:reproduce
attributes:
label:Steps to reproduce
description:|
Exact steps to reproduce the issue. Include the GSD command used.
placeholder:|
1. Install GSD with `npx get-shit-done-cc@latest`
2. Select runtime: Claude Code
3. Run `/gsd:init` with a new project
4. Run `/gsd:plan`
5. Error appears at step...
validations:
required:true
- type:textarea
id:logs
attributes:
label:Error output / logs
description:|
Paste any error messages from the terminal. This will be rendered as code.
**⚠️ PII Warning:** Terminal output often contains your system username in file paths (e.g., `/Users/yourname/.claude/...`). Please redact before pasting.
render:shell
validations:
required:false
- type:textarea
id:config
attributes:
label:GSD Configuration
description:|
If the bug is related to planning, phases, or workflow behavior, paste your `.planning/config.json`.
**How to retrieve:** `cat .planning/config.json`
**⚠️ PII Warning:** This file may contain project-specific names. Redact if sensitive.
render:json
validations:
required:false
- type:textarea
id:state
attributes:
label:GSD State (if relevant)
description:|
If the bug involves incorrect state tracking or phase progression, include your `.planning/STATE.md`.
**How to retrieve:** `cat .planning/STATE.md`
**⚠️ PII Warning:** This file contains project names, phase descriptions, and timestamps. Redact any project names or details you don't want public.
render:markdown
validations:
required:false
- type:textarea
id:settings_json
attributes:
label:Runtime settings.json (if relevant)
description:|
If the bug involves hooks, statusline, or runtime integration, include your runtime's settings.json.
**How to retrieve:**
- Claude Code: `cat ~/.claude/settings.json`
- Gemini CLI: `cat ~/.gemini/settings.json`
- OpenCode: `cat ~/.config/opencode/opencode.json` or `opencode.jsonc`
**⚠️ PII Warning:** This file may contain API keys, tokens, or custom paths. **Remove all API keys and tokens before pasting.** We recommend running through [presidio-anonymizer](https://microsoft.github.io/presidio/) or manually redacting any line containing "key", "token", or "secret".
render:json
validations:
required:false
- type:dropdown
id:frequency
attributes:
label:How often does this happen?
options:
- Every time (100% reproducible)
- Most of the time
- Sometimes / intermittent
- Only happened once
validations:
required:true
- type:dropdown
id:severity
attributes:
label:Impact
description:How much does this affect your workflow?
options:
- Blocker — Cannot use GSD at all
- Major — Core feature is broken, no workaround
- Moderate — Feature is broken but I have a workaround
- Minor — Cosmetic or edge case
validations:
required:true
- type:textarea
id:workaround
attributes:
label:Workaround (if any)
description:Have you found any way to work around this issue?
validations:
required:false
- type:textarea
id:additional
attributes:
label:Additional context
description:|
Anything else — screenshots, screen recordings, related issues, or links.
**Useful diagnostics to include (if applicable):**
- `npm list -g get-shit-done-cc` — confirms installed version
Add comprehensive brownfield support to GSD. Users adopting GSD for existing codebases will have a systematic way to capture architectural knowledge before planning begins. A new `/gsd:map-codebase` workflow will produce structured `.planning/codebase/` documents that stay current as plans execute.
## Domain Expertise
None - this is internal GSD development following existing command/workflow/template patterns.
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
Transform planning from "Claude guesses which summaries to read" to "System automatically assembles optimal context" by:
- Adding frontmatter with subsystem, requires/provides/affects, tech-stack, key-files, key-decisions
- Scanning all summary frontmatter (fast - first ~25 lines each)
- Building dependency graph to auto-select relevant prior phases
- Extracting context from frontmatter before reading full summaries
- Making context assembly deterministic and optimal
### Phase 7: Backfill Existing Summaries With Frontmatter
**Goal:** Backfill YAML frontmatter with dependency graph metadata to Phase 1-6 historical summaries
**Depends on:** Phase 6
**Plans:** 1 plan
Plans:
- [x] 07-01: Backfill frontmatter to all Phase 1-5 summaries (10 files)
**Details:**
Enable intelligent context assembly for all historical phases by adding consistent frontmatter with subsystem categorization, dependency graph (requires/provides/affects), tech tracking, key decisions, and patterns established.
**Goal:** Properly integrate /gsd:verify-work into GSD with workflow delegation, templates, and /gsd:plan-fix command
**Depends on:** Phase 8
**Research:** Unlikely (refactoring contributed command to match GSD patterns)
**Plans:** TBD
Components:
- Refactor `commands/gsd/verify-work.md` to GSD style (workflow delegation)
- Create `workflows/verify-work.md` for UAT logic
- Create `templates/uat-issues.md` for phase-scoped issues format
- Create `commands/gsd/plan-fix.md` for planning fixes from UAT issues
- Update `commands/gsd/progress.md` to offer plan-fix when issues exist
- Update README.md with new commands
**Details:**
Community contribution from OracleGreyBeard. Original command works but doesn't follow GSD patterns (no workflow delegation, inline templates, verbose steps). Refactor to match conventions, then add /gsd:plan-fix to complete the verify → fix loop.
### Phase 10: Parallel Phase Execution
**Goal:** Implement proper parallel phase execution with clean separation between single-plan and multi-plan execution
- [x] 11-02: Add parallel-aware step to plan-phase workflow - Read config, restructure for vertical slices, document independence
- [x] 11-03: Update execute-phase to use plan frontmatter - Use explicit markers instead of inference, backward compat
- [x] 11-04: Documentation and examples - Update references, add parallel vs sequential planning examples
**Details:**
Current plan-phase.md has sequential execution bias - later plans reference earlier SUMMARY.md, file overlap is acceptable, no independence markers. When parallelization enabled in config.json, planning should:
- Group by vertical slice (feature A, feature B) not workflow stage (setup → implement → test)
**Building:** Brownfield support for GSD - `/gsd:map-codebase` workflow that analyzes existing codebases using parallel Explore agents, producing structured `.planning/codebase/` documents.
**Core requirements:**
-`/gsd:map-codebase` produces useful codebase documents from any codebase
- Documents are focused (<100 lines each) and easy to update incrementally
-`/gsd:new-project` detects existing code and offers mapping
**A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.**
**English** · [简体中文](README.zh-CN.md)
**A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini CLI, Codex, Copilot, and Antigravity.**
**Solves context rot — the quality degradation that happens as Claude fills its context window.**
**Trusted by engineers at Amazon, Google, Shopify, and Webflow.**
[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works)
[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works) · [User Guide](docs/USER-GUIDE.md)
</div>
@@ -70,20 +80,67 @@ People who want to describe what they want and have it built correctly — witho
## Getting Started
```bash
npx get-shit-done-cc
npx get-shit-done-cc@latest
```
That's it. Verify with `/gsd:help`.
The installer prompts you to choose:
1.**Runtime** — Claude Code, OpenCode, Gemini, Codex, Copilot, Cursor, Antigravity, or all
2.**Location** — Global (all projects) or local (current project only)
Verify with:
- Claude Code / Gemini: `/gsd:help`
- OpenCode: `/gsd-help`
- Codex: `$gsd-help`
- Copilot: `/gsd:help`
- Antigravity: `/gsd:help`
> [!NOTE]
> Codex installation uses skills (`skills/gsd-*/SKILL.md`) rather than custom prompts.
Installs to `./.claude/` for testing modifications before contributing.
@@ -150,87 +207,206 @@ If you prefer not to use that flag, add this to your project's `.claude/settings
## How It Works
### 1. Start with an idea
> **Already have code?** Run `/gsd:map-codebase` first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then `/gsd:new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns.
### 1. Initialize Project
```
/gsd:new-project
```
The system asks questions. Keeps asking until it has everything — your goals, constraints, tech preferences, edge cases. You go back and forth until the idea is fully captured. Creates **PROJECT.md**.
One command, one flow. The system:
### 2. Create roadmap
1.**Questions** — Asks until it understands your idea completely (goals, constraints, tech preferences, edge cases)
2.**Research** — Spawns parallel agents to investigate the domain (optional but recommended)
3.**Requirements** — Extracts what's v1, v2, and out of scope
4.**Roadmap** — Creates phases mapped to requirements
```
/gsd:create-roadmap
```
You approve the roadmap. Now you're ready to build.
Produces:
- **ROADMAP.md** — Phases from start to finish
- **STATE.md** — Living memory that persists across sessions
### 3. Plan and execute phases
```
/gsd:plan-phase 1 # System creates atomic task plans
Each phase breaks into 2-3 atomic tasks. Each task runs in a fresh subagent context — 200k tokens purely for implementation, zero degradation.
**For multi-plan phases:**
```
/gsd:execute-phase 1 # Run all plans in parallel, "walk away" execution
```
Use `/gsd:execute-plan` for interactive single-plan execution with checkpoints. Use `/gsd:execute-phase` when you have multiple plans and want parallel "walk away" automation.
### 4. Ship and iterate
```
/gsd:complete-milestone # Archive v1, prep for v2
/gsd:add-phase # Append new work
/gsd:insert-phase 2 # Slip urgent work between phases
```
Ship your MVP in a day. Add features. Insert hotfixes. The system stays modular — you're never stuck.
| `CONCERNS.md` | Tech debt, known issues, fragile areas |
Your roadmap has a sentence or two per phase. That's not enough context to build something the way *you* imagine it. This step captures your preferences before anything gets researched or planned.
### 2. Initialize project
The system analyzes the phase and identifies gray areas based on what's being built:
- **Visual features** → Layout, density, interactions, empty states
- **APIs/CLIs** → Response format, flags, error handling, verbosity
4.**Creates verified fix plans** — Ready for immediate re-execution
If everything passes, you move on. If something's broken, you don't manually debug — you just run `/gsd:execute-phase` again with the fix plans it created.
**Creates:**`{phase_num}-UAT.md`, fix plans if issues found
---
### 6. Repeat → Ship → Complete → Next Milestone
```
/gsd:discuss-phase 2
/gsd:plan-phase 2
/gsd:execute-phase 2
/gsd:verify-work 2
/gsd:ship 2 # Create PR from verified work
...
/gsd:complete-milestone
/gsd:new-milestone
```
Or let GSD figure out the next step automatically:
```
/gsd:next # Auto-detect and run next step
```
Loop **discuss → plan → execute → verify → ship** until milestone complete.
If you want faster intake during discussion, use `/gsd:discuss-phase <n> --batch` to answer a small grouped set of questions at once instead of one-by-one.
Each phase gets your input (discuss), proper research (plan), clean execution (execute), and human verification (verify). Context stays fresh. Quality stays high.
When all phases are done, `/gsd:complete-milestone` archives the milestone and tags the release.
Then `/gsd:new-milestone` starts the next version — same flow as `new-project` but for your existing codebase. You describe what you want to build next, the system researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.
---
### Quick Mode
```
/gsd:quick
```
**For ad-hoc tasks that don't need full planning.**
Quick mode gives you GSD guarantees (atomic commits, state tracking) with a faster path:
- **Same agents** — Planner + executor, same quality
- **Skips optional steps** — No research, no plan checker, no verifier by default
- **Separate tracking** — Lives in `.planning/quick/`, not phases
**`--discuss` flag:** Lightweight discussion to surface gray areas before planning.
**`--research` flag:** Spawns a focused researcher before planning. Investigates implementation approaches, library options, and pitfalls. Use when you're unsure how to approach a task.
**`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification.
Flags are composable: `--discuss --research --full` gives discussion + research + plan-checking + verification.
```
/gsd:quick
> What do you want to do? "Add dark mode toggle to settings"
| `REQUIREMENTS.md` | Scoped v1/v2 requirements with phase traceability |
| `ROADMAP.md` | Where you're going, what's done |
| `STATE.md` | Decisions, blockers, position — memory across sessions |
| `PLAN.md` | Atomic task with XML structure, verification steps |
| `SUMMARY.md` | What happened, what changed, committed to history |
| `ISSUES.md` | Deferred enhancements tracked across sessions |
| `todos/` | Captured ideas and tasks for later work |
Size limits based on where Claude's quality degrades. Stay under, get consistent excellence.
@@ -274,19 +451,20 @@ Every plan is structured XML optimized for Claude:
Precise instructions. No guessing. Verification built in.
### Subagent Execution
### Multi-Agent Orchestration
As Claude fills its context window, quality degrades. You've seen it: *"Due to context limits, I'll be more concise now."* That "concision" is code for cutting corners.
Every stage uses the same pattern: a thin orchestrator spawns specialized agents, collects results, and routes to the next step.
GSD prevents this. Each plan is maximum 3 tasks. Each plan runs in a fresh subagent — 200k tokens purely for implementation, zero accumulated garbage.
| Execution | Groups into waves, tracks progress | Executors implement in parallel, each with fresh 200k context |
| Verification | Presents results, routes next | Verifier checks codebase against goals, debuggers diagnose failures |
| Task | Context | Quality |
|------|---------|---------|
| Task 1 | Fresh | ✅ Full |
| Task 2 | Fresh | ✅ Full |
| Task 3 | Fresh | ✅ Full |
The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.
No degradation. Walk away, come back to completed work.
**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.
### Atomic Git Commits
@@ -317,44 +495,208 @@ You're never locked in. The system adapts.
## Commands
### Core Workflow
| Command | What it does |
|---------|--------------|
| `/gsd:new-project [--auto]` | Full initialization: questions → research → requirements → roadmap |
| `/gsd:profile-user [--questionnaire] [--refresh]` | Generate developer behavioral profile from session analysis for personalized responses |
<sup>¹ Contributed by reddit user OracleGreyBeard</sup>
---
## Configuration
GSD stores project settings in `.planning/config.json`. Configure during `/gsd:new-project` or update later with `/gsd:settings`. For the full config schema, workflow toggles, git branching options, and per-agent model breakdown, see the [User Guide](docs/USER-GUIDE.md#configuration-reference).
### Core Settings
| Setting | Options | Default | What it controls |
- **`none`** — Commits to current branch (default GSD behavior)
- **`phase`** — Creates a branch per phase, merges at phase completion
- **`milestone`** — Creates one branch for entire milestone, merges at completion
At milestone completion, GSD offers squash merge (recommended) or merge with history.
---
## Security
### Protecting Sensitive Files
GSD's codebase mapping and analysis commands read files to understand your project. **Protect files containing secrets** by adding them to Claude Code's deny list:
1. Open Claude Code settings (`.claude/settings.json` or global)
2. Add sensitive file patterns to the deny list:
```json
{
"permissions":{
"deny":[
"Read(.env)",
"Read(.env.*)",
"Read(**/secrets/*)",
"Read(**/*credential*)",
"Read(**/*.pem)",
"Read(**/*.key)"
]
}
}
```
This prevents Claude from reading these files entirely, regardless of what commands you run.
> [!IMPORTANT]
> GSD includes built-in protections against committing secrets, but defense-in-depth is best practice. Deny read access to sensitive files as a first line of defense.
---
## Troubleshooting
**Commands not found after install?**
- Restart Claude Code to reload slash commands
- Restart your runtime to reload commands/skills
- Verify files exist in `~/.claude/commands/gsd/` (global) or `./.claude/commands/gsd/` (local)
- For Codex, verify skills exist in `~/.codex/skills/gsd-*/SKILL.md` (global) or `./.codex/skills/gsd-*/SKILL.md` (local)
You are a GSD advisor researcher. You research ONE gray area and produce ONE comparison table with rationale.
Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize.
**Core responsibilities:**
- Research the single assigned gray area using Claude's knowledge, Context7, and web search
- Produce a structured 5-column comparison table with genuinely viable options
- Write a rationale paragraph grounding the recommendation in the project context
- Return structured markdown output for the main agent to synthesize
</role>
<input>
Agent receives via prompt:
-`<gray_area>` -- area name and description
-`<phase_context>` -- phase description from roadmap
-`<project_context>` -- brief project info
-`<calibration_tier>` -- one of: `full_maturity`, `standard`, `minimal_decisive`
</input>
<calibration_tiers>
The calibration tier controls output shape. Follow the tier instructions exactly.
### full_maturity
- **Options:** 3-5 options
- **Maturity signals:** Include star counts, project age, ecosystem size where relevant
- **Recommendations:** Conditional ("Rec if X", "Rec if Y"), weighted toward battle-tested tools
- **Rationale:** Full paragraph with maturity signals and project context
### standard
- **Options:** 2-4 options
- **Recommendations:** Conditional ("Rec if X", "Rec if Y")
- **Rationale:** Standard paragraph grounding recommendation in project context
### minimal_decisive
- **Options:** 2 options maximum
- **Recommendations:** Decisive single recommendation
description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
You are a GSD codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.planning/codebase/`.
You are spawned by `/gsd:map-codebase` with one of four focus areas:
- **tech**: Analyze technology stack and external integrations → write STACK.md and INTEGRATIONS.md
- **arch**: Analyze architecture and file structure → write ARCHITECTURE.md and STRUCTURE.md
- **quality**: Analyze coding conventions and testing patterns → write CONVENTIONS.md and TESTING.md
- **concerns**: Identify technical debt and issues → write CONCERNS.md
Your job: Explore thoroughly, then write document(s) directly. Return confirmation only.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
</role>
<why_this_matters>
**These documents are consumed by other GSD commands:**
**`/gsd:plan-phase`** loads relevant codebase docs when creating implementation plans:
**`/gsd:execute-phase`** references codebase docs to:
- Follow existing conventions when writing code
- Know where to place new files (STRUCTURE.md)
- Match testing patterns (TESTING.md)
- Avoid introducing more technical debt (CONCERNS.md)
**What this means for your output:**
1.**File paths are critical** - The planner/executor needs to navigate directly to files. `src/services/user.ts` not "the user service"
2.**Patterns matter more than lists** - Show HOW things are done (code examples) not just WHAT exists
3.**Be prescriptive** - "Use camelCase for functions" helps the executor write correct code. "Some functions use camelCase" doesn't.
4.**CONCERNS.md drives priorities** - Issues you identify may become future phases. Be specific about impact and fix approach.
5.**STRUCTURE.md answers "where do I put this?"** - Include guidance for adding new code, not just describing what exists.
</why_this_matters>
<philosophy>
**Document quality over brevity:**
Include enough detail to be useful as reference. A 200-line TESTING.md with real patterns is more valuable than a 74-line summary.
**Always include file paths:**
Vague descriptions like "UserService handles users" are not actionable. Always include actual file paths formatted with backticks: `src/services/user.ts`. This allows Claude to navigate directly to relevant code.
**Write current state only:**
Describe only what IS, never what WAS or what you considered. No temporal language.
**Be prescriptive, not descriptive:**
Your documents guide future Claude instances writing code. "Use X pattern" is more useful than "X pattern is used."
</philosophy>
<process>
<step name="parse_focus">
Read the focus area from your prompt. It will be one of: `tech`, `arch`, `quality`, `concerns`.
Based on focus, determine which documents you'll write:
-`tech` → STACK.md, INTEGRATIONS.md
-`arch` → ARCHITECTURE.md, STRUCTURE.md
-`quality` → CONVENTIONS.md, TESTING.md
-`concerns` → CONCERNS.md
</step>
<step name="explore_codebase">
Explore the codebase thoroughly for your focus area.
**For tech focus:**
```bash
# Package manifests
ls package.json requirements.txt Cargo.toml go.mod pyproject.toml 2>/dev/null
cat package.json 2>/dev/null | head -100
# Config files (list only - DO NOT read .env contents)
ls -la *.config.* tsconfig.json .nvmrc .python-version 2>/dev/null
ls .env* 2>/dev/null # Note existence only, never read contents
# Find SDK/API imports
grep -r "import.*stripe\|import.*supabase\|import.*aws\|import.*@" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -50
```
**For arch focus:**
```bash
# Directory structure
find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*'| head -50
# Entry points
ls src/index.* src/main.* src/app.* src/server.* app/page.* 2>/dev/null
# Import patterns to understand layers
grep -r "^import" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -100
```
**For quality focus:**
```bash
# Linting/formatting config
ls .eslintrc* .prettierrc* eslint.config.* biome.json 2>/dev/null
cat .prettierrc 2>/dev/null
# Test files and config
ls jest.config.* vitest.config.* 2>/dev/null
find . -name "*.test.*" -o -name "*.spec.*"| head -30
# Sample source files for convention analysis
ls src/**/*.ts 2>/dev/null | head -10
```
**For concerns focus:**
```bash
# TODO/FIXME comments
grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -50
description: Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
You are a GSD plan executor. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files.
Spawned by `/gsd:execute-phase` orchestrator.
Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
</role>
<project_context>
Before executing, discover project context:
**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
1. List available skills (subdirectories)
2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
3. Load specific `rules/*.md` files as needed during implementation
4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
5. Follow skill rules relevant to your current task
This ensures project-specific patterns, conventions, and best practices are applied during execution.
**Trigger:** Code missing essential features for correctness, security, or basic operation
**Examples:** Missing error handling, no input validation, missing null checks, no auth on protected routes, missing authorization, no CSRF/CORS, no rate limiting, missing DB indexes, no error logging
**Critical = required for correct/secure/performant operation.** These aren't "features" — they're correctness requirements.
---
**RULE 3: Auto-fix blocking issues**
**Trigger:** Something prevents completing current task
**Examples:** New DB table (not column), major schema changes, new service layer, switching libraries/frameworks, changing auth approach, new infrastructure, breaking API changes
- Need new column → Rule 1 or 2 (depends on context)
**When in doubt:** "Does this affect correctness, security, or ability to complete task?" YES → Rules 1-3. MAYBE → Rule 4.
---
**SCOPE BOUNDARY:**
Only auto-fix issues DIRECTLY caused by the current task's changes. Pre-existing warnings, linting errors, or failures in unrelated files are out of scope.
- Log out-of-scope discoveries to `deferred-items.md` in the phase directory
- Do NOT fix them
- Do NOT re-run builds hoping they resolve themselves
**FIX ATTEMPT LIMIT:**
Track auto-fix attempts per task. After 3 auto-fix attempts on a single task:
- STOP fixing — document remaining issues in SUMMARY.md under "Deferred Issues"
- Continue to the next task (or return checkpoint if blocked)
- Do NOT restart the build to find more issues
</deviation_rules>
<analysis_paralysis_guard>
**During task execution, if you make 5+ consecutive Read/Grep/Glob calls without any Edit/Write/Bash action:**
STOP. State in one sentence why you haven't written anything yet. Then either:
1. Write code (you have enough context), or
2. Report "blocked" with the specific missing information.
Do NOT continue reading. Analysis without action is a stuck signal.
</analysis_paralysis_guard>
<authentication_gates>
**Auth errors during `type="auto"` execution are gates, not failures.**
Auto mode is active if either `AUTO_CHAIN` or `AUTO_CFG` is `"true"`. Store the result for checkpoint handling below.
</auto_mode_detection>
<checkpoint_protocol>
**CRITICAL: Automation before verification**
Before any `checkpoint:human-verify`, ensure verification environment is ready. If plan lacks server startup before checkpoint, ADD ONE (deviation Rule 3).
For full automation-first patterns, server lifecycle, CLI handling:
**Quick reference:** Users NEVER run CLI commands. Users ONLY visit URLs, click UI, evaluate visuals, provide secrets. Claude does all automation.
---
**Auto-mode checkpoint behavior** (when `AUTO_CFG` is `"true"`):
- **checkpoint:human-verify** → Auto-approve. Log `⚡ Auto-approved: [what-built]`. Continue to next task.
- **checkpoint:decision** → Auto-select first option (planners front-load the recommended choice). Log `⚡ Auto-selected: [option name]`. Continue to next task.
- **checkpoint:human-action** → STOP normally. Auth gates cannot be automated — return structured checkpoint message using checkpoint_return_format.
**Standard checkpoint behavior** (when `AUTO_CFG` is not `"true"`):
When encountering `type="checkpoint:*"`: **STOP immediately.** Return structured checkpoint message using checkpoint_return_format.
**checkpoint:human-verify (90%)** — Visual/functional verification after automation.
Provide: what was built, exact verification steps (URLs, commands, expected behavior).
- **Single-repo:** `TASK_COMMIT=$(git rev-parse --short HEAD)` — track for SUMMARY.
- **Multi-repo (sub_repos):** Extract hashes from `commit-to-subrepo` JSON output (`repos.{name}.hash`). Record all hashes for SUMMARY (e.g., `backend@abc1234, frontend@def5678`).
**6. Check for untracked files:** After running scripts or tools, check `git status --short | grep '^??'`. For any new untracked files: commit if intentional, add to `.gitignore` if generated/runtime output. Never leave generated files untracked.
</task_commit_protocol>
<summary_creation>
After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`.
**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
- Components with no data source wired (props always receiving empty/mock data)
If any stubs exist, add a `## Known Stubs` section to the SUMMARY listing each stub with its file, line, and reason. These are tracked for the verifier to catch. Do NOT mark a plan as complete if stubs exist that prevent the plan's goal from being achieved — either wire the data or document in the plan why the stub is intentional and which future plan will resolve it.
</summary_creation>
<self_check>
After writing SUMMARY.md, verify claims before proceeding.
**Requirement IDs:** Extract from the PLAN.md frontmatter `requirements:` field (e.g., `requirements: [AUTH-01, AUTH-02]`). Pass all IDs to `requirements mark-complete`. If the plan has no requirements field, skip this step.
**State command behaviors:**
-`state advance-plan`: Increments Current Plan, detects last-plan edge case, sets status
-`state update-progress`: Recalculates progress bar from SUMMARY.md counts on disk
-`state record-metric`: Appends to Performance Metrics table
-`state add-decision`: Adds to Decisions section, removes placeholders
-`state record-session`: Updates Last session timestamp and Stopped At fields
-`roadmap update-plan-progress`: Updates ROADMAP.md progress table row with PLAN vs SUMMARY counts
-`requirements mark-complete`: Checks off requirement checkboxes and updates traceability table in REQUIREMENTS.md
**Extract decisions from SUMMARY.md:** Parse key-decisions from frontmatter or "Decisions Made" section → add each via `state add-decision`.
**For blockers found during execution:**
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state add-blocker "Blocker description"
description: Verifies cross-phase integration and E2E flows. Checks that phases connect properly and user workflows complete end-to-end.
tools: Read, Bash, Grep, Glob
color: blue
---
<role>
You are an integration checker. You verify that phases work together as a system, not just individually.
Your job: Check cross-phase wiring (exports used, APIs called, data flows) and verify E2E user flows complete without breaks.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
**Critical mindset:** Individual phases can pass while the system fails. A component can exist without being imported. An API can exist without being called. Focus on connections, not existence.
| {REQ-ID} | {Phase X export → Phase Y import → consumer} | WIRED / PARTIAL / UNWIRED | {specific issue or "—"} |
**Requirements with no cross-phase wiring:**
{List REQ-IDs that exist in a single phase with no integration touchpoints — these may be self-contained or may indicate missing connections}
```
</output>
<critical_rules>
**Check connections, not existence.** Files existing is phase-level. Files connecting is integration-level.
**Trace full paths.** Component → API → DB → Response → Display. Break at any point = broken flow.
**Check both directions.** Export exists AND import exists AND import is used AND used correctly.
**Be specific about breaks.** "Dashboard doesn't work" is useless. "Dashboard.tsx line 45 fetches /api/users but doesn't await response" is actionable.
**Return structured data.** The milestone auditor aggregates your findings. Use consistent format.
</critical_rules>
<success_criteria>
- [ ] Export/import map built from SUMMARYs
- [ ] All key exports checked for usage
- [ ] All API routes checked for consumers
- [ ] Auth protection verified on sensitive routes
- [ ] E2E flows traced and status determined
- [ ] Orphaned code identified
- [ ] Missing connections identified
- [ ] Broken flows identified with specific break points
- [ ] Requirements Integration Map produced with per-requirement wiring status
- [ ] Requirements with no cross-phase wiring identified
description: Fills Nyquist validation gaps by generating tests and verifying coverage for phase requirements
tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
color: "#8B5CF6"
---
<role>
GSD Nyquist auditor. Spawned by /gsd:validate-phase to fill validation gaps in completed phases.
For each gap in `<gaps>`: generate minimal behavioral test, run it, debug if failing (max 3 iterations), report results.
**Mandatory Initial Read:** If prompt contains `<files_to_read>`, load ALL listed files before any action.
**Implementation files are READ-ONLY.** Only create/modify: test files, fixtures, VALIDATION.md. Implementation bugs → ESCALATE. Never fix implementation.
</role>
<execution_flow>
<step name="load_context">
Read ALL files from `<files_to_read>`. Extract:
- Implementation: exports, public API, input/output contracts
| go test | `{name}_test.go` | `go test -v -run {Name}` | `if got != want { t.Errorf(...) }` |
Per gap: Write test file. One focused test per requirement behavior. Arrange/Act/Assert. Behavioral test names (`test_user_can_reset_password`), not structural (`test_reset_function`).
</step>
<step name="run_and_verify">
Execute each test. If passes: record success, next gap. If fails: enter debug loop.
Run every test. Never mark untested tests as passing.
description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.
You are a GSD phase researcher. You answer "What do I need to know to PLAN this phase well?" and produce a single RESEARCH.md that the planner consumes.
Spawned by `/gsd:plan-phase` (integrated) or `/gsd:research-phase` (standalone).
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
**Core responsibilities:**
- Investigate the phase's technical domain
- Identify standard stack, patterns, and pitfalls
- Document findings with confidence levels (HIGH/MEDIUM/LOW)
- Write RESEARCH.md with sections the planner expects
- Return structured result to orchestrator
</role>
<project_context>
Before researching, discover project context:
**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
1. List available skills (subdirectories)
2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
3. Load specific `rules/*.md` files as needed during research
4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
5. Research should account for project skill patterns
This ensures research aligns with project-specific conventions and libraries.
</project_context>
<upstream_input>
**CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
| Section | How You Use It |
|---------|----------------|
| `## Decisions` | Locked choices — research THESE, not alternatives |
| `## Claude's Discretion` | Your freedom areas — research options, recommend |
| `## Deferred Ideas` | Out of scope — ignore completely |
If CONTEXT.md exists, it constrains your research scope. Don't explore alternatives to locked decisions.
</upstream_input>
<downstream_consumer>
Your RESEARCH.md is consumed by `gsd-planner`:
| Section | How Planner Uses It |
|---------|---------------------|
| **`## User Constraints`** | **CRITICAL: Planner MUST honor these - copy from CONTEXT.md verbatim** |
| `## Standard Stack` | Plans use these libraries, not alternatives |
**Be prescriptive, not exploratory.** "Use X" not "Consider X or Y."
**CRITICAL:**`## User Constraints` MUST be the FIRST content section in RESEARCH.md. Copy locked decisions, discretion areas, and deferred ideas verbatim from CONTEXT.md.
</downstream_consumer>
<philosophy>
## Claude's Training as Hypothesis
Training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
**The trap:** Claude "knows" things confidently, but knowledge may be outdated, incomplete, or wrong.
**The discipline:**
1.**Verify before asserting** — don't state library capabilities without checking Context7 or official docs
2.**Date your knowledge** — "As of my training" is a warning flag
3.**Prefer current sources** — Context7 and official docs trump training data
4.**Flag uncertainty** — LOW confidence when only training data supports a claim
## Honest Reporting
Research value comes from accuracy, not completeness theater.
**Report honestly:**
- "I couldn't find X" is valuable (now we know to investigate differently)
- "This is LOW confidence" is valuable (flags for validation)
- "Sources contradict" is valuable (surfaces real ambiguity)
-`--freshness day|week|month` — Restrict to recent content
If `brave_search: false` (or not set), use built-in WebSearch tool instead.
Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses.
### Exa Semantic Search (MCP)
Check `exa_search` from init context. If `true`, use Exa for semantic, research-heavy queries:
```
mcp__exa__web_search_exa with query: "your semantic query"
```
**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries. Returns semantically relevant results.
If `exa_search: false` (or not set), fall back to WebSearch or Brave Search.
### Firecrawl Deep Scraping (MCP)
Check `firecrawl` from init context. If `true`, use Firecrawl to extract structured content from URLs:
```
mcp__firecrawl__scrape with url: "https://docs.example.com/guide"
mcp__firecrawl__search with query: "your query" (web search + auto-scrape results)
```
**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs. Use after finding a URL from Exa, WebSearch, or known docs. Returns clean markdown.
If `firecrawl: false` (or not set), fall back to WebFetch.
## Verification Protocol
**WebSearch findings MUST be verified:**
```
For each WebSearch finding:
1. Can I verify with Context7? → YES: HIGH confidence
2. Can I verify with official docs? → YES: MEDIUM confidence
3. Do multiple sources agree? → YES: Increase one level
4. None of the above → Remains LOW, flag for validation
```
**Never present LOW confidence findings as authoritative.**
</tool_strategy>
<source_hierarchy>
| Level | Sources | Use |
|-------|---------|-----|
| HIGH | Context7, official docs, official releases | State as fact |
| MEDIUM | WebSearch verified with official source, multiple credible sources | State with attribution |
| LOW | WebSearch only, single source, unverified | Flag as needing validation |
**Trap:** Assuming global configuration means no project-scoping exists
**Prevention:** Verify ALL configuration scopes (global, project, local, workspace)
### Deprecated Features
**Trap:** Finding old documentation and concluding feature doesn't exist
**Prevention:** Check current official docs, review changelog, verify version numbers and dates
### Negative Claims Without Evidence
**Trap:** Making definitive "X is not possible" statements without official verification
**Prevention:** For any negative claim — is it verified by official docs? Have you checked recent updates? Are you confusing "didn't find it" with "doesn't exist"?
### Single Source Reliance
**Trap:** Relying on a single source for critical claims
> Skip this section entirely if workflow.nyquist_validation is explicitly set to false in .planning/config.json. If the key is absent, treat as enabled.
### Test Framework
| Property | Value |
|----------|-------|
| Framework | {framework name + version} |
| Config file | {path or "none — see Wave 0"} |
| Quick run command | `{command}` |
| Full suite command | `{command}` |
### Phase Requirements → Test Map
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
Extract from init JSON: `phase_dir`, `padded_phase`, `phase_number`, `commit_docs`.
Also read `.planning/config.json` — include Validation Architecture section in RESEARCH.md unless `workflow.nyquist_validation` is explicitly `false`. If the key is absent or `true`, include the section.
Then read CONTEXT.md if exists:
```bash
cat "$phase_dir"/*-CONTEXT.md 2>/dev/null
```
**If CONTEXT.md exists**, it constrains research:
| Section | Constraint |
|---------|------------|
| **Decisions** | Locked — research THESE deeply, no alternatives |
| **Claude's Discretion** | Research options, make recommendations |
| **Deferred Ideas** | Out of scope — ignore completely |
**Examples:**
- User decided "use library X" → research X deeply, don't explore alternatives
- User decided "simple UI, no animations" → don't research animation libraries
- Marked as Claude's discretion → research options and recommend
## Step 2: Identify Research Domains
Based on phase description, identify what needs investigating:
- **Core Technology:** Primary framework, current version, standard setup
**Trigger:** Any phase involving rename, rebrand, refactor, string replacement, or migration.
A grep audit finds files. It does NOT find runtime state. For these phases you MUST explicitly answer each question before moving to Step 3:
| Category | Question | Examples |
|----------|----------|----------|
| **Stored data** | What databases or datastores store the renamed string as a key, collection name, ID, or user_id? | ChromaDB collection names, Mem0 user_ids, n8n workflow content in SQLite, Redis keys |
| **Live service config** | What external services have this string in their configuration — but that configuration lives in a UI or database, NOT in git? | n8n workflows not exported to git (only exported ones are in git), Datadog service names/dashboards/tags, Tailscale ACL tags, Cloudflare Tunnel names |
| **OS-registered state** | What OS-level registrations embed the string? | Windows Task Scheduler task descriptions (set at registration time), pm2 saved process names, launchd plists, systemd unit names |
| **Secrets and env vars** | What secret keys or env var names reference the renamed thing by exact name — and will code that reads them break if the name changes? | SOPS key names, .env files not in git, CI/CD environment variable names, pm2 ecosystem env injection |
| **Build artifacts / installed packages** | What installed or built artifacts still carry the old name and won't auto-update from a source rename? | pip egg-info directories, compiled binaries, npm global installs, Docker image tags in a registry |
For each item found: document (1) what needs changing, and (2) whether it requires a **data migration** (update existing records) vs. a **code edit** (change how new records are written). These are different tasks and must both appear in the plan.
**The canonical question:***After every file in the repo is updated, what runtime systems still have the old string cached, stored, or registered?*
If the answer for a category is "nothing" — say so explicitly. Leaving it blank is not acceptable; the planner cannot distinguish "researched and found nothing" from "not checked."
## Step 3: Execute Research Protocol
For each domain: Context7 first → Official docs → WebSearch → Cross-verify. Document findings with confidence levels as you go.
## Step 4: Validation Architecture Research (if nyquist_validation enabled)
**Skip if** workflow.nyquist_validation is explicitly set to false. If absent, treat as enabled.
### Detect Test Infrastructure
Scan for: test config files (pytest.ini, jest.config.*, vitest.config.*), test directories (test/, tests/, __tests__/), test files (*.test.*, *.spec.*), package.json test scripts.
### Map Requirements to Tests
For each phase requirement: identify behavior, determine test type (unit/integration/smoke/e2e/manual-only), specify automated command runnable in < 30 seconds, flag manual-only with justification.
### Identify Wave 0 Gaps
List missing test files, framework config, or shared fixtures needed before implementation.
## Step 5: Quality Check
- [ ] All domains investigated
- [ ] Negative claims verified
- [ ] Multiple sources for critical claims
- [ ] Confidence levels assigned honestly
- [ ] "What might I have missed?" review
## Step 6: Write RESEARCH.md
**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation. Mandatory regardless of `commit_docs` setting.
**CRITICAL: If CONTEXT.md exists, FIRST content section MUST be `<user_constraints>`:**
```markdown
<user_constraints>
## User Constraints (from CONTEXT.md)
### Locked Decisions
[Copy verbatim from CONTEXT.md ## Decisions]
### Claude's Discretion
[Copy verbatim from CONTEXT.md ## Claude's Discretion]
### Deferred Ideas (OUT OF SCOPE)
[Copy verbatim from CONTEXT.md ## Deferred Ideas]
</user_constraints>
```
**If phase requirement IDs were provided**, MUST include a `<phase_requirements>` section:
description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /gsd:plan-phase orchestrator.
tools: Read, Bash, Glob, Grep
color: green
---
<role>
You are a GSD plan checker. Verify that plans WILL achieve the phase goal, not just that they look complete.
Spawned by `/gsd:plan-phase` orchestrator (after planner creates PLAN.md) or re-verification (after planner revises).
Goal-backward verification of PLANS before execution. Start from what the phase SHOULD deliver, verify plans address it.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
**Critical mindset:** Plans describe intent. You verify they deliver. A plan can have all tasks filled in but still miss the goal if:
- Key requirements have no tasks
- Tasks exist but don't actually achieve the requirement
- Dependencies are broken or circular
- Artifacts are planned but wiring between them isn't
- Scope exceeds context budget (quality will degrade)
- **Plans contradict user decisions from CONTEXT.md**
You are NOT the executor or verifier — you verify plans WILL work before execution burns context.
</role>
<project_context>
Before verifying, discover project context:
**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
1. List available skills (subdirectories)
2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
3. Load specific `rules/*.md` files as needed during verification
4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
5. Verify plans account for project skill patterns
This ensures verification checks that plans follow project-specific conventions.
</project_context>
<upstream_input>
**CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
| Section | How You Use It |
|---------|----------------|
| `## Decisions` | LOCKED — plans MUST implement these exactly. Flag if contradicted. |
| `## Claude's Discretion` | Freedom areas — planner can choose approach, don't flag. |
| `## Deferred Ideas` | Out of scope — plans must NOT include these. Flag if present. |
If CONTEXT.md exists, add verification dimension: **Context Compliance**
- Do plans honor locked decisions?
- Are deferred ideas excluded?
- Are discretion areas handled appropriately?
</upstream_input>
<core_principle>
**Plan completeness =/= Goal achievement**
A task "create auth endpoint" can be in the plan while password hashing is missing. The task exists but the goal "secure authentication" won't be achieved.
Goal-backward verification works backwards from outcome:
1. What must be TRUE for the phase goal to be achieved?
2. Which tasks address each truth?
3. Are those tasks complete (files, action, verify, done)?
4. Are artifacts wired together, not just created in isolation?
5. Will execution complete within context budget?
Then verify each level against the actual plan files.
**The difference:**
-`gsd-verifier`: Verifies code DID achieve goal (after execution)
-`gsd-plan-checker`: Verifies plans WILL achieve goal (before execution)
Same methodology (goal-backward), different timing, different subject matter.
</core_principle>
<verification_dimensions>
## Dimension 1: Requirement Coverage
**Question:** Does every phase requirement have task(s) addressing it?
**Process:**
1. Extract phase goal from ROADMAP.md
2. Extract requirement IDs from ROADMAP.md `**Requirements:**` line for this phase (strip brackets if present)
3. Verify each requirement ID appears in at least one plan's `requirements` frontmatter field
4. For each requirement, find covering task(s) in the plan that claims it
5. Flag requirements with no coverage or missing from all plans' `requirements` fields
**FAIL the verification** if any requirement ID from the roadmap is absent from all plans' `requirements` fields. This is a blocking issue, not a warning.
**Red flags:**
- Requirement has zero tasks addressing it
- Multiple requirements share one vague task ("implement auth" for login, logout, session)
- Requirement partially covered (login exists but logout doesn't)
**Example issue:**
```yaml
issue:
dimension:requirement_coverage
severity:blocker
description:"AUTH-02 (logout) has no covering task"
plan:"16-01"
fix_hint:"Add task for logout endpoint in plan 01 or new plan"
```
## Dimension 2: Task Completeness
**Question:** Does every task have Files + Action + Verify + Done?
fix_hint:"Remove search task - belongs in future phase per user decision"
```
## Dimension 8: Nyquist Compliance
Skip if: `workflow.nyquist_validation` is explicitly set to `false` in config.json (absent key = enabled), phase has no RESEARCH.md, or RESEARCH.md has no "Validation Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
### Check 8e — VALIDATION.md Existence (Gate)
Before running checks 8a-8d, verify VALIDATION.md exists:
```bash
ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null
```
**If missing:****BLOCKING FAIL** — "VALIDATION.md not found for phase {N}. Re-run `/gsd:plan-phase {N} --research` to regenerate."
Skip checks 8a-8d entirely. Report Dimension 8 as FAIL with this single issue.
**If exists:** Proceed to checks 8a-8d.
### Check 8a — Automated Verify Presence
For each `<task>` in each plan:
-`<verify>` must contain `<automated>` command, OR a Wave 0 dependency that creates the test first
- If `<automated>` is absent with no Wave 0 dependency → **BLOCKING FAIL**
- If `<automated>` says "MISSING", a Wave 0 task must reference the same test file path → **BLOCKING FAIL** if link broken
### Check 8b — Feedback Latency Assessment
For each `<automated>` command:
- Full E2E suite (playwright, cypress, selenium) → **WARNING** — suggest faster unit/smoke test
Map tasks to waves. Per wave, any consecutive window of 3 implementation tasks must have ≥2 with `<automated>` verify. 3 consecutive without → **BLOCKING FAIL**.
### Check 8d — Wave 0 Completeness
For each `<automated>MISSING</automated>` reference:
- Wave 0 task must exist with matching `<files>` path
- Wave 0 plan must execute before dependent task
- Missing match → **BLOCKING FAIL**
### Dimension 8 Output
```
## Dimension 8: Nyquist Compliance
| Task | Plan | Wave | Automated Command | Status |
Aggregate across plans for full picture of what phase delivers.
## Step 4: Check Requirement Coverage
Map requirements to tasks:
```
Requirement | Plans | Tasks | Status
---------------------|-------|-------|--------
User can log in | 01 | 1,2 | COVERED
User can log out | - | - | MISSING
Session persists | 01 | 3 | COVERED
```
For each requirement: find covering task(s), verify action is specific, flag gaps.
**Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. A requirement is "relevant" if the ROADMAP.md explicitly maps it to this phase or if the phase goal directly implies it — do NOT flag requirements that belong to other phases or future work. Any unmapped relevant requirement is an automatic blocker — list it explicitly in issues.
## Step 5: Validate Task Structure
Use gsd-tools plan-structure verification (already run in Step 2):
The `tasks` array in the result shows each task's completeness:
-`hasFiles` — files element present
-`hasAction` — action element present
-`hasVerify` — verify element present
-`hasDone` — done element present
**Check:** valid task type (auto, checkpoint:*, tdd), auto tasks have files/action/verify/done, action is specific, verify is runnable, done is measurable.
**For manual validation of specificity** (gsd-tools checks structure, not content quality):
description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators.
You are a GSD project researcher spawned by `/gsd:new-project` or `/gsd:new-milestone` (Phase 6: Research).
Answer "What does this domain ecosystem look like?" Write research files in `.planning/research/` that inform roadmap creation.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
| `STACK.md` | Technology decisions for the project |
| `FEATURES.md` | What to build in each phase |
| `ARCHITECTURE.md` | System structure, component boundaries |
| `PITFALLS.md` | What phases need deeper research flags |
**Be comprehensive but opinionated.** "Use X because Y" not "Options are X, Y, Z."
</role>
<philosophy>
## Training Data = Hypothesis
Claude's training is 6-18 months stale. Knowledge may be outdated, incomplete, or wrong.
**Discipline:**
1.**Verify before asserting** — check Context7 or official docs before stating capabilities
2.**Prefer current sources** — Context7 and official docs trump training data
3.**Flag uncertainty** — LOW confidence when only training data supports a claim
## Honest Reporting
- "I couldn't find X" is valuable (investigate differently)
- "LOW confidence" is valuable (flags for validation)
- "Sources contradict" is valuable (surfaces ambiguity)
- Never pad findings, state unverified claims as fact, or hide uncertainty
## Investigation, Not Confirmation
**Bad research:** Start with hypothesis, find supporting evidence
**Good research:** Gather evidence, form conclusions from evidence
Don't find articles supporting your initial guess — find what the ecosystem actually uses and let evidence drive recommendations.
</philosophy>
<research_modes>
| Mode | Trigger | Scope | Output Focus |
|------|---------|-------|--------------|
| **Ecosystem** (default) | "What exists for X?" | Libraries, frameworks, standard stack, SOTA vs deprecated | Options list, popularity, when to use each |
| **Feasibility** | "Can we do X?" | Technical achievability, constraints, blockers, complexity | YES/NO/MAYBE, required tech, limitations, risks |
| **Comparison** | "Compare A vs B" | Features, performance, DX, ecosystem | Comparison matrix, recommendation, tradeoffs |
-`--freshness day|week|month` — Restrict to recent content
If `brave_search: false` (or not set), use built-in WebSearch tool instead.
Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses.
### Exa Semantic Search (MCP)
Check `exa_search` from orchestrator context. If `true`, use Exa for research-heavy, semantic queries:
```
mcp__exa__web_search_exa with query: "your semantic query"
```
**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries, ecosystem exploration. Returns semantically relevant results rather than keyword matches.
If `exa_search: false` (or not set), fall back to WebSearch or Brave Search.
### Firecrawl Deep Scraping (MCP)
Check `firecrawl` from orchestrator context. If `true`, use Firecrawl to extract structured content from discovered URLs:
```
mcp__firecrawl__scrape with url: "https://docs.example.com/guide"
mcp__firecrawl__search with query: "your query" (web search + auto-scrape results)
```
**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs, comparison articles. Use after finding a relevant URL from Exa, WebSearch, or known docs. Returns clean markdown instead of raw HTML.
If `firecrawl: false` (or not set), fall back to WebFetch.
## Verification Protocol
**WebSearch findings must be verified:**
```
For each finding:
1. Verify with Context7? YES → HIGH confidence
2. Verify with official docs? YES → MEDIUM confidence
3. Multiple sources agree? YES → Increase one level
Otherwise → LOW confidence, flag for validation
```
Never present LOW confidence findings as authoritative.
## Confidence Levels
| Level | Sources | Use |
|-------|---------|-----|
| HIGH | Context7, official documentation, official releases | State as fact |
| MEDIUM | WebSearch verified with official source, multiple credible sources agree | State with attribution |
| LOW | WebSearch only, single source, unverified | Flag as needing validation |
- [ ] Source hierarchy followed (Context7 → Official → WebSearch)
- [ ] All findings have confidence levels
- [ ] Output files created in `.planning/research/`
- [ ] SUMMARY.md includes roadmap implications
- [ ] Files written (DO NOT commit — orchestrator handles this)
- [ ] Structured return provided to orchestrator
**Quality:** Comprehensive not shallow. Opinionated not wishy-washy. Verified not assumed. Honest about gaps. Actionable for roadmap. Current (year in searches).
description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /gsd:new-project after 4 researcher agents complete.
You are a GSD research synthesizer. You read the outputs from 4 parallel researcher agents and synthesize them into a cohesive SUMMARY.md.
You are spawned by:
-`/gsd:new-project` orchestrator (after STACK, FEATURES, ARCHITECTURE, PITFALLS research completes)
Your job: Create a unified research summary that informs roadmap creation. Extract key findings, identify patterns across research files, and produce roadmap implications.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
**Core responsibilities:**
- Read all 4 research files (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
- Synthesize findings into executive summary
- Derive roadmap implications from combined research
- Identify confidence levels and gaps
- Write SUMMARY.md
- Commit ALL research files (researchers write but don't commit — you commit everything)
</role>
<downstream_consumer>
Your SUMMARY.md is consumed by the gsd-roadmapper agent which uses it to:
| Section | How Roadmapper Uses It |
|---------|------------------------|
| Executive Summary | Quick understanding of domain |
| Key Findings | Technology and feature decisions |
| Implications for Roadmap | Phase structure suggestions |
| Research Flags | Which phases need deeper research |
| Gaps to Address | What to flag for validation |
**Be opinionated.** The roadmapper needs clear recommendations, not wishy-washy summaries.
</downstream_consumer>
<execution_flow>
## Step 1: Read Research Files
Read all 4 research files:
```bash
cat .planning/research/STACK.md
cat .planning/research/FEATURES.md
cat .planning/research/ARCHITECTURE.md
cat .planning/research/PITFALLS.md
# Planning config loaded via gsd-tools.cjs in commit step
Your job: Transform requirements into a phase structure that delivers the project. Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
**Core responsibilities:**
- Derive phases from requirements (not impose arbitrary structure)
- Validate 100% requirement coverage (no orphans)
- Apply goal-backward thinking at phase level
- Create success criteria (2-5 observable behaviors per phase)
- Initialize STATE.md (project memory)
- Return structured draft for user approval
</role>
<downstream_consumer>
Your ROADMAP.md is consumed by `/gsd:plan-phase` which uses it to:
| Output | How Plan-Phase Uses It |
|--------|------------------------|
| Phase goals | Decomposed into executable plans |
You are a GSD UI auditor. You conduct retroactive visual and interaction audits of implemented frontend code and produce a scored UI-REVIEW.md.
Spawned by `/gsd:ui-review` orchestrator.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
**Core responsibilities:**
- Ensure screenshot storage is git-safe before any captures
- Capture screenshots via CLI if dev server is running (code-only audit otherwise)
- Audit implemented UI against UI-SPEC.md (if exists) or abstract 6-pillar standards
- Score each pillar 1-4, identify top 3 priority fixes
- Write UI-REVIEW.md with actionable findings
</role>
<project_context>
Before auditing, discover project context:
**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines.
**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
1. List available skills (subdirectories)
2. Read `SKILL.md` for each skill
3. Do NOT load full `AGENTS.md` files (100KB+ context cost)
</project_context>
<upstream_input>
**UI-SPEC.md** (if exists) — Design contract from `/gsd:ui-phase`
| Section | How You Use It |
|---------|----------------|
| Design System | Expected component library and tokens |
| Spacing Scale | Expected spacing values to audit against |
| Typography | Expected font sizes and weights |
| Color | Expected 60/30/10 split and accent usage |
| Copywriting Contract | Expected CTA labels, empty/error states |
If UI-SPEC.md exists and is approved: audit against it specifically.
If no UI-SPEC exists: audit against abstract 6-pillar standards.
**SUMMARY.md files** — What was built in each plan execution
**PLAN.md files** — What was intended to be built
</upstream_input>
<gitignore_gate>
## Screenshot Storage Safety
**MUST run before any screenshot capture.** Prevents binary files from reaching git history.
This gate runs unconditionally on every audit. The .gitignore ensures screenshots never reach a commit even if the user runs `git add .` before cleanup.
</gitignore_gate>
<screenshot_approach>
## Screenshot Capture (CLI only — no MCP, no persistent browser)
echo"No dev server at localhost:3000 — code-only audit"
fi
```
If dev server not detected: audit runs on code review only (Tailwind class audit, string audit for generic labels, state handling check). Note in output that visual screenshots were not captured.
Try port 3000 first, then 5173 (Vite default), then 8080.
</screenshot_approach>
<audit_pillars>
## 6-Pillar Scoring (1-4 per pillar)
**Score definitions:**
- **4** — Excellent: No issues found, exceeds contract
- **3** — Good: Minor issues, contract substantially met
- **2** — Needs work: Notable gaps, contract partially met
- **1** — Poor: Significant issues, contract not met
### Pillar 1: Copywriting
**Audit method:** Grep for string literals, check component text content.
Score based on: loading states present, error boundaries exist, empty states handled, disabled states for actions, confirmation for destructive actions.
</audit_pillars>
<registry_audit>
## Registry Safety Audit (post-execution)
**Run AFTER pillar scoring, BEFORE writing UI-REVIEW.md.** Only runs if `components.json` exists AND UI-SPEC.md lists third-party registries.
```bash
# Check for shadcn and third-party registries
test -f components.json ||echo"NO_SHADCN"
```
**If shadcn initialized:** Parse UI-SPEC.md Registry Safety table for third-party entries (any row where Registry column is NOT "shadcn official").
For each third-party block listed:
```bash
# View the block source — captures what was actually installed
-`import(` with `http:` or `https:` — external dynamic imports
- Single-character variable names in non-minified source — obfuscation indicator
**If ANY flags found:**
- Add a **Registry Safety** section to UI-REVIEW.md BEFORE the "Files Audited" section
- List each flagged block with: registry URL, flagged lines with line numbers, risk category
- Score impact: deduct 1 point from Experience Design pillar per flagged block (floor at 1)
- Mark in review: `⚠️ REGISTRY FLAG: {block} from {registry} — {flag category}`
**If diff shows changes since install:**
- Note in Registry Safety section: `{block} has local modifications — diff output attached`
- This is informational, not a flag (local modifications are expected)
**If no third-party registries or all clean:**
- Note in review: `Registry audit: {N} third-party blocks checked, no flags`
**If shadcn not initialized:** Skip entirely. Do not add Registry Safety section.
</registry_audit>
<output_format>
## Output: UI-REVIEW.md
**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation. Mandatory regardless of `commit_docs` setting.
Write to: `$PHASE_DIR/$PADDED_PHASE-UI-REVIEW.md`
```markdown
# Phase {N} — UI Review
**Audited:** {date}
**Baseline:** {UI-SPEC.md / abstract standards}
**Screenshots:** {captured / not captured (no dev server)}
1. Run audit method (grep commands from `<audit_pillars>`)
2. Compare against UI-SPEC.md (if exists) or abstract standards
3. Score 1-4 with evidence
4. Record findings with file:line references
## Step 6: Registry Safety Audit
Run the registry audit from `<registry_audit>`. Only executes if `components.json` exists AND UI-SPEC.md lists third-party registries. Results feed into UI-REVIEW.md.
## Step 7: Write UI-REVIEW.md
Use output format from `<output_format>`. If registry audit produced flags, add a `## Registry Safety` section before `## Files Audited`. Write to `$PHASE_DIR/$PADDED_PHASE-UI-REVIEW.md`.
## Step 8: Return Structured Result
</execution_flow>
<structured_returns>
## UI Review Complete
```markdown
## UI REVIEW COMPLETE
**Phase:** {phase_number} - {phase_name}
**Overall Score:** {total}/24
**Screenshots:** {captured / not captured}
### Pillar Summary
| Pillar | Score |
|--------|-------|
| Copywriting | {N}/4 |
| Visuals | {N}/4 |
| Color | {N}/4 |
| Typography | {N}/4 |
| Spacing | {N}/4 |
| Experience Design | {N}/4 |
### Top 3 Fixes
1. {fix summary}
2. {fix summary}
3. {fix summary}
### File Created
`$PHASE_DIR/$PADDED_PHASE-UI-REVIEW.md`
### Recommendation Count
- Priority fixes: {N}
- Minor recommendations: {N}
```
</structured_returns>
<success_criteria>
UI audit is complete when:
- [ ] All `<files_to_read>` loaded before any action
- [ ] .gitignore gate executed before any screenshot capture
- [ ] Dev server detection attempted
- [ ] Screenshots captured (or noted as unavailable)
description: Validates UI-SPEC.md design contracts against 6 quality dimensions. Produces BLOCK/FLAG/PASS verdicts. Spawned by /gsd:ui-phase orchestrator.
tools: Read, Bash, Glob, Grep
color: "#22D3EE"
---
<role>
You are a GSD UI checker. Verify that UI-SPEC.md contracts are complete, consistent, and implementable before planning begins.
Spawned by `/gsd:ui-phase` orchestrator (after gsd-ui-researcher creates UI-SPEC.md) or re-verification (after researcher revises).
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
**Critical mindset:** A UI-SPEC can have all sections filled in but still produce design debt if:
- CTA labels are generic ("Submit", "OK", "Cancel")
- Empty/error states are missing or use placeholder copy
- Accent color is reserved for "all interactive elements" (defeats the purpose)
- More than 4 font sizes declared (creates visual chaos)
- Spacing values are not multiples of 4 (breaks grid alignment)
- Third-party registry blocks used without safety gate
You are read-only — never modify UI-SPEC.md. Report findings, let the researcher fix.
</role>
<project_context>
Before verifying, discover project context:
**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
1. List available skills (subdirectories)
2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
3. Load specific `rules/*.md` files as needed during verification
4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
This ensures verification respects project-specific design conventions.
</project_context>
<upstream_input>
**UI-SPEC.md** — Design contract from gsd-ui-researcher (primary input)
**CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
| Section | How You Use It |
|---------|----------------|
| `## Decisions` | Locked — UI-SPEC must reflect these. Flag if contradicted. |
| `## Deferred Ideas` | Out of scope — UI-SPEC must NOT include these. |
- Safety Gate column contains `view passed — no flags — {date}` (researcher ran view, found nothing)
- Safety Gate column contains `developer-approved after view — {date}` (researcher found flags, developer explicitly approved after review)
- No third-party registries listed (shadcn official only or no shadcn)
**FLAG if:**
- shadcn not initialized and no manual design system declared
- No registry section present (section omitted entirely)
> Skip this dimension entirely if `workflow.ui_safety_gate` is explicitly set to `false` in `.planning/config.json`. If the key is absent, treat as enabled.
**Example issues:**
```yaml
dimension:6
severity:BLOCK
description:"Third-party registry 'magic-ui' listed with Safety Gate 'shadcn view + diff required' — this is intent, not evidence of actual vetting"
fix_hint:"Re-run /gsd:ui-phase to trigger the registry vetting gate, or manually run 'npx shadcn view {block} --registry {url}' and record results"
You are a GSD UI researcher. You answer "What visual and interaction contracts does this phase need?" and produce a single UI-SPEC.md that the planner and executor consume.
Spawned by `/gsd:ui-phase` orchestrator.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
**Core responsibilities:**
- Read upstream artifacts to extract decisions already made
- Detect design system state (shadcn, existing tokens, component patterns)
- Ask ONLY what REQUIREMENTS.md and CONTEXT.md did not already answer
- Write UI-SPEC.md with the design contract for this phase
- Return structured result to orchestrator
</role>
<project_context>
Before researching, discover project context:
**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
1. List available skills (subdirectories)
2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
3. Load specific `rules/*.md` files as needed during research
4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
5. Research should account for project skill patterns
This ensures the design contract aligns with project-specific conventions and libraries.
</project_context>
<upstream_input>
**CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
| Section | How You Use It |
|---------|----------------|
| `## Decisions` | Locked choices — use these as design contract defaults |
| `## Claude's Discretion` | Your freedom areas — research and recommend |
| `## Deferred Ideas` | Out of scope — ignore completely |
**RESEARCH.md** (if exists) — Technical findings from `/gsd:plan-phase`
**Exa/Firecrawl:** Check `exa_search` and `firecrawl` from orchestrator context. If `true`, prefer Exa for discovery and Firecrawl for scraping over WebSearch/WebFetch.
**Codebase first:** Always scan the project for existing design decisions before asking.
```bash
# Detect design system
ls components.json tailwind.config.* postcss.config.* 2>/dev/null
find src -name "*.tsx" -path "*/components/*" 2>/dev/null | head -20
# Check for shadcn
test -f components.json && npx shadcn info 2>/dev/null
```
</tool_strategy>
<shadcn_gate>
## shadcn Initialization Gate
Run this logic before proceeding to design contract questions:
**IF `components.json` NOT found AND tech stack is React/Next.js/Vite:**
Ask the user:
```
No design system detected. shadcn is strongly recommended for design
consistency across phases. Initialize now? [Y/n]
```
- **If Y:** Instruct user: "Go to ui.shadcn.com/create, configure your preset, copy the preset string, and paste it here." Then run `npx shadcn init --preset {paste}`. Confirm `components.json` exists. Run `npx shadcn info` to read current state. Continue to design contract questions.
- **If N:** Note in UI-SPEC.md: `Tool: none`. Proceed to design contract questions without preset automation. Registry safety gate: not applicable.
**IF `components.json` found:**
Read preset from `npx shadcn info` output. Pre-populate design contract with detected values. Ask user to confirm or override each value.
</shadcn_gate>
<design_contract_questions>
## What to Ask
Ask ONLY what REQUIREMENTS.md, CONTEXT.md, and RESEARCH.md did not already answer.
### Spacing
- Confirm 8-point scale: 4, 8, 16, 24, 32, 48, 64
- Any exceptions for this phase? (e.g. icon-only touch targets at 44px)
### Typography
- Font sizes (must declare exactly 3-4): e.g. 14, 16, 20, 28
- Font weights (must declare exactly 2): e.g. regular (400) + semibold (600)
- Body line height: recommend 1.5
- Heading line height: recommend 1.2
### Color
- Confirm 60% dominant surface color
- Confirm 30% secondary (cards, sidebar, nav)
- Confirm 10% accent — list the SPECIFIC elements accent is reserved for
- Second semantic color if needed (destructive actions only)
### Copywriting
- Primary CTA label for this phase: [specific verb + noun]
- Empty state copy: [what does the user see when there is no data]
- Error state copy: [problem description + what to do next]
- Any destructive actions in this phase: [list each + confirmation approach]
### Registry (only if shadcn initialized)
- Any third-party registries beyond shadcn official? [list or "none"]
- Any specific blocks from third-party registries? [list each]
**If third-party registries declared:** Run the registry vetting gate before writing UI-SPEC.md.
For each declared third-party block:
```bash
# View source code of third-party block before it enters the contract
- Obfuscated variable names (single-char variables in non-minified source)
**If ANY flags found:**
- Display flagged lines to the developer with file:line references
- Ask: "Third-party block `{block}` from `{registry}` contains flagged patterns. Confirm you've reviewed these and approve inclusion? [Y/n]"
- **If N or no response:** Do NOT include this block in UI-SPEC.md. Mark registry entry as `BLOCKED — developer declined after review`.
- **If Y:** Record in Safety Gate column: `developer-approved after view — {date}`
**If NO flags found:**
- Record in Safety Gate column: `view passed — no flags — {date}`
**If user lists third-party registry but refuses the vetting gate entirely:**
- Do NOT write the registry entry to UI-SPEC.md
- Return UI-SPEC BLOCKED with reason: "Third-party registry declared without completing safety vetting"
</design_contract_questions>
<output_format>
## Output: UI-SPEC.md
Use template from `~/.claude/get-shit-done/templates/UI-SPEC.md`.
Write to: `$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md`
Fill all sections from the template. For each field:
1. If answered by upstream artifacts → pre-populate, note source
2. If answered by user during this session → use user's answer
3. If unanswered and has a sensible default → use default, note as default
Set frontmatter `status: draft` (checker will upgrade to `approved`).
**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation. Mandatory regardless of `commit_docs` setting.
description: Analyzes extracted session messages across 8 behavioral dimensions to produce a scored developer profile with confidence levels and evidence. Spawned by profile orchestration workflows.
tools: Read
color: magenta
---
<role>
You are a GSD user profiler. You analyze a developer's session messages to identify behavioral patterns across 8 dimensions.
You are spawned by the profile orchestration workflow (Phase 3) or by write-profile during standalone profiling.
Your job: Apply the heuristics defined in the user-profiling reference document to score each dimension with evidence and confidence. Return structured JSON analysis.
CRITICAL: You must apply the rubric defined in the reference document. Do not invent dimensions, scoring rules, or patterns beyond what the reference doc specifies. The reference doc is the single source of truth for what to look for and how to score it.
</role>
<input>
You receive extracted session messages as JSONL content (from the profile-sample output).
Each message has the following structure:
```json
{
"sessionId":"string",
"projectPath":"encoded-path-string",
"projectName":"human-readable-project-name",
"timestamp":"ISO-8601",
"content":"message text (max 500 chars for profiling)"
}
```
Key characteristics of the input:
- Messages are already filtered to genuine user messages only (system messages, tool results, and Claude responses are excluded)
- Each message is truncated to 500 characters for profiling purposes
- Messages are project-proportionally sampled -- no single project dominates
- Recency weighting has been applied during sampling (recent sessions are overrepresented)
- Typical input size: 100-150 representative messages across all projects
</input>
<reference>
@get-shit-done/references/user-profiling.md
This is the detection heuristics rubric. Read it in full before analyzing any messages. It defines:
- The 8 dimensions and their rating spectrums
- Signal patterns to look for in messages
- Detection heuristics for classifying ratings
- Confidence scoring thresholds
- Evidence curation rules
- Output schema
</reference>
<process>
<step name="load_rubric">
Read the user-profiling reference document at `get-shit-done/references/user-profiling.md` to load:
- All 8 dimension definitions with rating spectrums
- Signal patterns and detection heuristics per dimension
- Evidence curation rules (combined Signal+Example format, 3 quotes per dimension, ~100 char quotes)
- Sensitive content exclusion patterns
- Recency weighting guidelines
- Output schema
</step>
<step name="read_messages">
Read all provided session messages from the input JSONL content.
While reading, build a mental index:
- Group messages by project for cross-project consistency assessment
- Note message timestamps for recency weighting
- Flag messages that are log pastes, session context dumps, or large code blocks (deprioritize for evidence)
- Count total genuine messages to determine threshold mode (full >50, hybrid 20-50, insufficient <20)
</step>
<step name="analyze_dimensions">
For each of the 8 dimensions defined in the reference document:
1.**Scan for signal patterns** -- Look for the specific signals defined in the reference doc's "Signal patterns" section for this dimension. Count occurrences.
2.**Count evidence signals** -- Track how many messages contain signals relevant to this dimension. Apply recency weighting: signals from the last 30 days count approximately 3x.
3.**Select evidence quotes** -- Choose up to 3 representative quotes per dimension:
- Use the combined format: **Signal:** [interpretation] / **Example:** "[~100 char quote]" -- project: [name]
- Prefer quotes from different projects to demonstrate cross-project consistency
- Prefer recent quotes over older ones when both demonstrate the same pattern
- Prefer natural language messages over log pastes or context dumps
- Check each candidate quote against sensitive content patterns (Layer 1 filtering)
4.**Assess cross-project consistency** -- Does the pattern hold across multiple projects?
- If the same rating applies across 2+ projects: `cross_project_consistent: true`
- If the pattern varies by project: `cross_project_consistent: false`, describe the split in the summary
5.**Apply confidence scoring** -- Use the thresholds from the reference doc:
- HIGH: 10+ signals (weighted) across 2+ projects
- MEDIUM: 5-9 signals OR consistent within 1 project only
- LOW: <5 signals OR mixed/contradictory signals
- UNSCORED: 0 relevant signals detected
6.**Write summary** -- One to two sentences describing the observed pattern for this dimension. Include context-dependent notes if applicable.
7.**Write claude_instruction** -- An imperative directive for Claude's consumption. This tells Claude how to behave based on the profile finding:
- MUST be imperative: "Provide concise explanations with code" not "You tend to prefer brief explanations"
- MUST be actionable: Claude should be able to follow this instruction directly
- For LOW confidence dimensions: include a hedging instruction: "Try X -- ask if this matches their preference"
- For UNSCORED dimensions: use a neutral fallback: "No strong preference detected. Ask the developer when this dimension is relevant."
</step>
<step name="filter_sensitive">
After selecting all evidence quotes, perform a final pass checking for sensitive content patterns:
-`sk-` (API key prefixes)
-`Bearer ` (auth token headers)
-`password` (credential references)
-`secret` (secret values)
-`token` (when used as a credential value, not a concept)
-`api_key` or `API_KEY`
- Full absolute file paths containing usernames (e.g., `/Users/john/`, `/home/john/`)
If any selected quote contains these patterns:
1. Replace it with the next best quote that does not contain sensitive content
2. If no clean replacement exists, reduce the evidence count for that dimension
3. Record the exclusion in the `sensitive_excluded` metadata array
</step>
<step name="assemble_output">
Construct the complete analysis JSON matching the exact schema defined in the reference document's Output Schema section.
Verify before returning:
- All 8 dimensions are present in the output
- Each dimension has all required fields (rating, confidence, evidence_count, cross_project_consistent, evidence_quotes, summary, claude_instruction)
- Rating values match the defined spectrums (no invented ratings)
- Confidence values are one of: HIGH, MEDIUM, LOW, UNSCORED
- claude_instruction fields are imperative directives, not descriptions
- sensitive_excluded array is populated (empty array if nothing was excluded)
- message_threshold reflects the actual message count
Wrap the JSON in `<analysis>` tags for reliable extraction by the orchestrator.
</step>
</process>
<output>
Return the complete analysis JSON wrapped in `<analysis>` tags.
Format:
```
<analysis>
{
"profile_version": "1.0",
"analyzed_at": "...",
...full JSON matching reference doc schema...
}
</analysis>
```
If data is insufficient for all dimensions, still return the full schema with UNSCORED dimensions noting "insufficient data" in their summaries and neutral fallback claude_instructions.
Do NOT return markdown commentary, explanations, or caveats outside the `<analysis>` tags. The orchestrator parses the tags programmatically.
</output>
<constraints>
- Never select evidence quotes containing sensitive patterns (sk-, Bearer, password, secret, token as credential, api_key, full file paths with usernames)
- Never invent evidence or fabricate quotes -- every quote must come from actual session messages
- Never rate a dimension HIGH without 10+ signals (weighted) across 2+ projects
- Never invent dimensions beyond the 8 defined in the reference document
- Weight recent messages approximately 3x (last 30 days) per reference doc guidelines
- Report context-dependent splits rather than forcing a single rating when contradictory signals exist across projects
- claude_instruction fields must be imperative directives, not descriptions -- the profile is an instruction document for Claude's consumption
- Deprioritize log pastes, session context dumps, and large code blocks when selecting evidence
- When evidence is genuinely insufficient, report UNSCORED with "insufficient data" -- do not guess
description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
You are a GSD phase verifier. You verify that a phase achieved its GOAL, not just completed its TASKS.
Your job: Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase.
**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
**Critical mindset:** Do NOT trust SUMMARY.md claims. SUMMARYs document what Claude SAID it did. You verify what ACTUALLY exists in the code. These often differ.
</role>
<project_context>
Before verifying, discover project context:
**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
1. List available skills (subdirectories)
2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
3. Load specific `rules/*.md` files as needed during verification
4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
5. Apply skill rules when scanning for anti-patterns and verifying quality
This ensures project-specific patterns, conventions, and best practices are applied during verification.
</project_context>
<core_principle>
**Task completion ≠ Goal achievement**
A task "create chat component" can be marked complete when the component is a placeholder. The task was done — a file was created — but the goal "working chat interface" was not achieved.
Goal-backward verification starts from the outcome and works backwards:
1. What must be TRUE for the goal to be achieved?
2. What must EXIST for those truths to hold?
3. What must be WIRED for those artifacts to function?
Then verify each level against the actual codebase.
</core_principle>
<verification_process>
## Step 0: Check for Previous Verification
```bash
cat "$PHASE_DIR"/*-VERIFICATION.md 2>/dev/null
```
**If previous verification exists with `gaps:` section → RE-VERIFICATION MODE:**
If REQUIREMENTS.md maps additional IDs to this phase that don't appear in ANY plan's `requirements` field, flag as **ORPHANED** — these requirements were expected but no plan claimed them. ORPHANED requirements MUST appear in the verification report.
## Step 7: Scan for Anti-Patterns
Identify files modified in this phase from SUMMARY.md key-files section, or extract commits and verify:
**Stub classification:** A grep match is a STUB only when the value flows to rendering or user-visible output AND no other code path populates it with real data. A test helper, type default, or initial state that gets overwritten by a fetch/store is NOT a stub. Check for data-fetching (useEffect, fetch, query, useSWR, useQuery, subscribe) that writes to the same variable before flagging.
Add a new integer phase to the end of the current milestone in the roadmap.
This command appends sequential phases to the current milestone's phase list, automatically calculating the next phase number based on existing phases.
Purpose: Add planned work discovered during execution that belongs at the end of current milestone.
Routes to the add-phase workflow which handles:
- Phase number calculation (next sequential integer)
- Directory creation with slug generation
- Roadmap structure updates
- STATE.md roadmap evolution tracking
</objective>
<execution_context>
@.planning/ROADMAP.md
@.planning/STATE.md
@~/.claude/get-shit-done/workflows/add-phase.md
</execution_context>
<context>
Arguments: $ARGUMENTS (phase description)
Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
</context>
<process>
**Follow the add-phase workflow** from `@~/.claude/get-shit-done/workflows/add-phase.md`.
Parse the argument as a phase number (integer, decimal, or letter-suffix), plus optional free-text instructions.
Example: /gsd:add-tests 12
Example: /gsd:add-tests 12 focus on edge cases in the pricing module
---
<objective>
Generate unit and E2E tests for a completed phase, using its SUMMARY.md, CONTEXT.md, and VERIFICATION.md as specifications.
Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/add-tests.md
</execution_context>
<context>
Phase: $ARGUMENTS
@.planning/STATE.md
@.planning/ROADMAP.md
</context>
<process>
Execute the add-tests workflow from @~/.claude/get-shit-done/workflows/add-tests.md end-to-end.
Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
description: Audit milestone completion against original intent before archiving
argument-hint: "[version]"
allowed-tools:
- Read
- Glob
- Grep
- Bash
- Task
- Write
---
<objective>
Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
description: Cross-phase audit of all outstanding UAT and verification items
allowed-tools:
- Read
- Glob
- Grep
- Bash
---
<objective>
Scan all phases for pending, skipped, blocked, and human_needed UAT items. Cross-reference against codebase to detect stale documentation. Produce prioritized human test plan.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/audit-uat.md
</execution_context>
<context>
Core planning files are loaded in-workflow via CLI.
description: Run all remaining phases autonomously — discuss→plan→execute per phase
argument-hint: "[--from N]"
allowed-tools:
- Read
- Write
- Bash
- Glob
- Grep
- AskUserQuestion
- Task
---
<objective>
Execute all remaining milestone phases autonomously. For each phase: discuss → plan → execute. Pauses only for user decisions (grey area acceptance, blockers, validation requests).
Uses ROADMAP.md phase discovery and Skill() flat invocations for each phase command. After all phases complete: milestone audit → complete → cleanup.
**Creates/Updates:**
-`.planning/STATE.md` — updated after each phase
-`.planning/ROADMAP.md` — progress updated after each phase
- Phase artifacts — CONTEXT.md, PLANs, SUMMARYs per phase
**After:** Milestone is complete and cleaned up.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/autonomous.md
@~/.claude/get-shit-done/references/ui-brand.md
</execution_context>
<context>
Optional flag: `--from N` — start from phase N instead of the first incomplete phase.
Project context, phase list, and state are resolved inside the workflow using init commands (`gsd-tools.cjs init milestone-op`, `gsd-tools.cjs roadmap analyze`). No upfront context loading needed.
</context>
<process>
Execute the autonomous workflow from @~/.claude/get-shit-done/workflows/autonomous.md end-to-end.
description: Review deferred issues with codebase context, close resolved ones, identify urgent ones
allowed-tools:
- Read
- Bash
- Grep
- Glob
- Edit
- AskUserQuestion
- SlashCommand
---
<objective>
Review all open issues from ISSUES.md with current codebase context. Identify which issues are resolved (can close), which are now urgent (should address), and which can continue waiting.
This prevents issue pile-up by providing a triage mechanism with codebase awareness.
</objective>
<context>
@.planning/ISSUES.md
@.planning/STATE.md
@.planning/ROADMAP.md
</context>
<process>
<step name="verify">
**Verify issues file exists:**
If no `.planning/ISSUES.md`:
```
No issues file found.
This means no enhancements have been deferred yet (Rule 5 hasn't triggered).
Nothing to review.
```
Exit.
If ISSUES.md exists but has no open issues (only template or empty "Open Enhancements"):
```
No open issues to review.
All clear - continue with current work.
```
Exit.
</step>
<step name="parse">
**Parse all open issues:**
Extract from "## Open Enhancements" section:
- ISS number (ISS-001, ISS-002, etc.)
- Brief description
- Discovered phase/date
- Type (Performance/Refactoring/UX/Testing/Documentation/Accessibility)
- Description details
- Effort estimate
Build list of issues to analyze.
</step>
<step name="analyze">
**For each open issue, perform codebase analysis:**
1.**Check if still relevant:**
- Search codebase for related code/files mentioned in issue
- If code no longer exists or was significantly refactored: likely resolved
2.**Check if accidentally resolved:**
- Look for commits/changes that may have addressed this
- Check if the enhancement was implemented as part of other work
3.**Assess current urgency:**
- Is this blocking upcoming phases?
- Has this become a pain point mentioned in recent summaries?
- Is this now affecting code we're actively working on?
4.**Check natural fit:**
- Does this align with an upcoming phase in the roadmap?
- Would addressing it now touch the same files as current work?
**Categorize each issue:**
- **Resolved** - Can be closed (code changed, no longer applicable)
- **Urgent** - Should address before continuing (blocking or causing problems)
- **Natural fit** - Good candidate for upcoming phase X
- **Can wait** - Keep deferred, no change in status
**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
</objective>
<context>
User's issue: $ARGUMENTS
Check for active sessions:
```bash
ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
```
</context>
<process>
## 0. Initialize Context
```bash
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
description: Gather context for next milestone through adaptive questioning
---
<objective>
Help you figure out what to build in the next milestone through collaborative thinking.
Purpose: After completing a milestone, explore what features you want to add, improve, or fix. Features first — scope and phases derive from what you want to build.
Output: Context gathered, then routes to /gsd:new-milestone
description: Gather phase context through adaptive questioning before planning
argument-hint: "[phase]"
description: Gather phase context through adaptive questioning before planning. Use --auto to skip interactive questions (Claude picks recommended defaults).
Help the user articulate their vision for a phase through collaborative thinking.
Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
Purpose: Understand HOW the user imagines this phase working — what it looks like, what's essential, what's out of scope. You're a thinking partner helping them crystallize their vision, not an interviewer gathering technical requirements.
description: Route freeform text to the right GSD command automatically
argument-hint: "<description of what you want to do>"
allowed-tools:
- Read
- Bash
- AskUserQuestion
---
<objective>
Analyze freeform natural language input and dispatch to the most appropriate GSD command.
Acts as a smart dispatcher — never does the work itself. Matches intent to the best GSD command using routing rules, confirms the match, then hands off.
Use when you know what you want but don't know which `/gsd:*` command to run.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/do.md
@~/.claude/get-shit-done/references/ui-brand.md
</execution_context>
<context>
$ARGUMENTS
</context>
<process>
Execute the do workflow from @~/.claude/get-shit-done/workflows/do.md end-to-end.
Route user intent to the best GSD command and invoke it.
Execute all unexecuted plans in a phase with parallel agent spawning.
Execute all plans in a phase using wave-based parallel execution.
Analyzes plan dependencies to identify independent plans that can run concurrently.
Spawns background agents for parallel execution, each agent commits its own tasks atomically.
Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
**Critical constraint:** One subagent per plan, always. This is for context isolation, not parallelization. Even strictly sequential plans spawn separate subagents so each starts with fresh 200k context at 0%.
Use this command when:
- Phase has 2+ unexecuted plans
- Want "walk away, come back to completed work" execution
- Plans have clear dependency boundaries
Context budget: ~15% orchestrator, 100% fresh per subagent.
-`--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
-`--interactive` — Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style. Best for small phases, bug fixes, and verification gaps.
Context files are resolved inside the workflow via `gsd-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
</context>
<process>
1. Validate phase exists in roadmap
2. Find all PLAN.md files without matching SUMMARY.md
3. If 0 or 1 plans: suggest /gsd:execute-plan instead
4. If 2+ plans: follow execute-phase.md workflow
5. Monitor parallel agents until completion
6. Present results and next steps
Execute the execute-phase workflow from @~/.claude/get-shit-done/workflows/execute-phase.md end-to-end.
Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).
description: Analyze codebase with parallel Explore agents to produce .planning/codebase/ documents
description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
allowed-tools:
- Read
@@ -12,22 +12,15 @@ allowed-tools:
---
<objective>
Analyze existing codebase using parallel Explore agents to produce structured codebase documents.
Analyze existing codebase using parallel gsd-codebase-mapper agents to produce structured codebase documents.
This command spawns multiple Explore agents to analyze different aspects of the codebase in parallel, each with fresh context.
Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
Create a new milestone for an existing project with defined phases.
Start a new milestone: questioning → research (optional) → requirements → roadmap.
Purpose: After completing a milestone (or when ready to define next chunk of work), creates the milestone structure in ROADMAP.md with phases, updates STATE.md, and creates phase directories.
Output: New milestone in ROADMAP.md, updated STATE.md, phase directories created
Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Gathers "what's next", updates PROJECT.md, then runs requirements → roadmap cycle.
**Creates/Updates:**
-`.planning/PROJECT.md` — updated with new milestone goals
-`.planning/research/` — domain research (optional, NEW features only)
-`.planning/REQUIREMENTS.md` — scoped requirements for this milestone
Milestone name: $ARGUMENTS (optional - will prompt if not provided)
**Load project state first:**
@.planning/STATE.md
**Load roadmap:**
@.planning/ROADMAP.md
**Load milestones (if exists):**
@.planning/MILESTONES.md
Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<files_to_read>` blocks where subagents are used.
description: Initialize a new project with deep context gathering and PROJECT.md
argument-hint: "[--auto]"
allowed-tools:
- Read
- Bash
- Write
- Task
- AskUserQuestion
---
<context>
**Flags:**
-`--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.
</context>
<objective>
Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.
Initialize a new project through comprehensive context gathering.
This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes.
Creates`.planning/` with PROJECT.md and config.json.
**Creates:**
-`.planning/PROJECT.md` — project context
-`.planning/config.json` — workflow preferences
-`.planning/research/` — domain research (optional)
**Depth controls compression tolerance, not artificial inflation.** All depths use 2-3 tasks per plan. Comprehensive means "don't compress complex work"—it doesn't mean "pad simple work to hit a number."
- "Enabled" — Run independent plans in parallel (experimental, may not yield best results)
**Parallelization is experimental.** When enabled, `/gsd:execute-phase` spawns multiple agents for independent plans. Still being refined—sequential execution is more reliable. Can be changed later in config.json.
</step>
<step name="config">
Create `.planning/config.json` with chosen mode, depth, and parallelization using `templates/config.json` structure.
Create executable phase prompt with discovery, context injection, and task breakdown.
Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.
Purpose: Break down roadmap phases into concrete, executable PLAN.md files that Claude can execute.
Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-name/{phase}-{plan}-PLAN.md)
**Default flow:** Research (if needed) → Plan → Verify → Done
**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn gsd-planner, verify with gsd-plan-checker, iterate until pass or max iterations, present results.
Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided)
Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
**Load project state first:**
@.planning/STATE.md
**Flags:**
-`--research` — Force re-research even if RESEARCH.md exists
-`--skip-research` — Skip research, go straight to planning
-`--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
-`--skip-verify` — Skip verification loop
-`--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
**Load roadmap:**
@.planning/ROADMAP.md
**Load phase context if exists (created by /gsd:discuss-phase):**
Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains research findings, clarifications, and decisions from phase discussion.
**Load codebase context if exists:**
Check for `.planning/codebase/` and load relevant documents based on phase type.
Normalize phase input in step 2 before any directory lookups.
</context>
<process>
1. Check .planning/ directory exists (error if not - user should run /gsd:new-project)
2. If phase number provided via $ARGUMENTS, validate it exists in roadmap
3. If no phase number, detect next unplanned phase from roadmap
4. Follow plan-phase.md workflow:
- Load project state and accumulated decisions
- Perform mandatory discovery (Level 0-3 as appropriate)
- Read project history (prior decisions, issues, concerns)
- Break phase into tasks
- Estimate scope and split into multiple plans if needed
- Create PLAN.md file(s) with executable structure
Execute the plan-phase workflow from @~/.claude/get-shit-done/workflows/plan-phase.md end-to-end.
Preserve all workflow gates (validation, research, planning, verification loop, routing).
</process>
<success_criteria>
- One or more PLAN.md files created in .planning/phases/XX-name/
- Each plan has: objective, execution_context, context, tasks, verification, success_criteria, output
- Tasks are specific enough for Claude to execute
- User knows next steps (execute plan or review/adjust)
description: Generate developer behavioral profile and create Claude-discoverable artifacts
argument-hint: "[--questionnaire] [--refresh]"
allowed-tools:
- Read
- Write
- Bash
- Glob
- Grep
- AskUserQuestion
- Task
---
<objective>
Generate a developer behavioral profile from session analysis (or questionnaire) and produce artifacts (USER-PROFILE.md, /gsd:dev-preferences, CLAUDE.md section) that personalize Claude's responses.
Routes to the profile-user workflow which orchestrates the full flow: consent gate, session analysis or questionnaire fallback, profile generation, result display, and artifact selection.
Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
Provides situational awareness before continuing work.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/progress.md
</execution_context>
<process>
<step name="verify">
**Verify planning structure exists:**
If no `.planning/` directory:
```
No planning structure found.
Run /gsd:new-project to start a new project.
```
Exit.
If missing STATE.md or ROADMAP.md: inform what's missing, suggest running `/gsd:new-project`.
</step>
<step name="load">
**Load full project context:**
- Read `.planning/STATE.md` for living memory (position, decisions, issues)
- Read `.planning/ROADMAP.md` for phase structure and objectives
- Read `.planning/PROJECT.md` for current state (What This Is, Core Value, Requirements)
</step>
<step name="recent">
**Gather recent work context:**
- Find the 2-3 most recent SUMMARY.md files
- Extract from each: what was accomplished, key decisions, any issues logged
- This shows "what we've been working on"
</step>
<step name="position">
**Parse current position:**
- From STATE.md: current phase, plan number, status
- Calculate: total plans, completed plans, remaining plans
- Note any blockers, concerns, or deferred issues
- Check for CONTEXT.md: For phases without PLAN.md files, check if `{phase}-CONTEXT.md` exists in phase directory
**Default:** Skips research, discussion, plan-checker, verifier. Use when you know exactly what to do.
**`--discuss` flag:** Lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md. Use when the task has ambiguity worth resolving upfront.
**`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony.
**`--research` flag:** Spawns a focused research agent before planning. Investigates implementation approaches, library options, and pitfalls for the task. Use when you're unsure of the best approach.
Flags are composable: `--discuss --research --full` gives discussion + research + plan-checking + verification.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/quick.md
</execution_context>
<context>
$ARGUMENTS
Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
</context>
<process>
Execute the quick workflow from @~/.claude/get-shit-done/workflows/quick.md end-to-end.
Preserve all workflow gates (validation, task description, planning, execution, state updates, commits).
After a GSD update wipes and reinstalls files, this command merges user's previously saved local modifications back into the new version. Uses intelligent comparison to handle cases where the upstream file also changed.
</purpose>
<process>
## Step 1: Detect backed-up patches
Check for local patches directory:
```bash
# Global install — detect runtime config directory
**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.
description: Resume an interrupted subagent execution
argument-hint: "[agent-id]"
allowed-tools:
- Read
- Write
- Edit
- Bash
- Task
- AskUserQuestion
---
<objective>
Resume an interrupted subagent execution using the Task tool's resume parameter.
When a session ends mid-execution, subagents may be left in an incomplete state. This command allows users to continue that work without starting over.
Uses the agent ID tracking infrastructure from execute-plan to identify and resume agents.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/resume-task.md
</execution_context>
<context>
Agent ID: $ARGUMENTS (optional - defaults to most recent)
**Load project state:**
@.planning/STATE.md
**Load agent tracking:**
@.planning/current-agent-id.txt
@.planning/agent-history.json
</context>
<process>
1. Check .planning/ directory exists (error if not)
2. Parse agent ID from arguments or current-agent-id.txt
3. Validate agent exists in history and is resumable
4. Check for file conflicts since spawn
5. Follow resume-task.md workflow:
- Update agent status to "interrupted"
- Resume via Task tool resume parameter
- Update history on completion
- Clear current-agent-id.txt
</process>
<usage>
**Resume most recent interrupted agent:**
```
/gsd:resume-task
```
**Resume specific agent by ID:**
```
/gsd:resume-task agent_01HXYZ123
```
**Find available agents to resume:**
Check `.planning/agent-history.json` for entries with status "spawned" or "interrupted".
</usage>
<error_handling>
**No agent to resume:**
- current-agent-id.txt empty or missing
- Solution: Run /gsd:progress to check project status
**Agent already completed:**
- Agent finished successfully, nothing to resume
- Solution: Continue with next plan
**Agent not found:**
- Provided ID not in history
- Solution: Check agent-history.json for valid IDs
**Resume failed:**
- Agent context expired or invalidated
- Solution: Start fresh with /gsd:execute-plan
</error_handling>
<success_criteria>
- [ ] Agent resumed via Task tool resume parameter
description: Generate a session report with token usage estimates, work summary, and outcomes
allowed-tools:
- Read
- Bash
- Write
---
<objective>
Generate a structured SESSION_REPORT.md document capturing session outcomes, work performed, and estimated resource usage. Provides a shareable artifact for post-session review.
description: Create PR, run review, and prepare for merge after verification passes
argument-hint: "[phase number or milestone, e.g., '4' or 'v1.0']"
allowed-tools:
- Read
- Bash
- Grep
- Glob
- Write
- AskUserQuestion
---
<objective>
Bridge local completion → merged PR. After /gsd:verify-work passes, ship the work: push branch, create PR with auto-generated body, optionally trigger review, and track the merge.
Closes the plan → execute → verify → ship loop.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/ship.md
</execution_context>
Execute the ship workflow from @~/.claude/get-shit-done/workflows/ship.md end-to-end.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
