--full now enables discussion + research + plan-checking + verification.
New --validate flag covers what --full previously did (plan-checking +
verification only). All downstream workflow logic uses $VALIDATE_MODE.
Closes#1498
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Executor constraints now prohibit committing docs artifacts (SUMMARY.md,
STATE.md, PLAN.md) — these are the orchestrator's responsibility in
Step 8. Step 8 now explicitly stages all artifacts with git add before
calling gsd-tools commit, and documents that it must always run even if
the executor already committed some files.
This prevents PLAN.md from being left untracked when the executor runs
without worktree isolation (e.g. local repos with no remote, or when
workflow.use_worktrees is false).
Closes#1503
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Executor agents spawned with isolation="worktree" committed to temporary
branches in separate working trees, but no step existed to merge those
changes back or clean up. This left orphan worktrees and unmerged
branches after every execution.
Changes:
- execute-phase.md: add step 4.5 "Worktree cleanup" after wave
completion — merges worktree branch, removes worktree, deletes temp
branch. Handles merge conflicts gracefully.
- quick.md: add worktree cleanup step after executor returns, before
summary verification
- Both workflows skip cleanup when workflow.use_worktrees is false
- Both workflows skip silently when no worktrees are found
Closes#1496
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds `workflow.use_worktrees` config option (default: `true`) that
allows users to disable git worktree isolation for executor agents.
When set to `false`:
- Executor agents run without `isolation="worktree"`
- Plans execute sequentially on the main working tree
- No worktree merge ordering issues or orphaned worktrees
- Normal git hooks run (no --no-verify needed)
This provides an escape hatch for solo developers and users who
experience worktree merge conflicts, as worktree ordering issues
are inherently difficult when parallel agents modify overlapping
files.
Usage:
/gsd:settings → set workflow.use_worktrees to false
Or directly:
gsd-tools config-set workflow.use_worktrees false
Changes:
- config.cjs: add workflow.use_worktrees to valid keys
- planning-config.md: document the option
- execute-phase.md: read config, conditional worktree + sequential mode
- execute-plan.md: conditional worktree in Pattern A
- quick.md: conditional worktree for quick executor
- diagnose-issues.md: conditional worktree for debug agents
- 2 new tests (config set + workflow structural check)
Closes#1451
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add agent_skills config section that maps agent types to skill directory
paths. At spawn time, workflows load configured skills and inject them
as <agent_skills> blocks in Task() prompts, giving subagents access to
project-specific skill files.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
PR #1139 added <available_agent_types> sections to execute-phase.md and
plan-phase.md to prevent /clear from causing silent fallback to
general-purpose. However, 14 other workflows and 2 commands that also
spawn named GSD agents were missed, leaving them vulnerable to the same
regression after /clear.
Added <available_agent_types> listing to: research-phase, quick,
audit-milestone, diagnose-issues, discuss-phase-assumptions,
execute-plan, map-codebase, new-milestone, new-project, ui-phase,
ui-review, validate-phase, verify-work (workflows) and debug,
research-phase (commands).
Added regression test that enforces every workflow/command spawning
named subagent_type must have a matching <available_agent_types>
section listing all spawned types.
Fixes#1357
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
All code-writing agents (gsd-executor, gsd-debugger) were dispatched
without isolation: "worktree", causing branch pollution when agents
switched branches in the shared working tree during concurrent work.
Added isolation="worktree" to all Task() dispatch sites:
- execute-phase.md: executor agent dispatch
- execute-plan.md: Pattern A executor reference
- quick.md: quick task executor dispatch
- diagnose-issues.md: debugger agent dispatch
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Enable multiple Claude Code instances to work on the same codebase
simultaneously by scoping .planning/ state into workstreams.
Core changes:
- planningDir(cwd, ws?) and planningPaths(cwd, ws?) are now workstream-aware
via GSD_WORKSTREAM env var (auto-detected from --ws flag or active-workstream file)
- All bin/lib modules use planningDir(cwd) for scoped paths (STATE.md, ROADMAP.md,
phases/, REQUIREMENTS.md) and planningRoot(cwd) for shared paths (milestones/,
PROJECT.md, config.json, codebase/)
- New workstream.cjs module: create, list, status, complete, set, get, progress
- gsd-tools.cjs: --ws flag parsing with priority chain
(--ws > GSD_WORKSTREAM env > active-workstream file > flat mode)
- Collision detection: transition.md checks for other active workstreams before
suggesting next-milestone continuation (prevents WS A from trampling WS B)
- ${GSD_WS} routing propagation across all 9 workflow files ensures workstream
scope chains automatically through the workflow lifecycle
New files:
- get-shit-done/bin/lib/workstream.cjs (CRUD + collision detection)
- get-shit-done/commands/gsd/workstreams.md (slash command)
- get-shit-done/references/workstream-flag.md (documentation)
- tests/workstream.test.cjs (20 tests covering CRUD, env var routing, --ws flag)
All 1062 tests passing (1042 existing + 20 new workstream tests).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add composable --research flag to /gsd:quick that spawns a focused
gsd-phase-researcher before planning. Investigates implementation
approaches, library options, and pitfalls for the task.
Addresses the middle-ground gap between quick (no quality agents) and
full milestone workflows. All three flags are composable:
--discuss --research --full gives the complete quality pipeline.
Made-with: Cursor
Co-authored-by: ralberts3 <ralberts3@gatech.edu>
Quick task IDs were sequential integers (001, 002...) computed by reading
the local .planning/quick/ directory max value. Two users running /gsd:quick
simultaneously would get the same number, causing directory collisions on git.
Replace with a collision-resistant format: YYMMDD-xxx where xxx is the
number of 2-second blocks elapsed since midnight, encoded as 3 lowercase
Base36 characters (000–xbz). Practical collision window is ~2 seconds per
user — effectively zero for any realistic team workflow.
- init.cjs: remove nextNum scan logic, generate quickId from wall clock
- quick.md: rename all next_num refs to quick_id, update directory patterns
- init.test.cjs: rewrite cmdInitQuick tests for new ID format
Co-authored-by: yanbing <yanbing@corp.netease.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.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>
Surfaces gray areas and captures user decisions in CONTEXT.md before
planning, reducing hallucination risk for ambiguous quick tasks.
Composable with --full for discussion + plan-checking + verification.
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>
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>
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>
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>
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>
Claude Code v2.1.27+ has a bug where all Task tool agents report
"failed" due to `classifyHandoffIfNeeded is not defined` — a function
called but never defined in the cli.js bundle. The error fires AFTER
all agent work completes, so actual work is always done.
This adds spot-check fallback logic to execute-phase, execute-plan,
and quick workflows: when an agent reports this specific failure,
verify artifacts on disk (SUMMARY.md exists, git commits present).
If spot-checks pass, treat as successful.
Tracked upstream: anthropics/claude-code#24181
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
