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

claude_mpm/services/agents/agent_recommendation_service.py

@@ -0,0 +1,278 @@
+"""Agent Recommendation Service
+
+WHY: Provides intelligent agent recommendations based on toolchain detection
+and always-recommended core agents. Helps users discover and install the
+most relevant agents for their project without manual selection.
+
+DESIGN DECISION: Uses toolchain analysis to map detected languages/frameworks
+to specific engineer agents, plus always includes core agents.
+
+Architecture:
+- Toolchain-based recommendations: Python → python-engineer, etc.
+- Core agents (always recommended): engineer, qa-agent, memory-manager-agent, local-ops-agent,
+  research-agent, documentation-agent, security-agent
+- Confidence-based filtering: Only recommend high-confidence detections
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+from ...services.project.toolchain_analyzer import ToolchainAnalyzerService
+
+
+class AgentRecommendationService:
+    """Service for recommending agents based on project toolchain.
+
+    WHY: Users shouldn't have to manually figure out which agents to install.
+    This service provides intelligent recommendations based on detected stack.
+
+    DESIGN DECISION: Separated from configure.py for reusability and testability.
+    Can be used by CLI, API, or future auto-configuration features.
+    """
+
+    # Core agents always included - matches ToolchainDetector.CORE_AGENTS
+    # Uses exact agent IDs from repository for consistency
+    CORE_AGENTS = {
+        "engineer",
+        "qa-agent",
+        "memory-manager-agent",
+        "local-ops-agent",
+        "research-agent",
+        "documentation-agent",
+        "security-agent",
+    }
+
+    # Map detected languages to recommended engineer agents
+    LANGUAGE_TO_AGENTS: Dict[str, List[str]] = {
+        "python": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "javascript": [
+            "engineer/backend/javascript-engineer",
+            "engineer/data/typescript-engineer",
+        ],
+        "typescript": [
+            "engineer/data/typescript-engineer",
+            "engineer/backend/javascript-engineer",
+        ],
+        "rust": [
+            "engineer/backend/rust-engineer",
+        ],
+        "go": [
+            "engineer/backend/golang-engineer",
+        ],
+        "java": [
+            "engineer/backend/java-engineer",
+        ],
+        "dart": [
+            "engineer/mobile/dart-engineer",
+        ],
+        "php": [
+            "engineer/backend/php-engineer",
+        ],
+        "ruby": [
+            "engineer/backend/ruby-engineer",
+        ],
+        "swift": [
+            "engineer/mobile/swift-engineer",
+        ],
+        "kotlin": [
+            "engineer/mobile/kotlin-engineer",
+        ],
+    }
+
+    # Map detected frameworks to recommended agents
+    FRAMEWORK_TO_AGENTS: Dict[str, List[str]] = {
+        # Frontend frameworks
+        "react": [
+            "engineer/frontend/react-engineer",
+            "qa/web-qa",
+        ],
+        "nextjs": [
+            "engineer/frontend/nextjs-engineer",
+            "engineer/frontend/react-engineer",
+            "ops/platform/vercel-ops",
+        ],
+        "vue": [
+            "engineer/frontend/vue-engineer",
+        ],
+        "angular": [
+            "engineer/frontend/angular-engineer",
+        ],
+        # Backend frameworks
+        "fastapi": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "django": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "flask": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "express": [
+            "engineer/backend/javascript-engineer",
+            "qa/api-qa",
+        ],
+        "nest": [
+            "engineer/backend/javascript-engineer",
+            "qa/api-qa",
+        ],
+        # Mobile frameworks
+        "flutter": [
+            "engineer/mobile/dart-engineer",
+        ],
+        "react-native": [
+            "engineer/frontend/react-engineer",
+            "engineer/mobile/react-native-engineer",
+        ],
+        # Desktop frameworks
+        "tauri": [
+            "engineer/mobile/tauri-engineer",
+            "engineer/backend/rust-engineer",
+        ],
+        "electron": [
+            "engineer/backend/javascript-engineer",
+        ],
+    }
+
+    def __init__(self, toolchain_analyzer: Optional[ToolchainAnalyzerService] = None):
+        """Initialize agent recommendation service.
+
+        Args:
+            toolchain_analyzer: Optional pre-initialized toolchain analyzer.
+                               If None, creates a new instance.
+        """
+        self.toolchain_analyzer = toolchain_analyzer or ToolchainAnalyzerService()
+
+    def get_recommended_agents(
+        self,
+        project_path: Optional[str] = None,
+        confidence_threshold: float = 0.5,
+    ) -> Set[str]:
+        """Get recommended agents for a project.
+
+        Args:
+            project_path: Path to project directory. Defaults to cwd.
+            confidence_threshold: Minimum confidence for recommendations (0.0-1.0).
+                                 Only include detected components above this threshold.
+
+        Returns:
+            Set of recommended agent IDs (e.g., {"qa-agent", "research-agent", ...})
+
+        Example:
+            >>> service = AgentRecommendationService()
+            >>> recommended = service.get_recommended_agents()
+            >>> "qa-agent" in recommended
+            True
+            >>> # For Python project:
+            >>> "engineer/backend/python-engineer" in recommended
+            True
+        """
+        # Start with core agents (always recommended)
+        recommended = self.CORE_AGENTS.copy()
+
+        # Analyze project toolchain
+        if project_path is None:
+            project_path = str(Path.cwd())
+
+        try:
+            # ToolchainAnalyzerService.analyze_toolchain takes Path, not str
+            analysis = self.toolchain_analyzer.analyze_toolchain(Path(project_path))
+        except Exception as e:
+            # If analysis fails, just return core agents
+            print(f"Warning: Toolchain analysis failed: {e}")
+            return recommended
+
+        # Add language-specific agents
+        # ToolchainAnalysis has a single LanguageDetection object, not a list
+        if analysis.language_detection:
+            # Check primary language
+            primary_lang = analysis.language_detection.primary_language.lower()
+            if primary_lang in self.LANGUAGE_TO_AGENTS:
+                recommended.update(self.LANGUAGE_TO_AGENTS[primary_lang])
+
+            # Check secondary languages
+            for lang_component in analysis.language_detection.secondary_languages:
+                lang = lang_component.name.lower()
+                if lang in self.LANGUAGE_TO_AGENTS:
+                    recommended.update(self.LANGUAGE_TO_AGENTS[lang])
+
+        # Add framework-specific agents
+        for framework in analysis.frameworks:
+            fw_name = framework.name.lower()
+            if fw_name in self.FRAMEWORK_TO_AGENTS:
+                recommended.update(self.FRAMEWORK_TO_AGENTS[fw_name])
+
+        return recommended
+
+    def get_detection_summary(self, project_path: Optional[str] = None) -> Dict:
+        """Get human-readable summary of detected toolchain.
+
+        Args:
+            project_path: Path to project directory. Defaults to cwd.
+
+        Returns:
+            Dict with keys:
+            - detected_languages: List of detected language names
+            - detected_frameworks: List of detected framework names
+            - recommended_count: Number of recommended agents
+            - detection_quality: "high", "medium", "low", or "none"
+
+        Example:
+            >>> summary = service.get_detection_summary()
+            >>> summary['detected_languages']
+            ['Python', 'JavaScript']
+            >>> summary['recommended_count']
+            15
+        """
+        if project_path is None:
+            project_path = str(Path.cwd())
+
+        try:
+            analysis = self.toolchain_analyzer.analyze_toolchain(Path(project_path))
+
+            # Extract languages from LanguageDetection object
+            languages = []
+            if analysis.language_detection:
+                languages.append(analysis.language_detection.primary_language)
+                languages.extend(
+                    comp.name
+                    for comp in analysis.language_detection.secondary_languages
+                )
+
+            # Extract frameworks
+            frameworks = [fw.name for fw in analysis.frameworks]
+
+            # Get recommended agents
+            recommended = self.get_recommended_agents(project_path)
+
+            # Determine detection quality from overall_confidence
+            confidence_map = {
+                "high": "high",
+                "medium": "medium",
+                "low": "low",
+                "very_low": "low",
+            }
+            quality = confidence_map.get(
+                str(analysis.overall_confidence).lower(), "unknown"
+            )
+
+            return {
+                "detected_languages": languages,
+                "detected_frameworks": frameworks,
+                "recommended_count": len(recommended),
+                "detection_quality": quality,
+            }
+        except Exception as e:
+            # Log the error for debugging
+            print(f"Warning: Toolchain analysis failed: {e}")
+            return {
+                "detected_languages": [],
+                "detected_frameworks": [],
+                "recommended_count": len(self.CORE_AGENTS),
+                "detection_quality": "none",
+            }

claude_mpm/services/agents/agent_review_service.py

@@ -0,0 +1,280 @@
+"""Agent review service for comparing project agents with managed agents.
+
+WHY: This service helps users maintain a clean agent directory by:
+1. Identifying which agents are managed vs custom
+2. Detecting outdated versions of managed agents
+3. Finding unused agents that don't match the detected toolchain
+4. Safely archiving unnecessary agents instead of deleting them
+
+DESIGN DECISIONS:
+- Archive to .claude/agents/unused/ instead of deleting (safe, recoverable)
+- Add timestamps to archived files to prevent conflicts
+- Preserve custom user agents (not in managed set)
+- Compare versions to detect outdated managed agents
+"""
+
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Set
+
+from claude_mpm.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class AgentReviewService:
+    """Service for reviewing and managing project agents.
+
+    This service analyzes the relationship between project agents and managed
+    agents from the claude-mpm-agents repository, categorizing them as:
+    - Managed: In sync with managed agents
+    - Outdated: Older version of managed agent exists
+    - Custom: User-created agents not in managed set
+    - Unused: Not recommended for this project's toolchain
+    """
+
+    def __init__(self):
+        """Initialize the agent review service."""
+        self.logger = get_logger(__name__)
+
+    def review_project_agents(
+        self,
+        project_agents_dir: Path,
+        managed_agents: List[Dict[str, Any]],
+        recommended_agent_ids: Set[str],
+    ) -> Dict[str, List[Dict[str, Any]]]:
+        """Review existing project agents and categorize them.
+
+        Args:
+            project_agents_dir: Directory containing project agents (.claude/agents/)
+            managed_agents: List of managed agent dicts from cache
+            recommended_agent_ids: Set of agent IDs recommended for this toolchain
+
+        Returns:
+            Dictionary with categorized agents:
+            {
+                "managed": [...],      # In sync with managed
+                "outdated": [...],     # Older version exists
+                "custom": [...],       # User-created
+                "unused": [...],       # Not needed for this toolchain
+            }
+        """
+        results = {
+            "managed": [],
+            "outdated": [],
+            "custom": [],
+            "unused": [],
+        }
+
+        if not project_agents_dir.exists():
+            self.logger.debug(
+                f"Project agents directory does not exist: {project_agents_dir}"
+            )
+            return results
+
+        # Build lookup map of managed agents by ID
+        managed_by_id = {agent["agent_id"]: agent for agent in managed_agents}
+
+        # Scan project agents
+        for agent_file in project_agents_dir.glob("*.md"):
+            # Skip the unused directory itself
+            if agent_file.name == "unused":
+                continue
+
+            agent_name = agent_file.stem
+
+            # Parse agent to get version and metadata
+            project_agent_info = self._parse_project_agent(agent_file)
+
+            # Check if this is a managed agent
+            if agent_name in managed_by_id:
+                managed_agent = managed_by_id[agent_name]
+
+                # Compare versions
+                project_version = project_agent_info.get("version", "unknown")
+                managed_version = managed_agent.get("version", "unknown")
+
+                if self._is_outdated(project_version, managed_version):
+                    # Outdated version of managed agent
+                    results["outdated"].append(
+                        {
+                            "name": agent_name,
+                            "path": agent_file,
+                            "current_version": project_version,
+                            "available_version": managed_version,
+                            "recommended": agent_name in recommended_agent_ids,
+                        }
+                    )
+                else:
+                    # Up-to-date managed agent
+                    results["managed"].append(
+                        {
+                            "name": agent_name,
+                            "path": agent_file,
+                            "version": project_version,
+                            "recommended": agent_name in recommended_agent_ids,
+                        }
+                    )
+            else:
+                # Custom user agent (not in managed set)
+                results["custom"].append(
+                    {
+                        "name": agent_name,
+                        "path": agent_file,
+                        "version": project_agent_info.get("version", "unknown"),
+                    }
+                )
+
+        # Identify unused agents (managed or outdated but not recommended)
+        for category in ["managed", "outdated"]:
+            for agent in results[category][:]:  # Copy list to modify during iteration
+                if not agent.get("recommended", False):
+                    # This managed/outdated agent is not recommended for this toolchain
+                    results["unused"].append(agent)
+                    results[category].remove(agent)
+
+        self.logger.info(
+            f"Agent review complete: "
+            f"{len(results['managed'])} managed, "
+            f"{len(results['outdated'])} outdated, "
+            f"{len(results['custom'])} custom, "
+            f"{len(results['unused'])} unused"
+        )
+
+        return results
+
+    def archive_agents(
+        self, agents_to_archive: List[Dict[str, Any]], project_agents_dir: Path
+    ) -> Dict[str, Any]:
+        """Archive agents by moving them to .claude/agents/unused/.
+
+        Args:
+            agents_to_archive: List of agent dicts with 'name' and 'path' keys
+            project_agents_dir: Base agents directory (.claude/agents/)
+
+        Returns:
+            Dictionary with archival results:
+            {
+                "archived": [...],  # Successfully archived
+                "errors": [...],    # Archival errors
+            }
+        """
+        results = {"archived": [], "errors": []}
+
+        if not agents_to_archive:
+            return results
+
+        # Create unused directory
+        unused_dir = project_agents_dir / "unused"
+        unused_dir.mkdir(exist_ok=True)
+
+        for agent in agents_to_archive:
+            agent_path = agent["path"]
+            agent_name = agent["name"]
+
+            try:
+                # Generate timestamped filename to avoid conflicts
+                timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+                archived_name = f"{agent_name}_{timestamp}.md"
+                archived_path = unused_dir / archived_name
+
+                # Move the file
+                shutil.move(str(agent_path), str(archived_path))
+
+                results["archived"].append(
+                    {
+                        "name": agent_name,
+                        "original_path": str(agent_path),
+                        "archived_path": str(archived_path),
+                    }
+                )
+
+                self.logger.debug(f"Archived {agent_name} to {archived_path}")
+
+            except Exception as e:
+                error_msg = f"Failed to archive {agent_name}: {e}"
+                self.logger.error(error_msg)
+                results["errors"].append(error_msg)
+
+        self.logger.info(
+            f"Archived {len(results['archived'])} agents, "
+            f"{len(results['errors'])} errors"
+        )
+
+        return results
+
+    def _parse_project_agent(self, agent_file: Path) -> Dict[str, Any]:
+        """Parse a project agent file to extract metadata.
+
+        Args:
+            agent_file: Path to agent Markdown file
+
+        Returns:
+            Dictionary with agent metadata (version, name, etc.)
+        """
+        try:
+            content = agent_file.read_text(encoding="utf-8")
+
+            # Extract version from YAML frontmatter
+            import re
+
+            version_match = re.search(
+                r'^version:\s*["\']?(.+?)["\']?$', content, re.MULTILINE
+            )
+            version = version_match.group(1) if version_match else "unknown"
+
+            return {
+                "version": version,
+                "name": agent_file.stem,
+            }
+
+        except Exception as e:
+            self.logger.warning(f"Failed to parse agent {agent_file.name}: {e}")
+            return {"version": "unknown", "name": agent_file.stem}
+
+    def _is_outdated(self, current_version: str, available_version: str) -> bool:
+        """Check if current version is outdated compared to available version.
+
+        Args:
+            current_version: Currently deployed version
+            available_version: Available version from managed agents
+
+        Returns:
+            True if current version is outdated
+        """
+        # Handle unknown versions
+        if current_version == "unknown" or available_version == "unknown":
+            return False
+
+        # Simple string comparison for now
+        # TODO: Implement semantic version comparison (1.2.3 vs 1.2.4)
+        return current_version != available_version
+
+    def get_archive_summary(self, project_agents_dir: Path) -> Dict[str, Any]:
+        """Get summary of archived agents.
+
+        Args:
+            project_agents_dir: Base agents directory (.claude/agents/)
+
+        Returns:
+            Dictionary with archive statistics
+        """
+        unused_dir = project_agents_dir / "unused"
+
+        if not unused_dir.exists():
+            return {"count": 0, "agents": []}
+
+        archived_files = list(unused_dir.glob("*.md"))
+
+        return {
+            "count": len(archived_files),
+            "agents": [
+                {
+                    "name": f.stem,
+                    "path": str(f),
+                    "size_bytes": f.stat().st_size,
+                }
+                for f in archived_files
+            ],
+        }

claude_mpm/services/agents/deployment/agent_discovery_service.py

@@ -215,9 +215,8 @@ class AgentDiscoveryService:
             # Extract YAML frontmatter
             frontmatter = self._extract_yaml_frontmatter(template_content)
             if not frontmatter:
-                self.logger.warning(
-                    f"No valid YAML frontmatter in {template_file.name}"
-                )
+                # Silently return None for files without frontmatter
+                # (e.g., PM instruction templates in templates/ directory)
                 return None
 
             # Extract metadata directly from frontmatter (flat structure)

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -129,12 +129,13 @@ class AgentTemplateBuilder:
                 base_templates.append(base_agent_file)
                 self.logger.debug(f"Found BASE-AGENT.md at: {base_agent_file}")
 
-            # Stop at git repository root if detected
+            # Stop at git repository root if detected (check AFTER finding BASE-AGENT.md)
             if (current_dir / ".git").exists():
                 self.logger.debug(f"Reached git repository root at: {current_dir}")
                 break
 
-            # Stop at common repository root indicators
+            # Stop at common repository root indicators (check AFTER finding BASE-AGENT.md)
+            # This ensures we check the 'agents' directory before stopping at 'remote-agents'
             if current_dir.name in [".claude-mpm", "remote-agents", "cache"]:
                 self.logger.debug(
                     f"Reached repository root indicator at: {current_dir}"
@@ -675,6 +676,7 @@ Only include memories that are:
 """
             content = content + memory_instructions
 
+        # Combine frontmatter and content
         return frontmatter + content
 
     def build_agent_yaml(