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

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -26,6 +26,18 @@ from .agent_version_manager import AgentVersionManager
 from .remote_agent_discovery_service import RemoteAgentDiscoveryService
 
 
+def _normalize_agent_name(name: str) -> str:
+    """Normalize agent name for consistent comparison.
+
+    Converts spaces, underscores to hyphens and lowercases.
+    Examples:
+        "Dart Engineer" -> "dart-engineer"
+        "dart_engineer" -> "dart-engineer"
+        "DART-ENGINEER" -> "dart-engineer"
+    """
+    return name.lower().replace(" ", "-").replace("_", "-")
+
+
 class MultiSourceAgentDeploymentService:
     """Service for deploying agents from multiple sources with version comparison.
 
@@ -179,14 +191,14 @@ class MultiSourceAgentDeploymentService:
         system_templates_dir: Optional[Path] = None,
         project_agents_dir: Optional[Path] = None,
         user_agents_dir: Optional[Path] = None,
-        remote_agents_dir: Optional[Path] = None,
+        agents_cache_dir: Optional[Path] = None,
         working_directory: Optional[Path] = None,
     ) -> Dict[str, List[Dict[str, Any]]]:
-        """Discover agents from all 4 tiers (system, user, remote, project).
+        """Discover agents from all 4 tiers (system, user, cache, project).
 
         Priority hierarchy (highest to lowest):
         4. Project agents - Highest priority, project-specific customizations
-        3. Remote agents - GitHub-synced agents from cache
+        3. Cached agents - GitHub-synced agents from cache
         2. User agents - DEPRECATED, user-level customizations
         1. System templates - Lowest priority, built-in agents
 
@@ -194,7 +206,7 @@ class MultiSourceAgentDeploymentService:
             system_templates_dir: Directory containing system agent templates
             project_agents_dir: Directory containing project-specific agents
             user_agents_dir: Directory containing user custom agents (DEPRECATED)
-            remote_agents_dir: Directory containing cached remote agents
+            agents_cache_dir: Directory containing cached agents from Git sources
             working_directory: Current working directory for finding project agents
 
         Returns:
@@ -225,12 +237,12 @@ class MultiSourceAgentDeploymentService:
             if not user_agents_dir.exists():
                 user_agents_dir = None
 
-        if not remote_agents_dir:
-            # Check for remote agents in cache directory
+        if not agents_cache_dir:
+            # Check for agents in cache directory
             cache_dir = Path.home() / ".claude-mpm" / "cache"
-            remote_agents_dir = cache_dir / "remote-agents"
-            if not remote_agents_dir.exists():
-                remote_agents_dir = None
+            agents_cache_dir = cache_dir / "agents"
+            if not agents_cache_dir.exists():
+                agents_cache_dir = None
 
         # Discover agents from each source in priority order
         # Note: We process in reverse priority order (system first) and build up the dictionary
@@ -238,7 +250,7 @@ class MultiSourceAgentDeploymentService:
         sources = [
             ("system", system_templates_dir),
             ("user", user_agents_dir),
-            ("remote", remote_agents_dir),
+            ("remote", agents_cache_dir),
             ("project", project_agents_dir),
         ]
 
@@ -323,7 +335,7 @@ class MultiSourceAgentDeploymentService:
     def get_agents_by_collection(
         self,
         collection_id: str,
-        remote_agents_dir: Optional[Path] = None,
+        agents_cache_dir: Optional[Path] = None,
     ) -> List[Dict[str, Any]]:
         """Get all agents from a specific collection.
 
@@ -331,7 +343,7 @@ class MultiSourceAgentDeploymentService:
 
         Args:
             collection_id: Collection identifier (e.g., "bobmatnyc/claude-mpm-agents")
-            remote_agents_dir: Directory containing remote agents cache
+            agents_cache_dir: Directory containing agents cache
 
         Returns:
             List of agent dictionaries from the specified collection
