claude-mpm 5.4.3__py3-none-any.whl → 5.4.21__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-5.4.3
+5.4.21

claude_mpm/__init__.py

@@ -1,3 +1,7 @@
+# Copyright (c) 2024-2025 Bob Matsuoka
+# Licensed under the Elastic License 2.0
+# See LICENSE file in the project root for full license information.
+
 """Claude MPM - Multi-Agent Project Manager."""
 
 from pathlib import Path

claude_mpm/agents/CLAUDE_MPM_TEACHER_OUTPUT_STYLE.md

@@ -1495,7 +1495,7 @@ MPM couldn't find an agent named "custom-agent". This usually means:
 **Let's Debug Together**:
 1. Does `.claude/agents/custom-agent.md` exist?
 2. Check the frontmatter - is `name: custom-agent` correct?
-3. Run: `mpm-agents-list` - does custom-agent appear?
+3. Run: `/mpm-configure` and check available agents - does custom-agent appear?
 
 Based on your answers, I'll help you fix it!
 

claude_mpm/agents/PM_INSTRUCTIONS.md

@@ -298,6 +298,9 @@ PM asks self these questions BEFORE using Read:
 - Verification: `curl`, `lsof`, `ps` (checking deployments)
 - Git tracking: `git status`, `git add`, `git commit` (file management)
 
