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

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(

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -16,6 +16,8 @@ import os
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
+import yaml
+
 from claude_mpm.core.config import Config
 from claude_mpm.core.logging_config import get_logger
 
@@ -51,6 +53,70 @@ class MultiSourceAgentDeploymentService:
         self.logger = get_logger(__name__)
         self.version_manager = AgentVersionManager()
 
+    def _read_template_version(self, template_path: Path) -> Optional[str]:
+        """Read version from template file (supports both .md and .json formats).
+
+        For .md files: Extract version from YAML frontmatter
+        For .json files: Extract version from JSON structure
+
+        Args:
+            template_path: Path to template file
+
+        Returns:
+            Version string or None if version cannot be extracted
+        """
+        try:
+            if template_path.suffix == ".md":
+                # Parse markdown with YAML frontmatter
+                content = template_path.read_text()
+
+                # Extract YAML frontmatter (between --- markers)
+                if not content.strip().startswith("---"):
+                    return None
+
+                parts = content.split("---", 2)
+                if len(parts) < 3:
+                    return None
+
+                # Parse YAML frontmatter
+                frontmatter = yaml.safe_load(parts[1])
+                if not frontmatter:
+                    return None
+
+                # Extract version from frontmatter
+                version = frontmatter.get("version")
+                return version if version else None
+
+            if template_path.suffix == ".json":
+                # Parse JSON template
+                template_data = json.loads(template_path.read_text())
+                metadata = template_data.get("metadata", {})
+                version = (
+                    template_data.get("agent_version")
+                    or template_data.get("version")
+                    or metadata.get("version")
+                )
+                return version if version else None
+
+            self.logger.warning(
+                f"Unknown template format: {template_path.suffix} for {template_path.name}"
+            )
+            return None
+
+        except yaml.YAMLError as e:
+            self.logger.warning(
+                f"Invalid YAML frontmatter in {template_path.name}: {e}"
+            )
+            return None
+        except json.JSONDecodeError as e:
+            self.logger.warning(f"Invalid JSON in {template_path.name}: {e}")
+            return None
+        except Exception as e:
+            self.logger.warning(
+                f"Error reading template version from {template_path.name}: {e}"
+            )
+            return None
+
     def _build_canonical_id_for_agent(self, agent_info: Dict[str, Any]) -> str:
         """Build or retrieve canonical_id for an agent.
 
@@ -827,17 +893,20 @@ class MultiSourceAgentDeploymentService:
                 comparison_results["needs_update"].append(agent_name)
                 continue
 
-            # Read template version
-            try:
-                template_data = json.loads(template_path.read_text())
-                metadata = template_data.get("metadata", {})
-                template_version = self.version_manager.parse_version(
-                    template_data.get("agent_version")
-                    or template_data.get("version")
-                    or metadata.get("version", "0.0.0")
+            # Read template version using format-aware helper
+            version_string = self._read_template_version(template_path)
+            if not version_string:
+                self.logger.warning(
+                    f"Could not extract version from template for '{agent_name}', skipping"
                 )
+                continue
+
+            try:
+                template_version = self.version_manager.parse_version(version_string)
             except Exception as e:
-                self.logger.warning(f"Error reading template for '{agent_name}': {e}")
+                self.logger.warning(
+                    f"Error parsing version '{version_string}' for '{agent_name}': {e}"
+                )
                 continue
 
             # Read deployed version