@@ -342,18 +354,16 @@ class MultiSourceAgentDeploymentService:
             >>> len(agents)
             45
         """
-        if not remote_agents_dir:
+        if not agents_cache_dir:
             cache_dir = Path.home() / ".claude-mpm" / "cache"
-            remote_agents_dir = cache_dir / "remote-agents"
+            agents_cache_dir = cache_dir / "agents"
 
-        if not remote_agents_dir.exists():
-            self.logger.warning(
-                f"Remote agents directory not found: {remote_agents_dir}"
-            )
+        if not agents_cache_dir.exists():
+            self.logger.warning(f"Agents cache directory not found: {agents_cache_dir}")
             return []
 
         # Use RemoteAgentDiscoveryService to get collection agents
-        remote_service = RemoteAgentDiscoveryService(remote_agents_dir)
+        remote_service = RemoteAgentDiscoveryService(agents_cache_dir)
         collection_agents = remote_service.get_agents_by_collection(collection_id)
 
         self.logger.info(
@@ -470,7 +480,7 @@ class MultiSourceAgentDeploymentService:
         system_templates_dir: Optional[Path] = None,
         project_agents_dir: Optional[Path] = None,
         user_agents_dir: Optional[Path] = None,
-        remote_agents_dir: Optional[Path] = None,
+        agents_cache_dir: Optional[Path] = None,
         working_directory: Optional[Path] = None,
         excluded_agents: Optional[List[str]] = None,
         config: Optional[Config] = None,
@@ -482,7 +492,7 @@ class MultiSourceAgentDeploymentService:
             system_templates_dir: Directory containing system agent templates
             project_agents_dir: Directory containing project-specific agents
             user_agents_dir: Directory containing user custom agents (DEPRECATED)
-            remote_agents_dir: Directory containing cached remote agents
+            agents_cache_dir: Directory containing cached agents from Git sources
             working_directory: Current working directory for finding project agents
             excluded_agents: List of agent names to exclude from deployment
             config: Configuration object for additional filtering
@@ -499,7 +509,7 @@ class MultiSourceAgentDeploymentService:
             system_templates_dir=system_templates_dir,
             project_agents_dir=project_agents_dir,
             user_agents_dir=user_agents_dir,
-            remote_agents_dir=remote_agents_dir,
+            agents_cache_dir=agents_cache_dir,
             working_directory=working_directory,
         )
 
@@ -533,10 +543,42 @@ class MultiSourceAgentDeploymentService:
 
         # Apply exclusion filters
         if excluded_agents:
-            for agent_name in excluded_agents:
-                if agent_name in selected_agents:
-                    self.logger.info(f"Excluding agent '{agent_name}' from deployment")
-                    del selected_agents[agent_name]
+            # Find agents to remove by matching normalized names
+            # Normalization handles: "Dart Engineer", "dart_engineer", "dart-engineer"
+            agents_to_remove = []
+            excluded_set = {_normalize_agent_name(name) for name in excluded_agents}
+
+            for canonical_id, agent_info in list(selected_agents.items()):
+                # Check agent name field (normalized)
+                agent_name = _normalize_agent_name(agent_info.get("name", ""))
+
+                # Also check the agent_id portion of canonical_id (after the colon)
+                # Example: "bobmatnyc/claude-mpm-agents:pm" -> "pm"
+                raw_agent_id = (
+                    canonical_id.split(":")[-1] if ":" in canonical_id else canonical_id
+                )
+                agent_id = _normalize_agent_name(raw_agent_id)
+
+                # Check file stem from path (most reliable match)
+                file_stem = ""
+                path_str = agent_info.get("path") or agent_info.get("file_path")
+                if path_str:
+                    file_stem = _normalize_agent_name(Path(path_str).stem)
+
+                if (
+                    agent_name in excluded_set
+                    or agent_id in excluded_set
+                    or file_stem in excluded_set
+                ):
+                    agents_to_remove.append(canonical_id)
+                    self.logger.info(
+                        f"Excluding agent '{agent_info.get('name', raw_agent_id)}' "
+                        f"(canonical_id: {canonical_id}) from deployment"
+                    )
+
+            # Remove matched agents
+            for canonical_id in agents_to_remove:
+                del selected_agents[canonical_id]
 
         # Apply config-based filtering if provided
         if config:
@@ -585,6 +627,107 @@ class MultiSourceAgentDeploymentService:
 
         return agents_to_deploy, agent_sources, cleanup_results
 
+    def cleanup_excluded_agents(
+        self,
+        deployed_agents_dir: Path,
+        agents_to_deploy: Dict[str, Path],
+    ) -> Dict[str, Any]:
+        """Remove agents from deployed directory that aren't in the deployment list.
+
+        Similar to skill cleanup logic, this removes agents that were previously
+        deployed but are no longer in the enabled agents list (e.g., filtered out
+        by profile configuration).
+
+        Args:
+            deployed_agents_dir: Directory containing deployed agents (~/.claude/agents)
+            agents_to_deploy: Dictionary mapping agent file stems to template paths
+
+        Returns:
+            Dictionary with cleanup results:
+            - removed: List of removed agent names
+            - errors: List of errors during cleanup
+        """
+        cleanup_results = {"removed": [], "errors": []}
+
+        # Safety check - only operate on deployed agents directory
+        if not deployed_agents_dir.exists():
+            self.logger.debug(
+                "Deployed agents directory does not exist, no cleanup needed"
+            )
+            return cleanup_results
+
+        # Build set of agent names that should exist (file stems without .md extension)
+        expected_agents = set(agents_to_deploy.keys())
+
+        try:
+            # Check each file in deployed_agents_dir
+            for item in deployed_agents_dir.iterdir():
+                # Only process .md files
+                if not item.is_file() or item.suffix != ".md":
+                    continue
+
+                # Skip hidden files
+                if item.name.startswith("."):
+                    continue
+
+                # Get agent name (file stem)
+                agent_name = item.stem
+
+                # Check if this agent should be kept
+                if agent_name not in expected_agents:
+                    try:
+                        # Security: Validate path is within deployed_agents_dir
+                        resolved_item = item.resolve()
+                        resolved_target = deployed_agents_dir.resolve()
+
+                        if not str(resolved_item).startswith(str(resolved_target)):
+                            self.logger.error(
+                                f"Refusing to remove path outside target directory: {item}"
+                            )
+                            cleanup_results["errors"].append(
+                                {
+                                    "agent": agent_name,
+                                    "error": "Path outside target directory",
+                                }
+                            )
+                            continue
+
+                        # Remove the agent file
+                        item.unlink()
+                        cleanup_results["removed"].append(agent_name)
+                        self.logger.info(f"Removed excluded agent: {agent_name}")
+
+                    except PermissionError as e:
+                        error_msg = f"Permission denied removing {agent_name}: {e}"
+                        self.logger.error(error_msg)
+                        cleanup_results["errors"].append(
+                            {"agent": agent_name, "error": error_msg}
+                        )
+                    except Exception as e:
+                        error_msg = f"Error removing {agent_name}: {e}"
+                        self.logger.error(error_msg)
+                        cleanup_results["errors"].append(
+                            {"agent": agent_name, "error": error_msg}
+                        )
+
+        except Exception as e:
+            self.logger.error(f"Error during agent cleanup: {e}")
+            cleanup_results["errors"].append(
+                {"agent": "cleanup_process", "error": str(e)}
+            )
+
+        # Log cleanup summary
+        if cleanup_results["removed"]:
+            self.logger.info(
+                f"Cleanup complete: removed {len(cleanup_results['removed'])} excluded agents"
+            )
+        if cleanup_results["errors"]:
+            self.logger.warning(
+                f"Encountered {len(cleanup_results['errors'])} errors during cleanup"
+            )
+
+        return cleanup_results
+
     def cleanup_outdated_user_agents(
         self,
         agents_by_name: Dict[str, List[Dict[str, Any]]],

claude_mpm/services/agents/deployment/remote_agent_discovery_service.py

@@ -42,7 +42,7 @@ class RemoteAgentMetadata:
 class RemoteAgentDiscoveryService:
     """Discovers and converts remote Markdown agents to JSON format.
 