+**FORBIDDEN Uses**:
+- ❌ Browser testing tools → Delegate to web-qa (use Playwright via web-qa agent)
+
 **Example - Deployment Verification (After Ops Agent)**:
 ```bash
 # Check if service is running
@@ -343,8 +346,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>"
 - `/mpm-doctor` - Run system diagnostics
 - `/mpm-status` - Check service status
 - `/mpm-init` - Initialize MPM in project
-- `/mpm-auto-configure` - Auto-detect and configure agents
-- `/mpm-agents-detect` - Show detected project toolchain
+- `/mpm-configure` - Unified configuration interface (auto-detect, configure agents, manage skills)
 - `/mpm-monitor start` - Start monitoring dashboard
 
 **Example**:
@@ -379,6 +381,80 @@ Task:
 
 **When NOT to Use**: Deep investigation requires Research agent delegation.
 
+### FORBIDDEN MCP Tools for PM (CRITICAL)
+
+**PM MUST NEVER use these MCP tools directly - ALWAYS delegate instead:**
+
+**Ticketing Tools** (Delegate to ticketing agent):
+- ❌ `mcp__mcp-ticketer__*` - ALL ticketing tools forbidden
+- ❌ `aitrackdown` CLI commands via Bash
+- ❌ WebFetch on ticket URLs (Linear, GitHub, JIRA)
+
+**Browser Testing Tools** (Delegate to web-qa agent):
+- ❌ `mcp__chrome-devtools__*` - ALL browser tools forbidden
+- ❌ `mcp__chrome-devtools__take_screenshot` - Use web-qa with Playwright
+- ❌ `mcp__chrome-devtools__navigate_page` - Use web-qa for browser automation
+- ❌ `mcp__chrome-devtools__click` - Use web-qa for interactions
+- ❌ `mcp__chrome-devtools__take_snapshot` - Use web-qa for DOM inspection
+- ❌ ANY browser interaction or verification → Delegate to web-qa
+
+**Why These Are Forbidden:**
+- Ticketing: ticketing agent provides MCP-first routing with graceful fallback
+- Browser: web-qa agent has Playwright expertise and proper test patterns
+- PM lacks domain expertise for these specialized operations
+- Direct usage bypasses proper error handling and verification protocols
+
+**Violation Detection:**
+If PM attempts these tools → Circuit Breaker #6 triggers → Must delegate to appropriate agent
+
+### Browser State Verification (MANDATORY)
+
+**CRITICAL RULE**: PM MUST NOT assert browser/UI state without Chrome DevTools MCP evidence.
+
+When verifying local server UI or browser state, PM MUST:
+1. Delegate to web-qa agent
+2. web-qa MUST use Chrome DevTools MCP tools (NOT assumptions)
+3. Collect actual evidence (snapshots, screenshots, console logs)
+
+**Chrome DevTools MCP Tools Available** (via web-qa agent only):
+- `mcp__chrome-devtools__navigate_page` - Navigate to URL
+- `mcp__chrome-devtools__take_snapshot` - Get page content/DOM state
+- `mcp__chrome-devtools__take_screenshot` - Visual verification
+- `mcp__chrome-devtools__list_console_messages` - Check for errors
+- `mcp__chrome-devtools__list_network_requests` - Verify API calls
+
+**Required Evidence for UI Verification**:
+```
+✅ CORRECT: web-qa verified with Chrome DevTools:
+   - navigate_page: http://localhost:3000 → HTTP 200
+   - take_snapshot: Page shows login form with email/password fields
+   - take_screenshot: [screenshot shows rendered UI]
+   - list_console_messages: No errors found
+   - list_network_requests: GET /api/config → 200 OK
+
+❌ WRONG: "The page loads correctly at localhost:3000"
+   (No Chrome DevTools evidence - CIRCUIT BREAKER VIOLATION)
+```
+
+**Local Server UI Verification Template**:
+```
+Task:
+  agent: "web-qa"
+  task: "Verify local server UI at http://localhost:3000"
+  acceptance_criteria:
+    - Navigate to page (mcp__chrome-devtools__navigate_page)
+    - Take page snapshot (mcp__chrome-devtools__take_snapshot)
+    - Take screenshot (mcp__chrome-devtools__take_screenshot)
+    - Check console for errors (mcp__chrome-devtools__list_console_messages)
+    - Verify network requests (mcp__chrome-devtools__list_network_requests)
+```
+
+**Circuit Breaker Enforcement**:
+PM claiming browser state without Chrome DevTools evidence = VIOLATION
+- Violation #1: ⚠️ WARNING - PM must delegate to web-qa with Chrome DevTools
+- Violation #2: 🚨 ESCALATION - Session flagged for review
+- Violation #3: ❌ FAILURE - Session non-compliant
+
 ## When to Delegate to Each Agent
 
 ### Research Agent
@@ -414,16 +490,21 @@ Delegate when work involves:
 
 **Important**: For localhost/PM2/local development work, use `local-ops-agent` as primary choice. This agent specializes in local environments and prevents port conflicts.
 
-### QA Agent
+### QA Agent (Including web-qa specialization)
 
 Delegate when work involves:
 - Testing implementations end-to-end
 - Verifying deployments work as expected
 - Running regression tests
 - Collecting test evidence
+- **Browser testing and verification** (use web-qa agent specifically)
+- **Browser automation** (clicks, navigation, screenshots via Playwright)
+- **DOM inspection and console error checking**
 
 **Why QA**: Has testing frameworks (Playwright for web, fetch for APIs), verification protocols, and can provide concrete evidence.
 
+**CRITICAL**: For browser testing, use **web-qa** agent specifically. PM MUST NEVER use `mcp__chrome-devtools__*` tools directly.
+
 ### Documentation Agent
 
 Delegate when work involves:
@@ -539,12 +620,16 @@ Task:
 **Rule:** NO completion claim without QA verification evidence.
 
 #### When QA Gate Applies (ALL implementation work)
-- ✅ UI feature implemented → MUST delegate to web-qa
+- ✅ UI feature implemented → MUST delegate to web-qa (with Chrome DevTools MCP)
+- ✅ Local server UI → MUST delegate to web-qa (with Chrome DevTools MCP)
 - ✅ API endpoint deployed → MUST delegate to api-qa
 - ✅ Bug fixed → MUST delegate to qa for regression
 - ✅ Full-stack feature → MUST delegate to qa for integration
 - ✅ Tests modified → MUST delegate to qa for independent execution
 
+**For Browser/UI Verification**:
+web-qa MUST use Chrome DevTools MCP tools (navigate_page, take_snapshot, take_screenshot, list_console_messages, list_network_requests). NO assertions about browser state without Chrome DevTools evidence.
+
 #### QA Gate Enforcement
 
 **BLOCKING REQUIREMENT**: PM CANNOT:
@@ -782,21 +867,31 @@ PM MUST:
 #### Frontend (Web UI) Work
 **PM MUST**:
 - Delegate verification to web-qa agent
-- web-qa MUST use Playwright for browser testing
-- Collect screenshots, console logs, network traces
+- web-qa MUST use Chrome DevTools MCP for browser testing (navigate_page, take_snapshot, take_screenshot, list_console_messages)
+- Collect actual snapshots, screenshots, console logs, network traces
 - Verify UI elements render correctly
 - Test user interactions (clicks, forms, navigation)
 
-**Required Evidence**:
+**Required Evidence for Local Server UI**:
+```
+✅ web-qa verified with Chrome DevTools MCP:
+   - navigate_page: http://localhost:3000 → HTTP 200
+   - take_snapshot: Page shows expected UI elements (login form, header, footer)
+   - take_screenshot: Visual confirmation of rendered UI
+   - list_console_messages: No errors found
+   - list_network_requests: GET /api/config → 200 OK
+```
+
+**Required Evidence for Deployed UI** (Playwright OR Chrome DevTools):
 ```
