claude-mpm 5.4.41__py3-none-any.whl → 5.6.23__py3-none-any.whl

claude_mpm/services/agents/deployment/remote_agent_discovery_service.py

@@ -402,10 +402,11 @@ class RemoteAgentDiscoveryService:
             )
             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.agents_cache_dir / "dist" / "agents"
@@ -422,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.agents_cache_dir / cat).exists() for cat in category_dirs
-            )
-
-            if has_categories:
-                self.logger.debug(
-                    f"Using flattened cache structure: {self.agents_cache_dir}"
-                )
-                scan_dir = self.agents_cache_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.agents_cache_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"))
@@ -470,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]
 

claude_mpm/services/agents/deployment/startup_reconciliation.py

@@ -0,0 +1,138 @@
+"""
+Startup Reconciliation Hook
+
+This module provides a hook for performing agent/skill reconciliation
+during application startup, ensuring deployed state matches configuration.
+
+Usage:
+    from claude_mpm.services.agents.deployment.startup_reconciliation import (
+        perform_startup_reconciliation
+    )
+
+    # In your startup code
+    perform_startup_reconciliation()
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.core.logging_utils import get_logger
+from claude_mpm.core.unified_config import UnifiedConfig
+
+from .deployment_reconciler import DeploymentReconciler, DeploymentResult
+
+logger = get_logger(__name__)
+
+
+def perform_startup_reconciliation(
+    project_path: Optional[Path] = None,
+    config: Optional[UnifiedConfig] = None,
+    silent: bool = False,
+) -> tuple[DeploymentResult, DeploymentResult]:
+    """
+    Perform agent and skill reconciliation during startup.
+
+    This ensures the deployed state (.claude/agents, .claude/skills) matches
+    the configuration (agents.enabled, skills.enabled lists).
+
+    Args:
+        project_path: Project directory (default: current directory)
+        config: Configuration instance (auto-loads if None)
+        silent: Suppress info logging (only errors)
+
+    Returns:
+        Tuple of (agent_result, skill_result)
+    """
+    project_path = project_path or Path.cwd()
+
+    # Load config if not provided
+    if config is None:
+        config = UnifiedConfig()
+
+    # Initialize reconciler
+    reconciler = DeploymentReconciler(config)
+
+    if not silent:
+        logger.info("Performing startup reconciliation...")
+
+    # Reconcile agents
+    agent_result = reconciler.reconcile_agents(project_path)
+
+    if agent_result.deployed and not silent:
+        logger.info(f"Deployed agents: {', '.join(agent_result.deployed)}")
+    if agent_result.removed and not silent:
+        logger.info(f"Removed agents: {', '.join(agent_result.removed)}")
+    if agent_result.errors:
+        for error in agent_result.errors:
+            logger.error(f"Agent reconciliation error: {error}")
+
+    # Reconcile skills
+    skill_result = reconciler.reconcile_skills(project_path)
+
+    if skill_result.deployed and not silent:
+        logger.info(f"Deployed skills: {', '.join(skill_result.deployed)}")
+    if skill_result.removed and not silent:
+        logger.info(f"Removed skills: {', '.join(skill_result.removed)}")
+    if skill_result.errors:
+        for error in skill_result.errors:
+            logger.error(f"Skill reconciliation error: {error}")
+
+    if not silent:
+        total_errors = len(agent_result.errors) + len(skill_result.errors)
+        if total_errors == 0:
+            logger.info("Startup reconciliation complete")
+        else:
+            logger.warning(
+                f"Startup reconciliation complete with {total_errors} errors"
+            )
+
+    return agent_result, skill_result
+
+
+def check_reconciliation_needed(
+    project_path: Optional[Path] = None, config: Optional[UnifiedConfig] = None
+) -> bool:
+    """
+    Check if reconciliation is needed (without performing it).
+
+    Args:
+        project_path: Project directory
+        config: Configuration instance
+
+    Returns:
+        True if reconciliation would make changes
+    """
+    project_path = project_path or Path.cwd()
+
+    if config is None:
+        config = UnifiedConfig()
+
+    reconciler = DeploymentReconciler(config)
+    view = reconciler.get_reconciliation_view(project_path)
+
+    agent_state = view["agents"]
+    skill_state = view["skills"]
+
+    # Check if any changes needed
+    return (
+        len(agent_state.to_deploy) > 0
+        or len(agent_state.to_remove) > 0
+        or len(skill_state.to_deploy) > 0
+        or len(skill_state.to_remove) > 0
+    )
+
+
+# Example integration in startup code:
+#
+# from claude_mpm.services.agents.deployment.startup_reconciliation import (
+#     perform_startup_reconciliation,
+#     check_reconciliation_needed
+# )
+#
+# def startup():
+#     # Check if reconciliation needed
+#     if check_reconciliation_needed():
+#         logger.info("Reconciliation needed, performing...")
+#         perform_startup_reconciliation()
+#     else:
+#         logger.debug("No reconciliation needed")

claude_mpm/services/agents/git_source_manager.py

@@ -395,8 +395,27 @@ class GitSourceManager:
                     )
                     logger.debug(f"[DEBUG] Found {len(agents)} agents so far")
 
-        logger.debug(f"[DEBUG] list_cached_agents COMPLETE: {len(agents)} total agents")
-        return agents
+        logger.debug(
+            f"[DEBUG] list_cached_agents COMPLETE: {len(agents)} total agents (before deduplication)"
+        )
+
+        # Deduplicate agents by agent_id (Bug #2 fix)
+        # When same agent exists in multiple locations, keep only first occurrence
+        seen_ids = set()
+        deduplicated_agents = []
+
+        for agent in agents:
+            agent_id = agent.get("agent_id") or agent.get("metadata", {}).get("name")
+            if agent_id and agent_id not in seen_ids:
+                seen_ids.add(agent_id)
+                deduplicated_agents.append(agent)
+            elif agent_id:
+                logger.debug(f"[DEBUG] Skipping duplicate agent: {agent_id}")
+
+        logger.debug(
+            f"[DEBUG] After deduplication: {len(deduplicated_agents)} unique agents"
+        )
+        return deduplicated_agents
 
     def _discover_agents_in_directory(
         self,

claude_mpm/services/agents/loading/framework_agent_loader.py

@@ -10,10 +10,19 @@ Loading precedence: Project → User → System
 
 This service integrates with the main agent_loader.py to provide
 markdown-based agent profiles alongside JSON-based templates.
+
+Auto-Deployment: When no agents are configured, the standard 6 core agents
+are automatically deployed:
+- engineer: General-purpose implementation
+- research: Codebase exploration and analysis
+- qa: Testing and quality assurance
+- documentation: Documentation generation
+- ops: Basic deployment operations
+- ticketing: Ticket tracking (essential for PM workflow)
 """
 
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from claude_mpm.agents.agent_loader import AgentTier, list_agents_by_tier
 from claude_mpm.core.logging_utils import get_logger