-    Remote agents are discovered from the cache directory (~/.claude-mpm/cache/remote-agents/)
+    Remote agents are discovered from the cache directory (~/.claude-mpm/cache/agents/)
     where they are stored as Markdown files. This service:
     1. Discovers all *.md files in the remote agents cache
     2. Parses Markdown frontmatter and content to extract metadata
@@ -61,20 +61,20 @@ class RemoteAgentDiscoveryService:
     - Flexibility: Supports optional sections with defaults
     """
 
-    def __init__(self, remote_agents_dir: Path):
+    def __init__(self, agents_cache_dir: Path):
         """Initialize the remote agent discovery service.
 
         Args:
-            remote_agents_dir: Directory containing cached remote agent Markdown files
+            agents_cache_dir: Directory containing cached agent Markdown files
         """
-        self.remote_agents_dir = remote_agents_dir
+        self.agents_cache_dir = agents_cache_dir
         self.logger = get_logger(__name__)
 
     def _extract_collection_id_from_path(self, file_path: Path) -> Optional[str]:
         """Extract collection_id from repository path structure.
 
         Collection ID is derived from the repository path structure:
-        ~/.claude-mpm/cache/remote-agents/{owner}/{repo}/agents/...
+        ~/.claude-mpm/cache/agents/{owner}/{repo}/agents/...
 
         Args:
             file_path: Absolute path to agent Markdown file