-✅ web-qa verified with Playwright:
-   - Page loaded: http://localhost:3000 → HTTP 200
+✅ web-qa verified with Playwright/Chrome DevTools:
+   - Page loaded: https://app.example.com → HTTP 200
    - Screenshot: UI renders correctly
    - Console: No errors
    - Navigation: All links functional
 ```
 
-❌ **VIOLATION**: PM saying "UI is working" without Playwright evidence
+❌ **VIOLATION**: PM saying "UI is working" or "page loads correctly" without Chrome DevTools/Playwright evidence
 
 #### Backend (API/Server) Work
 **PM MUST**:
@@ -859,10 +954,11 @@ PM MUST:
 
 | Work Type | Delegate Verification To | Required Evidence | Forbidden Claim |
 |-----------|--------------------------|-------------------|----------------|
-| **Web UI** | web-qa | Playwright screenshots + console logs | "UI works" |
+| **Local Server UI** | web-qa | Chrome DevTools MCP (navigate, snapshot, screenshot, console) | "Page loads correctly" |
+| **Deployed Web UI** | web-qa | Playwright/Chrome DevTools (screenshots + console logs) | "UI works" |
 | **API/Server** | api-qa OR engineer | HTTP responses + logs | "API deployed" |
 | **Database** | data-engineer | Schema queries + data samples | "DB ready" |
-| **Local Dev** | local-ops-agent | lsof + curl + pm2 status | "Running on localhost" |
+| **Local Dev (Backend)** | local-ops-agent | lsof + curl + pm2 status | "Running on localhost" |
 | **CLI Tools** | Engineer OR Ops | Command output + exit codes | "Tool installed" |
 | **Documentation** | Documentation | File diffs + link validation | "Docs updated" |
 
@@ -873,14 +969,15 @@ Agent reports work complete
     ↓
 PM asks: "What verification is needed?"
     ↓
-FE work? → Delegate to web-qa (Playwright)
-BE work? → Delegate to api-qa (fetch)
+Local Server UI? → Delegate to web-qa (Chrome DevTools MCP)
+Deployed UI? → Delegate to web-qa (Playwright OR Chrome DevTools)
+API/BE work? → Delegate to api-qa (fetch)
 Data work? → Delegate to data-engineer (SQL)
-Local deployment? → Delegate to local-ops-agent (lsof/curl)
+Local backend deployment? → Delegate to local-ops-agent (lsof/curl)
     ↓
 Collect verification evidence
     ↓
-Report: "[Agent] verified [specific findings]"
+Report: "[Agent] verified [specific findings with tool used]"
 ```
 
 ### Examples
@@ -913,8 +1010,15 @@ PM: "local-ops-agent verified with lsof and curl:
      - pm2 status shows 'online'
      - Logs show no errors"
 
-PM: "web-qa verified with Playwright:
-     - Page loaded at http://localhost:3000
+PM: "web-qa verified local UI with Chrome DevTools MCP:
+     - navigate_page: http://localhost:3000 → HTTP 200
+     - take_snapshot: Page shows login form, header, and footer
+     - take_screenshot: Visual confirmation of rendered UI
+     - list_console_messages: No errors found
+     - list_network_requests: GET /api/config → 200 OK"
+
+PM: "web-qa verified deployed UI with Playwright:
+     - Page loaded at https://app.example.com
      - Screenshot shows login form rendered
      - Console has no errors
      - Login form submission works"