@@ -21,6 +30,17 @@ from claude_mpm.core.unified_paths import get_path_manager
 
 logger = get_logger(__name__)
 
+# Standard 6 core agents that are auto-deployed when no agents are specified
+# This list is the canonical source - other modules should import from here
+CORE_AGENTS: List[str] = [
+    "engineer",  # General-purpose implementation
+    "research",  # Codebase exploration and analysis
+    "qa",  # Testing and quality assurance
+    "documentation",  # Documentation generation
+    "ops",  # Basic deployment operations
+    "ticketing",  # Ticket tracking (essential for PM workflow)
+]
+
 
 class FrameworkAgentLoader:
     """Loads agent profiles from project, user, and system directories with proper precedence"""
@@ -86,7 +106,7 @@ class FrameworkAgentLoader:
                 data_claude = package_path / "data" / "agents" / "CLAUDE.md"
                 if data_instructions.exists() or data_claude.exists():
                     return package_path / "data"
-        except Exception:
+        except Exception:  # nosec B110 - intentional fallthrough to next location
             pass
 
         current = Path.cwd()
@@ -431,3 +451,56 @@ Please operate according to your profile specifications and maintain quality sta
 """
 
         return instruction.strip()
+
+    def get_core_agents(self) -> List[str]:
+        """
+        Get the standard 6 core agents for auto-deployment.
+
+        These agents are automatically deployed when no agents are specified
+        in the configuration. They provide essential PM workflow functionality.
+
+        Returns:
+            List of core agent IDs
+
+        Example:
+            >>> loader = FrameworkAgentLoader()
+            >>> core = loader.get_core_agents()
+            >>> 'engineer' in core
+            True
+            >>> len(core)
+            6
+        """
+        return CORE_AGENTS.copy()
+
+    def get_agents_with_fallback(self) -> Dict[str, list]:
+        """
+        Get available agents, falling back to core agents if none found.
+
+        This method implements the auto-deployment logic: when no agents
+        are found in any tier (project, user, system), it returns the
+        standard 6 core agents as a fallback.
+
+        Returns:
+            Dictionary with agent lists by tier. If no agents found in any tier,
+            returns core agents under 'fallback' key.
+
+        Example:
+            >>> loader = FrameworkAgentLoader()
+            >>> loader.initialize()
+            >>> agents = loader.get_agents_with_fallback()
+            >>> if 'fallback' in agents:
+            ...     print("Using core agents as fallback")
+        """
+        available = self.get_available_agents()
+
+        # Check if any agents are found
+        total_agents = sum(len(agents) for agents in available.values())
+
+        if total_agents == 0:
+            logger.info(
+                "No agents found in configuration. "
+                "Auto-deploying standard 6 core agents."
+            )
+            return {"fallback": CORE_AGENTS.copy()}
+
+        return available

claude_mpm/services/agents/single_tier_deployment_service.py

@@ -30,12 +30,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from src.claude_mpm.config.agent_sources import AgentSourceConfiguration
-from src.claude_mpm.models.git_repository import GitRepository
-from src.claude_mpm.services.agents.deployment.remote_agent_discovery_service import (
+from claude_mpm.config.agent_sources import AgentSourceConfiguration
+from claude_mpm.models.git_repository import GitRepository
+from claude_mpm.services.agents.deployment.remote_agent_discovery_service import (
     RemoteAgentDiscoveryService,
 )
-from src.claude_mpm.services.agents.git_source_manager import GitSourceManager
+from claude_mpm.services.agents.git_source_manager import GitSourceManager
 
 logger = logging.getLogger(__name__)
 

claude_mpm/services/agents/sources/git_source_sync_service.py

@@ -13,11 +13,16 @@ import logging
 import time
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 import requests
 
 from claude_mpm.core.file_utils import get_file_hash
+
+# Import normalize function for exclusion filtering
+from claude_mpm.services.agents.deployment.multi_source_deployment_service import (
+    _normalize_agent_name,
+)
 from claude_mpm.services.agents.sources.agent_sync_state import AgentSyncState
 from claude_mpm.utils.progress import create_progress_bar
 
@@ -923,6 +928,62 @@ class GitSourceSyncService:
         """
         return self.cache_dir
 
