From 665c948c221fc7b3b13f98c0ee7cdd6c19aba513 Mon Sep 17 00:00:00 2001
From: Tom Boucher <trekkie@nomorestars.com>
Date: Wed, 18 Mar 2026 11:58:36 -0400
Subject: [PATCH] feat: MCP tool awareness for GSD subagents (#973) (#1137)

GSD executor agents ignore MCP tools (e.g. jCodeMunch) even when CLAUDE.md
explicitly instructs their use. Agents default to Grep/Glob because those
are explicitly referenced in workflow patterns.

Added MCP tool instructions to:
- execute-phase.md: <mcp_tools> section in executor agent prompt telling
  agents to prefer MCP tools over Grep/Glob when available
- execute-plan.md: Step 2 in execute section with MCP tool fallback guidance

Agents now:
1. Check if CLAUDE.md references MCP tools
2. Prefer MCP tools for code navigation when accessible
3. Fall back to Grep/Glob if MCP tools are not available

Fixes #973
---
 get-shit-done/workflows/execute-phase.md | 7 +++++++
 get-shit-done/workflows/execute-plan.md  | 3 ++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md
index b522dba55..f77f3f272 100644
--- a/get-shit-done/workflows/execute-phase.md
+++ b/get-shit-done/workflows/execute-phase.md
@@ -158,6 +158,13 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
        - .claude/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
        </files_to_read>
 
+       <mcp_tools>
+       If CLAUDE.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
+       or other MCP servers), prefer those tools over Grep/Glob for code navigation when available.
+       MCP tools often save significant tokens by providing structured code indexes.
+       Check tool availability first — if MCP tools are not accessible, fall back to Grep/Glob.
+       </mcp_tools>
+
        <success_criteria>
        - [ ] All tasks executed
        - [ ] Each task committed individually
diff --git a/get-shit-done/workflows/execute-plan.md b/get-shit-done/workflows/execute-plan.md
index d47b6a18f..5dd6f8fc0 100644
--- a/get-shit-done/workflows/execute-plan.md
+++ b/get-shit-done/workflows/execute-plan.md
@@ -135,7 +135,8 @@ If previous SUMMARY has unresolved "Issues Encountered" or "Next Phase Readiness
 Deviations are normal — handle via rules below.
 
 1. Read @context files from prompt
-2. Per task:
+2. **MCP tools:** If CLAUDE.md or project instructions reference MCP tools (e.g. jCodeMunch for code navigation), prefer them over Grep/Glob when available. Fall back to Grep/Glob if MCP tools are not accessible.
+3. Per task:
    - **MANDATORY read_first gate:** If the task has a `<read_first>` field, you MUST read every listed file BEFORE making any edits. This is not optional. Do not skip files because you "already know" what's in them — read them. The read_first files establish ground truth for the task.
    - `type="auto"`: if `tdd="true"` → TDD execution. Implement with deviation rules + auth gates. Verify done criteria. Commit (see task_commit). Track hash for Summary.
    - `type="checkpoint:*"`: STOP → checkpoint_protocol → wait for user → continue only after confirmation.