@@ -83,28 +83,29 @@ class RemoteAgentDiscoveryService:
             Collection ID in format "owner/repo-name" or None if not found
 
         Example:
-            Input:  ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents/pm.md
+            Input:  ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents/pm.md
             Output: "bobmatnyc/claude-mpm-agents"
         """
         try:
-            # Find "remote-agents" in the path
+            # Find "agents" cache directory in the path (looking for .claude-mpm/cache/agents)
             path_parts = file_path.parts
-            remote_agents_idx = -1
+            agents_cache_idx = -1
 
             for i, part in enumerate(path_parts):
-                if part == "remote-agents":
-                    remote_agents_idx = i
+                # Look for cache/agents pattern
+                if part == "agents" and i > 0 and path_parts[i - 1] == "cache":
+                    agents_cache_idx = i
                     break
 
-            if remote_agents_idx == -1 or remote_agents_idx + 2 >= len(path_parts):
+            if agents_cache_idx == -1 or agents_cache_idx + 2 >= len(path_parts):
                 self.logger.debug(
                     f"Could not extract collection_id from path: {file_path}"
                 )
                 return None
 
-            # Extract owner and repo (next two parts after "remote-agents")
-            owner = path_parts[remote_agents_idx + 1]
-            repo = path_parts[remote_agents_idx + 2]
+            # Extract owner and repo (next two parts after "cache/agents")
+            owner = path_parts[agents_cache_idx + 1]
+            repo = path_parts[agents_cache_idx + 2]
 
             collection_id = f"{owner}/{repo}"
             self.logger.debug(f"Extracted collection_id: {collection_id}")
@@ -128,25 +129,26 @@ class RemoteAgentDiscoveryService:
             Relative path from repo root, or None if not found
 
         Example:
-            Input:  ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents/pm.md
+            Input:  ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents/pm.md
             Output: "agents/pm.md"
         """
         try:
-            # Find "remote-agents" in the path
+            # Find "agents" cache directory in the path
             path_parts = file_path.parts
-            remote_agents_idx = -1
+            agents_cache_idx = -1
 
             for i, part in enumerate(path_parts):
-                if part == "remote-agents":
-                    remote_agents_idx = i
+                # Look for cache/agents pattern
+                if part == "agents" and i > 0 and path_parts[i - 1] == "cache":
+                    agents_cache_idx = i
                     break
 
