claude-mpm 5.1.8__py3-none-any.whl → 5.4.22__py3-none-any.whl

claude_mpm/agents/templates/circuit-breakers.md

@@ -1154,6 +1154,139 @@ Before delegating implementation, PM MUST verify:
 
 ---
 
+## Circuit Breaker #8: Skills Management Violation
+
+**Purpose**: Prevent PM from performing skill operations directly instead of delegating to mpm-skills-manager
+
+### Trigger Conditions
+
+**IF PM attempts ANY of the following:**
+
+#### Direct Skill Operations
+- PM creates SKILL.md files directly (using Write/Edit tools)
+- PM modifies manifest.json for skills
+- PM attempts to deploy skills without mpm-skills-manager
+- PM creates PRs to skills repository directly
+- PM recommends skills without technology detection
+- PM attempts skill validation or structure checks
+
+#### Missing Delegation Signals
+- User request contains skill keywords but PM doesn't delegate
+- PM attempts to handle "create skill", "add skill", "improve skill" requests directly
+- PM tries to analyze technology stack without mpm-skills-manager
+- PM bypasses skill workflow for skill-related operations
+
+### Violation Response
+
+**→ STOP IMMEDIATELY**
+
+**→ ERROR**: `"PM VIOLATION - Must delegate skill operations to mpm-skills-manager"`
+
+**→ REQUIRED ACTION**: Delegate ALL skill operations to mpm-skills-manager agent
+
+**→ VIOLATIONS TRACKED AND REPORTED**
+
+### Correct Delegation Pattern
+
+PM delegates ALL skill operations to mpm-skills-manager:
+- "I'll have mpm-skills-manager create the [technology] skill"
+- "I'll delegate skill recommendation to mpm-skills-manager"
+- "mpm-skills-manager will handle the PR for this skill improvement"
+- "I'll have mpm-skills-manager detect the project technology stack"
+
+### Why This Matters
+
+**mpm-skills-manager provides critical functionality:**
+- Technology stack detection from project files
+- Skill validation and structure enforcement
+- manifest.json integrity management
+- GitHub PR workflow integration for skill contributions
+- Skill versioning and lifecycle management
+
+**PM lacks skill management expertise:**
+- No access to skill validation tools
+- No knowledge of manifest.json structure requirements
+- No PR workflow integration for skills repository
+- Risk of creating malformed skills without validation
+
+### Examples
+
+#### ❌ VIOLATION Examples
+
+```
+# Violation: PM creating skill file directly
+User: "Create a FastAPI skill"
+PM: Write(file_path="skills/fastapi/SKILL.md", ...)  # ❌ VIOLATION
+
+# Violation: PM modifying manifest directly
+PM: Edit(file_path="manifest.json", ...)  # ❌ VIOLATION
+
+# Violation: PM creating PR to skills repository
+PM: Task(agent="version-control", task="Create PR to claude-code-skills")  # ❌ VIOLATION
+
+# Violation: PM recommending skills without detection
+User: "What skills do I need?"
+PM: "You need React and FastAPI skills"  # ❌ VIOLATION - no technology detection
+```
+
+#### ✅ CORRECT Examples
+
+```
+# Correct: Skill creation delegation
+User: "Create a FastAPI skill"
+PM: Task(agent="mpm-skills-manager", task="Create comprehensive skill for FastAPI framework")
+
+# Correct: Skill recommendation delegation
+User: "What skills do I need for this project?"
+PM: Task(agent="mpm-skills-manager", task="Detect project technology stack and recommend relevant skills")
+
+# Correct: Skill improvement delegation
+User: "The React skill is missing hooks patterns"
+PM: Task(agent="mpm-skills-manager", task="Improve React skill by adding hooks patterns section")
+
+# Correct: Technology detection delegation
+User: "What frameworks are we using?"
+PM: Task(agent="mpm-skills-manager", task="Analyze project files and identify all frameworks and technologies")
+```
+
+### Enforcement Levels
+
+| Violation Count | Response | Action |
+|----------------|----------|--------|
+| **Violation #1** | ⚠️ WARNING | PM reminded to delegate skill operations to mpm-skills-manager |
+| **Violation #2** | 🚨 ESCALATION | PM must STOP and delegate to mpm-skills-manager immediately |
+| **Violation #3+** | ❌ FAILURE | Session marked as non-compliant, skill operations blocked |
+
+### Skill-Related Trigger Keywords
+
+**PM should detect these keywords and delegate to mpm-skills-manager:**
+
+**Skill Operations**:
+- "skill", "add skill", "create skill", "new skill"
+- "improve skill", "update skill", "skill is missing"
+- "deploy skill", "install skill", "remove skill"
+
+**Technology Detection**:
+- "detect stack", "analyze technologies", "what frameworks"
+- "project stack", "identify dependencies"
+- "what are we using", "technology analysis"
+
+**Skill Discovery**:
+- "recommend skills", "suggest skills", "what skills"
+- "skills for [framework]", "need skills for"
+
+### Integration with PM Workflow
+
+**When PM sees skill keywords → IMMEDIATELY delegate to mpm-skills-manager**
+
+**No exceptions for:**
+- "Simple" skill operations (all require validation)
+- "Quick" manifest updates (integrity critical)
+- "Minor" skill improvements (still need PR workflow)
+- Technology stack "guesses" (detection required)
+
+---
+
 ## Violation Tracking Format
 
 When PM attempts forbidden action, use this format:
