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>
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>
Wire the --reviews flag through the full stack so plan-phase can
replan incorporating cross-AI review feedback from REVIEWS.md:
- core.cjs: add has_reviews detection in searchPhaseInDir
- init.cjs: wire has_reviews and reviews_path through all init functions
- plan-phase.md command: add --reviews to argument-hint and flags
- plan-phase.md workflow: add step 2.5 validation, skip research,
skip existing plans prompt, pass reviews_path to planner
- gsd-planner.md: add reviews_mode section for consuming review feedback
- COMMANDS.md: add --reviews and missing flags to docs
Closes the gap where --reviews was referenced in 6 places (review
workflow, review command, help workflow, COMMANDS.md, FEATURES.md)
but never implemented.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Decisions in CONTEXT.md are now numbered (D-01, D-02, etc.) so
downstream agents can reference them and the plan-checker can verify
100% coverage.
Changes:
- templates/context.md: Decisions use **D-XX:** prefix format
- workflows/discuss-phase.md: write_context step numbers decisions
- agents/gsd-planner.md: Self-check verifies decision ID references
in task actions; tasks reference D-XX IDs for traceability
- agents/gsd-plan-checker.md: Dimension 7 (Context Compliance)
extracts D-XX IDs and verifies every decision has a task
* fix: remove dangling skills: from agent frontmatter and strip in Gemini converter (closes#1023, closes#953, closes#930)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: invert skills frontmatter test to assert absence (fixes CI)
The PR deliberately removed skills: from agent frontmatter (breaks
Gemini CLI), but the test still asserted its presence. Inverted the
assertion to ensure skills: stays removed.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
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>
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>
Gap closure plans hardcode wave: 1 and depends_on: [], bypassing the
standard wave assignment logic. When multiple gap closure plans have
dependencies between them, they all land in wave 1 and execute in
parallel — ignoring dependency ordering. Add an explicit wave
computation step using the same assign_waves algorithm as standard
planning.
Closes#856
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add skills: field to all 11 agent frontmatter files with forward-compatible
GSD workflow skill references (silently ignored until skill files are created).
Add commented hooks: examples to 9 file-writing agents showing PostToolUse
hook syntax for project-specific linting/formatting. Read-only agents
(plan-checker, integration-checker) skip hooks as they cannot modify files.
Per Claude Code docs: subagents don't inherit skills or hooks from the
parent conversation — they must be explicitly listed in frontmatter.
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>
- gsd-executor: Add <analysis_paralysis_guard> block after deviation_rules.
If executor makes 5+ consecutive Read/Grep/Glob calls without any
Edit/Write/Bash action, it must stop and either write or report blocked.
Prevents infinite analysis loops that stall execution.
- gsd-plan-checker: Add exhaustive cross-check in Step 4 requirement coverage.
Checker now also reads PROJECT.md requirements (not just phase goal) to
verify no relevant requirement is silently dropped. Unmapped requirements
become automatic blockers listed explicitly in issues.
- gsd-planner: Add task-level TDD guidance alongside existing TDD Detection.
For code-producing tasks in standard plans, tdd="true" + <behavior> block
makes test expectations explicit before implementation. Complements the
existing dedicated TDD plan approach — both can coexist.
Co-authored-by: CyPack <GITHUB_EMAIL_ADRESIN>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: use `.claude/skills/` instead of `.agents/skills/` in agent and workflow skill references
Claude Code resolves project skills from `.claude/skills/` (project-level)
and `~/.claude/skills/` (user-level). The `.agents/skills/` path is the
universal/IDE-agnostic convention that Claude Code does not resolve, causing
project skills to be silently ignored by all affected agents and workflows.
Fixes#758
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: support both `.claude/skills/` and `.agents/skills/` for cross-IDE compatibility
Instead of replacing `.agents/skills/` with `.claude/skills/`, reference both
paths so GSD works with Claude Code (`.claude/skills/`) and other IDE agents
like OpenCode (`.agents/skills/`).
Addresses review feedback from begna112 on #758.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Stephen Miller <Stephen@betterbox.pw>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Reduces token overhead of Dimension 8 and related agent additions by ~37%
with no behavioral change. Removes theory explanation, dead XML tags
(<manual>, <sampling_rate>), aspirational execution tracking, and
documentation-density prose from runtime agent bodies.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Adds automated feedback architecture research to gsd-phase-researcher,
enforces it as Dimension 8 in gsd-plan-checker, and introduces
{phase}-VALIDATION.md as the per-phase validation contract.
Ensures every phase plan includes automated verify commands before
execution begins. Opt-out via workflow.nyquist_validation: false.
Closes#122 (partial), related #117
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>
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>
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>
Agents (executor, verifier, planner) were writing markdown files via
Bash heredocs. When approved, Claude Code persisted the entire heredoc
as a permission entry, breaking settings.local.json on next launch.
Added explicit "use Write tool" directives to all three agents and
added missing Write tool to gsd-verifier's tool list.
Closes#526Closes#491
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(gsd-tools): add frontmatter CRUD, verification suite, template fill, and state progression
Four new command groups that delegate deterministic operations from AI agents to code:
- frontmatter get/set/merge/validate: Safe YAML frontmatter manipulation with schema validation
- verify plan-structure/phase-completeness/references/commits/artifacts/key-links: Structural checks agents previously burned context on
- template fill summary/plan/verification: Pre-filled document skeletons so agents only fill creative content
- state advance-plan/record-metric/update-progress/add-decision/add-blocker/resolve-blocker/record-session: Automate arithmetic and formatting in STATE.md
Adds reconstructFrontmatter() + spliceFrontmatter() helpers for safe frontmatter roundtripping,
and parseMustHavesBlock() for 3-level YAML parsing of must_haves structures.
20 new functions, ~1037 new lines.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: wire gsd-tools commands into agents and workflows
- gsd-verifier: use `verify artifacts` and `verify key-links` instead of
manual grep patterns for stub detection and wiring verification
- gsd-executor: use `state advance-plan`, `state update-progress`,
`state record-metric`, `state add-decision`, `state record-session`
instead of manual STATE.md manipulation
- gsd-plan-checker: use `verify plan-structure` and `frontmatter get`
for structural validation and must_haves extraction
- gsd-planner: add validation step using `frontmatter validate` and
`verify plan-structure` after writing PLAN.md
- execute-plan.md: use gsd-tools state commands for position/progress updates
- verify-phase.md: use gsd-tools for must_haves extraction and artifact/link verification
This makes the gsd-tools commands from PR #485 actually used by the system.
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* prompt(001): map dependencies for new-project command
* fix(#326): enforce context fidelity in planning pipeline
Root cause: User decisions from CONTEXT.md were available but not
enforced throughout the RESEARCH → PLAN → VERIFY chain.
Changes:
- gsd-planner: Add <context_fidelity> section requiring agents to
parse and honor user decisions BEFORE creating tasks. Includes
self-check checklist and conflict handling guidance.
- gsd-phase-researcher: Add User Constraints as FIRST section in
downstream consumer table. Require researcher to copy CONTEXT.md
decisions verbatim to RESEARCH.md so planner sees them even if
it only skims.
- research.md template: Add <user_constraints> section that must
be populated first. Locked decisions, Claude's discretion, and
deferred ideas copied verbatim from CONTEXT.md.
The command file (commands/gsd/plan-phase.md) already passes
CONTEXT_CONTENT to all agents. These changes add the enforcement
layer in the agent instructions.
Fixes#326, #216, #206
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Rolled back the intel system due to overengineering concerns:
- 1200+ line hook with SQLite graph database
- 21MB sql.js dependency
- Entity generation spawning additional Claude calls
- Complex system with unclear value
Removed:
- /gsd:analyze-codebase command
- /gsd:query-intel command
- gsd-intel-index.js, gsd-intel-session.js, gsd-intel-prune.js hooks
- gsd-entity-generator, gsd-indexer agents
- entity.md template
- sql.js dependency
Preserved:
- Model profiles feature
- Statusline hook
- All other v1.9.x improvements
-3,065 lines removed
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add load_codebase_intelligence step to gsd-planner.md
- Add load_codebase_intelligence step to gsd-executor.md
- Include .planning/intel/summary.md in plan context template
- Subagents now use detected conventions during planning/execution
* 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>
Revision mode was missing git commit step - plans updated based on
checker issues were written to disk but never committed.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Planner was only describing that it should use these files,
not explicitly reading them. Added mandatory bash commands
to cat phase-specific context files in gather_phase_context step.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes#82
When add-phase or insert-phase creates placeholder entries in ROADMAP.md,
plan-phase now finalizes them:
- Goal: derives from CONTEXT.md/RESEARCH.md if placeholder
- Plans: updates count and adds checkbox list of plan files
- Commits ROADMAP.md alongside PLAN.md files
User setup info belongs in plan frontmatter only. The execute-plan
workflow surfaces it at the right time (after automation completes).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Research decisions made at roadmap creation time are:
- Premature: Can't know if research is needed before discuss-phase
- Redundant: --skip-research flag exists for explicit control
- Counterproductive: Gives Claude an excuse to skip research entirely
Removed:
- Research: Likely/Unlikely fields from roadmap template
- detect_research_needs step from create-roadmap workflow
- "If roadmap flagged Research: Likely" checks from gsd-planner
Research now always runs during plan-phase unless:
- RESEARCH.md already exists (silent reuse)
- --skip-research flag passed
- --gaps flag passed (gap closure mode)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds back guidance that was lost during consolidation:
- Task sizing heuristic (15-60 min target)
- Signals for too large / too small tasks
- Specificity side-by-side examples table
- "The test" for checking task clarity
