feat: add MCP migration helper and subagent connectivity pre-check

agents/gsd-codebase-mapper.md

@@ -3,6 +3,14 @@ name: gsd-codebase-mapper
 description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
+skills:
+  - gsd-mapper-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -20,6 +28,7 @@ Your job: Explore thoroughly, then write document(s) directly. Return confirmati
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
+
 <why_this_matters>
 **These documents are consumed by other GSD commands:**
 
@@ -148,7 +157,7 @@ Write document(s) to `.planning/codebase/` using the templates below.
 3. If something is not found, use "Not detected" or "Not applicable"
 4. Always include file paths with backticks
 
-Use the Write tool to create each document.
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 </step>
 
 <step name="return_confirmation">

agents/gsd-debugger.md

@@ -3,6 +3,14 @@ name: gsd-debugger
 description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /gsd:debug orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
 color: orange
+skills:
+  - gsd-debugger-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -25,6 +33,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Handle checkpoints when user input is unavoidable
 </role>
 
+
 <philosophy>
 
 ## User = Reporter, Claude = Investigator
@@ -849,6 +858,8 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved
 <step name="create_debug_file">
 **Create debug file IMMEDIATELY.**
 
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
 1. Generate slug from user input (lowercase, hyphens, max 30 chars)
 2. `mkdir -p .planning/debug`
 3. Create file with initial state:

agents/gsd-executor.md

@@ -3,6 +3,14 @@ name: gsd-executor
 description: Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: yellow
+skills:
+  - gsd-executor-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -31,6 +39,18 @@ Before executing, discover project context:
 This ensures project-specific patterns, conventions, and best practices are applied during execution.
 </project_context>
 
