* feat(agents): auto-inject relevant global learnings into planner context
* fix(agents): address review feedback for learnings planner injection
- Add features.global_learnings to VALID_CONFIG_KEYS for explicit validation
- Fix error message in cmdConfigSet to mention features.<feature_name> pattern
- Clarify tag syntax in planner injection step (frontmatter tags or objective keywords)
* feat(config): add execution context profiles for mode-specific agent output
* fix(config): add enum validation for context config key
Validate context values against allowed enum (dev, research, review)
in cmdConfigSet before writing to config.json, matching the pattern
used for model_profile validation. Add rejection test for invalid
context values.
Integrate lightweight thinking partner analysis at two workflow decision
points, controlled by features.thinking_partner config (default: false):
1. discuss-phase: when developer answers reveal competing priorities
(detected via keyword/structural signals), offers brief tradeoff
analysis before locking decisions
2. plan-phase: when plan-checker flags architectural tradeoffs, analyzes
options and recommends an approach aligned with phase goals before
entering the revision loop
The thinking partner is opt-in, skippable (No, I have decided),
and brief (3-5 bullets). A third integration point for /gsd-explore
will be added when #1729 lands.
Closes#1726
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Fixes#1707
Extracts config defaults from loadConfig() into an exported
CONFIG_DEFAULTS constant in core.cjs. config.cjs and verify.cjs
now reference CONFIG_DEFAULTS instead of duplicating values,
preventing future divergence.
* 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>
* fix: replace /gsd: command format with /gsd- skill format in all suggestions
All next-step suggestions shown to users were still using the old colon
format (/gsd:xxx) which cannot be copy-pasted as skills. Migrated all
occurrences across agents/, commands/, get-shit-done/, docs/, README files,
bin/install.js (hardcoded defaults for claude runtime), and
get-shit-done/bin/lib/*.cjs (generate-claude-md templates and error messages).
Updated tests to assert new hyphen format instead of old colon format.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: migrate remaining /gsd: format to /gsd- in hooks, workflows, and sdk
Addresses remaining user-facing occurrences missed in the initial migration:
- hooks/: fix 4 user-facing messages (pause-work, update, fast, quick)
and 2 comments in gsd-workflow-guard.js
- get-shit-done/workflows/: fix 21 Skill() literal calls that Claude
executes directly (installer does not transform workflow content)
- sdk/prompt-sanitizer.ts: update regex to strip /gsd- format in addition
to legacy /gsd: format; update JSDoc comment
- tests/: update autonomous-ui-steps, prompt-sanitizer to assert new format
Note: commands/gsd/*.md frontmatter (name: gsd:xxx) intentionally unchanged
— installer derives skillName from directory path, not the name field.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(plan-phase): preserve --chain flag in auto-advance sync and handle ui-phase gate in chain mode
Bug 1: step 15 sync-flag check only guarded against --auto, causing
_auto_chain_active to be cleared when plan-phase is invoked without
--auto in ARGUMENTS even though a --chain pipeline was active. Added
--chain to the guard condition, matching discuss-phase behaviour.
Bug 2: UI Design Contract gate (step 5.6) always exited the workflow
when UI-SPEC was missing, breaking the discuss --chain pipeline
silently. When _auto_chain_active is true, the gate now auto-invokes
gsd-ui-phase --auto via Skill() and continues to step 6 without
prompting. Manual invocations retain the existing AskUserQuestion flow.
* fix: remove <sub>/clear</sub> pattern and duplicate old-format command in discuss-phase.md
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix(config): warn on unrecognized keys in config.json instead of silent drop (#1535)
loadConfig() silently ignores any config.json keys not in its known
set, leaving users confused when their settings have no effect. Add a
stderr warning listing unrecognized top-level keys so the problem
surfaces immediately.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(config): derive known keys from VALID_CONFIG_KEYS instead of hardcoded set
Address review feedback: replace hardcoded KNOWN_CONFIG_KEYS with
programmatic derivation from config-set's VALID_CONFIG_KEYS (single
source of truth). New config keys added to config-set are automatically
recognized by loadConfig without a separate update. Add sync test
verifying all VALID_CONFIG_KEYS entries pass without warning.
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 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>
Add agent_skills config section that maps agent types to skill directory
paths. At spawn time, workflows load configured skills and inject them
as <agent_skills> blocks in Task() prompts, giving subagents access to
project-specific skill files.
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>
When enabled, /gsd:autonomous chains directly from plan-phase to execute-phase,
skipping smart discuss. A minimal CONTEXT.md is auto-generated from the ROADMAP
phase goal so downstream agents have valid input. Manual /gsd:discuss-phase still
works regardless of the setting.
Changes:
- config.cjs: add workflow.skip_discuss to VALID_CONFIG_KEYS and hardcoded defaults (false)
- autonomous.md: check workflow.skip_discuss before smart_discuss, write minimal CONTEXT.md when skipping
- settings.md: add Skip Discuss toggle to interactive settings UI and global defaults
- config.test.cjs: 6 regression tests for the new config key
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The discuss-phase command file contained a 93-line detailed <process>
block that competed with the actual workflow file. The agent treated
this summary as complete instructions and never read the execution_context
files (discuss-phase.md, discuss-phase-assumptions.md, context.md template).
Root cause: Unlike execute-phase and plan-phase commands (which have short
2-line process blocks deferring to the workflow file), discuss-phase had
inline step-by-step instructions detailed enough to act on without reading
the referenced workflow files.
Changes:
- Replace discuss-phase command's <process> block with a short directive
that forces reading the workflow file, matching execute-phase/plan-phase
pattern
- Add MANDATORY instruction that execution_context files ARE the
instructions, not optional reading
- Register workflow.research_before_questions and workflow.discuss_mode
as valid config keys (were missing from VALID_CONFIG_KEYS)
- Fix config key mismatch: workflows referenced "research_questions"
but documented key is "workflow.research_before_questions"
- Move research_before_questions from hooks section to workflow section
in settings workflow
- Add research_before_questions default to config template and builder
- Add suggestion mapping for deprecated hooks.research_questions key
- Add 6 regression tests covering config keys and process block guard
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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.
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
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).
- 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
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
* 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
* 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>
* 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>
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>