@@ -1173,6 +1306,7 @@ When PM attempts forbidden action, use this format:
 | **FILE TRACKING** | PM didn't track new files | `PM ended session without tracking 2 new files` |
 | **TICKETING** | PM used ticketing tools directly | `PM used mcp-ticketer tool - Must delegate to ticketing` |
 | **RESEARCH GATE** | PM skipped Research for ambiguous task | `PM delegated to Engineer without Research - Must delegate to Research first` |
+| **SKILLS** | PM attempted skill operations directly | `PM created SKILL.md directly - Must delegate to mpm-skills-manager` |
 
 ---
 
@@ -1207,6 +1341,8 @@ Violations are tracked and escalated based on severity:
 - "Is this task ambiguous? Should I delegate to Research BEFORE Engineer?"
 - "Did Research validate the approach before implementation?"
 - "Does my delegation include Research context?"
+- "Is this a skill-related request? Should I delegate to mpm-skills-manager?"
+- "Am I about to create/modify skill files directly instead of delegating?"
 - "Did any agent create a new file during this session?"
 - "Have I run `git status` to check for untracked files?"
 - "Are all trackable files staged in git?"
@@ -1232,6 +1368,7 @@ Violations are tracked and escalated based on severity:
 - [ ] No ticketing tool misuse (Circuit Breaker #6)
 - [ ] **Research delegated for all ambiguous tasks** ← Circuit Breaker #7
 - [ ] **Implementation references Research findings** ← Circuit Breaker #7
+- [ ] **All skill operations delegated to mpm-skills-manager** ← Circuit Breaker #8
 - [ ] Unresolved issues documented
 - [ ] Violation report provided (if violations occurred)
 
@@ -1241,7 +1378,7 @@ Violations are tracked and escalated based on severity:
 
 ## The PM Mantra
 
-**"I don't investigate. I don't implement. I don't assert. I research-first for ambiguous tasks. I delegate, verify, and track files."**
+**"I don't investigate. I don't implement. I don't assert. I research-first for ambiguous tasks. I delegate skills to mpm-skills-manager. I delegate, verify, and track files."**
 
 ---
 

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/agent_state_manager.py

@@ -152,7 +152,7 @@ class SimpleAgentManager:
 
                     # Get metadata for display info
                     metadata = template_data.get("metadata", {})
-                    metadata.get("name", agent_id)
+                    display_name = metadata.get("name", agent_id)
                     description = metadata.get(
                         "description", "No description available"
                     )
@@ -182,9 +182,10 @@ class SimpleAgentManager:
                         dependencies=display_tools,
                     )
 
-                    # Set deployment status
+                    # Set deployment status and display name
                     agent_config.is_deployed = is_deployed
                     agent_config.source_type = "local"
+                    agent_config.display_name = display_name
 
                     agents.append(agent_config)
 
