- Extend cmdStatePrune to prune Performance Metrics table rows older than cutoff
- Add workflow.auto_prune_state config key (default: false)
- Call cmdStatePrune automatically in cmdPhaseComplete when enabled
- Document workflow.auto_prune_state in planning-config.md reference
- Add silent option to cmdStatePrune for programmatic use without stdout
Closes#2087
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Plans with 1-2 tasks now execute inline (Pattern C) instead of spawning
a subagent (Pattern A). This avoids ~14K token subagent spawn overhead
and preserves the orchestrator's prompt cache for small plans.
The threshold is configurable via workflow.inline_plan_threshold
(default: 2). Set to 0 to always spawn subagents. Plans above the
threshold continue to use checkpoint-based routing as before.
Closes#1979
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
`intel.enabled` is the documented opt-in for the intel subsystem
(see commands/gsd/intel.md and docs/CONFIGURATION.md), but it was
missing from VALID_CONFIG_KEYS in config.cjs, so the canonical
command failed:
$ gsd-tools config-set intel.enabled true
Error: Unknown config key: "intel.enabled"
Add the key to the whitelist, document it under a new "Intel Fields"
section in planning-config.md alongside the other namespaced fields,
and cover it with a config-set test.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(review): add per-CLI model selection via config
- Add review.models.<cli> dynamic config keys to VALID_CONFIG_KEYS
- Update review.md to read model preferences via config-get at runtime
- Null/missing values fall back to CLI defaults (backward compatible)
- Add key suggestion for common typo (review.model)
- Update planning-config reference doc
Closes#1849
* fix(review): handle absent and null model config gracefully
Address PR #1859 review feedback from @trek-e:
1. Add `|| true` to all four config-get subshell invocations in
review.md so that an absent review.models.<cli> key does not
produce a non-zero exit from the subshell. cmdConfigGet calls
error() (process.exit(1)) when the key path is missing; the
2>/dev/null suppresses the message but the exit code was still
discarded silently. The || true makes the fall-through explicit
and survives future set -e adoption.
2. Add `&& [ "$VAR" != "null" ]` to all four if guards. cmdConfigSet
does not parse the literal 'null' as JSON null — it stores the
string 'null' — and cmdConfigGet --raw returns the literal text
'null' for that value. Without the extra guard the workflow would
pass `-m "null"` to the CLI, which crashes. The issue spec
documents null as the "fall back to CLI default" sentinel, so this
restores the contract.
3. Add tests/review-model-config.test.cjs covering all five cases
trek-e listed:
- isValidConfigKey accepts review.models.gemini (via config-set)
- isValidConfigKey accepts review.models.codex (via config-set)
- review.model is rejected and suggests review.models.<cli-name>
- config-set then config-get round-trip with a model ID
- config-set then config-get round-trip with null (returns "null")
Tests follow the node:test + node:assert/strict pattern from
tests/agent-skills.test.cjs and use runGsdTools from helpers.cjs.
Closes#1849
* fix(core): resolve @file: references in gsd-tools stdout (#1891)
Workflows used bash-specific `if [[ "$INIT" == @file:* ]]` to detect
when large JSON was written to a temp file. This syntax breaks on
PowerShell and other non-bash shells.
Intercept stdout in gsd-tools.cjs to transparently resolve @file:
references before they reach the caller, matching the existing --pick
path behavior. The bash checks in workflow files become harmless
no-ops and can be removed over time.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(config): add missing config fields to planning-config.md (#1880)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Tibsfox <tibsfox@tibsfox.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix mode: "code-first"/"plan-first"/"hybrid" → "interactive"/"yolo"
(verified against templates/config.json and workflows/new-project.md)
- Fix discuss_mode: "auto"/"analyze" → "assumptions"
(verified against workflows/settings.md line 188)
- Add regression tests asserting correct values and rejecting stale ones
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(references): extend planning-config.md with complete field reference
Add a comprehensive field table generated from CONFIG_DEFAULTS and
VALID_CONFIG_KEYS covering all config.json fields with types, defaults,
allowed values, and descriptions. Includes field interaction notes
(auto-detection, threshold triggers) and three copy-pasteable example
configurations for common setups.
Closes#1741
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(docs): add missing sub_repos and model_overrides to config reference (#1741)
- Add sub_repos field to planning-config.md field table
- Add model_overrides field to planning-config.md field table
- Fix test namespace map to cover both missing fields
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(docs): add thinking_partner field and plan_checker alias note (#1741)
- Add features.thinking_partner to config reference documentation
- Document plan_checker as flat-key alias of workflow.plan_check
- Move file reads from describe scope into before() hooks
- Add test coverage for thinking_partner field
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* test: add stale /gsd: colon reference regression guard
Fixes#1748
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: replace 39 stale /gsd: colon references with /gsd- hyphen format
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat(i18n): add response_language config for cross-phase language consistency
Adds `response_language` config key that propagates through all init
outputs via withProjectRoot(). Workflows read this field and instruct
agents to present user-facing questions in the configured language,
solving the problem of language preference resetting at phase boundaries.
Usage: gsd-tools config-set response_language "Portuguese"
Closes#1399
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test(security): allowlist discuss-phase.md for size threshold
discuss-phase.md legitimately exceeds 50K chars due to power mode
and i18n directives — not prompt stuffing.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds `manager.flags.{discuss,plan,execute}` config keys so users can
configure flags that /gsd:manager passes to each step when dispatching.
For example, `manager.flags.discuss: "--auto --analyze"` makes every
discuss dispatched from the manager include those flags.
Closes#1400
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The map-codebase workflow had a hardcoded 300000ms (5 minute) timeout
for parallel subagent tasks. On large codebases or with slower models
(e.g. GPT via Codex), subagents can need 10-20+ minutes, causing the
parent to kill still-working agents and fall back to sequential mode.
Changes:
- Add workflow.subagent_timeout config key (default: 300000ms)
- Register in VALID_CONFIG_KEYS (config.cjs)
- Add to loadConfig() defaults and return object (core.cjs)
- Emit in map-codebase init context (init.cjs)
- Update map-codebase.md to use config value instead of hardcoded 300000
- Document in planning-config.md reference
Users can now increase the timeout via:
/gsd:settings workflow.subagent_timeout 900000
Closes#1472
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds `git.base_branch` config option that controls the target branch
for PRs and merges. When unset, auto-detects from origin/HEAD and
falls back to "main".
This fixes projects using `master`, `develop`, or any other default
branch — previously `/gsd:ship` would create PRs targeting `main`
(which may not exist) and `/gsd:complete-milestone` would try to
checkout `main` and fail.
Changes:
- config.cjs: add git.base_branch to valid config keys
- planning-config.md: document the option with auto-detect behavior
- ship.md: detect base branch at init, use in PR create, branch
detection, push report, and completion report
- complete-milestone.md: detect base branch, use for squash merge
and merge-with-history checkout targets
- 1 new test for config-set git.base_branch
Usage:
gsd-tools config-set git.base_branch master
Or auto-detect (default — reads origin/HEAD):
git.base_branch: null
Closes#1466
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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>
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>
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>
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>
* 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
* 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>