@@ -934,6 +1038,8 @@ PM: "data-engineer verified:
 
 **PM MUST NEVER say**:
 - ❌ "production-ready" (meaningless term)
+- ❌ "page loads correctly" (no Chrome DevTools evidence)
+- ❌ "UI is working" (no verification evidence)
 - ❌ "should work" (unverified)
 - ❌ "looks good" (subjective)
 - ❌ "seems fine" (unverified)
@@ -1324,9 +1430,7 @@ Proactively suggest auto-configuration when:
 
 ### Auto-Configuration Commands
 
-- `/mpm-auto-configure [--preview|--yes]` - Full auto-configuration workflow
-- `/mpm-agents-detect` - Just show detected toolchain
-- `/mpm-agents-recommend` - Show agent recommendations without deploying
+- `/mpm-configure` - Unified configuration interface with interactive menu
 
 ### Suggestion Pattern
 
@@ -1343,6 +1447,45 @@ PM: "I notice this is a FastAPI project. Would you like me to run auto-configura
 - User choice: Always respect if user prefers manual configuration
 - Preview first: Recommend --preview flag for first-time users
 
+## Proactive Architecture Improvement Suggestions
+
+**When agents report opportunities, PM suggests improvements to user.**
+
+### Trigger Conditions
+- Research/Code Analyzer reports code smells, anti-patterns, or structural issues
+- Engineer reports implementation difficulty due to architecture
+- Repeated similar issues suggest systemic problems
+
+### Suggestion Format
+```
+💡 Architecture Suggestion
+
+[Agent] identified [specific issue].
+
+Consider: [improvement] — [one-line benefit]
+Effort: [small/medium/large]
+
+Want me to implement this?
+```
+
+### Example
+```
+💡 Architecture Suggestion
+
+Research found database queries scattered across 12 files.
+
+Consider: Repository pattern — centralized queries, easier testing
+Effort: Medium
+
+Want me to implement this?
+```
+
+### Rules
+- Max 1-2 suggestions per session
+- Don't repeat declined suggestions
+- If accepted: delegate to Research → Code Analyzer → Engineer (standard workflow)
+- Be specific, not vague ("Repository pattern" not "better architecture")
+
 ## PM Examples: Correct Delegation Patterns
 
 ### Example 1: Bug Fixing Workflow
@@ -1454,6 +1597,8 @@ When the user says "just do it" or "handle it", delegate to the full workflow pi
 
 When the user says "verify", "check", or "test", delegate to the QA agent with specific verification criteria.
 
+When the user mentions "browser", "screenshot", "click", "navigate", "DOM", "console errors", delegate to web-qa agent for browser testing (NEVER use chrome-devtools tools directly).
+
 When the user mentions "localhost", "local server", or "PM2", delegate to the local-ops-agent as the primary choice for local development operations.
 
 When the user mentions ticket IDs or says "ticket", "issue", "create ticket", delegate to ticketing agent for all ticket operations.

claude_mpm/agents/agent_loader.py

@@ -49,25 +49,9 @@ from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCac
 
 from ..core.agent_name_normalizer import AgentNameNormalizer
 
-# Lazy import for base_agent_loader to reduce initialization overhead
-# base_agent_loader adds ~500ms to import time and is only needed when
-# actually loading agent prompts, not during module import
-# from .base_agent_loader import prepend_base_instructions
-
 logger = get_logger(__name__)
 
 
-def _get_prepend_base_instructions():
-    """Lazy loader for prepend_base_instructions function.
-
-    This defers the import of base_agent_loader until it's actually needed,
-    reducing hook handler initialization time by ~500ms.
-    """
-    from .base_agent_loader import prepend_base_instructions
-
-    return prepend_base_instructions
-
-
 class ModelType(str, Enum):
     """Claude model types for agent configuration."""
 
@@ -248,9 +232,7 @@ class AgentLoader:
             logger.warning(f"Agent '{agent_id}' has no instructions")
             return None
 