@@ -235,7 +236,7 @@ class SimpleAgentManager:
                 # Create AgentConfig with source information
                 # Store full agent_dict for later use in deployment
                 agent_config = AgentConfig(
-                    name=agent_id,  # Use agent_id as name for uniqueness
+                    name=name,  # Use display name for UI
                     description=(
                         f"[{category}] {description[:60]}..."
                         if len(description) > 60
@@ -248,6 +249,7 @@ class SimpleAgentManager:
                 agent_config.source_type = "remote"
                 agent_config.is_deployed = is_deployed
                 agent_config.display_name = name
+                agent_config.agent_id = agent_id  # Store technical ID for reference
                 agent_config.full_agent_id = agent_id
                 agent_config.source_dict = agent_dict  # Store full dict for deployment
 
@@ -272,9 +274,9 @@ class SimpleAgentManager:
             True if agent is deployed, False otherwise
         """
         # Check virtual deployment state (primary method)
+        # Only checking project-level deployment in simplified architecture
         deployment_state_paths = [
             Path.cwd() / ".claude" / "agents" / ".mpm_deployment_state",
-            Path.home() / ".claude" / "agents" / ".mpm_deployment_state",
         ]
 
         for state_path in deployment_state_paths:
@@ -319,8 +321,8 @@ class SimpleAgentManager:
             leaf_name = agent_id.split("/")[-1]
             agent_file_names.append(f"{leaf_name}.md")
 
-        # Check .claude-mpm/agents/ directory (project level)
-        project_agents_dir = Path.cwd() / ".claude-mpm" / "agents"
+        # Check .claude/agents/ directory (project deployment)
+        project_agents_dir = Path.cwd() / ".claude" / "agents"
         if project_agents_dir.exists():
             for agent_file_name in agent_file_names:
                 agent_file = project_agents_dir / agent_file_name
@@ -330,15 +332,4 @@ class SimpleAgentManager:
                     )
                     return True
 
-        # Check ~/.claude/agents/ directory (user level)
-        user_agents_dir = Path.home() / ".claude" / "agents"
-        if user_agents_dir.exists():
-            for agent_file_name in agent_file_names:
-                agent_file = user_agents_dir / agent_file_name
-                if agent_file.exists():
-                    self.logger.debug(
-                        f"Agent {agent_id} found as physical file: {agent_file}"
-                    )
-                    return True
-
         return False

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,
@@ -167,6 +164,10 @@ class AgentsCommand(AgentCommand):
                 "available": self._list_available_from_sources,
                 # Agent discovery with rich filtering (Phase 1: Discovery & Browsing)
                 "discover": self._discover_agents,
+                # NEW: Collection-based agent management
+                "list-collections": self._list_collections,
+                "deploy-collection": self._deploy_collection,
+                "list-by-collection": self._list_by_collection,
                 # Cache git management commands
                 "cache-status": self._cache_status,
                 "cache-pull": self._cache_pull,
@@ -1821,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.
 
@@ -2157,6 +2130,171 @@ class AgentsCommand(AgentCommand):
             self.logger.error(f"Error in auto-configure: {e}", exc_info=True)
             return CommandResult.error_result(f"Error in auto-configure: {e}")
 
+    def _list_collections(self, args) -> CommandResult:
+        """List all available agent collections.
+
+        NEW: Shows all collections with agent counts and metadata.
+        Enables discovery of available agent collections before deployment.
+        """
+        try:
+            from pathlib import Path
+
+            from ...services.agents.deployment.remote_agent_discovery_service import (
+                RemoteAgentDiscoveryService,
+            )
+
+            # Get remote agents cache directory
+            cache_dir = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+
+            if not cache_dir.exists():
+                return CommandResult.error_result(
+                    "No remote agent collections found. Run 'claude-mpm agents deploy' first."
+                )
+
+            # Use RemoteAgentDiscoveryService to list collections
+            remote_service = RemoteAgentDiscoveryService(cache_dir)
+            collections = remote_service.list_collections()
+
+            if not collections:
+                return CommandResult.success_result(
+                    "No agent collections found in cache.", data={"collections": []}
+                )
+
+            # Format output
+            output_lines = ["Available Agent Collections:\n"]
+            for collection in collections:
+                output_lines.append(
+                    f"  • {collection['collection_id']} ({collection['agent_count']} agents)"
+                )
+
+            return CommandResult.success_result(
+                "\n".join(output_lines), data={"collections": collections}
+            )
+
+        except Exception as e:
+            self.logger.error(f"Error listing collections: {e}", exc_info=True)
+            return CommandResult.error_result(f"Error listing collections: {e}")
+
+    def _deploy_collection(self, args) -> CommandResult:
+        """Deploy all agents from a specific collection.
+
+        NEW: Enables bulk deployment of all agents from a named collection.
+        Useful for deploying entire agent sets at once.
+        """
+        try:
+            from pathlib import Path
+
+            from ...services.agents.deployment.multi_source_deployment_service import (
+                MultiSourceAgentDeploymentService,
+            )
+
+            collection_id = args.collection_id
+
+            # Get agents from collection
+            service = MultiSourceAgentDeploymentService()
+            cache_dir = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+            agents = service.get_agents_by_collection(collection_id, cache_dir)
+
+            if not agents:
+                return CommandResult.error_result(
+                    f"No agents found in collection '{collection_id}'"
+                )
+
+            # Dry run mode
+            if getattr(args, "dry_run", False):
+                agent_names = [
+                    agent.get("metadata", {}).get("name", "Unknown") for agent in agents
+                ]
+                output = f"Would deploy {len(agents)} agents from collection '{collection_id}':\n"
+                for name in agent_names:
+                    output += f"  • {name}\n"
+                return CommandResult.success_result(
+                    output,
+                    data={"collection_id": collection_id, "agent_count": len(agents)},
+                )
+
+            # Deploy agents
+            # TODO: Implement actual deployment logic using deployment service
+            # For now, show what would be deployed
+            return CommandResult.success_result(
+                f"Deployment of collection '{collection_id}' would deploy {len(agents)} agents.\n"
+                f"(Full deployment implementation pending)",
+                data={
+                    "collection_id": collection_id,
+                    "agent_count": len(agents),
+                    "status": "pending_implementation",
+                },
+            )
+
+        except Exception as e:
+            self.logger.error(f"Error deploying collection: {e}", exc_info=True)
+            return CommandResult.error_result(f"Error deploying collection: {e}")
+
+    def _list_by_collection(self, args) -> CommandResult:
+        """List agents from a specific collection.
+
+        NEW: Shows detailed information about agents in a collection.
+        Supports multiple output formats (table, json, yaml).
+        """
+        try:
+            import json as json_lib
+            from pathlib import Path
+
+            from ...services.agents.deployment.multi_source_deployment_service import (
+                MultiSourceAgentDeploymentService,
+            )
+
+            collection_id = args.collection_id
+            output_format = getattr(args, "format", "table")
+
+            # Get agents from collection
+            service = MultiSourceAgentDeploymentService()
+            cache_dir = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+            agents = service.get_agents_by_collection(collection_id, cache_dir)
+
+            if not agents:
+                return CommandResult.error_result(
+                    f"No agents found in collection '{collection_id}'"
+                )
+
+            # Format output based on requested format
+            if output_format == "json":
+                return CommandResult.success_result(
+                    json_lib.dumps(agents, indent=2),
+                    data={"collection_id": collection_id, "agents": agents},
+                )
+            if output_format == "yaml":
+                try:
+                    import yaml
+
+                    return CommandResult.success_result(
+                        yaml.dump(agents, default_flow_style=False),
+                        data={"collection_id": collection_id, "agents": agents},
+                    )
+                except ImportError:
+                    return CommandResult.error_result(
+                        "YAML support not available (install PyYAML)"
+                    )
+
+            # Table format (default)
+            output_lines = [f"Agents in collection '{collection_id}':\n"]
+            for agent in agents:
+                metadata = agent.get("metadata", {})
+                name = metadata.get("name", "Unknown")
+                description = metadata.get("description", "No description")
+                version = agent.get("version", "unknown")
+                output_lines.append(f"  • {name} (v{version})")
+                output_lines.append(f"    {description}\n")
+
+            return CommandResult.success_result(
+                "\n".join(output_lines),
+                data={"collection_id": collection_id, "agent_count": len(agents)},
+            )
+
+        except Exception as e:
+            self.logger.error(f"Error listing collection agents: {e}", exc_info=True)
+            return CommandResult.error_result(f"Error listing collection agents: {e}")
+
     def _cache_status(self, args) -> CommandResult:
         """Show git status of agent cache.