Break the 5324-line monolith into focused modules:
- core.cjs: shared utilities, constants, internal helpers
- frontmatter.cjs: YAML frontmatter parsing/serialization/CRUD
- state.cjs: STATE.md operations + progression engine
- phase.cjs: phase CRUD, query, and lifecycle
- roadmap.cjs: roadmap parsing and updates
- verify.cjs: verification suite + consistency/health validation
- config.cjs: config ensure/set/get
- template.cjs: template selection and fill
- milestone.cjs: milestone + requirements lifecycle
- commands.cjs: standalone utility commands
- init.cjs: compound init commands for workflow bootstrapping
gsd-tools.cjs is now a thin CLI router (~550 lines including
JSDoc) that imports from lib/ modules. All 81 tests pass.
Also updates package.json test script to point to tests/.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move 81 tests (18 describe blocks) from single monolithic test file
into 7 domain-specific test files under tests/ with shared helpers.
Test parity verified: 81/81 pass before and after split.
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>
/gsd:health --repair now creates a timestamped backup
(STATE.md.bak-YYYY-MM-DDTHH-MM-SS) before overwriting STATE.md,
preventing accidental data loss of accumulated context.
Co-Authored-By: Claude <noreply@anthropic.com>
Subagents now read project-level CLAUDE.md if it exists:
- Workflows: execute-phase, plan-phase, quick
- Agents: gsd-executor, gsd-planner, gsd-phase-researcher, gsd-plan-checker
Agents read ./CLAUDE.md in their fresh context, following project-specific
guidelines, security requirements, and coding conventions.
Fixes: #671
Co-Authored-By: Claude <noreply@anthropic.com>
gsd-executor had no instruction to update ROADMAP or REQUIREMENTS after
completing a plan — both stayed unchecked throughout milestone execution.
- Add `roadmap update-plan-progress` call to executor state_updates
- Add `requirements mark-complete` CLI command to gsd-tools
- Wire requirement marking into executor and execute-plan workflows
- Include ROADMAP.md and REQUIREMENTS.md in executor final commit
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Closes five gaps where requirements could slip through unchecked at milestone
level: audit now cross-references VERIFICATION.md + SUMMARY frontmatter +
REQUIREMENTS.md traceability, integration checker receives req IDs, gap objects
carry plan-level detail, plan-milestone-gaps updates traceability, and
complete-milestone gates on requirements status.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Tighten all requirements references to use MUST/REQUIRED/CRITICAL language
instead of passive suggestions. Close the verification loop by extracting
phase requirement IDs from ROADMAP and passing them through the full chain:
researcher receives IDs → planner writes to PLAN frontmatter → executor
copies to SUMMARY → verifier cross-references against REQUIREMENTS.md with
orphan detection.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Write workflow.auto_advance to config.json so auto-mode survives
context compaction (re-read from disk on every workflow init)
- Auto-approve human-verify and auto-select first option for decision
checkpoints in both executor and orchestrator
- Pass --auto flag from plan-phase to execute-phase spawn
- Clear auto_advance on milestone complete (Route B)
- Document auto-mode checkpoint behavior in golden rules
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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>
- Auto mode now chains: new-project → discuss-phase 1 → plan → execute → transition
- Accept pasted text OR file reference (not just @ references)
- YOLO mode implicit in --auto (skip that question)
- Config questions (depth, git, agents) asked FIRST in new Step 2a
- Step 5 skipped in auto mode (config already collected)
- Auto-advance banner shown before invoking discuss-phase
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Enables quality guarantees on quick tasks without full milestone ceremony.
--full spawns plan-checker (max 2 iterations) and post-execution verifier,
produces VERIFICATION.md, and adds Status column to STATE.md table.
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>
Document the #1 but... pattern for users who want a modified version
of an existing AskUserQuestion option without retyping it.
Closes#385
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Strip .planning/ from staging before merge commits when commit_docs is
false. Prevents planning files from being committed during milestone
completion even when using branching strategies.
- Add commit_docs to config extraction in handle_branches step
- Reset .planning/ from staging before squash merge commits
- Use --no-commit flag for --no-ff merges to allow reset before commit
- Document branch merge behavior in planning-config.md
Closes#608
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phase directories created by /gsd:add-phase and /gsd:insert-phase were
empty until planning, causing git to ignore them. This prevented syncing
across machines.
Fixes#427
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add optional phase archival to milestone completion and a standalone
/gsd:cleanup command for retroactive use. Phase dirs move to
.planning/milestones/v{X.Y}-phases/, reducing phases/ clutter after
multiple milestones.
Core changes:
- getArchivedPhaseDirs() and searchPhaseInDir() helpers in gsd-tools
- findPhaseInternal() searches archives when phase not found in current
- cmdPhasesList() accepts --include-archived flag
- cmdHistoryDigest() scans both current and archived phases
- cmdMilestoneComplete() accepts --archive-phases flag
- Workflow globs replaced with find-phase/phases-list CLI calls
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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>
Multi-milestone roadmaps use #### for phases nested under milestone
headers. Expanded all phase-matching regexes from #{2,3} to #{2,4}.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New projects seed config from ~/.gsd/defaults.json when available,
skipping the 8 setup questions. /gsd:settings offers to save current
settings as global defaults after configuration.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phase insert failed when zero-padding differed between user input and
ROADMAP.md headers (e.g. "9.05" vs "09.05"). Normalize input and use
flexible regex matching with optional leading zeros.
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>
Allow overriding specific agent models without changing the entire profile.
Add model_overrides key to config that takes precedence over profile lookup.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Three routing fixes:
- transition.md checks for CONTEXT.md before routing — discuss-phase when
missing, plan-phase when present (matches progress.md behavior)
- execute-phase.md offer_next delegates to transition.md instead of emitting
duplicate "Next Up" blocks
- discuss-phase.md adds explicit handling for "Other" free-text responses
Closes#530
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace NL instructions in execute-plan and execute-phase workflows with
deterministic `roadmap update-plan-progress` command that counts PLAN vs
SUMMARY files on disk. Prevents LLM from miscounting plan progress.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add 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 was deriving verification truths from the vague one-line Goal
field, allowing partial implementations to pass. Now extracts Success Criteria
as a structured array from `roadmap get-phase` and uses them directly as truths,
with Goal derivation as fallback for older ROADMAPs without Success Criteria.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
cmdPhaseComplete now updates REQUIREMENTS.md when a phase finishes:
- Checks off requirement checkboxes (- [ ] → - [x])
- Updates traceability table status (Pending → Complete)
Parses Requirements line from ROADMAP.md phase section to find
which REQ-IDs belong to the completing phase.
Fixes#539
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add update_state step to record session info after context gathering,
matching the pattern used by execute-plan, add-todo, and other workflows.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fix hardcoded headers exceeding the 12-character validation limit and
add max-length guidance for dynamically generated headers.
Closes#559
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Claude Code's "opus" alias maps to a specific model version (claude-opus-4-1).
Organizations that block older opus versions while allowing newer ones see
agents silently fall back to Sonnet. By returning "inherit" instead, agents
use whatever opus version the user has configured in their session.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add `close_parent_artifacts` step to execute-phase workflow that resolves
parent UAT gaps and debug sessions when a decimal/polish phase completes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
`init phase-op` only checked disk for phase directories, failing on
phases with Plans: TBD since no directory exists yet. Now falls back
to parsing ROADMAP.md when findPhaseInternal returns null.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Hooks had hardcoded `.claude` paths that broke OpenCode users. The
installer now templates `.js` hooks with runtime-specific config dirs,
same as it already does for `.md` files. Also added `./.claude/`
replacement for local install paths in workflows.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Parser now accepts both `## Phase X:` and `### Phase X:` headers
- `roadmap get-phase` detects when phases exist in summary list but
missing detail sections, returns `error: 'malformed_roadmap'`
- `roadmap analyze` returns `missing_phase_details` array
- Updated gsd-roadmapper instructions with explicit format requirements
- Added 2 tests for new functionality (77 total, all passing)
Closes#598, closes#599
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>
- Add `websearch` command to gsd-tools.js for Brave API
- Detect BRAVE_API_KEY env var or ~/.gsd/brave_api_key file
- Persist brave_search setting to config.json on project init
- Update researcher agents to check config before calling
Graceful degradation: if brave_search is false, agents use
built-in WebSearch without wasted Bash calls.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