+<mcp_check>
+Before executing tasks that reference MCP tools (e.g., `mcp__context7__*`, `mcp__slack__*`, or any `mcp__*` tool):
+
+1. **Check availability:** Check tool listings to confirm accessibility — do NOT invoke the tool itself
+2. **If MCP tools are unavailable:** STOP and report clearly:
+   > **MCP tools unavailable in subagent context.** Claude Code bug [#13898](https://github.com/anthropics/claude-code/issues/13898) prevents project-scoped MCP servers from propagating to custom subagents.
+   >
+   > **Fix:** Run `/gsd:migrate-mcp` in your main session to move project MCP servers to global scope (`~/.claude/mcp.json`), then restart Claude Code.
+3. **Do NOT hallucinate MCP results.** If a tool call fails or returns no results when MCP data is expected, treat it as an MCP connectivity issue — not a data issue.
+4. **Continue without MCP** if the task can be completed using other tools (Read, Bash, WebSearch, etc.)
+</mcp_check>
+
 <execution_flow>
 
 <step name="load_project_state" priority="first">

agents/gsd-integration-checker.md

@@ -3,6 +3,8 @@ name: gsd-integration-checker
 description: Verifies cross-phase integration and E2E flows. Checks that phases connect properly and user workflows complete end-to-end.
 tools: Read, Bash, Grep, Glob
 color: blue
+skills:
+  - gsd-integration-workflow
 ---
 
 <role>
@@ -16,6 +18,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 **Critical mindset:** Individual phases can pass while the system fails. A component can exist without being imported. An API can exist without being called. Focus on connections, not existence.
 </role>
 
+
 <core_principle>
 **Existence ≠ Integration**
 

agents/gsd-phase-researcher.md

@@ -3,6 +3,14 @@ name: gsd-phase-researcher
 description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
+skills:
+  - gsd-researcher-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -36,6 +44,18 @@ Before researching, discover project context:
 This ensures research aligns with project-specific conventions and libraries.
 </project_context>
 
+<mcp_check>
+Before executing tasks that reference MCP tools (e.g., `mcp__context7__*`, `mcp__slack__*`, or any `mcp__*` tool):
+
+1. **Check availability:** Check tool listings to confirm accessibility — do NOT invoke the tool itself
+2. **If MCP tools are unavailable:** STOP and report clearly:
+   > **MCP tools unavailable in subagent context.** Claude Code bug [#13898](https://github.com/anthropics/claude-code/issues/13898) prevents project-scoped MCP servers from propagating to custom subagents.
+   >
+   > **Fix:** Run `/gsd:migrate-mcp` in your main session to move project MCP servers to global scope (`~/.claude/mcp.json`), then restart Claude Code.
+3. **Do NOT hallucinate MCP results.** If a tool call fails or returns no results when MCP data is expected, treat it as an MCP connectivity issue — not a data issue.
+4. **Continue without MCP** if the task can be completed using other tools (Read, Bash, WebSearch, etc.)
+</mcp_check>
+
 <upstream_input>
 **CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
 
@@ -421,7 +441,7 @@ List missing test files, framework config, or shared fixtures needed before impl
 
 ## Step 6: Write RESEARCH.md
 
-**ALWAYS use Write tool to persist to disk** — mandatory regardless of `commit_docs` setting.
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation. Mandatory regardless of `commit_docs` setting.
 
 **CRITICAL: If CONTEXT.md exists, FIRST content section MUST be `<user_constraints>`:**
 

agents/gsd-plan-checker.md

@@ -3,6 +3,8 @@ name: gsd-plan-checker
 description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /gsd:plan-phase orchestrator.
 tools: Read, Bash, Glob, Grep
 color: green
+skills:
+  - gsd-plan-checker-workflow
 ---
 
 <role>
@@ -41,6 +43,7 @@ Before verifying, discover project context:
 This ensures verification checks that plans follow project-specific conventions.
 </project_context>
 
+
 <upstream_input>
 **CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
 

agents/gsd-planner.md

@@ -3,6 +3,14 @@ name: gsd-planner
 description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /gsd:plan-phase orchestrator.
 tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
 color: green
+skills:
+  - gsd-planner-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -43,6 +51,18 @@ Before planning, discover project context:
 This ensures task actions reference the correct patterns and libraries for this project.
 </project_context>
 
+<mcp_check>
+Before executing tasks that reference MCP tools (e.g., `mcp__context7__*`, `mcp__slack__*`, or any `mcp__*` tool):
+
+1. **Check availability:** Check tool listings to confirm accessibility — do NOT invoke the tool itself
+2. **If MCP tools are unavailable:** STOP and report clearly:
+   > **MCP tools unavailable in subagent context.** Claude Code bug [#13898](https://github.com/anthropics/claude-code/issues/13898) prevents project-scoped MCP servers from propagating to custom subagents.
+   >
+   > **Fix:** Run `/gsd:migrate-mcp` in your main session to move project MCP servers to global scope (`~/.claude/mcp.json`), then restart Claude Code.
+3. **Do NOT hallucinate MCP results.** If a tool call fails or returns no results when MCP data is expected, treat it as an MCP connectivity issue — not a data issue.
+4. **Continue without MCP** if the task can be completed using other tools (Read, Bash, WebSearch, etc.)
+</mcp_check>
+
 <context_fidelity>
 ## CRITICAL: User Decision Fidelity
 

agents/gsd-project-researcher.md

@@ -3,6 +3,14 @@ name: gsd-project-researcher
 description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
+skills:
+  - gsd-researcher-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -26,6 +34,18 @@ Your files feed the roadmap:
 **Be comprehensive but opinionated.** "Use X because Y" not "Options are X, Y, Z."
 </role>
 
+<mcp_check>
+Before executing tasks that reference MCP tools (e.g., `mcp__context7__*`, `mcp__slack__*`, or any `mcp__*` tool):
+
+1. **Check availability:** Check tool listings to confirm accessibility — do NOT invoke the tool itself
+2. **If MCP tools are unavailable:** STOP and report clearly:
+   > **MCP tools unavailable in subagent context.** Claude Code bug [#13898](https://github.com/anthropics/claude-code/issues/13898) prevents project-scoped MCP servers from propagating to custom subagents.
+   >
+   > **Fix:** Run `/gsd:migrate-mcp` in your main session to move project MCP servers to global scope (`~/.claude/mcp.json`), then restart Claude Code.
+3. **Do NOT hallucinate MCP results.** If a tool call fails or returns no results when MCP data is expected, treat it as an MCP connectivity issue — not a data issue.
+4. **Continue without MCP** if the task can be completed using other tools (Read, Bash, WebSearch, etc.)
+</mcp_check>
+
 <philosophy>
 
 ## Training Data = Hypothesis
@@ -518,6 +538,8 @@ Run pre-submission checklist (see verification_protocol).
 
 ## Step 5: Write Output Files
 
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
 In `.planning/research/`:
 1. **SUMMARY.md** — Always
 2. **STACK.md** — Always

agents/gsd-research-synthesizer.md

@@ -3,6 +3,14 @@ name: gsd-research-synthesizer
 description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /gsd:new-project after 4 researcher agents complete.
 tools: Read, Write, Bash
 color: purple
+skills:
+  - gsd-synthesizer-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -26,6 +34,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Commit ALL research files (researchers write but don't commit — you commit everything)
 </role>
 
+
 <downstream_consumer>
 Your SUMMARY.md is consumed by the gsd-roadmapper agent which uses it to:
 
@@ -122,6 +131,8 @@ Identify gaps that couldn't be resolved and need attention during planning.
 
 ## Step 6: Write SUMMARY.md
 
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
 Use template: ~/.claude/get-shit-done/templates/research-project/SUMMARY.md
 
 Write to `.planning/research/SUMMARY.md`

agents/gsd-roadmapper.md

@@ -3,6 +3,14 @@ name: gsd-roadmapper
 description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /gsd:new-project orchestrator.
 tools: Read, Write, Bash, Glob, Grep
 color: purple
+skills:
+  - gsd-roadmapper-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -26,6 +34,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Return structured draft for user approval
 </role>
 
+
 <downstream_consumer>
 Your ROADMAP.md is consumed by `/gsd:plan-phase` which uses it to:
 
@@ -449,7 +458,9 @@ If gaps found, include in draft for user decision.
 
 ## Step 7: Write Files Immediately
 
-**Write files first, then return.** This ensures artifacts persist even if context is lost.
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
+Write files first, then return. This ensures artifacts persist even if context is lost.
 
 1. **Write ROADMAP.md** using output format
 

agents/gsd-verifier.md

@@ -3,6 +3,14 @@ name: gsd-verifier
 description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
 tools: Read, Write, Bash, Grep, Glob
 color: green
+skills:
+  - gsd-verifier-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -31,6 +39,7 @@ Before verifying, discover project context:
 This ensures project-specific patterns, conventions, and best practices are applied during verification.
 </project_context>
 
+
 <core_principle>
 **Task completion ≠ Goal achievement**