Auto-discover project skills from .claude/skills/, .agents/skills/,
.cursor/skills/, and .github/skills/ directories and surface them in
CLAUDE.md as a managed section with name, description, and path.
This enables Layer 1 (discovery) at session startup — agents now know
which project-specific skills are available without waiting for
subagent injection via agent-skills at execution time.
Behavior:
- Scans standard skill directories for subdirectories containing SKILL.md
- Extracts name and description from YAML frontmatter
- Supports multi-line descriptions (indented continuation lines)
- Skips GSD's own gsd-* prefixed skill directories
- Deduplicates by skill name across directories
- Falls back to actionable guidance when no skills found
- Section is placed between Architecture and Workflow Enforcement
- sections_total bumped from 5 to 6
Update documentation in all supported languages to include CodeRabbit as
an available reviewer for the `/gsd:review` command. Adjust command
examples and descriptions to reflect this addition.
Update the `/gsd:review` workflow documentation to include CodeRabbit as
a supported AI reviewer. Clarify that CodeRabbit reviews the current git
diff and may take up to 5 minutes. Update CLI detection and review
process descriptions accordingly.
--full now enables discussion + research + plan-checking + verification.
New --validate flag covers what --full previously did (plan-checking +
verification only). All downstream workflow logic uses $VALIDATE_MODE.
Closes#1498
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When running in --auto or headless mode, the discuss step could loop
indefinitely — each pass reads its own CONTEXT.md, finds "gaps" in
referenced types/interfaces, creates new decisions to fill them, and
repeats. Observed: 34 passes, 167 decisions, 7 hours, zero code written.
Fixes:
- Add max_discuss_passes config (default: 3) to WorkflowConfig
- Add single-pass guard instruction to SDK self-discuss prompt
- Add pass cap documentation to CLI discuss-phase workflow
- Add pass guard step to SDK headless discuss-phase prompt
- Add stall detection note to autonomous workflow
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Executor constraints now prohibit committing docs artifacts (SUMMARY.md,
STATE.md, PLAN.md) — these are the orchestrator's responsibility in
Step 8. Step 8 now explicitly stages all artifacts with git add before
calling gsd-tools commit, and documents that it must always run even if
the executor already committed some files.
This prevents PLAN.md from being left untracked when the executor runs
without worktree isolation (e.g. local repos with no remote, or when
workflow.use_worktrees is false).
Closes#1503
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Executor agents spawned with isolation="worktree" committed to temporary
branches in separate working trees, but no step existed to merge those
changes back or clean up. This left orphan worktrees and unmerged
branches after every execution.
Changes:
- execute-phase.md: add step 4.5 "Worktree cleanup" after wave
completion — merges worktree branch, removes worktree, deletes temp
branch. Handles merge conflicts gracefully.
- quick.md: add worktree cleanup step after executor returns, before
summary verification
- Both workflows skip cleanup when workflow.use_worktrees is false
- Both workflows skip silently when no worktrees are found
Closes#1496
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When discuss-phase is interrupted mid-session (usage limit, crash,
network drop), all user answers were lost — the workflow only wrote
CONTEXT.md and DISCUSSION-LOG.md at the very end. Users had to redo
entire discussion sessions from scratch.
Changes:
- Write DISCUSS-CHECKPOINT.json after each grey area completes,
capturing all decisions, completed/remaining areas, deferred ideas,
and canonical refs
- check_existing step now detects checkpoint files and offers "Resume"
or "Start fresh" — skips already-completed areas on resume
- Checkpoint cleaned up after successful CONTEXT.md write
- Works in both interactive and --auto modes
Closes#1485
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When settings.json contains comments (// or /* */), which many CLI tools
allow, JSON.parse() fails and readSettings() silently returned {}.
This empty object was then written back by writeSettings(), destroying
the user's entire configuration.
Changes:
- Add stripJsonComments() that handles line comments, block comments,
trailing commas, and preserves comments inside string values
- readSettings() tries standard JSON first (fast path), falls back to
JSONC stripping on parse failure
- On truly malformed files (even JSONC stripping fails), return null
with a warning instead of silently returning {} — prevents data loss
- All callers of readSettings() now guard against null return to skip
settings modification rather than overwriting with empty object
Closes#1461
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When phases have many user decisions, the planner sometimes silently
simplifies them (e.g., "D-26: calculated costs" becomes "static labels v1")
instead of delivering what the user decided. This causes downstream
execution to build the wrong thing.
Three changes prevent this:
1. **gsd-planner.md** — `<scope_reduction_prohibition>` section:
- Prohibits language like "v1", "static for now", "future enhancement"
- Requires decision coverage matrix mapping every D-XX to a task
- When phase is too complex: return PHASE SPLIT RECOMMENDED instead
of simplifying decisions
2. **gsd-plan-checker.md** — Dimension 7b: Scope Reduction Detection:
- Scans task actions for scope reduction patterns
- Cross-references with CONTEXT.md to verify full delivery
- Always BLOCKER severity (never warning)
- Includes real-world example from production incident
3. **plan-phase.md** — Step 9b: Handle Phase Split:
- New flow when planner returns PHASE SPLIT RECOMMENDED
- Three options: Split / Proceed anyway / Prioritize
- User decides which decisions are "now" vs "later"
Root cause: planner's instinct when facing complexity is to simplify
individual requirements. Correct behavior is to split the phase so
every decision is implemented at full fidelity.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds project-scoped planning directory resolution via GSD_PROJECT
environment variable. When set, planningDir() routes to
.planning/{project}/ instead of .planning/, enabling multiple
independent projects to coexist under a single .planning/ root.
Use case: shared workspaces (e.g., Obsidian vaults, monorepo knowledge
bases) where multiple projects are managed from one directory. Each
project keeps its own config.json, ROADMAP.md, STATE.md, and phases/
under .planning/{project-name}/.
GSD_PROJECT follows the same pattern as GSD_WORKSTREAM and can be
combined with it: .planning/{project}/workstreams/{ws}/
Also updates loadConfig() to read config.json from the project-scoped
directory when GSD_PROJECT is active.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add comprehensive test coverage for the workflow.use_worktrees config toggle:
- config-get returns false after setting to false (roundtrip verification)
- config-get errors with "Key not found" when not set (validates workflow
fallback behavior where `|| echo "true"` provides the default)
- config-get returns true after setting to true
- Toggle back and forth works correctly
- Structural tests verify USE_WORKTREES is wired into quick.md,
diagnose-issues.md, execute-plan.md, planning-config.md, and config.cjs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Verify that gsd-check-update.js writes to the shared ~/.cache/gsd/
directory and that gsd-statusline.js checks the shared cache first
with legacy fallback. These structural tests guard against regression
of the multi-runtime cache mismatch fix.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Phases with all summaries but no passing VERIFICATION.md now show as
"Executed" instead of "Complete", preventing false progress reporting.
Adds determinePhaseStatus() helper used by both cmdStats() and
cmdProgressRender(). Also fixes duplicate phase directory accumulation
in cmdStats() — plans/summaries from directories sharing the same
phase number are now summed instead of silently overwritten.
New statuses: Executed (summaries done, no verification), Needs Review
(verification exists with human_needed status).
Closes#1459
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The reapply-patches workflow used a two-way comparison (user's backup vs
new version) which couldn't distinguish user customizations from version
drift. This caused 10/10 files to be misclassified as "no custom content"
in real-world usage, silently discarding user modifications.
Changes:
- Rewrite workflow with three-way merge strategy (pristine baseline vs
user-modified backup vs newly installed version)
- Add critical invariant: files in gsd-local-patches/ must NEVER be
classified as "no custom content" — they were backed up because the
installer's hash check detected modifications
- Add git-aware detection path using commit history when config dir is
a git repo
- Add pristine_hashes to backup-meta.json so the reapply workflow can
verify reconstructed baseline files
- Add from_manifest_timestamp to backup-meta.json for version tracking
- Conservative default: flag as CONFLICT when uncertain, not SKIP
Closes#1469
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Address review findings from #1454:
1. runVerifyStep now returns success:false when gaps persist after
exhausting retries (was always returning success:true)
2. human_needed + callback accept correctly sets outcome to passed
3. retryOnce skips retry for verification outcomes (gaps_found,
human_needed) which have their own internal retry logic
4. Updated 3 existing tests to expect success:false on exhausted gaps
5. Added 3 regression tests:
- persistent gaps_found does NOT append Advance step
- persistent gaps_found does NOT call phaseComplete
- verifier disabled still advances normally
Adds `workflow.use_worktrees` config option (default: `true`) that
allows users to disable git worktree isolation for executor agents.
When set to `false`:
- Executor agents run without `isolation="worktree"`
- Plans execute sequentially on the main working tree
- No worktree merge ordering issues or orphaned worktrees
- Normal git hooks run (no --no-verify needed)
This provides an escape hatch for solo developers and users who
experience worktree merge conflicts, as worktree ordering issues
are inherently difficult when parallel agents modify overlapping
files.
Usage:
/gsd:settings → set workflow.use_worktrees to false
Or directly:
gsd-tools config-set workflow.use_worktrees false
Changes:
- config.cjs: add workflow.use_worktrees to valid keys
- planning-config.md: document the option
- execute-phase.md: read config, conditional worktree + sequential mode
- execute-plan.md: conditional worktree in Pattern A
- quick.md: conditional worktree for quick executor
- diagnose-issues.md: conditional worktree for debug agents
- 2 new tests (config set + workflow structural check)
Closes#1451
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Background agents for plan/execute now call Skill(gsd:plan-phase) and
Skill(gsd:execute-phase) instead of reimplementing the workflow steps
inline. This ensures local patches, quality gates, and proper branching
are respected. Also removes --no-verify anti-pattern and specifies
exact Skill names in error handler fallbacks.
Fixes#1453
Previously, the advance step ran unconditionally after verify,
marking phases as complete in ROADMAP.md even when gaps_found.
This caused subsequent auto runs to skip unfinished phases.
Now checks if all verify steps passed before advancing. When
verification fails, the phase remains incomplete so the next
auto run re-attempts it.
cmdPhaseComplete updated Status and Completed columns in the progress
table but skipped the Plans Complete column and plan-level checkboxes.
If update-plan-progress was missed for any plan, the phase completion
safety net didn't catch it, leaving ROADMAP.md inconsistent.
Fixes#1446
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds --only N flag to /gsd:autonomous that restricts execution to a
single phase, enabling safe parallel execution across terminals:
Terminal 1: /gsd:autonomous --only 16
Terminal 2: /gsd:autonomous --only 17
Terminal 3: /gsd:autonomous --only 18
Changes:
- Step 1: Parse --only N alongside --from N (also sets FROM_PHASE)
- Step 2: Filter phase list to exact match when --only active
- Step 4: Skip iteration — single phase does not loop
- Step 5: Skip lifecycle — audit/complete/cleanup only for full runs
- Step 6: Resume message uses --only when active
- Success criteria updated with --only N requirements
Parallel safety: each phase operates in its own .planning/phases/NN-*
directory. ROADMAP.md and STATE.md are read-only during phase execution.
Closes#1383
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The next.md workflow Route 5 referenced `/gsd:complete-phase` which
doesn't exist — only `/gsd:complete-milestone` does. After verify-work
completes for a phase, Route 6 handles advancement to the next phase
automatically, so the dangling reference is simply removed.
Closes#1441
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The CLI (commands.cjs, init.cjs) uses `todos/completed/` but three
workflow files and three FEATURES.md docs referenced `todos/done/`.
This caused completed todos to land in different directories depending
on whether the CLI command or the workflow instructions were followed.
Closes#1438
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Research agents must now tag every factual claim with its source:
[VERIFIED], [CITED], or [ASSUMED]. An Assumptions Log section in
RESEARCH.md collects all [ASSUMED] claims so downstream agents and
users can identify decisions that need confirmation before execution.
Prevents unvalidated assumptions (e.g. "audit logs should be permanent")
from propagating unchallenged through research → planning → execution.
Closes#1431
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
convertClaudeToCodexMarkdown() was missing path replacement — unlike
Copilot/Gemini/Antigravity converters which all replace $HOME/.claude/
paths. This left hardcoded .claude references in Codex agent files,
causing ENOENT when gsd-tools.cjs tried to load from ~/.claude/ on
Codex installations.
Closes#1430
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The verifier's Step 2 previously used Option A (PLAN frontmatter
must_haves) exclusively when present, skipping Option B (ROADMAP SCs).
This allowed planners to define a subset of must_haves, silently
bypassing roadmap Success Criteria verification.
Now ROADMAP SCs are always loaded first (Step 2a), PLAN must_haves
are merged on top (Step 2b), and a merge step (Step 2c) ensures
plan-authored must_haves can add but never subtract from the roadmap
contract.
Addresses #1418 (Gap 2)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The verifier agent could set status: passed even when the report contained
a non-empty "Human Verification Required" section. This bypassed the
human_needed → HUMAN-UAT.md → user approval gate, allowing phases to be
marked complete without human testing.
Replace the advisory status descriptions with an ordered decision tree
(most restrictive first): gaps_found → human_needed → passed. The passed
status is now only valid when zero human verification items exist.
Synced the same decision tree in the verify-phase workflow.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two fixes for multi-runtime installations:
1. Update cache now writes to ~/.cache/gsd/ instead of the runtime-
specific config dir, preventing mismatches when check-update and
statusline resolve to different runtimes. Statusline reads from
shared path first with legacy fallback.
2. Stale hooks detection now checks configDir/hooks/ where hooks are
actually installed, not configDir/get-shit-done/hooks/ which does
not exist.
Closes#1421
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Probe <projectDir>/.claude/get-shit-done/bin/gsd-tools.cjs before falling back
to ~/.claude/get-shit-done/bin/gsd-tools.cjs, fixing MODULE_NOT_FOUND for
repo-local GSD installations. Also adds repo-local agent definition path.
Closes#1424
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
gsd-tools detects plan files by matching the glob `*-PLAN.md`
(e.g. 01-01-PLAN.md). When the planner generates files using a
different convention — wave-based names, wrong prefix order, or
lowercase — the tool returns plan_count: 0 and execution cannot
proceed.
Root cause: the write_phase_prompt step only said
"Write to .../XX-name/{phase}-{NN}-PLAN.md" — ambiguous enough
for the agent to produce PLAN-01-auth.md, 01-PLAN-01.md, etc.
Observed across real usage (306 sessions analyzed):
- Phases 2, 3, 4: plan files used wave-based names instead of the
numeric format gsd-tools expects; required manual detection and
adaptation before execution could proceed each time
- gsd-tools roadmap get-phase failed on Phase 3 due to format
mismatch; Claude fell back to parsing ROADMAP.md manually
- Naming mismatch caused friction in at least 4 separate sessions,
each requiring a manual workaround
Fix: add a CRITICAL naming block in write_phase_prompt with the
exact required pattern, component definitions, correct/incorrect
examples, and explicit ❌ markers for variants that break detection.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add installSdk() and promptSdk() to the installer so users can
optionally install @gsd-build/sdk during GSD setup. The --sdk flag
installs without prompting; interactive installs get a Y/N prompt
after runtime installation completes. SDK installs use @latest with
suppressed npm noise (--force --no-fund --loglevel=error, stdio: pipe).
Cherry-picked from fix/sdk-cli-runtime-bugs (de9f18f) which was
left out of #1407.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The phase-extraction regex /(\d+)-/ only matched the last integer
segment before a dash, so decimal phases like 45.14 were misresolved
to phase 14 — silently switching to the wrong branch.
Closes#1402
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When project_code is set (e.g., "CK"), phase directories are prefixed
with the code: CK-01-foundation, CK-02-api, etc. This disambiguates
phases across multiple GSD projects in the same session.
Changes:
- Add project_code to VALID_CONFIG_KEYS and buildNewProjectConfig defaults
- Add project_code to loadConfig in core.cjs
- Prepend prefix in cmdPhaseAdd and cmdPhaseInsert
- Update searchPhaseInDir, cmdFindPhase, comparePhaseNum, and
normalizePhaseName to strip prefix before matching/sorting
- Support {project} placeholder in git.phase_branch_template
- Add 4 tests covering prefixed add, null code, find, and sort
Closes#1019
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
get-shit-done/commands/gsd/workstreams.md was identical to
commands/gsd/workstreams.md, causing Claude Code to register
every gsd:* command twice as gsd:gsd:* when scanning plugin
directories.
Fixesgsd-build/get-shit-done#1389
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
add-backlog and thread commands called generate-slug without --raw,
capturing JSON output (with newlines) as the directory name. Also
cap slugs at 60 chars to prevent absurdly long directory names.
Fixesgsd-build/get-shit-done#1391
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Node v25 preserves trailing slashes in path.join, causing
writeFileSync to fail with ENOENT when the converted path
ends in '/'. Affects all Windsurf users on Node v25+.
Fixesgsd-build/get-shit-done#1392
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- gsd-security-auditor.md: replace <threat_register> with <threat_model>
(stale tag name inconsistent with every other file in the PR)
- verify-work.md: parse threats_open from SECURITY.md frontmatter when
file exists; block if > 0, matching execute-phase.md gate logic
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The autonomous workflow ran discuss -> plan -> execute per phase but
skipped ui-phase (design contract) and ui-review (visual audit) for
frontend phases. This adds two conditional steps that match the UI
detection logic already in plan-phase step 5.6:
- Step 3a.5: generates UI-SPEC before planning if frontend indicators
are detected and no UI-SPEC exists
- Step 3d.5: runs advisory UI review after successful execution if a
UI-SPEC is present
Both steps respect workflow.ui_phase and workflow.ui_review config
toggles and skip silently for non-frontend phases.
Fixes#1375
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