+    def _cleanup_excluded_agents(
+        self,
+        deployment_dir: Path,
+        excluded_set: Set[str],
+    ) -> Dict[str, List[str]]:
+        """Remove excluded agents from deployment directory.
+
+        Removes any agents in the deployment directory whose normalized
+        names match the exclusion list. This ensures that excluded agents
+        are cleaned up from previous deployments.
+
+        Args:
+            deployment_dir: Directory containing deployed agents
+            excluded_set: Set of normalized agent names to exclude
+
+        Returns:
+            Dictionary with cleanup results:
+            - removed: List of agent names that were removed
+        """
+        cleanup_results: Dict[str, List[str]] = {"removed": []}
+
+        if not deployment_dir.exists():
+            logger.debug("Deployment directory does not exist, no cleanup needed")
+            return cleanup_results
+
+        for item in deployment_dir.iterdir():
+            # Only process .md files
+            if not item.is_file() or item.suffix != ".md":
+                continue
+
+            # Skip hidden files
+            if item.name.startswith("."):
+                continue
+
+            # Normalize agent name for comparison
+            agent_name = _normalize_agent_name(item.stem)
+
+            # Check if this agent is excluded
+            if agent_name in excluded_set:
+                try:
+                    item.unlink()
+                    cleanup_results["removed"].append(item.stem)
+                    logger.info(f"Removed excluded agent: {item.stem}")
+                except PermissionError as e:
+                    logger.error(f"Permission denied removing {item.stem}: {e}")
+                except Exception as e:
+                    logger.error(f"Failed to remove {item.stem}: {e}")
+
+        # Log summary
+        if cleanup_results["removed"]:
+            logger.info(
+                f"Cleanup complete: removed {len(cleanup_results['removed'])} excluded agents"
+            )
+
+        return cleanup_results
+
     def deploy_agents_to_project(
         self,
         project_dir: Path,
@@ -977,6 +1038,8 @@ class GitSourceSyncService:
         """
         import shutil
 
+        from claude_mpm.core.config import Config
+
         # Deploy to .claude/agents/ where Claude Code expects them
         deployment_dir = project_dir / ".claude" / "agents"
         deployment_dir.mkdir(parents=True, exist_ok=True)
@@ -989,10 +1052,55 @@ class GitSourceSyncService:
             "deployment_dir": str(deployment_dir),
         }
 
+        # Load project config to get exclusion list
+        config_file = project_dir / ".claude-mpm" / "configuration.yaml"
+        if config_file.exists():
+            config = Config(config_file=config_file)
+            excluded_agents = config.get("excluded_agents", [])
+        else:
+            # No project config, no exclusions
+            excluded_agents = []
+
+        # Create normalized exclusion set
+        excluded_set: Set[str] = (
+            {_normalize_agent_name(name) for name in excluded_agents}
+            if excluded_agents
+            else set()
+        )
+
+        if excluded_set:
+            logger.info(
+                f"Applying exclusions: {', '.join(sorted(excluded_agents))} "
+                f"(normalized: {', '.join(sorted(excluded_set))})"
+            )
+
         # Get agents from cache or use provided list
         if agent_list is None:
             agent_list = self._discover_cached_agents()
 
+        # Filter out excluded agents
+        if excluded_set:
+            original_count = len(agent_list)
+            agent_list = [
+                agent_path
+                for agent_path in agent_list
+                if _normalize_agent_name(Path(agent_path).stem) not in excluded_set
+            ]
+            filtered_count = original_count - len(agent_list)
+            if filtered_count > 0:
+                logger.info(f"Filtered out {filtered_count} excluded agents")
+
+        # Clean up any previously deployed excluded agents
+        if excluded_set:
+            cleanup_results = self._cleanup_excluded_agents(
+                deployment_dir, excluded_set
+            )
+            if cleanup_results["removed"]:
+                logger.info(
+                    f"Cleaned up {len(cleanup_results['removed'])} excluded agents: "
+                    f"{', '.join(cleanup_results['removed'])}"
+                )
+
         logger.info(
             f"Deploying {len(agent_list)} agents from cache to {deployment_dir}"
         )
@@ -1010,14 +1118,17 @@ class GitSourceSyncService:
                 deploy_filename = Path(agent_path).name
                 deploy_file = deployment_dir / deploy_filename
 
-                # Check if update needed (compare modification times)
+                # Check if update needed (compare content, not just mtime)
+                # DESIGN: Use content hash comparison for reliable change detection
+                # Mtime comparison can fail when cache downloads have older timestamps
                 should_deploy = force
                 was_existing = deploy_file.exists()
 
                 if not force and was_existing:
-                    cache_mtime = cache_file.stat().st_mtime
-                    deploy_mtime = deploy_file.stat().st_mtime
-                    should_deploy = cache_mtime > deploy_mtime
+                    # Compare file contents using hash
+                    cache_content = cache_file.read_bytes()
+                    deploy_content = deploy_file.read_bytes()
+                    should_deploy = cache_content != deploy_content
 
                 if not should_deploy and was_existing:
                     results["skipped"].append(deploy_filename)

claude_mpm/services/agents/startup_sync.py

@@ -32,7 +32,9 @@ from claude_mpm.services.agents.sources.git_source_sync_service import (
 logger = logging.getLogger(__name__)
 
 
-def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+def sync_agents_on_startup(
+    config: Optional[Dict[str, Any]] = None, force_refresh: bool = False
+) -> Dict[str, Any]:
     """Synchronize agents from remote sources on Claude MPM startup.
 
     Design Decision: Single-source support for Stage 1
@@ -44,6 +46,7 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
 
     Args:
         config: Optional configuration dictionary. If None, loads from Config singleton.
+        force_refresh: Force download even if cache is fresh (bypasses ETag).
 
     Returns:
         Dictionary with sync results:
@@ -156,7 +159,7 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
                 )
 
                 # Perform sync
-                sync_result = sync_service.sync_agents(force_refresh=False)
+                sync_result = sync_service.sync_agents(force_refresh=force_refresh)
 
                 # Aggregate results
                 result["sources_synced"] += 1

claude_mpm/services/cli/__init__.py

@@ -5,6 +5,7 @@ Services specifically for CLI command support and utilities.
 
 from .agent_dependency_service import AgentDependencyService, IAgentDependencyService
 from .agent_validation_service import AgentValidationService, IAgentValidationService
+from .incremental_pause_manager import IncrementalPauseManager, PauseAction
 from .startup_checker import IStartupChecker, StartupCheckerService, StartupWarning
 
 __all__ = [
@@ -13,6 +14,8 @@ __all__ = [
     "IAgentDependencyService",
     "IAgentValidationService",
     "IStartupChecker",
+    "IncrementalPauseManager",
+    "PauseAction",
     "StartupCheckerService",
     "StartupWarning",
 ]