-            if remote_agents_idx == -1 or remote_agents_idx + 3 >= len(path_parts):
+            if agents_cache_idx == -1 or agents_cache_idx + 3 >= len(path_parts):
                 return None
 
             # Path after owner/repo is the source path
-            # remote-agents/{owner}/{repo}/{source_path}
-            repo_root_idx = remote_agents_idx + 3
+            # cache/agents/{owner}/{repo}/{source_path}
+            repo_root_idx = agents_cache_idx + 3
             source_parts = path_parts[repo_root_idx:]
 
             return "/".join(source_parts)
@@ -273,7 +275,7 @@ class RemoteAgentDiscoveryService:
 
         Supports both cache structures:
         1. Git repo: Calculate relative to /agents/ subdirectory
-        2. Flattened cache: Calculate relative to remote_agents_dir directly
+        2. Flattened cache: Calculate relative to agents_cache_dir directly
 
         Example (Git repo):
             Input:  /cache/bobmatnyc/claude-mpm-agents/agents/engineer/backend/python-engineer.md
@@ -281,8 +283,8 @@ class RemoteAgentDiscoveryService:
             Output: engineer/backend/python-engineer
 
         Example (Flattened cache):
-            Input:  /cache/remote-agents/engineer/python-engineer.md
-            Root:   /cache/remote-agents
+            Input:  /cache/agents/engineer/python-engineer.md
+            Root:   /cache/agents
             Output: engineer/python-engineer
 
         Args:
@@ -293,7 +295,7 @@ class RemoteAgentDiscoveryService:
         """
         try:
             # Try git repo structure first: /agents/ subdirectory
-            agents_dir = self.remote_agents_dir / "agents"
+            agents_dir = self.agents_cache_dir / "agents"
             if agents_dir.exists():
                 try:
                     relative_path = file_path.relative_to(agents_dir)
@@ -301,12 +303,12 @@ class RemoteAgentDiscoveryService:
                 except ValueError:
                     pass  # Not under agents_dir, try flattened structure
 
-            # Try flattened cache structure: calculate relative to remote_agents_dir
+            # Try flattened cache structure: calculate relative to agents_cache_dir
             try:
-                relative_path = file_path.relative_to(self.remote_agents_dir)
+                relative_path = file_path.relative_to(self.agents_cache_dir)
                 return str(relative_path.with_suffix("")).replace("\\", "/")
             except ValueError:
-                pass  # Not under remote_agents_dir either
+                pass  # Not under agents_cache_dir either
 
             # Fall back to filename
             self.logger.warning(
@@ -327,7 +329,7 @@ class RemoteAgentDiscoveryService:
 
         Supports both cache structures:
         1. Git repo: Calculate relative to /agents/ subdirectory
-        2. Flattened cache: Calculate relative to remote_agents_dir directly
+        2. Flattened cache: Calculate relative to agents_cache_dir directly
 
         Example (Git repo):
             Input:  /cache/bobmatnyc/claude-mpm-agents/agents/engineer/backend/python-engineer.md
@@ -335,8 +337,8 @@ class RemoteAgentDiscoveryService:
             Output: engineer/backend
 
         Example (Flattened cache):
-            Input:  /cache/remote-agents/engineer/python-engineer.md
-            Root:   /cache/remote-agents
+            Input:  /cache/agents/engineer/python-engineer.md
+            Root:   /cache/agents
             Output: engineer
 
         Args:
@@ -347,7 +349,7 @@ class RemoteAgentDiscoveryService:
         """
         try:
             # Try git repo structure first: /agents/ subdirectory
-            agents_dir = self.remote_agents_dir / "agents"
+            agents_dir = self.agents_cache_dir / "agents"
             if agents_dir.exists():
                 try:
                     relative_path = file_path.relative_to(agents_dir)
@@ -356,13 +358,13 @@ class RemoteAgentDiscoveryService:
                 except ValueError:
                     pass  # Not under agents_dir, try flattened structure
 
-            # Try flattened cache structure: calculate relative to remote_agents_dir
+            # Try flattened cache structure: calculate relative to agents_cache_dir
             try:
