From 4c6b4928351f88ebd1946e9123e9dc9dfe9f872b Mon Sep 17 00:00:00 2001
From: Scott Jennings <scott.jennings+CIGINT@cloudimperiumgames.com>
Date: Wed, 10 Dec 2025 18:51:38 -0600
Subject: [PATCH] feat: add cleanup for lingering external agent processes

Add instructions to detect and terminate any stale external agent
review processes when starting a new code review session in Claude Code.
---
 .../4-implementation/code-review/instructions.xml   | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml
index 09834e73..6373ae04 100644
--- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml
+++ b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml
@@ -4,6 +4,19 @@
   <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
   <critical>Generate all documents in {document_output_language}</critical>
 
+  <!-- ================================================================ -->
+  <!-- CLAUDE CODE CLEANUP - KILL LINGERING EXTERNAL AGENT PROCESSES   -->
+  <!-- ================================================================ -->
+  <!-- If BMAD is running as Claude Code (not the external agent), clean up
+       any terminal processes from previous external agent code reviews.
+       This prevents context pollution from stale review sessions. -->
+  <check if="BMAD is running as Claude Code (detected via KillShell tool availability or CLAUDE_CODE env)">
+    <action>Check for any running background shells/terminals from previous external agent reviews</action>
+    <action>If any `claude -p` or similar external agent processes are found running, use KillShell to terminate them</action>
+    <action>This ensures a clean slate for the new code review session</action>
+    <output>🧹 Cleaned up previous external agent review processes (if any)</output>
+  </check>
+
   <!-- ================================================================ -->
   <!-- EXTERNAL AGENT MANDATE - THIS IS THE MOST IMPORTANT RULE        -->
   <!-- ================================================================ -->