* docs(01-02): complete gsd-doc-writer agent skeleton plan
- SUMMARY.md for plan 01-02
- STATE.md advanced to plan 2/2, progress 50%
- ROADMAP.md updated with phase 1 plan progress
- REQUIREMENTS.md marked DOCG-01 and DOCG-08 complete
* feat(01-01): create lib/docs.cjs with cmdDocsInit and detection helpers
- Add cmdDocsInit following cmdInitMapCodebase pattern
- Add hasGsdMarker(), scanExistingDocs(), detectProjectType()
- Add detectDocTooling(), detectMonorepoWorkspaces() private helpers
- GSD_MARKER constant for generated-by tracking
- Only Node.js built-ins and local lib requires used
* feat(01-01): wire docs-init into gsd-tools.cjs and register gsd-doc-writer model profile
- Add const docs = require('./lib/docs.cjs') to gsd-tools.cjs
- Add case 'docs-init' routing to docs.cmdDocsInit
- Add docs-init to help text and JSDoc header
- Register gsd-doc-writer in MODEL_PROFILES (quality:opus, balanced:sonnet, budget:haiku)
- Fix docs.cjs: inline withProjectRoot logic via checkAgentsInstalled (private in init.cjs)
* docs(01-01): complete docs-init command plan
- SUMMARY.md documenting cmdDocsInit, detection helpers, wiring
- STATE.md advanced, progress updated to 100%
- ROADMAP.md phase 1 marked Complete
- REQUIREMENTS.md INFRA-01, INFRA-02, CONS-03 marked complete
* feat(01-02): create gsd-doc-writer agent skeleton
- YAML frontmatter with name, description, tools, color: purple
- role block with doc_assignment receiving convention
- create_mode and update_mode sections
- 9 stub template sections (readme, architecture, getting_started, development, testing, api, configuration, deployment, contributing)
- Each template has Required Sections list and Phase 3 TODO
- critical_rules prohibiting GSD methodology and CHANGELOG
- success_criteria checklist
- No GSD methodology leaks in template sections
* feat(02-01): add docs-update workflow Steps 1-6 — init, classify, route, resolve, detect
- init_context step calling docs-init with @file: handling and agent-skills loading
- validate_agents step warns on missing gsd-doc-writer without halting
- classify_project step maps project_type signals to 5 primary labels plus conditional docs
- build_doc_queue step with always-on 6 docs and conditional API/CONTRIBUTING/DEPLOYMENT routing
- resolve_modes step with doc-type to canonical path mapping and create/update detection
- detect_runtime_capabilities step with Task tool detection and sequential fallback routing
* docs(02-01): complete docs-update workflow plan — 13-step orchestration for parallel doc generation
- 02-01-SUMMARY.md: plan results, decisions, file inventory
- STATE.md: advanced to last plan, progress 100%, decisions recorded
- ROADMAP.md: Phase 2 marked Complete (1/1 plans with summary)
- REQUIREMENTS.md: marked INFRA-04, DOCG-03, DOCG-04, CONS-01, CONS-02, CONS-04 complete
* docs(03-02): complete command entry point and workflow extension plan
- 03-02-SUMMARY.md: plan results, decisions, file inventory
- STATE.md: advanced to plan 2, progress 100%, decisions recorded
- ROADMAP.md: Phase 3 marked Complete (2/2 plans with summaries)
- REQUIREMENTS.md: marked INFRA-03, EXIST-01, EXIST-02, EXIST-04 complete
* feat(03-01): fill all 9 doc templates, add supplement mode and per-package README template
- Replace all 9 template stubs with full content guidance (Required Sections, Content Discovery, Format Notes)
- Add shared doc_tooling_guidance block for Docusaurus, VitePress, MkDocs, Storybook routing
- Add supplement_mode block: append-only strategy with heading comparison and safety rules
- Add template_readme_per_package for monorepo per-package README generation
- Update role block to list supplement as third mode; add rule 7 to critical_rules
- Add supplement mode check to success_criteria
- Remove all Phase 3 TODO stubs and placeholder comments
* feat(03-02): add docs-update command entry point with --force and --verify-only flags
- YAML frontmatter with name, argument-hint, allowed-tools
- objective block documents flag semantics with literal-token enforcement pattern
- execution_context references docs-update.md workflow
- context block passes $ARGUMENTS and documents flag derivation rules
- --force takes precedence over --verify-only when both present
* feat(03-02): extend docs-update workflow with preservation_check, monorepo dispatch, and verify-only
- preservation_check step between resolve_modes and detect_runtime_capabilities
- preservation_check skips on --force, --verify-only, or no hand-written docs
- per-file AskUserQuestion choice: preserve/supplement/regenerate with fallback default to preserve
- dispatch_monorepo_packages step after collect_wave_2 for per-package READMEs
- verify_only_report early-exit step with VERIFY marker count and Phase 4 deferral message
- preservation_mode field added to all doc_assignment blocks in dispatch_wave_1, dispatch_wave_2
- sequential_generation extended with monorepo per-package section
- commit_docs updated to include per-package README files pattern
- report extended with per-package README rows and preservation decisions
- success_criteria updated with preservation, --force, --verify-only, and monorepo checks
* feat(04-01): create gsd-doc-verifier agent with claim extraction and filesystem verification
- YAML frontmatter with name, description, tools, and color fields
- claim_extraction section with 5 categories: file paths, commands, API endpoints, functions, dependencies
- skip_rules section for VERIFY markers, placeholders, example prefixes, and diff blocks
- verification_process with 6 steps using filesystem tools only (no self-consistency checks)
- output_format with exact JSON shape per D-01
- critical_rules enforcing filesystem-only verification and read-only operation
* feat(04-01): add fix_mode to gsd-doc-writer with surgical correction instructions
- Add fix_mode section after supplement_mode in modes block
- Document fix mode as valid option in role block mode list
- Add failures field to doc_assignment fields (fix mode only)
- fix_mode enforces surgical precision: only correct listed failing lines
- VERIFY marker fallback when correct value cannot be determined
* test(04-03): add docs-init integration test suite
- 13 tests across 4 describe blocks covering JSON output shape, project type
detection, existing doc scanning, GSD marker detection, and doc tooling
- Tests use node:test + node:assert/strict with beforeEach/afterEach lifecycle
- All 13 tests pass with `node --test tests/docs-update.test.cjs`
* feat(04-02): add verify_docs, fix_loop, scan_for_secrets steps to docs-update workflow
- verify_docs step spawns gsd-doc-verifier per generated doc and collects structured JSON results
- fix_loop step bounded at 2 iterations with regression detection (D-05/D-06)
- scan_for_secrets step uses exact map-codebase grep pattern before commit (D-07/D-08)
- verify_only_report updated to invoke real gsd-doc-verifier instead of VERIFY marker count stub
- success_criteria updated with 4 new verification gate checklist items
* docs(04-02): complete verification gate workflow steps plan
- SUMMARY.md: verify_docs, fix_loop, scan_for_secrets, and updated verify_only_report
- STATE.md: advanced to ready_for_verification, 100% progress, decisions logged
- ROADMAP.md: phase 4 marked Complete (3/3 plans with SUMMARYs)
- REQUIREMENTS.md: VERF-01, VERF-02, VERF-03 all marked complete
* refactor(profiles): Adds 'gsd-doc-verifier' to the 'MODEL_PROFILES'
* feat(agents): Add critical rules for file creation and update install test
* docs(05): create phase plan for docs output refinement
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(05-01): make scanExistingDocs recursive into docs/ subdirectories
- Replace flat docs/ scan with recursive walkDir helper (MAX_DEPTH=4)
- Add SKIP_DIRS filtering at every level of recursive walk
- Add fallback to documentation/ or doc/ when docs/ does not exist
- Update JSDoc to reflect recursive scanning behavior
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(05-01): update gsd-doc-writer default path guidance to docs/
- Change "No tooling detected" guidance to default to docs/ directory
- Add README.md and CONTRIBUTING.md as root-level exceptions
- Add instruction to create docs/ directory if it does not exist
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(05-02): invert path table to default docs to docs/ directory
- Invert resolve_modes path table: docs/ is primary for all types except readme and contributing
- Add mkdir -p docs/ instruction before agent dispatch
- Update all downstream path references: collect_wave_1, collect_wave_2, commit_docs, report, verify tables
- Update sequential_generation wave_1_outputs and resolved path references
- Update success criteria and verify_only_report examples to use docs/ paths
* feat(05-02): add CONTRIBUTING confirmation gate and existing doc review queue
- Add CONTRIBUTING.md user confirmation prompt in build_doc_queue (skipped with --force or when file exists)
- Add review_queue for non-canonical existing docs (verification only, not rewriting)
- Add review_queue verification in verify_docs step with fix_loop exclusion
- Add existing doc accuracy review section to report step with manual correction guidance
* docs(05-02): complete path table inversion and doc queue improvements plan
- Add 05-02-SUMMARY.md with execution results
- Update STATE.md with position, decisions, and metrics
- Update ROADMAP.md with phase 05 plan progress
* fix(05): replace plain text y/n prompts with AskUserQuestion in docs-update workflow
Three prompts were using plain text (y/n) instead of GSD's standard
AskUserQuestion pattern: CONTRIBUTING.md confirmation, doc queue
proceed gate, and secrets scan confirmation.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(05): structure-aware paths, non-canonical doc fixes, and gap detection
- resolve_modes now inspects existing doc directory structure and places
new docs in matching subdirectories (e.g., docs/architecture/ if that
pattern exists), instead of dumping everything flat into docs/
- Non-canonical docs with inaccuracies are now sent to gsd-doc-writer
in fix mode for surgical corrections, not just reported
- Added documentation gap detection step that scans the codebase for
undocumented areas and prompts user to create missing docs
- Added type: custom support to gsd-doc-writer with template_custom
section for gap-detected documentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(05): smarter structure-aware path resolution for grouped doc directories
When a project uses grouped subdirectories (docs/architecture/,
docs/api/, docs/guides/), ALL canonical docs must be placed in
appropriate groups — none left flat in docs/. Added resolution
chain per doc type with fallback creation. Filenames now match
existing naming style (lowercase-kebab vs UPPERCASE). Queue
presentation shows actual resolved paths, not defaults.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(05): restore mode resolution table as primary queue presentation
The table showing resolved paths, modes, and sources for each doc
must be displayed before the proceed/abort confirmation. It was
replaced by a simple list — now restored as the canonical queue view.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(05): use table format for existing docs review queue presentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(05): add work manifest for structured handoffs between workflow steps
Root cause from smoke test: orchestrator forgot to verify 45 non-canonical
docs because the review_queue had no structural scaffolding — it existed
only in orchestrator memory. Fix:
1. Write docs-work-manifest.json to .planning/tmp/ after resolve_modes
with all canonical_queue, review_queue, and gap_queue items
2. Every subsequent step (dispatch, collect, verify, fix_loop, report)
MUST read the manifest first — single source of truth
3. Restructured verify_docs into explicit Phase 1 (canonical) and
Phase 2 (non-canonical) with separate dispatch for each
4. Both queues now eligible for fix_loop corrections
5. Added manifest read instructions to all dispatch/collect steps
Follows the same pattern as execute-phase's phase-plan-index for
tracking work items across multi-step orchestration.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(05): update workflow purpose to reflect full command scope
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(05): remove redundant steps from docs-update workflow
- Remove validate_agents step (if command is available, agents are installed)
- Remove agents_installed/missing_agents extraction from init_context
- Remove available_agent_types block (agent types specified in each Task call)
- Remove detect_runtime_capabilities step (runtime knows its own tools)
- Replace hardcoded flat paths in collect_wave_1/2 with manifest resolved_paths
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(05): restore available_agent_types section required by test suite
Test enforces that workflows spawning named agents must declare them
in an <available_agent_types> block. Added back with both gsd-doc-writer
and gsd-doc-verifier listed.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Research agents must now tag every factual claim with its source:
[VERIFIED], [CITED], or [ASSUMED]. An Assumptions Log section in
RESEARCH.md collects all [ASSUMED] claims so downstream agents and
users can identify decisions that need confirmation before execution.
Prevents unvalidated assumptions (e.g. "audit logs should be permanent")
from propagating unchallenged through research → planning → execution.
Closes#1431
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The verifier's Step 2 previously used Option A (PLAN frontmatter
must_haves) exclusively when present, skipping Option B (ROADMAP SCs).
This allowed planners to define a subset of must_haves, silently
bypassing roadmap Success Criteria verification.
Now ROADMAP SCs are always loaded first (Step 2a), PLAN must_haves
are merged on top (Step 2b), and a merge step (Step 2c) ensures
plan-authored must_haves can add but never subtract from the roadmap
contract.
Addresses #1418 (Gap 2)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The verifier agent could set status: passed even when the report contained
a non-empty "Human Verification Required" section. This bypassed the
human_needed → HUMAN-UAT.md → user approval gate, allowing phases to be
marked complete without human testing.
Replace the advisory status descriptions with an ordered decision tree
(most restrictive first): gaps_found → human_needed → passed. The passed
status is now only valid when zero human verification items exist.
Synced the same decision tree in the verify-phase workflow.
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>
- gsd-security-auditor.md: replace <threat_register> with <threat_model>
(stale tag name inconsistent with every other file in the PR)
- verify-work.md: parse threats_open from SECURITY.md frontmatter when
file exists; block if > 0, matching execute-phase.md gate logic
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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>