-                relative_path = file_path.relative_to(self.remote_agents_dir)
+                relative_path = file_path.relative_to(self.agents_cache_dir)
                 parts = relative_path.parts[:-1]  # Exclude filename
                 return "/".join(parts) if parts else "universal"
             except ValueError:
-                pass  # Not under remote_agents_dir either
+                pass  # Not under agents_cache_dir either
 
             return "universal"
         except Exception:
@@ -385,7 +387,7 @@ class RemoteAgentDiscoveryService:
             List of agent dictionaries in JSON template format
 
         Example:
-            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/agents"))
             >>> agents = service.discover_remote_agents()
             >>> len(agents)
             5
@@ -394,20 +396,21 @@ class RemoteAgentDiscoveryService:
         """
         agents = []
 
-        if not self.remote_agents_dir.exists():
+        if not self.agents_cache_dir.exists():
             self.logger.debug(
-                f"Remote agents directory does not exist: {self.remote_agents_dir}"
+                f"Agents cache directory does not exist: {self.agents_cache_dir}"
             )
             return agents
 
-        # Support three cache structures (PRIORITY ORDER):
+        # Support four cache structures (PRIORITY ORDER):
         # 1. Built output: {path}/dist/agents/ - PREFERRED (built with BASE-AGENT composition)
         # 2. Git repo path: {path}/agents/ - source files (fallback)
-        # 3. Flattened cache: {path}/ - directly contains category directories (legacy)
+        # 3. Owner/repo structure: {path}/{owner}/{repo}/agents/ - GitHub sync structure
+        # 4. Flattened cache: {path}/ - directly contains category directories (legacy)
 
         # Priority 1: Check for dist/agents/ (built output with BASE-AGENT composition)
-        dist_agents_dir = self.remote_agents_dir / "dist" / "agents"
-        agents_dir = self.remote_agents_dir / "agents"
+        dist_agents_dir = self.agents_cache_dir / "dist" / "agents"
+        agents_dir = self.agents_cache_dir / "agents"
 
         if dist_agents_dir.exists():
             # PREFERRED: Use built agents from dist/agents/
@@ -420,32 +423,52 @@ class RemoteAgentDiscoveryService:
             self.logger.debug(f"Using source agents (no dist/ found): {agents_dir}")
             scan_dir = agents_dir
         else:
-            # LEGACY: Flattened cache structure - scan root directly
-            # Check if this looks like the flattened cache (has category subdirectories)
-            category_dirs = [
-                "universal",
-                "engineer",
-                "ops",
-                "qa",
-                "security",
-                "documentation",
-            ]
-            has_categories = any(
-                (self.remote_agents_dir / cat).exists() for cat in category_dirs
-            )
-
-            if has_categories:
-                self.logger.debug(
-                    f"Using flattened cache structure: {self.remote_agents_dir}"
-                )
-                scan_dir = self.remote_agents_dir
+            # Priority 3: Check for {owner}/{repo}/agents/ structure (GitHub sync)
+            # e.g., ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents/
+            owner_repo_agents_dir = None
+            for owner_dir in self.agents_cache_dir.iterdir():
+                if owner_dir.is_dir() and not owner_dir.name.startswith("."):
+                    for repo_dir in owner_dir.iterdir():
+                        if repo_dir.is_dir():
+                            potential_agents = repo_dir / "agents"
+                            if potential_agents.exists():
+                                owner_repo_agents_dir = potential_agents
+                                self.logger.debug(
+                                    f"Using GitHub sync structure: {owner_repo_agents_dir}"
+                                )
+                                break
+                    if owner_repo_agents_dir:
+                        break
+
+            if owner_repo_agents_dir:
+                scan_dir = owner_repo_agents_dir
             else:
-                self.logger.warning(
-                    f"No agent directories found. Checked: {dist_agents_dir}, {agents_dir}, "
-                    f"and category directories in {self.remote_agents_dir}. "
-                    f"Expected agents in /dist/agents/, /agents/, or category directories."
+                # LEGACY: Flattened cache structure - scan root directly
+                # Check if this looks like the flattened cache (has category subdirectories)
+                category_dirs = [
+                    "universal",
+                    "engineer",
+                    "ops",
+                    "qa",
+                    "security",
+                    "documentation",
+                ]
+                has_categories = any(
+                    (self.agents_cache_dir / cat).exists() for cat in category_dirs
                 )
-                return agents
+
+                if has_categories:
+                    self.logger.debug(
+                        f"Using flattened cache structure: {self.agents_cache_dir}"
+                    )
+                    scan_dir = self.agents_cache_dir
+                else:
+                    self.logger.warning(
+                        f"No agent directories found. Checked: {dist_agents_dir}, {agents_dir}, "
+                        f"owner/repo/agents/ structure, and category directories in {self.agents_cache_dir}. "
+                        "Expected agents in /dist/agents/, /agents/, owner/repo/agents/, or category directories."
+                    )
+                    return agents
 
         # Find all Markdown files recursively
         md_files = list(scan_dir.rglob("*.md"))
@@ -468,6 +491,9 @@ class RemoteAgentDiscoveryService:
             "SKILL.md",
             "SKILLS.md",
             "skill-template.md",
+            # Legacy agents superseded by newer versions
+            # TODO: Remove after bobmatnyc/claude-mpm-agents#XXX is merged
+            "memory-manager.md",  # Superseded by memory-manager-agent.md (v1.2.0)
         }
         md_files = [f for f in md_files if f.name not in excluded_files]
 
@@ -482,16 +508,16 @@ class RemoteAgentDiscoveryService:
 
         # In flattened cache mode, also exclude files from git repository subdirectories
         # (files under directories that contain .git folder)
-        if scan_dir == self.remote_agents_dir:
+        if scan_dir == self.agents_cache_dir:
             filtered_files = []
             for f in md_files:
                 # Check if this file is inside a git repository (has .git in path)
-                # Git repos are at {remote_agents_dir}/{owner}/{repo}/.git
-                path_parts = f.relative_to(self.remote_agents_dir).parts
+                # Git repos are at {agents_cache_dir}/{owner}/{repo}/.git
+                path_parts = f.relative_to(self.agents_cache_dir).parts
                 if len(path_parts) >= 2:
                     # Check if this looks like a git repo path (owner/repo)
                     potential_repo = (
-                        self.remote_agents_dir / path_parts[0] / path_parts[1]
+                        self.agents_cache_dir / path_parts[0] / path_parts[1]
                     )
                     if (potential_repo / ".git").exists():
                         # This file is in a git repo, skip it (we'll handle git repos separately)
@@ -518,7 +544,7 @@ class RemoteAgentDiscoveryService:
                 self.logger.warning(f"Failed to parse remote agent {md_file.name}: {e}")
 
         self.logger.info(
-            f"Discovered {len(agents)} remote agents from {self.remote_agents_dir.name}"
+            f"Discovered {len(agents)} remote agents from {self.agents_cache_dir.name}"
         )
         return agents
 
@@ -735,7 +761,7 @@ class RemoteAgentDiscoveryService:
             RemoteAgentMetadata if found, None otherwise
         """
         # Bug #4 fix: Search in /agents/ subdirectory, not root directory
-        agents_dir = self.remote_agents_dir / "agents"
+        agents_dir = self.agents_cache_dir / "agents"
         if not agents_dir.exists():
             return None
 
@@ -767,7 +793,7 @@ class RemoteAgentDiscoveryService:
             List of agent dictionaries from the specified collection
 
         Example:
-            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/agents"))
             >>> agents = service.get_agents_by_collection("bobmatnyc/claude-mpm-agents")
             >>> len(agents)
             45
@@ -795,7 +821,7 @@ class RemoteAgentDiscoveryService:
             - agents: List of agent IDs in collection
 
         Example:
-            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/agents"))
             >>> collections = service.list_collections()
             >>> collections
             [