Add codebase-first assumption-driven alternative to the interview-style
discuss-phase. New `workflow.discuss_mode: "assumptions"` config routes
to a separate workflow that spawns a gsd-assumptions-analyzer agent to
read 5-15 codebase files, surface assumptions with evidence, and ask
only for corrections (~2-4 interactions vs ~15-20).
- New gsd-assumptions-analyzer agent for deep codebase analysis
- New discuss-phase-assumptions.md workflow (15 steps)
- Command-level routing via dual @reference + process gate
- Identical CONTEXT.md output — downstream agents unaffected
- Existing discuss-phase.md workflow untouched (zero diff)
- Mode-aware plan-phase gate and progress display
- User documentation and integration tests
- Update agent count and list in copilot-install tests (17 → 18)
Closes#637
Co-Authored-By: Claude Opus 4.6 (1M context) <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>
Windows users experience plan-phase freezes due to Claude Code stdio
deadlocks with MCP servers. When a subagent hangs, the orchestrator
blocks indefinitely with no timeout or error.
Adds:
- Windows troubleshooting section to plan-phase.md with:
- Orphaned process cleanup (PowerShell commands)
- Stale task directory cleanup (~/.claude/tasks/)
- MCP server reduction advice
- --skip-research fallback to reduce agent chain
- Stale task directory detection to health.md (I002 diagnostic)
- Reports count of stale dirs on --repair
- Safe cleanup guidance
Closes#732
Add step 13 (Requirements Coverage Gate) to plan-phase workflow.
After plans pass the checker, verifies all phase requirements are
covered by at least one plan before declaring planning complete.
- Extracts REQ-IDs from plan frontmatter and compares against
phase_req_ids from ROADMAP
- Cross-checks CONTEXT.md features against plan objectives to
detect silently dropped scope
- Reports gaps with options: re-plan, defer, or proceed
- Skips when phase_req_ids is null/TBD (no requirements mapped)
Fixes#984
Co-authored-by: TÂCHES <afromanguy@me.com>
After /clear, Claude Code sometimes loses awareness of custom agent types
and falls back to 'general-purpose'. This happens because the model doesn't
re-read .claude/agents/ after context reset.
Added <available_agent_types> sections to:
- execute-phase.md: lists all 12 valid GSD agent types with descriptions
- plan-phase.md: lists the 3 agent types used during planning
The explicit listing in workflow instructions ensures the model always has
an unambiguous reference to valid agent types, regardless of whether
.claude/agents/ was re-read after /clear.
Fixes#949
When plan-phase invokes discuss-phase as a nested Skill call,
AskUserQuestion calls auto-resolve with empty answers — the user never
sees the question UI. This is a Claude Code runtime bug with nested
subcontexts.
Made the 'Run discuss-phase first' path explicitly exit the workflow
with a display message instead of risking nested invocation:
- Added explicit warning: do NOT invoke as nested Skill/Task
- Show the command for user to run as top-level
- Exit the plan-phase workflow immediately
Fixes#1009
Instead of silently skipping research based on the config toggle,
plan-phase now asks the user whether to research before planning
(when no explicit --research or --skip-research flag is provided).
The prompt includes a contextual recommendation:
- 'Research first (Recommended)' for new features, integrations, etc.
- 'Skip research' for bug fixes, refactors, well-understood tasks
The --research and --skip-research flags still work as silent overrides
for automation. Auto mode (--auto) respects the config toggle silently.
Fixes#846
Add pre-planning design contract generation and post-execution visual audit
for frontend phases. Closes the gap where execute-phase runs without a visual
contract, producing inconsistent spacing, color, and typography across components.
New agents: gsd-ui-researcher (UI-SPEC.md), gsd-ui-checker (6-dimension
validation), gsd-ui-auditor (6-pillar scored audit + registry re-vetting).
Third-party shadcn registry blocks are machine-vetted at contract time,
verification time, and audit time — three enforcement points, not a checkbox.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* 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>
Executor agents often produce shallow work because plans say "align X with Y"
without specifying what the aligned result looks like. The executor changes one
value and calls it done.
This adds three mandatory fields to every task:
- `<read_first>`: Files the executor MUST read before editing. Ensures ground
truth is loaded, not assumed.
- `<acceptance_criteria>`: Grep-verifiable conditions checked after each task.
No subjective language ("looks consistent"), only concrete checks
("file contains 'exact string'").
- `<action>` guidance: Must include concrete values (identifiers, signatures,
config keys), never vague references like "update to match production".
Adds `<deep_work_rules>` to planner instructions with mandatory quality gate
checks. Executor workflow enforces both gates: read before edit, verify after
edit. Adds generic pre-commit hook failure handling guidance.
Co-authored-by: Dammerzone <dammerzone@users.noreply.github.com>
* fix: add mandatory canonical_refs section to CONTEXT.md
CONTEXT.md is the bridge between user decisions and downstream agents
(researcher, planner). When projects have external specs, ADRs, or
design docs, these references were being silently dropped — mentioned
inline as "see ADR-019" but never collected into a section that agents
could find and read. This caused agents to plan and implement without
reading the specs they were supposed to follow.
Changes:
- templates/context.md: Add <canonical_refs> section to file template,
all 3 examples, and guidelines (marked MANDATORY)
- workflows/discuss-phase.md: Add step 1b (extract canonical refs),
add section to write_context template, add to success criteria
- workflows/plan-phase.md: Add canonical ref extraction to PRD express
path and its CONTEXT.md template
- workflows/quick.md: Add lightweight canonical_refs to --discuss mode
The section is mandatory but gracefully handles projects without external
docs ("No external specs — requirements fully captured in decisions above").
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: make canonical refs an accumulator across entire discussion
Refs come from 4 sources, not just ROADMAP.md:
1. ROADMAP.md Canonical refs line (initial seed)
2. REQUIREMENTS.md/PROJECT.md referenced specs
3. Codebase scout (code comments citing ADRs)
4. User during discussion ("read adr-014", "check the MCP spec")
Source 4 is often the MOST important — these are docs the user
specifically wants downstream agents to follow. The previous
version only handled source 1 and silently dropped the rest.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <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>
* 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>
Replace general-purpose workaround pattern with named subagent types:
- plan-phase: researcher and planner now spawn as gsd-phase-researcher/gsd-planner
- new-project: 4 researcher spawns now use gsd-project-researcher
- research-phase: researcher spawns now use gsd-phase-researcher
- quick: planner revision now uses gsd-planner
- diagnose-issues: debug agents now use gsd-debugger (matches template spec)
Removes 'First, read agent .md file' prompt prefix — named agent types
auto-load their .md file as system prompt, making the workaround redundant.
Preserves intentional general-purpose orchestrator spawns in discuss-phase
and plan-phase (auto-advance) where the agent runs an entire workflow.
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>
The auto-advance chain (discuss → plan → execute) was spawning each
subsequent phase as a Task(subagent_type="general-purpose"), creating
3-4 levels of nested agent sessions. At that nesting depth, the
Claude Code runtime hits resource limits or stdio contention, causing
the execute-phase to freeze or attempt to shell out to `claude` as a
subprocess (which is explicitly blocked).
The fix replaces Task spawns with Skill invocations for phase
transitions:
- discuss-phase auto-advance: Skill("gsd:plan-phase") instead of
Task(general-purpose)
- plan-phase auto-advance: Skill("gsd:execute-phase") instead of
Task(general-purpose)
The Skill tool runs in the same process context as the caller,
keeping the entire auto-advance chain flat at a single nesting level.
Each phase still spawns its own worker agents (gsd-executor,
gsd-planner, etc.) as Tasks, but the orchestration chain itself
no longer creates unnecessary depth.
Closes#686
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>
* 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>
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>
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>
- 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>
Closes#253 — plans were silently created without CONTEXT.md, and
discuss-phase didn't warn when plans already existed.
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>
When init commands include many file contents (state, roadmap, requirements,
etc.), the JSON output can exceed Claude Code's Bash tool buffer (~50KB),
causing parse errors. The output() function now auto-detects large payloads
and writes to a tmpfile, returning @file:/path instead. All workflows that
consume init output handle both formats.
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>
Add opt-in mechanism to chain discuss → plan → execute automatically
via Task() subagents, eliminating manual /clear + paste overhead.
- Add `--auto` flag to discuss-phase and plan-phase commands
- Add `workflow.auto_advance` config toggle (default: false)
- Add auto_advance step to discuss-phase workflow (spawns plan-phase)
- Add step 14 to plan-phase workflow (spawns execute-phase)
- Add auto_advance toggle to /gsd:settings
Chain stops gracefully on INCONCLUSIVE, CHECKPOINT, or verification
failures. No work lost — artifacts persist at each step.
Closes#541
Co-Authored-By: Claude Opus 4.5 <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>
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>
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>
- Replaced 868-line workflow with deprecation notice
- Points to agents/gsd-planner.md for methodology
- Documents historical content for reference
- Kept file for git history
Unify gap handling - whether discovered by code verification or user
testing, gaps feed into the same plan-phase --gaps workflow.
Changes:
- Delete commands/gsd/plan-fix.md (redundant)
- Update verify-work to route to plan-phase --gaps
- Update progress Route E to detect UAT gaps
- Change UAT.md "Issues" section to "Gaps" with YAML format
- Extend plan-phase --gaps to read from both VERIFICATION.md and UAT.md
- Update diagnose-issues to output gaps in YAML format
- Update all references (debug, templates, workflows)
One path: gap discovered → diagnosed → plan-phase --gaps → fixed
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>
