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>
Document resolve_model_ids: "omit" (set automatically by installer for
non-Claude runtimes), explain model_overrides with non-Claude model IDs,
and add a decision table for choosing between inherit, omit, and
overrides. Updates CONFIGURATION.md, USER-GUIDE.md, and the
model-profiles.md skill reference.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Enable multiple Claude Code instances to work on the same codebase
simultaneously by scoping .planning/ state into workstreams.
Core changes:
- planningDir(cwd, ws?) and planningPaths(cwd, ws?) are now workstream-aware
via GSD_WORKSTREAM env var (auto-detected from --ws flag or active-workstream file)
- All bin/lib modules use planningDir(cwd) for scoped paths (STATE.md, ROADMAP.md,
phases/, REQUIREMENTS.md) and planningRoot(cwd) for shared paths (milestones/,
PROJECT.md, config.json, codebase/)
- New workstream.cjs module: create, list, status, complete, set, get, progress
- gsd-tools.cjs: --ws flag parsing with priority chain
(--ws > GSD_WORKSTREAM env > active-workstream file > flat mode)
- Collision detection: transition.md checks for other active workstreams before
suggesting next-milestone continuation (prevents WS A from trampling WS B)
- ${GSD_WS} routing propagation across all 9 workflow files ensures workstream
scope chains automatically through the workflow lifecycle
New files:
- get-shit-done/bin/lib/workstream.cjs (CRUD + collision detection)
- get-shit-done/commands/gsd/workstreams.md (slash command)
- get-shit-done/references/workstream-flag.md (documentation)
- tests/workstream.test.cjs (20 tests covering CRUD, env var routing, --ws flag)
All 1062 tests passing (1042 existing + 20 new workstream tests).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add --pick flag to gsd-tools.cjs for extracting a single field from
JSON output, replacing all jq pipe usage across workflow and reference
files. Since Node.js is already a hard dependency, this eliminates the
need for jq on systems where it is not installed (notably Windows).
Changes:
- gsd-tools.cjs: add --pick <field> global flag with dot-notation and
bracket syntax support (e.g., --pick section, --pick directories[-1])
- Replace 15 jq pipe patterns across 6 workflow/reference files with
--pick flag or inline Node.js one-liner for variable extraction
- Add regression tests for --pick flag behavior
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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>
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>
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)
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
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>
* 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>
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 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>
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>
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>
- 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>
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>
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>
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>
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>
* 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>
- 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 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
* 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>
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>
* 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>
/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>
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>
- 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>
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>
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>