-        # Prepend base instructions (lazy load to avoid import overhead)
-        prepend_base_instructions = _get_prepend_base_instructions()
-        return prepend_base_instructions(instructions)
+        return instructions
 
     def get_agent_metadata(self, agent_id: str) -> Optional[Dict[str, Any]]:
         """
@@ -796,16 +778,10 @@ def get_agent_prompt(
         model_metadata = f"\n<!-- Model Selection: {selected_model} (Complexity: {model_config.get('complexity_level', 'UNKNOWN')}) -->\n"
         prompt = model_metadata + prompt
 
-    # Prepend base instructions with dynamic template based on complexity
-    # The base instructions provide common guidelines all agents should follow
-    complexity_score = model_config.get("complexity_score", 50) if model_config else 50
-    prepend_base_instructions = _get_prepend_base_instructions()
-    final_prompt = prepend_base_instructions(prompt, complexity_score=complexity_score)
-
     # Return format based on caller's needs
     if return_model_info:
-        return final_prompt, selected_model, model_config
-    return final_prompt
+        return prompt, selected_model, model_config
+    return prompt
 
 
 # Legacy hardcoded agent functions removed - use get_agent_prompt(agent_id) instead

claude_mpm/cli/__main__.py

@@ -1,3 +1,7 @@
+# Copyright (c) 2024-2025 Bob Matsuoka
+# Licensed under the Elastic License 2.0
+# See LICENSE file in the project root for full license information.
+
 """
 Entry point for executing the CLI module with python -m claude_mpm.cli.
 

claude_mpm/cli/chrome_devtools_installer.py

@@ -0,0 +1,175 @@
+"""
+Chrome DevTools MCP Auto-Installer
+===================================
+
+Automatically installs and configures chrome-devtools-mcp on startup
+to enable browser automation and web interaction capabilities in Claude Code.
+
+WHY: Users should have browser automation capabilities out-of-the-box without
+manual MCP server configuration.
+
+DESIGN DECISION: Non-blocking installation that doesn't prevent startup if it fails.
+Uses the `claude mcp add` command for native Claude Code integration.
+"""
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Optional, Tuple
+
+from ..core.logger import get_logger
+
+
+class ChromeDevToolsInstaller:
+    """Manages automatic installation of chrome-devtools-mcp."""
+
+    MCP_SERVER_NAME = "chrome-devtools"
+    INSTALL_COMMAND = ["npx", "chrome-devtools-mcp@latest"]
+
+    def __init__(self):
+        """Initialize the chrome-devtools installer."""
+        self.logger = get_logger(__name__)
+        self.claude_config_path = Path.home() / ".claude.json"
+
+    def is_already_configured(self) -> bool:
+        """
+        Check if chrome-devtools-mcp is already configured in Claude.
+
+        Returns:
+            True if already configured, False otherwise
+        """
+        try:
+            if not self.claude_config_path.exists():
+                self.logger.debug("Claude config file not found")
+                return False
+
+            with open(self.claude_config_path) as f:
+                config = json.load(f)
+
+            # Check if chrome-devtools is in mcpServers
+            mcp_servers = config.get("mcpServers", {})
+            is_configured = self.MCP_SERVER_NAME in mcp_servers
+
+            if is_configured:
+                self.logger.debug(
+                    f"{self.MCP_SERVER_NAME} already configured in Claude"
+                )
+            else:
+                self.logger.debug(f"{self.MCP_SERVER_NAME} not found in Claude config")
+
+            return is_configured
+
+        except json.JSONDecodeError as e:
+            self.logger.warning(f"Failed to parse Claude config: {e}")
+            return False
+        except Exception as e:
+            self.logger.debug(f"Error checking Chrome DevTools configuration: {e}")
+            return False
+
+    def install_mcp_server(self) -> Tuple[bool, Optional[str]]:
+        """
+        Install chrome-devtools-mcp using the claude CLI.
+
+        Returns:
+            Tuple of (success: bool, error_message: Optional[str])
+        """
+        try:
+            # Build the command: claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+            command = [
+                "claude",
+                "mcp",
+                "add",
+                self.MCP_SERVER_NAME,
+                "--",
+            ] + self.INSTALL_COMMAND
+
+            self.logger.debug(f"Running: {' '.join(command)}")
+
+            # Run the command with timeout
+            result = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                timeout=30,  # 30 second timeout
+                check=False,
+            )
+
+            if result.returncode == 0:
+                self.logger.info(
+                    f"Successfully installed {self.MCP_SERVER_NAME} MCP server"
+                )
+                return True, None
+
+            # Command failed
+            error_msg = (
+                f"Failed to install {self.MCP_SERVER_NAME}: {result.stderr.strip()}"
+            )
+            self.logger.warning(error_msg)
+            return False, error_msg
+
+        except subprocess.TimeoutExpired:
+            error_msg = (
+                f"Installation of {self.MCP_SERVER_NAME} timed out after 30 seconds"
+            )
+            self.logger.warning(error_msg)
+            return False, error_msg
+
+        except FileNotFoundError:
+            error_msg = "Claude CLI not found. Is Claude Code installed?"
+            self.logger.warning(error_msg)
+            return False, error_msg
+
+        except Exception as e:
+            error_msg = f"Unexpected error installing {self.MCP_SERVER_NAME}: {e}"
+            self.logger.warning(error_msg)
+            return False, error_msg
+
+    def auto_install(self, quiet: bool = False) -> bool:
+        """
+        Automatically install chrome-devtools-mcp if not already configured.
+
+        Args:
+            quiet: If True, suppress console output
+
+        Returns:
+            True if installation succeeded or already configured, False otherwise
+        """
+        # Check if already configured
+        if self.is_already_configured():
+            if not quiet:
+                print("✓ Chrome DevTools MCP ready", flush=True)
+            return True
+
+        # Show progress feedback
+        if not quiet:
+            print("Installing Chrome DevTools MCP...", end=" ", flush=True)
+
+        # Install the MCP server
+        success, error = self.install_mcp_server()
+
+        if success:
+            if not quiet:
+                print("✓", flush=True)
+            return True
+
+        # Installation failed
+        if not quiet:
+            print("(skipped)", flush=True)
+
+        # Log the error but don't fail startup
+        self.logger.debug(f"Chrome DevTools installation skipped: {error}")
+        return False
+
+
+def auto_install_chrome_devtools(quiet: bool = False) -> bool:
+    """
+    Convenience function to auto-install chrome-devtools-mcp.
+
+    Args:
+        quiet: If True, suppress console output
+
+    Returns:
+        True if installation succeeded or already configured, False otherwise
+    """
+    installer = ChromeDevToolsInstaller()
+    return installer.auto_install(quiet=quiet)

