Merge pull request #1196 from trek-e/fix/windows-subagent-timeout-732

get-shit-done/workflows/health.md

@@ -157,3 +157,25 @@ Report final status.
 - Orphaned plan cleanup
 
 </repair_actions>
+
+<stale_task_cleanup>
+**Windows-specific:** Check for stale Claude Code task directories that accumulate on crash/freeze.
+These are left behind when subagents are force-killed and consume disk space.
+
+When `--repair` is active, detect and clean up:
+
+```bash
+# Check for stale task directories (older than 24 hours)
+TASKS_DIR="$HOME/.claude/tasks"
+if [ -d "$TASKS_DIR" ]; then
+  STALE_COUNT=$(find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null | wc -l)
+  if [ "$STALE_COUNT" -gt 0 ]; then
+    echo "⚠️  Found $STALE_COUNT stale task directories in ~/.claude/tasks/"
+    echo "   These are leftover from crashed subagent sessions."
+    echo "   Run: rm -rf ~/.claude/tasks/*  (safe — only affects dead sessions)"
+  fi
+fi
+```
+
+Report as info diagnostic: `I002 | info | Stale subagent task directories found | Yes (--repair removes them)`
+</stale_task_cleanup>

get-shit-done/workflows/plan-phase.md

@@ -737,6 +737,30 @@ 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
+```
+</windows_troubleshooting>
+
 <success_criteria>
 - [ ] .planning/ directory validated
 - [ ] Phase validated against roadmap