Address 4 root causes of Windows + Claude Code reliability issues:
1. Workflow shell robustness: add || true guards to informational commands
(ls, grep, find, cat) that return non-zero on "no results", preventing
workflow step failures under strict execution models. Guard glob loops
with [ -e "$var" ] || continue to handle empty glob expansion.
2. Hook stdin handling: replace readFileSync('/dev/stdin') with async
process.stdin + timeout in agent templates (gsd-verifier.md). Existing
JS hooks already have timeout guards.
3. project_root detection: fix isInsideGitRepo() to check .git at the
candidate parent level (not just below it), enabling correct detection
when .git and .planning/ are siblings at the same directory level —
the common single-repo case from a subdirectory.
4. @file: handoff: add missing @file: handlers to autonomous.md and
manager.md workflows that call gsd-tools init but lacked the handler
for large output payloads.
Fixes#1343
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Worktree agents (gsd-executor, gsd-debugger) prompt for edit permissions
on every new directory they touch, even when the user has "accept edits"
enabled. This is caused by Claude Code's directory-scoped permission
model not propagating to worktree paths.
Setting permissionMode: acceptEdits in the agent frontmatter tells Claude
Code to auto-approve file edits for these agents, bypassing the per-
directory prompts. This is safe because these agents are already granted
Write/Edit in their tools list and are spawned in isolated worktrees.
- Add permissionMode: acceptEdits to gsd-executor.md frontmatter
- Add permissionMode: acceptEdits to gsd-debugger.md frontmatter
- Add regression tests verifying worktree agents have the field
- Add test ensuring all isolation="worktree" spawns are covered
Upstream: anthropics/claude-code#29110, anthropics/claude-code#28041
Fixes#1334
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add UI keyword detection list for identifying frontend-heavy phases
- Roadmapper annotates phases with **UI hint**: yes when keywords match
- Annotation consumed by downstream workflows to suggest /gsd:ui-phase
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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>
Verification checked structure but not whether data actually flows
end-to-end or whether external dependencies are available. Adds:
- Step 4b (Data-Flow Trace): Level 4 verification traces upstream from
wired artifacts to verify data sources produce real data, catching
hollow components that render empty/hardcoded values
- Step 7b (Behavioral Spot-Checks): lightweight smoke tests that verify
runnable code produces expected output, not just that it exists
- Step 2.6 (Environment Audit): researcher probes target machine for
external tools/services/runtimes before planning, so plans include
fallback strategies for missing dependencies
Closes#1245
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Teaches the debugger agent to trace path/URL/key construction across
producer and consumer code — prevents shallow investigation that misses
directory mismatches like the stale hooks bug (#1249).
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>
Add CLAUDE.md enforcement across the three core agents:
- gsd-plan-checker: new Dimension 10 verifies plans respect project
conventions, forbidden patterns, and required tools from CLAUDE.md
- gsd-phase-researcher: outputs Project Constraints section from
CLAUDE.md so planner can verify compliance
- gsd-executor: treats CLAUDE.md directives as hard constraints,
with precedence over plan instructions
Includes 4 regression tests validating the new dimension and
enforcement directives across all three agents.
Closes#1260
Co-Authored-By: Claude Opus 4.6 <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
Enhanced gsd-verifier's anti-pattern detection to catch:
- Hardcoded empty data props (={[]}, ={{}}, ={null})
- 'not available' and 'not yet implemented' placeholder text
- Data stub classification guidance (only flag when value flows
to rendering without a data-fetching path)
Added stub tracking to gsd-executor's summary creation:
- Before writing SUMMARY, scan files for stub patterns
- Document stubs in a '## Known Stubs' section
- Block plan completion if stubs prevent the plan's goal
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
Adds an optional advisor mode to discuss-phase that provides research-backed
comparison tables before asking users to make decisions. Activates when
USER-PROFILE.md exists, degrades gracefully otherwise.
New agent: gsd-advisor-researcher -- spawned in parallel per gray area,
returns structured 5-column comparison tables calibrated to the user vendor
philosophy preference (full_maturity/standard/minimal_decisive).
Workflow changes (discuss-phase.md):
- Advisor mode detection in analyze_phase step
- New advisor_research step spawns parallel research agents
- Table-first discussion flow in discuss_areas when advisor mode active
- Standard conversational flow unchanged when advisor mode inactive
The hash recording step used `git rev-parse --short HEAD` which fails
when the project root is not a git repo (multi-repo workspaces). Update
the protocol to extract hashes from commit-to-subrepo JSON output and
record all sub-repo hashes in the SUMMARY.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add support for workspaces with multiple independent git repositories.
When configured, GSD routes commits to the correct sub-repo and ensures
.planning/ stays at the project root.
Core features:
- detectSubRepos(): scans child directories for .git to discover repos
- findProjectRoot(): walks up from CWD to find the project root that
owns .planning/, preventing orphaned .planning/ in sub-repos
- loadConfig auto-syncs sub_repos when repos are added or removed
- Migrates legacy "multiRepo: true" to sub_repos array automatically
- All init commands include project_root in output
- cmdCommitToSubrepo: groups files by sub-repo prefix, commits independently
Zero impact on single-repo workflows — sub_repos defaults to empty array.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds a Runtime State Inventory step that fires when a phase involves
renaming, rebranding, refactoring, or migrating strings across a codebase.
The core problem: grep audits find files. They do NOT find runtime state —
ChromaDB collection names, Mem0 user_ids, n8n workflows in SQLite, Windows
Task Scheduler descriptions, pm2 process names, SOPS key names, pip
egg-info directories, etc. These survive a complete file-level rename and
will break the system silently after the code is "done".
Three additions:
1. Pre-Submission Checklist — adds a reminder item so the checklist gate
catches skipped inventories before RESEARCH.md is committed
2. output_format — adds Runtime State Inventory table to the RESEARCH.md
template so the section appears in every rename/refactor phase's output
3. execution_flow Step 2.5 — structured investigation protocol with the
five categories (stored data, live service config, OS-registered state,
secrets/env vars, build artifacts), explicit examples for each, and the
canonical question that frames the whole exercise
Three additive quality improvements to the execution pipeline:
1. Pre-wave dependency check (execute-phase): Before spawning wave N+1,
verify key-links from prior wave artifacts. Catches cross-plan wiring
gaps before they cascade into downstream failures.
2. Cross-Plan Data Contracts dimension (plan-checker): New Dimension 9
checks that plans sharing data pipelines have compatible transformations.
Flags when one plan strips data another plan needs in original form.
3. Export-level spot check (verify-phase): After Level 3 wiring passes,
spot-check individual exports for actual usage. Catches dead stores
that exist in wired files but are never called.
The researcher agent now verifies each recommended package version
using 'npm view [package] version' before writing the Standard Stack
section. This prevents recommending stale versions from training data.
Addresses patch 5 from #899
After committing task changes, the executor now checks for untracked
files (git status --short | grep '^??') and handles them: commit if
intentional, add to .gitignore if generated/runtime output.
This prevents generated artifacts (build outputs, .env files, cache
files) from being silently left untracked in the working tree.
Changes:
- execute-plan.md: Add step 6 to task commit protocol
- gsd-executor.md: Add step 6 to task commit protocol
Fixes#957
Strip unsupported `skills:` key from gsd-ui-auditor, gsd-ui-checker, and
gsd-ui-researcher agent frontmatter. Update Copilot install test expectations
to 36 skills / 15 agents.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When a debug session resolves, append a structured entry to
.planning/debug/knowledge-base.md capturing error patterns,
root cause, and fix approach.
At the start of each new investigation (Phase 0), the debugger
loads the knowledge base and checks for keyword overlap with
current symptoms. Matches surface as hypothesis candidates to
test first — reducing repeat investigation time for known patterns.
The knowledge base is append-only and project-scoped, so it
builds value over the lifetime of a codebase rather than
resetting each session.
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: 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>
* 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>
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>
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>
Two defensive hardening changes:
1. state.cjs: Replace two identical inline extractField closures
(cmdStateSnapshot and buildStateFrontmatter) with a shared
stateExtractField(content, fieldName) helper at module scope.
The helper uses escapeRegex on fieldName before interpolation
into RegExp constructors, preventing breakage if a field name
ever contains regex metacharacters. Net removal of duplicated
logic.
2. gsd-plan-checker.md: Bound the "relevant" definition in the
exhaustive cross-check instruction. A requirement is "relevant"
only if ROADMAP.md explicitly maps it to this phase or the phase
goal directly implies it — prevents false blocker flags for
requirements belonging to other phases.
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>
Add 'never use heredoc' instruction to 6 agents that were missing it:
gsd-codebase-mapper, gsd-debugger, gsd-phase-researcher,
gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper.
All 9 file-writing agents now consistently prevent settings.local.json
corruption from heredoc permission entries (GSD #526).
Read-only agents (plan-checker, integration-checker) excluded as they
cannot write 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>
- 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>
The verifier was the only agent missing the <project_context> section
that executor, planner, researcher, and plan-checker all have. This
aligns it with the existing pattern so project skills and CLAUDE.md
instructions are applied during verification and anti-pattern scanning.
Closes discussion from PR #723.
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>