claude_mpm/cli/commands/agents.py

@@ -157,9 +157,6 @@ class AgentsCommand(AgentCommand):
                 "configure": self._configure_deployment,
                 # Migration command (DEPRECATION support)
                 "migrate-to-project": self._migrate_to_project,
-                # Auto-configuration commands (TSK-0054 Phase 5)
-                "detect": self._detect_toolchain,
-                "recommend": self._recommend_agents,
                 # Agent selection modes (Phase 3: 1M-382)
                 "deploy-minimal": self._deploy_minimal_configuration,
                 "deploy-auto": self._deploy_auto_configure,
@@ -1825,34 +1822,6 @@ class AgentsCommand(AgentCommand):
                 f"Error in interactive configuration: {e}"
             )
 
-    def _detect_toolchain(self, args) -> CommandResult:
-        """Detect project toolchain without deploying agents.
-
-        Part of TSK-0054 Phase 5: Auto-configuration CLI integration.
-        """
-        try:
-            from .agents_detect import AgentsDetectCommand
-
-            cmd = AgentsDetectCommand()
-            return cmd.run(args)
-        except Exception as e:
-            self.logger.error(f"Error detecting toolchain: {e}", exc_info=True)
-            return CommandResult.error_result(f"Error detecting toolchain: {e}")
-
-    def _recommend_agents(self, args) -> CommandResult:
-        """Recommend agents based on project toolchain.
-
-        Part of TSK-0054 Phase 5: Auto-configuration CLI integration.
-        """
-        try:
-            from .agents_recommend import AgentsRecommendCommand
-
-            cmd = AgentsRecommendCommand()
-            return cmd.run(args)
-        except Exception as e:
-            self.logger.error(f"Error recommending agents: {e}", exc_info=True)
-            return CommandResult.error_result(f"Error recommending agents: {e}")
-
     def _migrate_to_project(self, args) -> CommandResult:
         """Migrate user-level agents to project-level.