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>
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>
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>
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>
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>
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>
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>
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 `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>
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>
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>
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>
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>
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>
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.
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
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>
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>
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>
- 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>
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>
- 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>
- 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>
- 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>
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>
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>
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>
Remove confusing `parallelizable` boolean field. It was redundant -
execute-phase already computes parallelizability from `depends_on`
and file conflicts.
Changes:
- Remove `parallelizable: true|false` from plan frontmatter
- Rename `files_exclusive` to `files_modified` (clearer intent)
- Simplify execute-phase dependency detection logic
- Update phase-prompt template and plan-phase workflow
Parallelization is now fully automatic based on:
- `depends_on: []` (empty = independent)
- `files_modified: [...]` (no overlap = can parallelize)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Context isolation is the primary goal, not parallelization.
Even sequential plans spawn separate subagents for fresh 200k context.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Update categorization table to show frontmatter-aware criteria
- Add categorization priority documentation
- Update calculate_wave() to check frontmatter depends_on first
- Handle parallelizable: false as implicit Wave 2+ assignment
- Fall back to inferred requires only when no frontmatter
- Add [frontmatter] annotation in wave output for plans using new fields
- Add PLAN_PARALLELIZABLE, PLAN_DEPENDS_ON, PLAN_FILES_EXCLUSIVE arrays
- Check for parallelizable, depends_on, files_exclusive in plan frontmatter
- Use frontmatter values directly when present
- Fall back to inference logic for old plans without frontmatter
- Document dependency detection priority
