* refactor(#1852): lazy-split plan-phase.md into steps/ Extract 3 self-contained, rarely-hit sections into gsd-core/workflows/plan-phase/steps/ via lazy 'Read and execute' pointers (mirrors execute-phase/steps/, ADR-1610 progressive disclosure — no eager @-import): closed-phase-gate (1.5), prd-express-path (3.5), windows-troubleshooting. Byte-invariant: plan-phase.md 94459 -> 89775 (-4684), each step < 32 KiB anchor, resolved instructions unchanged. Scope note: only 3 sections were extractable. plan-phase.md is guarded by a dense net of content-presence tests (plan-bounce/enh-3209/phase6-planning-capabilities assert specific sections/flags inline) that block extracting the larger blocks without also refactoring those tests — durable low-80s headroom is deferred pending maintainer re-scope (issue #1852). Cascade: size:baseline regen, 16 golden-install-parity fixtures regen, INVENTORY in sync. Full plan-phase test surface green (4129/4130, 0 fail); lint:ci exit 0. * docs(changeset): Changed fragment for #1934 (plan-phase lazy-split) * docs(changeset): mark #1934 fragment docs-exempt (internal workflow refactor) * fix(#1852): add gsd_run launcher preamble to prd-express-path step The extracted prd-express-path.md calls gsd_run but the canonical launcher preamble lived in the parent plan-phase.md — runtime-launcher-parity (#373) walks workflows/ recursively and requires every .md using gsd_run to carry exactly one preamble + the $HOME/.claude fallback arm (same as the existing execute-phase/steps/ files). Injected via scripts/sync-runtime-launcher.cjs; golden fixtures + size baseline regenerated. plan-phase.md unchanged (89775). --------- Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
This commit is contained in:
Rezolv
7
.changeset/rapid-orcas-sing.md
Normal file
7
.changeset/rapid-orcas-sing.md
Normal file
@@ -0,0 +1,7 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 1934
|
||||
---
|
||||
**Lazy-split `plan-phase.md` into a `steps/` directory** — ~4.7 KB lighter eager context per `/gsd-plan-phase` call via byte-invariant progressive disclosure (ADR-1610). (#1852)
|
||||
|
||||
<!-- docs-exempt: internal workflow structure refactor; byte-invariant lazy extraction (ADR-1610), no user-facing behavior or doc change -->
|
||||
@@ -91,46 +91,7 @@ Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_
|
||||
|
||||
## 1.5. Closed-Phase Gate (#3569)
|
||||
|
||||
The init JSON includes `phase_status` — one of `Pending | Planned | In Progress | Executed | Complete | Needs Review`. `Complete` means the phase has all summaries AND a `VERIFICATION.md` with `status: passed`. Replanning a closed phase silently rewrites plan docs that no longer match the shipped code, so the workflow must hard-stop here unless the operator explicitly overrides.
|
||||
|
||||
Parse `phase_status` from the init JSON, then:
|
||||
|
||||
```bash
|
||||
FORCE_REPLAN=false
|
||||
if [[ "$ARGUMENTS" =~ (^|[[:space:]])--force([[:space:]]|$) ]]; then
|
||||
FORCE_REPLAN=true
|
||||
fi
|
||||
|
||||
if [ "${phase_status}" = "Complete" ]; then
|
||||
if [[ "$ARGUMENTS" =~ (^|[[:space:]])--reviews([[:space:]]|$) ]]; then
|
||||
# --reviews on a closed phase is never legitimate — concerns belong in a
|
||||
# new phase or issue against the closed phase's commits.
|
||||
cat <<EOF >&2
|
||||
Phase ${phase_number} (${phase_name}) is already CLOSED (VERIFICATION status: passed).
|
||||
/gsd:plan-phase --reviews cannot replan a closed phase. If the review surfaced
|
||||
real concerns, open a follow-up phase or file an issue against the closed
|
||||
phase's commits. There is no --force override for --reviews on a closed phase.
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
if [ "$FORCE_REPLAN" != "true" ]; then
|
||||
cat <<EOF >&2
|
||||
Phase ${phase_number} (${phase_name}) is already CLOSED (VERIFICATION status: passed).
|
||||
Replanning a closed phase will overwrite plan docs that no longer match the
|
||||
shipped code. If you intentionally want to replan over closed work, re-run
|
||||
with: /gsd:plan-phase ${phase_number} --force
|
||||
|
||||
Otherwise, to view what shipped, see: ${verification_path}
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
# FORCE_REPLAN=true: continue, but emit a banner so the operator sees the
|
||||
# decision in the transcript and in any committed plan docs.
|
||||
echo "WARNING: Replanning CLOSED phase ${phase_number} under --force. Verify the closeout was wrong before committing new plan docs." >&2
|
||||
fi
|
||||
```
|
||||
|
||||
The gate fires only on `Complete`. `Executed` and `Needs Review` are not gated — those states mean planning was finished but verification did not pass, and replanning is a legitimate next step.
|
||||
Read and execute `gsd-core/workflows/plan-phase/steps/closed-phase-gate.md` — it parses `phase_status` from the init JSON, sets `FORCE_REPLAN` from `$ARGUMENTS`, and hard-stops replanning a `Complete` phase: `--reviews` on a closed phase is never overridable (exit 1), and replanning otherwise requires `--force` (else exit 1, pointing at `${verification_path}`); under `--force` it continues but emits a WARNING banner. Only `Complete` is gated — `Executed` / `Needs Review` are legitimate replans.
|
||||
|
||||
## 2. Parse and Normalize Arguments
|
||||
|
||||
@@ -249,103 +210,7 @@ MVP_MODE=$(gsd_run query phase.mvp-mode "${PHASE}" $MVP_FLAG_ARG --pick active)
|
||||
|
||||
**If `--prd <filepath>` provided:**
|
||||
|
||||
1. Read the PRD file:
|
||||
```bash
|
||||
PRD_CONTENT=$(cat "$PRD_FILE" 2>/dev/null)
|
||||
if [ -z "$PRD_CONTENT" ]; then
|
||||
echo "Error: PRD file not found: $PRD_FILE"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
2. Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► PRD EXPRESS PATH
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Using PRD: {PRD_FILE}
|
||||
Generating CONTEXT.md from requirements...
|
||||
```
|
||||
|
||||
3. Parse the PRD content and generate CONTEXT.md. The orchestrator should:
|
||||
- Extract all requirements, user stories, acceptance criteria, and constraints from the PRD
|
||||
- Map each to a locked decision (everything in the PRD is treated as a locked decision)
|
||||
- Identify any areas the PRD doesn't cover and mark as "Claude's Discretion"
|
||||
- **Extract canonical refs** from ROADMAP.md for this phase, plus any specs/ADRs referenced in the PRD — expand to full file paths (MANDATORY)
|
||||
- Create CONTEXT.md in the phase directory
|
||||
|
||||
4. Write CONTEXT.md:
|
||||
```markdown
|
||||
# Phase [X]: [Name] - Context
|
||||
|
||||
**Gathered:** [date]
|
||||
**Status:** Ready for planning
|
||||
**Source:** PRD Express Path ({PRD_FILE})
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
[Extracted from PRD — what this phase delivers]
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
{For each requirement/story/criterion in the PRD:}
|
||||
### [Category derived from content]
|
||||
- [Requirement as locked decision]
|
||||
|
||||
### Claude's Discretion
|
||||
[Areas not covered by PRD — implementation details, technical choices]
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
[MANDATORY. Extract from ROADMAP.md and any docs referenced in the PRD.
|
||||
Use full relative paths. Group by topic area.]
|
||||
|
||||
### [Topic area]
|
||||
- `path/to/spec-or-adr.md` — [What it decides/defines]
|
||||
|
||||
[If no external specs: "No external specs — requirements fully captured in decisions above"]
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
[Any specific references, examples, or concrete requirements from PRD]
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
[Items in PRD explicitly marked as future/v2/out-of-scope]
|
||||
[If none: "None — PRD covers phase scope"]
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: XX-name*
|
||||
*Context gathered: [date] via PRD Express Path*
|
||||
```
|
||||
|
||||
5. Commit:
|
||||
```bash
|
||||
gsd_run query commit "docs(${padded_phase}): generate context from PRD" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
|
||||
```
|
||||
|
||||
6. Set `context_content` to the generated CONTEXT.md content and continue to step 5 (Handle Research).
|
||||
|
||||
**Effect:** This completely bypasses step 4 (Load CONTEXT.md) since we just created it. The rest of the workflow (research, planning, verification) proceeds normally with the PRD-derived context.
|
||||
Read and execute `gsd-core/workflows/plan-phase/steps/prd-express-path.md` — it reads the PRD (`$PRD_FILE`), generates `CONTEXT.md` (every PRD requirement/story/criterion → locked decision, uncovered areas → "Claude's Discretion", canonical refs extracted from ROADMAP.md + PRD-referenced specs), commits it, sets `context_content`, and bypasses step 4 (Load CONTEXT.md). The rest of the workflow proceeds normally with the PRD-derived context.
|
||||
|
||||
## 3.6. Handle ADR Ingest Express Path
|
||||
|
||||
@@ -1730,27 +1595,7 @@ Verification: {Passed | Passed with override | Skipped}
|
||||
</offer_next>
|
||||
|
||||
<windows_troubleshooting>
|
||||
**Windows users:** If plan-phase freezes during agent spawning (common on Windows due to
|
||||
stdio deadlocks with MCP servers — see Claude Code issue anthropics/claude-code#28126):
|
||||
|
||||
1. **Force-kill:** Close the terminal (Ctrl+C may not work)
|
||||
2. **Clean up orphaned processes:**
|
||||
```powershell
|
||||
# Kill orphaned node processes from stale MCP servers
|
||||
Get-Process node -ErrorAction SilentlyContinue | Where-Object {$_.StartTime -lt (Get-Date).AddHours(-1)} | Stop-Process -Force
|
||||
```
|
||||
3. **Clean up stale task directories:**
|
||||
```powershell
|
||||
# Remove stale subagent task dirs (Claude Code never cleans these on crash)
|
||||
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\tasks\*" -ErrorAction SilentlyContinue
|
||||
```
|
||||
4. **Reduce MCP server count:** Temporarily disable non-essential MCP servers in settings.json
|
||||
5. **Retry:** Restart Claude Code and run `/gsd:plan-phase` again
|
||||
|
||||
If freezes persist, try `--skip-research` to reduce the agent chain from 3 to 2 agents:
|
||||
```
|
||||
/gsd:plan-phase N --skip-research
|
||||
```
|
||||
Read `gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md` if plan-phase freezes on Windows during agent spawning (stdio deadlocks with MCP servers, anthropics/claude-code#28126) — it covers force-kill, orphaned-node cleanup, stale task-dir cleanup, reducing the MCP server count, and the `--skip-research` fallback.
|
||||
</windows_troubleshooting>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
42
gsd-core/workflows/plan-phase/steps/closed-phase-gate.md
Normal file
42
gsd-core/workflows/plan-phase/steps/closed-phase-gate.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Closed-Phase Gate (#3569)
|
||||
|
||||
The init JSON includes `phase_status` — one of `Pending | Planned | In Progress | Executed | Complete | Needs Review`. `Complete` means the phase has all summaries AND a `VERIFICATION.md` with `status: passed`. Replanning a closed phase silently rewrites plan docs that no longer match the shipped code, so the workflow must hard-stop here unless the operator explicitly overrides.
|
||||
|
||||
Parse `phase_status` from the init JSON, then:
|
||||
|
||||
```bash
|
||||
FORCE_REPLAN=false
|
||||
if [[ "$ARGUMENTS" =~ (^|[[:space:]])--force([[:space:]]|$) ]]; then
|
||||
FORCE_REPLAN=true
|
||||
fi
|
||||
|
||||
if [ "${phase_status}" = "Complete" ]; then
|
||||
if [[ "$ARGUMENTS" =~ (^|[[:space:]])--reviews([[:space:]]|$) ]]; then
|
||||
# --reviews on a closed phase is never legitimate — concerns belong in a
|
||||
# new phase or issue against the closed phase's commits.
|
||||
cat <<EOF >&2
|
||||
Phase ${phase_number} (${phase_name}) is already CLOSED (VERIFICATION status: passed).
|
||||
/gsd:plan-phase --reviews cannot replan a closed phase. If the review surfaced
|
||||
real concerns, open a follow-up phase or file an issue against the closed
|
||||
phase's commits. There is no --force override for --reviews on a closed phase.
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
if [ "$FORCE_REPLAN" != "true" ]; then
|
||||
cat <<EOF >&2
|
||||
Phase ${phase_number} (${phase_name}) is already CLOSED (VERIFICATION status: passed).
|
||||
Replanning a closed phase will overwrite plan docs that no longer match the
|
||||
shipped code. If you intentionally want to replan over closed work, re-run
|
||||
with: /gsd:plan-phase ${phase_number} --force
|
||||
|
||||
Otherwise, to view what shipped, see: ${verification_path}
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
# FORCE_REPLAN=true: continue, but emit a banner so the operator sees the
|
||||
# decision in the transcript and in any committed plan docs.
|
||||
echo "WARNING: Replanning CLOSED phase ${phase_number} under --force. Verify the closeout was wrong before committing new plan docs." >&2
|
||||
fi
|
||||
```
|
||||
|
||||
The gate fires only on `Complete`. `Executed` and `Needs Review` are not gated — those states mean planning was finished but verification did not pass, and replanning is a legitimate next step.
|
||||
102
gsd-core/workflows/plan-phase/steps/prd-express-path.md
Normal file
102
gsd-core/workflows/plan-phase/steps/prd-express-path.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# PRD Express Path — generate CONTEXT.md from a PRD
|
||||
|
||||
Runs when `--prd <filepath>` is provided (§3.5 of `plan-phase.md`).
|
||||
|
||||
1. Read the PRD file:
|
||||
```bash
|
||||
PRD_CONTENT=$(cat "$PRD_FILE" 2>/dev/null)
|
||||
if [ -z "$PRD_CONTENT" ]; then
|
||||
echo "Error: PRD file not found: $PRD_FILE"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
2. Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► PRD EXPRESS PATH
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Using PRD: {PRD_FILE}
|
||||
Generating CONTEXT.md from requirements...
|
||||
```
|
||||
|
||||
3. Parse the PRD content and generate CONTEXT.md. The orchestrator should:
|
||||
- Extract all requirements, user stories, acceptance criteria, and constraints from the PRD
|
||||
- Map each to a locked decision (everything in the PRD is treated as a locked decision)
|
||||
- Identify any areas the PRD doesn't cover and mark as "Claude's Discretion"
|
||||
- **Extract canonical refs** from ROADMAP.md for this phase, plus any specs/ADRs referenced in the PRD — expand to full file paths (MANDATORY)
|
||||
- Create CONTEXT.md in the phase directory
|
||||
|
||||
4. Write CONTEXT.md:
|
||||
```markdown
|
||||
# Phase [X]: [Name] - Context
|
||||
|
||||
**Gathered:** [date]
|
||||
**Status:** Ready for planning
|
||||
**Source:** PRD Express Path ({PRD_FILE})
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
[Extracted from PRD — what this phase delivers]
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
{For each requirement/story/criterion in the PRD:}
|
||||
### [Category derived from content]
|
||||
- [Requirement as locked decision]
|
||||
|
||||
### Claude's Discretion
|
||||
[Areas not covered by PRD — implementation details, technical choices]
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
[MANDATORY. Extract from ROADMAP.md and any docs referenced in the PRD.
|
||||
Use full relative paths. Group by topic area.]
|
||||
|
||||
### [Topic area]
|
||||
- `path/to/spec-or-adr.md` — [What it decides/defines]
|
||||
|
||||
[If no external specs: "No external specs — requirements fully captured in decisions above"]
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
[Any specific references, examples, or concrete requirements from PRD]
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
[Items in PRD explicitly marked as future/v2/out-of-scope]
|
||||
[If none: "None — PRD covers phase scope"]
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: XX-name*
|
||||
*Context gathered: [date] via PRD Express Path*
|
||||
```
|
||||
|
||||
5. Commit:
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
|
||||
gsd_run query commit "docs(${padded_phase}): generate context from PRD" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
|
||||
```
|
||||
|
||||
6. Set `context_content` to the generated CONTEXT.md content and continue to step 5 (Handle Research).
|
||||
|
||||
**Effect:** This completely bypasses step 4 (Load CONTEXT.md) since we just created it. The rest of the workflow (research, planning, verification) proceeds normally with the PRD-derived context.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Windows Troubleshooting
|
||||
|
||||
**Windows users:** If plan-phase freezes during agent spawning (common on Windows due to
|
||||
stdio deadlocks with MCP servers — see Claude Code issue anthropics/claude-code#28126):
|
||||
|
||||
1. **Force-kill:** Close the terminal (Ctrl+C may not work)
|
||||
2. **Clean up orphaned processes:**
|
||||
```powershell
|
||||
# Kill orphaned node processes from stale MCP servers
|
||||
Get-Process node -ErrorAction SilentlyContinue | Where-Object {$_.StartTime -lt (Get-Date).AddHours(-1)} | Stop-Process -Force
|
||||
```
|
||||
3. **Clean up stale task directories:**
|
||||
```powershell
|
||||
# Remove stale subagent task dirs (Claude Code never cleans these on crash)
|
||||
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\tasks\*" -ErrorAction SilentlyContinue
|
||||
```
|
||||
4. **Reduce MCP server count:** Temporarily disable non-essential MCP servers in settings.json
|
||||
5. **Retry:** Restart Claude Code and run `/gsd:plan-phase` again
|
||||
|
||||
If freezes persist, try `--skip-research` to reduce the agent chain from 3 to 2 agents:
|
||||
```
|
||||
/gsd:plan-phase N --skip-research
|
||||
```
|
||||
@@ -264,7 +264,10 @@
|
||||
"gsd-core/workflows/note.md": "3ce09c0aa0a20599",
|
||||
"gsd-core/workflows/pause-work.md": "3196d681d4dd8c71",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "94b193dfc9ca3681",
|
||||
"gsd-core/workflows/plan-phase.md": "fde84f67730f7131",
|
||||
"gsd-core/workflows/plan-phase.md": "659b52bd338720fe",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "4099ef6d0868de60",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "473d4d6e5b1f6340",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "e9de7a96bbfff261",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "b1623082557cdca5",
|
||||
"gsd-core/workflows/plant-seed.md": "1fb45cd49f66f572",
|
||||
"gsd-core/workflows/pr-branch.md": "c8fd9fa250cb39fd",
|
||||
|
||||
@@ -333,7 +333,10 @@
|
||||
"gsd-core/workflows/note.md": "5a99eb396c744619",
|
||||
"gsd-core/workflows/pause-work.md": "7bcbdf27ba957c8b",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "02fee851c82e3b25",
|
||||
"gsd-core/workflows/plan-phase.md": "5e3c949ca65cd672",
|
||||
"gsd-core/workflows/plan-phase.md": "dc0beefd1316a860",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "b36f77ac7344a072",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "d64097345ffac40d",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "49f58c3f75be3eb5",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "10007f8382864bcd",
|
||||
"gsd-core/workflows/plant-seed.md": "7b795d7a1b4c9f06",
|
||||
"gsd-core/workflows/pr-branch.md": "f2a35833fe784a53",
|
||||
|
||||
@@ -263,7 +263,10 @@
|
||||
"gsd-core/workflows/note.md": "42b66686b2c102cb",
|
||||
"gsd-core/workflows/pause-work.md": "0be71264eafd16dc",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "1976bf2001969719",
|
||||
"gsd-core/workflows/plan-phase.md": "b0373c2198f4acf7",
|
||||
"gsd-core/workflows/plan-phase.md": "f0401a3221b74b58",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "4099ef6d0868de60",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "d64097345ffac40d",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "e9de7a96bbfff261",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "414df04b7ddff73c",
|
||||
"gsd-core/workflows/plant-seed.md": "936a848f1d6c409e",
|
||||
"gsd-core/workflows/pr-branch.md": "c8827e8a15426bf5",
|
||||
|
||||
@@ -267,7 +267,10 @@
|
||||
"gsd-core/workflows/note.md": "5a99eb396c744619",
|
||||
"gsd-core/workflows/pause-work.md": "9c1acf8c30a244fd",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "95ca791b0867fe2d",
|
||||
"gsd-core/workflows/plan-phase.md": "ab9ed0b5acfe7d8a",
|
||||
"gsd-core/workflows/plan-phase.md": "e4256d987d376112",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "b36f77ac7344a072",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "ae59c247ad4a57d2",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "090c31e22b1508fe",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "2cdba6216184aac4",
|
||||
"gsd-core/workflows/plant-seed.md": "d0d63f83ae7c939b",
|
||||
"gsd-core/workflows/pr-branch.md": "15ccec6bd303ea46",
|
||||
|
||||
@@ -333,7 +333,10 @@
|
||||
"gsd-core/workflows/note.md": "5a99eb396c744619",
|
||||
"gsd-core/workflows/pause-work.md": "7bcbdf27ba957c8b",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "02fee851c82e3b25",
|
||||
"gsd-core/workflows/plan-phase.md": "58d02dbdb533603a",
|
||||
"gsd-core/workflows/plan-phase.md": "9fc35fa37928c14e",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "b36f77ac7344a072",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "d64097345ffac40d",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "49f58c3f75be3eb5",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "10007f8382864bcd",
|
||||
"gsd-core/workflows/plant-seed.md": "7b795d7a1b4c9f06",
|
||||
"gsd-core/workflows/pr-branch.md": "f2a35833fe784a53",
|
||||
|
||||
@@ -299,7 +299,10 @@
|
||||
"gsd-core/workflows/note.md": "664da466ab989f9d",
|
||||
"gsd-core/workflows/pause-work.md": "3c2ee96295959527",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "8ee841bcc7adc836",
|
||||
"gsd-core/workflows/plan-phase.md": "f9a1846e30603d38",
|
||||
"gsd-core/workflows/plan-phase.md": "5d3ed552933f81da",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "d838b87563feedf6",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "44a12264f8b61d03",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "f5edc589cab52a7b",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "f27818025e279aa4",
|
||||
"gsd-core/workflows/plant-seed.md": "bfa729ff2ad3441a",
|
||||
"gsd-core/workflows/pr-branch.md": "3b13915429c0e8d9",
|
||||
|
||||
@@ -265,7 +265,10 @@
|
||||
"gsd-core/workflows/note.md": "4a5ee74cf2fc1f54",
|
||||
"gsd-core/workflows/pause-work.md": "324e04e675dc7f7f",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "c0eb896eb42e22d4",
|
||||
"gsd-core/workflows/plan-phase.md": "16ff6a162cbd4c01",
|
||||
"gsd-core/workflows/plan-phase.md": "371be4167168d461",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "4099ef6d0868de60",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "d911a080dc1cece6",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "e9de7a96bbfff261",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "c238b5858ceb4e57",
|
||||
"gsd-core/workflows/plant-seed.md": "56451bdf104983b3",
|
||||
"gsd-core/workflows/pr-branch.md": "a080aed95785cf32",
|
||||
|
||||
@@ -333,7 +333,10 @@
|
||||
"gsd-core/workflows/note.md": "1c1e466c764e3deb",
|
||||
"gsd-core/workflows/pause-work.md": "0be71264eafd16dc",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "1976bf2001969719",
|
||||
"gsd-core/workflows/plan-phase.md": "1f40b9c15ebef2ff",
|
||||
"gsd-core/workflows/plan-phase.md": "ba95020c3495b191",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "e06ccd4d4c0703fb",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "d64097345ffac40d",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "3bed01c3c906ac52",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "783c5171101b26b9",
|
||||
"gsd-core/workflows/plant-seed.md": "b28224f37faa9b95",
|
||||
"gsd-core/workflows/pr-branch.md": "1f77535b6b156ad9",
|
||||
|
||||
@@ -333,7 +333,10 @@
|
||||
"gsd-core/workflows/note.md": "95199087905ba3e6",
|
||||
"gsd-core/workflows/pause-work.md": "7bcbdf27ba957c8b",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "02fee851c82e3b25",
|
||||
"gsd-core/workflows/plan-phase.md": "81c6ef4292e5f9bf",
|
||||
"gsd-core/workflows/plan-phase.md": "3fe02a5fc860bb46",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "b36f77ac7344a072",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "d64097345ffac40d",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "49f58c3f75be3eb5",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "57c284df29121220",
|
||||
"gsd-core/workflows/plant-seed.md": "339890021123e017",
|
||||
"gsd-core/workflows/pr-branch.md": "f2a35833fe784a53",
|
||||
|
||||
@@ -264,7 +264,10 @@
|
||||
"gsd-core/workflows/note.md": "42b66686b2c102cb",
|
||||
"gsd-core/workflows/pause-work.md": "2c3abcaa1fa6d2e2",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "419744c1191354af",
|
||||
"gsd-core/workflows/plan-phase.md": "ad2d30c92b495bcb",
|
||||
"gsd-core/workflows/plan-phase.md": "e1dcabd0499a03f9",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "4099ef6d0868de60",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "99949122a3bd455e",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "62f8e4f3b475fe5f",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "8ebcd05fcd5a0d15",
|
||||
"gsd-core/workflows/plant-seed.md": "76379e2aeb18d53b",
|
||||
"gsd-core/workflows/pr-branch.md": "79f4d93e31af9c49",
|
||||
|
||||
@@ -333,7 +333,10 @@
|
||||
"gsd-core/workflows/note.md": "f8c2842a2217f776",
|
||||
"gsd-core/workflows/pause-work.md": "8b81699a46ca8e9b",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "1976bf2001969719",
|
||||
"gsd-core/workflows/plan-phase.md": "38d57cf05c12ab50",
|
||||
"gsd-core/workflows/plan-phase.md": "a7642fb6484cf12e",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "4099ef6d0868de60",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "44a12264f8b61d03",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "e9de7a96bbfff261",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "88e294a5cc616e90",
|
||||
"gsd-core/workflows/plant-seed.md": "249d3c6b4d474106",
|
||||
"gsd-core/workflows/pr-branch.md": "c8827e8a15426bf5",
|
||||
|
||||
@@ -300,7 +300,10 @@
|
||||
"gsd-core/workflows/note.md": "5a99eb396c744619",
|
||||
"gsd-core/workflows/pause-work.md": "7bcbdf27ba957c8b",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "02fee851c82e3b25",
|
||||
"gsd-core/workflows/plan-phase.md": "f40fb8f961a35925",
|
||||
"gsd-core/workflows/plan-phase.md": "e69e435b47d77070",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "b36f77ac7344a072",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "d64097345ffac40d",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "49f58c3f75be3eb5",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "10007f8382864bcd",
|
||||
"gsd-core/workflows/plant-seed.md": "7b795d7a1b4c9f06",
|
||||
"gsd-core/workflows/pr-branch.md": "f2a35833fe784a53",
|
||||
|
||||
@@ -333,7 +333,10 @@
|
||||
"gsd-core/workflows/note.md": "0d1374f2a2257858",
|
||||
"gsd-core/workflows/pause-work.md": "c9f0b8826845dda7",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "5ec459734bf7570c",
|
||||
"gsd-core/workflows/plan-phase.md": "6db3e766b7703874",
|
||||
"gsd-core/workflows/plan-phase.md": "03745f51d63d99b8",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "4099ef6d0868de60",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "fa7f29c323f4cb57",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "e9de7a96bbfff261",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "4f884d793d72d3fd",
|
||||
"gsd-core/workflows/plant-seed.md": "507e886d0f70d84c",
|
||||
"gsd-core/workflows/pr-branch.md": "3abaa18246facdc3",
|
||||
|
||||
@@ -264,7 +264,10 @@
|
||||
"gsd-core/workflows/note.md": "42b66686b2c102cb",
|
||||
"gsd-core/workflows/pause-work.md": "54f1c0a9e79e2c59",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "1b820f4e70acce86",
|
||||
"gsd-core/workflows/plan-phase.md": "140b9f4360646c96",
|
||||
"gsd-core/workflows/plan-phase.md": "574fc8008416e6a7",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "4099ef6d0868de60",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "451a287826b36227",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "d050d8d551ed1756",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "b809588bff4f48b5",
|
||||
"gsd-core/workflows/plant-seed.md": "e3949fcbcf5d375f",
|
||||
"gsd-core/workflows/pr-branch.md": "95850381230787ed",
|
||||
|
||||
@@ -264,7 +264,10 @@
|
||||
"gsd-core/workflows/note.md": "acc9130fb1e94f0b",
|
||||
"gsd-core/workflows/pause-work.md": "09a6b8980f7b771a",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "022822b3b6971b75",
|
||||
"gsd-core/workflows/plan-phase.md": "9781d27e30242ed8",
|
||||
"gsd-core/workflows/plan-phase.md": "8eddecda8fcd8765",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "e06ccd4d4c0703fb",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "382dac17d70ebfac",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "619946c879f33b9d",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "8fb889570c17db15",
|
||||
"gsd-core/workflows/plant-seed.md": "dc911406ada4d188",
|
||||
"gsd-core/workflows/pr-branch.md": "e939128047e02395",
|
||||
|
||||
@@ -264,7 +264,10 @@
|
||||
"gsd-core/workflows/note.md": "1c1e466c764e3deb",
|
||||
"gsd-core/workflows/pause-work.md": "5ce6a137bd9fc0f8",
|
||||
"gsd-core/workflows/plan-milestone-gaps.md": "19911e87fd4185f2",
|
||||
"gsd-core/workflows/plan-phase.md": "55ddbe990fcaa74f",
|
||||
"gsd-core/workflows/plan-phase.md": "f6e8c5e38d5c5a52",
|
||||
"gsd-core/workflows/plan-phase/steps/closed-phase-gate.md": "e06ccd4d4c0703fb",
|
||||
"gsd-core/workflows/plan-phase/steps/prd-express-path.md": "7c2be59e3e19299a",
|
||||
"gsd-core/workflows/plan-phase/steps/windows-troubleshooting.md": "3fed4740a91d0443",
|
||||
"gsd-core/workflows/plan-review-convergence.md": "7e01c19b7b9a2aad",
|
||||
"gsd-core/workflows/plant-seed.md": "9d36ecd08093a494",
|
||||
"gsd-core/workflows/pr-branch.md": "cc28ab5cd9db16b9",
|
||||
|
||||
@@ -52,7 +52,7 @@
|
||||
"note.md": 6563,
|
||||
"pause-work.md": 14397,
|
||||
"plan-milestone-gaps.md": 11765,
|
||||
"plan-phase.md": 94459,
|
||||
"plan-phase.md": 89775,
|
||||
"plan-review-convergence.md": 23468,
|
||||
"plant-seed.md": 11741,
|
||||
"pr-branch.md": 15919,
|
||||
|
||||
Reference in New Issue
Block a user