claude-mpm 5.4.21__py3-none-any.whl → 5.4.59__py3-none-any.whl

claude_mpm/cli/startup.py

@@ -10,7 +10,6 @@ Part of cli/__init__.py refactoring to reduce file size and improve modularity.
 
 import os
 import sys
-import warnings
 from pathlib import Path
 
 
@@ -60,43 +59,79 @@ def sync_hooks_on_startup(quiet: bool = False) -> bool:
         return False
 
 
-def check_legacy_cache() -> None:
-    """Check for legacy cache/agents/ directory and warn user.
+def cleanup_legacy_agent_cache() -> None:
+    """Remove legacy hierarchical agent cache directories.
+
+    WHY: Old agent cache used category-based directory structure directly in cache.
+    New structure uses remote source paths. This cleanup prevents confusion from
+    stale cache directories.
 
-    WHY: cache/agents/ is deprecated in favor of cache/remote-agents/.
-    Research confirmed that cache/remote-agents/ is the canonical location
-    with 26 active code references, while cache/agents/ has only 7 legacy references.
+    Old structure (removed):
+        ~/.claude-mpm/cache/agents/engineer/
+        ~/.claude-mpm/cache/agents/ops/
+        ~/.claude-mpm/cache/agents/qa/
+        ...
 
-    DESIGN DECISIONS:
-    - Non-blocking warning: Doesn't stop execution, just informs user
-    - Migration guidance: Provides clear path to migrate
-    - One-time check: Only warns if legacy cache contains files
+    New structure (kept):
+        ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents/...
+
+    DESIGN DECISION: Runs early in startup before agent deployment to ensure
+    clean cache state. Removes only known legacy directories to avoid deleting
+    user data.
     """
-    home = Path.home()
-    legacy_cache = home / ".claude-mpm" / "cache" / "agents"
-    canonical_cache = home / ".claude-mpm" / "cache" / "remote-agents"
-    migration_marker = home / ".claude-mpm" / "cache" / ".migrated_to_remote_agents"
+    import shutil
+    from pathlib import Path
 
-    # Skip if already migrated or no legacy cache
-    if migration_marker.exists() or not legacy_cache.exists():
-        return
+    from ..core.logger import get_logger
+
+    logger = get_logger("startup")
 
-    # Check if legacy cache has actual agent files
-    legacy_files = list(legacy_cache.glob("*.md")) + list(legacy_cache.glob("*.json"))
-    if not legacy_files:
+    cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
+    if not cache_dir.exists():
         return
 
-    # Only warn if canonical cache doesn't exist (indicating unmigrated system)
-    if not canonical_cache.exists():
-        warnings.warn(
-            f"\n⚠️  DEPRECATION: Legacy cache directory detected\n"
-            f"   Location: {legacy_cache}\n"
-            f"   Files found: {len(legacy_files)}\n\n"
-            f"The 'cache/agents/' directory is deprecated. Please migrate to 'cache/remote-agents/'.\n"
-            f"Run: python scripts/migrate_cache_to_remote_agents.py\n",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+    # Known legacy category directories (from old hierarchical structure)
+    legacy_dirs = [
+        "claude-mpm",
+        "documentation",
+        "engineer",
+        "ops",
+        "qa",
+        "security",
+        "universal",
+    ]
+
+    removed = []
+
+    # Remove legacy category directories
+    for dir_name in legacy_dirs:
+        legacy_path = cache_dir / dir_name
+        if legacy_path.exists() and legacy_path.is_dir():
+            try:
+                shutil.rmtree(legacy_path)
+                removed.append(dir_name)
+            except Exception as e:
+                logger.debug(f"Failed to remove legacy directory {dir_name}: {e}")
+
+    # Also remove stray BASE-AGENT.md in cache root
+    base_agent = cache_dir / "BASE-AGENT.md"
+    if base_agent.exists():
+        try:
+            base_agent.unlink()
+            removed.append("BASE-AGENT.md")
+        except Exception as e:
+            logger.debug(f"Failed to remove BASE-AGENT.md: {e}")
+
+    if removed:
+        logger.info(f"Cleaned up legacy agent cache: {', '.join(removed)}")
+
+
+def check_legacy_cache() -> None:
+    """Deprecated: Legacy cache checking is no longer needed.
+
+    This function is kept for backward compatibility but does nothing.
+    All agent cache operations now use the standardized cache/agents/ directory.
+    """
 
 
 def setup_early_environment(argv):
@@ -431,19 +466,48 @@ def sync_remote_agents_on_startup():
     block startup to ensure claude-mpm remains functional.
 
     Workflow:
-    1. Sync all enabled Git sources (download/cache files) - Phase 1 progress bar
-    2. Deploy agents to ~/.claude/agents/ - Phase 2 progress bar
-    3. Cleanup orphaned agents (ours but no longer deployed) - Phase 3
-    4. Log deployment results
+    1. Cleanup legacy agent cache directories (if any)
+    2. Sync all enabled Git sources (download/cache files) - Phase 1 progress bar
+    3. Deploy agents to ~/.claude/agents/ - Phase 2 progress bar
+    4. Cleanup orphaned agents (ours but no longer deployed) - Phase 3
+    5. Log deployment results
     """
-    # Check for legacy cache and warn user if found
+    # Cleanup legacy cache directories first (before syncing)
+    cleanup_legacy_agent_cache()
+
+    # DEPRECATED: Legacy warning - replaced by automatic cleanup above
     check_legacy_cache()
 
     try:
+        # Load active profile if configured
+        # Get project root (where .claude-mpm exists)
+        from pathlib import Path
+
+        from ..core.shared.config_loader import ConfigLoader
         from ..services.agents.deployment.agent_deployment import AgentDeploymentService
         from ..services.agents.startup_sync import sync_agents_on_startup
+        from ..services.profile_manager import ProfileManager
         from ..utils.progress import ProgressBar
 
+        project_root = Path.cwd()
+
+        profile_manager = ProfileManager(project_dir=project_root)
+        config_loader = ConfigLoader()
+        main_config = config_loader.load_main_config()
+        active_profile = main_config.get("active_profile")
+
+        if active_profile:
+            success = profile_manager.load_profile(active_profile)
+            if success:
+                summary = profile_manager.get_filtering_summary()
+                from ..core.logger import get_logger
+
+                logger = get_logger("cli")
+                logger.info(
+                    f"Profile '{active_profile}' active: "
+                    f"{summary['enabled_agents_count']} agents enabled"
+                )
+
         # Phase 1: Sync files from Git sources
         result = sync_agents_on_startup()
 
@@ -470,19 +534,132 @@ def sync_remote_agents_on_startup():
             # Phase 2: Deploy agents from cache to ~/.claude/agents/
             # This mirrors the skills deployment pattern (lines 371-407)
             try:
-                # Initialize deployment service
-                deployment_service = AgentDeploymentService()
+                # Initialize deployment service with profile-filtered configuration
+                from ..core.config import Config
+
+                deploy_config = None
+                if active_profile and profile_manager.active_profile:
+                    # Create config with excluded agents based on profile
+                    # Get all agents that should be excluded (not in enabled list)
+                    from pathlib import Path
+
+                    cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
+                    if cache_dir.exists():
+                        # Find all agent files
+                        # Supports both flat cache and {owner}/{repo}/agents/ structure
+                        all_agent_files = [
+                            f
+                            for f in cache_dir.rglob("*.md")
+                            if "/agents/" in str(f)
+                            and f.stem.lower() != "base-agent"
+                            and f.name.lower()
+                            not in {"readme.md", "changelog.md", "contributing.md"}
+                        ]
+
+                        # Build exclusion list for agents not in profile
+                        excluded_agents = []
+                        for agent_file in all_agent_files:
+                            agent_name = agent_file.stem
+                            if not profile_manager.is_agent_enabled(agent_name):
+                                excluded_agents.append(agent_name)
+
+                        if excluded_agents:
+                            # Get singleton config and update with profile settings
+                            # BUGFIX: Config is a singleton that ignores dict parameter if already initialized.
+                            # Creating Config({...}) doesn't store excluded_agents - use set() instead.
+                            deploy_config = Config()
+                            deploy_config.set(
+                                "agent_deployment.excluded_agents", excluded_agents
+                            )
+                            deploy_config.set(
+                                "agent_deployment.filter_non_mpm_agents", False
+                            )
+                            deploy_config.set("agent_deployment.case_sensitive", False)
+                            deploy_config.set(
+                                "agent_deployment.exclude_dependencies", False
+                            )
+                            logger.info(
+                                f"Profile '{active_profile}': Excluding {len(excluded_agents)} agents from deployment"
+                            )
+
+                deployment_service = AgentDeploymentService(config=deploy_config)
 
                 # Count agents in cache to show accurate progress
                 from pathlib import Path
 
-                cache_dir = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+                cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
                 agent_count = 0
 
                 if cache_dir.exists():
-                    # Count MD files in cache (agent markdown files from Git)
-                    # BUGFIX: Only count files in agent directories, not docs/templates/READMEs
-                    # Valid agent paths must contain "/agents/" or be in root-level category dirs
+                    # BUGFIX (cache-count-inflation): Clean up stale cache files
+                    # from old repositories before counting to prevent inflated counts.
+                    # Issue: Old caches like bobmatnyc/claude-mpm-agents/agents/
+                    # were counted alongside current agents, inflating count
+                    # from 44 to 85.
+                    #
+                    # Solution: Remove files with nested /agents/ paths
+                    # (e.g., cache/agents/user/repo/agents/...)
+                    # Keep only current agents (e.g., cache/agents/engineer/...)
+                    removed_count = 0
+                    stale_dirs = set()
+
+                    for md_file in cache_dir.rglob("*.md"):
+                        # Stale cache files have multiple /agents/ in their path RELATIVE to cache_dir
+                        # Current: cache/agents/bobmatnyc/claude-mpm-agents/agents/engineer/...
+                        #          (1 occurrence in relative path: /agents/)
+                        # Old flat: cache/agents/engineer/...
+                        #           (0 occurrences in relative path - no repo structure)
+                        # The issue: str(md_file).count("/agents/") counts BOTH cache/agents/ AND repo/agents/
+                        # Fix: Count /agents/ in path RELATIVE to cache_dir (after cache/agents/)
+                        relative_path = str(md_file.relative_to(cache_dir))
+                        if relative_path.count("/agents/") > 1:
+                            # Track parent directory for cleanup
+                            # Extract subdirectory under cache/agents/
+                            # (e.g., "bobmatnyc")
+                            parts = md_file.parts
+                            cache_agents_idx = parts.index("agents")
+                            if cache_agents_idx + 1 < len(parts):
+                                stale_subdir = parts[cache_agents_idx + 1]
+                                # Only remove if it's not a known category directory
+                                if stale_subdir not in [
+                                    "engineer",
+                                    "ops",
+                                    "qa",
+                                    "universal",
+                                    "documentation",
+                                    "claude-mpm",
+                                    "security",
+                                ]:
+                                    stale_dirs.add(cache_dir / stale_subdir)
+
+                            md_file.unlink()
+                            removed_count += 1
+
+                    # Remove empty stale directories
+                    for stale_dir in stale_dirs:
+                        if stale_dir.exists() and stale_dir.is_dir():
+                            try:
+                                # Remove directory and all contents
+                                import shutil
+
+                                shutil.rmtree(stale_dir)
+                            except Exception:
+                                pass  # Ignore cleanup errors
+
+                    if removed_count > 0:
+                        from loguru import logger
+
+                        logger.info(
+                            f"Cleaned up {removed_count} stale cache files "
+                            f"from old repositories"
+                        )
+
+                    # Count MD files in cache (agent markdown files from
+                    # current repos)
+                    # BUGFIX: Only count files in agent directories,
+                    # not docs/templates/READMEs
+                    # Valid agent paths must contain "/agents/" exactly ONCE
+                    # (current structure)
                     # Exclude PM templates, BASE-AGENT, and documentation files
                     pm_templates = {
                         "base-agent.md",
@@ -505,25 +682,30 @@ def sync_remote_agents_on_startup():
                         "auto-deploy-index.md",
                     }
 
-                    # Find all markdown files
+                    # Find all markdown files (after cleanup)
                     all_md_files = list(cache_dir.rglob("*.md"))
 
                     # Filter to only agent files:
-                    # 1. Must have "/agents/" in path (from git repos)
+                    # 1. Must have "/agents/" in path (current structure supports
+                    #    both flat and {owner}/{repo}/agents/ patterns)
                     # 2. Must not be in PM templates or doc files
                     # 3. Exclude BASE-AGENT.md which is not a deployable agent
-                    # 4. Exclude build artifacts (dist/, build/, .cache/) to prevent double-counting
+                    # 4. Exclude build artifacts (dist/, build/, .cache/)
+                    #    to prevent double-counting
                     agent_files = [
                         f
                         for f in all_md_files
                         if (
-                            # Must be in an agent directory (from git repos like bobmatnyc/claude-mpm-agents/agents/)
+                            # Must be in an agent directory
+                            # Supports: cache/agents/{category}/... (flat)
+                            # Supports: cache/agents/{owner}/{repo}/agents/{category}/... (GitHub sync)
                             "/agents/" in str(f)
                             # Exclude PM templates, doc files, and BASE-AGENT
                             and f.name.lower() not in pm_templates
                             and f.name.lower() not in doc_files
                             and f.name.lower() != "base-agent.md"
-                            # Exclude build artifacts (prevents double-counting source + built files)
+                            # Exclude build artifacts (prevents double-counting
+                            # source + built files)
                             and not any(
                                 part in str(f).split("/")
                                 for part in ["dist", "build", ".cache"]
@@ -539,6 +721,7 @@ def sync_remote_agents_on_startup():
                         target_dir=deploy_target,
                         force_rebuild=False,  # Only deploy if versions differ
                         deployment_mode="update",  # Version-aware updates
+                        config=deploy_config,  # Pass config to respect profile filtering
                     )
 
                     # Get actual counts from deployment result (reflects configured agents)
@@ -594,27 +777,27 @@ def sync_remote_agents_on_startup():
                     )
 
                     # Show total configured agents (deployed + updated + already existing)
-                    # Include repo count for context and removed count if any
+                    # Include cache count for context and removed count if any
                     if deployed > 0 or updated > 0:
                         if removed > 0:
                             deploy_progress.finish(
                                 f"Complete: {deployed} new, {updated} updated, {skipped} unchanged, "
-                                f"{removed} removed ({total_configured} configured from {agent_count} in repo)"
+                                f"{removed} removed ({total_configured} configured from {agent_count} files in cache)"
                             )
                         else:
                             deploy_progress.finish(
                                 f"Complete: {deployed} new, {updated} updated, {skipped} unchanged "
-                                f"({total_configured} configured from {agent_count} in repo)"
+                                f"({total_configured} configured from {agent_count} files in cache)"
                             )
                     elif removed > 0:
                         deploy_progress.finish(
-                            f"Complete: {total_configured} agents ready - all unchanged, "
-                            f"{removed} removed ({agent_count} available in repo)"
+                            f"Complete: {total_configured} agents deployed, "
+                            f"{removed} removed ({agent_count} files in cache)"
                         )
                     else:
                         deploy_progress.finish(
-                            f"Complete: {total_configured} agents ready - all unchanged "
-                            f"({agent_count} available in repo)"
+                            f"Complete: {total_configured} agents deployed "
+                            f"({agent_count} files in cache)"
                         )
 
                     # Display deployment errors to user (not just logs)
@@ -679,13 +862,16 @@ def sync_remote_skills_on_startup():
     1. Sync all enabled Git sources (download/cache files) - Phase 1 progress bar
     2. Scan deployed agents for skill requirements → save to configuration.yaml
     3. Resolve which skills to deploy (user_defined vs agent_referenced)
-    4. Deploy resolved skills to ~/.claude/skills/ - Phase 2 progress bar
-    5. Log deployment results with source indication
+    4. Apply profile filtering if active
+    5. Deploy resolved skills to ~/.claude/skills/ - Phase 2 progress bar
+    6. Log deployment results with source indication
     """
     try:
         from pathlib import Path
 
         from ..config.skill_sources import SkillSourceConfiguration
+        from ..core.shared.config_loader import ConfigLoader
+        from ..services.profile_manager import ProfileManager
         from ..services.skills.git_skill_source_manager import GitSkillSourceManager
         from ..services.skills.selective_skill_deployer import (
             get_required_skills_from_agents,
@@ -694,6 +880,28 @@ def sync_remote_skills_on_startup():
         )
         from ..utils.progress import ProgressBar
 
+        # Load active profile if configured
+        # Get project root (where .claude-mpm exists)
+        project_root = Path.cwd()
+
+        profile_manager = ProfileManager(project_dir=project_root)
+        config_loader = ConfigLoader()
+        main_config = config_loader.load_main_config()
+        active_profile = main_config.get("active_profile")
+
+        if active_profile:
+            success = profile_manager.load_profile(active_profile)
+            if success:
+                from ..core.logger import get_logger
+
+                logger = get_logger("cli")
+                summary = profile_manager.get_filtering_summary()
+                logger.info(
+                    f"Profile '{active_profile}' active: "
+                    f"{summary['enabled_skills_count']} skills enabled, "
+                    f"{summary['disabled_patterns_count']} patterns disabled"
+                )
+
         config = SkillSourceConfiguration()
         manager = GitSkillSourceManager(config)
 
@@ -782,108 +990,191 @@ def sync_remote_skills_on_startup():
 
         # Phase 2: Scan agents and save to configuration.yaml
         # This step populates configuration.yaml with agent-referenced skills
-        if results["synced_count"] > 0:
-            agents_dir = Path.cwd() / ".claude" / "agents"
-
-            # Scan agents for skill requirements
-            agent_skills = get_required_skills_from_agents(agents_dir)
-
-            # Save to project-level configuration.yaml
-            project_config_path = Path.cwd() / ".claude-mpm" / "configuration.yaml"
-            save_agent_skills_to_config(list(agent_skills), project_config_path)
+        # CRITICAL: Always scan agents to populate agent_referenced, even when using cached skills.
+        # Without this, skill_filter=None causes ALL skills to deploy and NO cleanup to run.
+        agents_dir = Path.cwd() / ".claude" / "agents"
+
+        # Scan agents for skill requirements (ALWAYS run to ensure cleanup works)
+        agent_skills = get_required_skills_from_agents(agents_dir)
+        logger.info(
+            f"Agent scan found {len(agent_skills)} unique skills across deployed agents"
+        )
 
-            # Phase 3: Resolve which skills to deploy (user_defined or agent_referenced)
-            skills_to_deploy, skill_source = get_skills_to_deploy(project_config_path)
+        # Save to project-level configuration.yaml
+        project_config_path = Path.cwd() / ".claude-mpm" / "configuration.yaml"
+        save_agent_skills_to_config(list(agent_skills), project_config_path)
+        logger.debug(
+            f"Saved {len(agent_skills)} agent-referenced skills to {project_config_path}"
+        )
 
-            # Get all skills to determine counts
-            all_skills = manager.get_all_skills()
-            total_skill_count = len(all_skills)
+        # Phase 3: Resolve which skills to deploy (user_defined or agent_referenced)
+        skills_to_deploy, skill_source = get_skills_to_deploy(project_config_path)
 
-            # Determine skill count based on resolution
-            skill_count = (
-                len(skills_to_deploy) if skills_to_deploy else total_skill_count
+        # CRITICAL DEBUG: Log deployment resolution to diagnose cleanup issues
+        if skills_to_deploy:
+            logger.info(
+                f"Resolved {len(skills_to_deploy)} skills from {skill_source} (cleanup will run)"
+            )
+        else:
+            logger.warning(
+                f"No skills resolved from {skill_source} - will deploy ALL skills WITHOUT cleanup! "
+                f"This may indicate agent_referenced is empty in configuration.yaml."
             )
 
-            if skill_count > 0:
-                # Deploy skills with resolved filter
-                # Deploy to project directory (like agents), not user directory
-                deployment_result = manager.deploy_skills(
-                    target_dir=Path.cwd() / ".claude" / "skills",
-                    force=False,
-                    skill_filter=set(skills_to_deploy) if skills_to_deploy else None,
+        # Phase 4: Apply profile filtering if active
+        if active_profile and profile_manager.active_profile:
+            # Filter skills based on profile
+            if skills_to_deploy:
+                # Filter the resolved skill list
+                original_count = len(skills_to_deploy)
+                filtered_skills = [
+                    skill
+                    for skill in skills_to_deploy
+                    if profile_manager.is_skill_enabled(skill)
+                ]
+                filtered_count = original_count - len(filtered_skills)
+
+                # SAFEGUARD: Warn if all skills were filtered out (misconfiguration)
+                if not filtered_skills and original_count > 0:
+                    logger.warning(
+                        f"Profile '{active_profile}' filtered ALL {original_count} skills. "
+                        f"This may indicate a naming mismatch in the profile."
+                    )
+                elif filtered_count > 0:
+                    logger.info(
+                        f"Profile '{active_profile}' filtered {filtered_count} skills "
+                        f"({len(filtered_skills)} remaining)"
+                    )
+
+                skills_to_deploy = filtered_skills
+                skill_source = f"{skill_source} + profile filtered"
+            else:
+                # No explicit skill list - filter from all available
+                all_skills = manager.get_all_skills()
+                filtered_skills = [
+                    skill["name"]
+                    for skill in all_skills
+                    if profile_manager.is_skill_enabled(skill["name"])
+                ]
+                skills_to_deploy = filtered_skills
+                skill_source = "profile filtered"
+                logger.info(
+                    f"Profile '{active_profile}': "
+                    f"{len(filtered_skills)} skills enabled from {len(all_skills)} available"
                 )
 
-                # Get actual counts from deployment result
-                deployed = deployment_result.get("deployed_count", 0)
-                skipped = deployment_result.get("skipped_count", 0)
-                filtered = deployment_result.get("filtered_count", 0)
-                total_available = deployed + skipped
+        # Get all skills to determine counts
+        all_skills = manager.get_all_skills()
+        total_skill_count = len(all_skills)
 
-                # Only show progress bar if there are skills to deploy
-                if total_available > 0:
-                    deploy_progress = ProgressBar(
-                        total=total_available,
-                        prefix="Deploying skill directories",
-                        show_percentage=True,
-                        show_counter=True,
-                    )
-                    # Update progress bar to completion
-                    deploy_progress.update(total_available)
-                else:
-                    # No skills to deploy - create dummy progress for message only
-                    deploy_progress = ProgressBar(
-                        total=1,
-                        prefix="Deploying skill directories",
-                        show_percentage=False,
-                        show_counter=False,
-                    )
-                    deploy_progress.update(1)
+        # Determine skill count based on resolution
+        skill_count = (
+            len(skills_to_deploy) if skills_to_deploy else total_skill_count
+        )
+
+        if skill_count > 0:
+            # Deploy skills with resolved filter
+            # Deploy ONLY to project directory (not user-level)
+            # DESIGN DECISION: Project-level deployment keeps skills isolated per project,
+            # avoiding pollution of user's global ~/.claude/skills/ directory.
+
+            # Deploy to project-local directory with cleanup
+            deployment_result = manager.deploy_skills(
+                target_dir=Path.cwd() / ".claude" / "skills",
+                force=False,
+                # CRITICAL FIX: Empty list should mean "deploy no skills", not "deploy all"
+                # When skills_to_deploy is [], we want skill_filter=set() NOT skill_filter=None
+                # None means "no filtering" (deploy all), empty set means "filter to nothing"
+                skill_filter=set(skills_to_deploy) if skills_to_deploy is not None else None,
+            )
 
-                # Show total available skills (deployed + already existing)
-                # Include source indication (user_defined vs agent_referenced)
-                # Note: total_skill_count is from the repo, total_available is what's deployed/needed
-                source_label = (
-                    "user override" if skill_source == "user_defined" else "from agents"
+            # REMOVED: User-level deployment (lines 1068-1074)
+            # Reason: Skills should be project-specific, not user-global.
+            # Claude Code can read from project-level .claude/skills/ directory.
+
+            # Get actual counts from deployment result (use project-local for display)
+            deployed = deployment_result.get("deployed_count", 0)
+            skipped = deployment_result.get("skipped_count", 0)
+            filtered = deployment_result.get("filtered_count", 0)
+            removed = deployment_result.get("removed_count", 0)
+            total_available = deployed + skipped
+
+            # Only show progress bar if there are skills to deploy
+            if total_available > 0:
+                deploy_progress = ProgressBar(
+                    total=total_available,
+                    prefix="Deploying skill directories",
+                    show_percentage=True,
+                    show_counter=True,
                 )
+                # Update progress bar to completion
+                deploy_progress.update(total_available)
+            else:
+                # No skills to deploy - create dummy progress for message only
+                deploy_progress = ProgressBar(
+                    total=1,
+                    prefix="Deploying skill directories",
+                    show_percentage=False,
+                    show_counter=False,
+                )
+                deploy_progress.update(1)
+
+            # Show total available skills (deployed + already existing)
+            # Include source indication (user_defined vs agent_referenced)
+            # Note: total_skill_count is from cache, total_available is what's deployed/needed
+            source_label = (
+                "user override" if skill_source == "user_defined" else "from agents"
+            )
 
+            # Build finish message with cleanup info
+            if deployed > 0 or removed > 0:
+                parts = []
                 if deployed > 0:
-                    if filtered > 0:
-                        deploy_progress.finish(
-                            f"Complete: {deployed} new, {skipped} unchanged "
-                            f"({total_available} {source_label}, {filtered} available in repo)"
-                        )
-                    else:
-                        deploy_progress.finish(
-                            f"Complete: {deployed} new, {skipped} unchanged "
-                            f"({total_available} skills {source_label} from {total_skill_count} in repo)"
-                        )
-                elif filtered > 0:
-                    # Skills filtered means agents require fewer skills than available
+                    parts.append(f"{deployed} new")
+                if skipped > 0:
+                    parts.append(f"{skipped} unchanged")
+                if removed > 0:
+                    parts.append(f"{removed} removed")
+
+                status = ", ".join(parts)
+
+                if filtered > 0:
                     deploy_progress.finish(
-                        f"No skills needed ({source_label}, {total_skill_count} available in repo)"
+                        f"Complete: {status} ({total_available} {source_label}, {filtered} files in cache)"
                     )
                 else:
                     deploy_progress.finish(
-                        f"Complete: {total_available} skills {source_label} "
-                        f"({total_skill_count} available in repo)"
+                        f"Complete: {status} ({total_available} skills {source_label} from {total_skill_count} files in cache)"
                     )
+            elif filtered > 0:
+                # Skills filtered means agents require fewer skills than available
+                deploy_progress.finish(
+                    f"No skills needed ({source_label}, {total_skill_count} files in cache)"
+                )
+            else:
+                # No changes - all skills already deployed
+                msg = f"Complete: {total_available} skills {source_label}"
+                if removed > 0:
+                    msg += f", {removed} removed"
+                msg += f" ({total_skill_count} files in cache)"
+                deploy_progress.finish(msg)
+
+            # Log deployment errors if any
+            from ..core.logger import get_logger
 
-                # Log deployment errors if any
-                from ..core.logger import get_logger
-
-                logger = get_logger("cli")
+            logger = get_logger("cli")
 
-                errors = deployment_result.get("errors", [])
-                if errors:
-                    logger.warning(
-                        f"Skill deployment completed with {len(errors)} errors: {errors}"
-                    )
+            errors = deployment_result.get("errors", [])
+            if errors:
+                logger.warning(
+                    f"Skill deployment completed with {len(errors)} errors: {errors}"
+                )
 
-                # Log sync errors if any
-                if results["failed_count"] > 0:
-                    logger.warning(
-                        f"Skill sync completed with {results['failed_count']} failures"
-                    )
+            # Log sync errors if any
+            if results["failed_count"] > 0:
+                logger.warning(
+                    f"Skill sync completed with {results['failed_count']} failures"
+                )
 
     except Exception as e:
         # Non-critical - log but don't fail startup
@@ -921,7 +1212,7 @@ def show_agent_summary():
             installed_count = len(agent_files)
 
         # Count available agents in cache (from remote sources)
-        cache_dir = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+        cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
         available_count = 0
         if cache_dir.exists():
             # Use same filtering logic as agent deployment (lines 486-533 in startup.py)
@@ -966,7 +1257,7 @@ def show_agent_summary():
         # Display summary if we have agents
         if installed_count > 0 or available_count > 0:
             print(
-                f"✓ Agents: {installed_count} installed / {available_count} available",
+                f"✓ Agents: {installed_count} deployed / {max(0, available_count - installed_count)} cached",
                 flush=True,
             )
 
@@ -983,61 +1274,64 @@ def show_skill_summary():
     Display skill availability summary on startup.
 
     WHY: Users should see at a glance how many skills are deployed and available
-    from collections, similar to the agent summary.
+    from cache, similar to the agent summary showing "X deployed / Y cached".
 
-    DESIGN DECISION: Fast, non-blocking check that counts skills from deployment
-    directory and collection repos. Shows "X installed (Y available)" format.
+    DESIGN DECISION: Fast, non-blocking check that counts skills from:
+    - Deployed skills: PROJECT-level .claude/skills/ directory
+    - Cached skills: ~/.claude-mpm/cache/skills/ directory (from remote sources)
+
+    Shows format: "✓ Skills: X deployed / Y cached"
     Failures are silent to avoid blocking startup.
     """
     try:
         from pathlib import Path
 
-        # Count deployed skills (installed)
-        skills_dir = Path.home() / ".claude" / "skills"
-        installed_count = 0
-        if skills_dir.exists():
+        # Count deployed skills (PROJECT-level, not user-level)
+        project_skills_dir = Path.cwd() / ".claude" / "skills"
+        deployed_count = 0
+        if project_skills_dir.exists():
             # Count directories with SKILL.md (excludes collection repos)
             # Exclude collection directories (obra-superpowers, etc.)
             skill_dirs = [
                 d
-                for d in skills_dir.iterdir()
+                for d in project_skills_dir.iterdir()
                 if d.is_dir()
                 and (d / "SKILL.md").exists()
                 and not (d / ".git").exists()  # Exclude collection repos
             ]
-            installed_count = len(skill_dirs)
+            deployed_count = len(skill_dirs)
 
-        # Count available skills in collections
-        available_count = 0
-        if skills_dir.exists():
-            # Scan all collection directories (those with .git)
-            for collection_dir in skills_dir.iterdir():
-                if (
-                    not collection_dir.is_dir()
-                    or not (collection_dir / ".git").exists()
-                ):
+        # Count cached skills (from remote sources, not deployed yet)
+        # This matches the agent summary pattern: deployed vs cached
+        cache_dir = Path.home() / ".claude-mpm" / "cache" / "skills"
+        cached_count = 0
+        if cache_dir.exists():
+            # Scan all repository directories in cache
+            # Cache structure: ~/.claude-mpm/cache/skills/{owner}/{repo}/...
+            for repo_dir in cache_dir.rglob("*"):
+                if not repo_dir.is_dir():
                     continue
 
-                # Count skill directories in this collection
+                # Count skill directories (those with SKILL.md)
                 # Skills can be nested in: skills/category/skill-name/SKILL.md
                 # or in flat structure: skill-name/SKILL.md
-                for root, dirs, files in os.walk(collection_dir):
+                for root, dirs, files in os.walk(repo_dir):
                     if "SKILL.md" in files:
-                        # Exclude build artifacts and hidden directories (within the collection)
-                        # Get relative path from collection_dir to avoid excluding based on .claude parent
+                        # Exclude build artifacts and hidden directories
                         root_path = Path(root)
-                        relative_parts = root_path.relative_to(collection_dir).parts
                         if not any(
                             part.startswith(".")
                             or part in ["dist", "build", "__pycache__"]
-                            for part in relative_parts
+                            for part in root_path.parts
                         ):
-                            available_count += 1
+                            cached_count += 1
 
-        # Display summary if we have skills
-        if installed_count > 0 or available_count > 0:
+        # Display summary using agent summary format: "X deployed / Y cached"
+        # Only show non-deployed cached skills (subtract deployed from cached)
+        non_deployed_cached = max(0, cached_count - deployed_count)
+        if deployed_count > 0 or non_deployed_cached > 0:
             print(
-                f"✓ Skills: {installed_count} installed ({available_count} available)",
+                f"✓ Skills: {deployed_count} deployed / {non_deployed_cached} cached",
                 flush=True,
             )
 
@@ -1049,6 +1343,45 @@ def show_skill_summary():
         logger.debug(f"Failed to generate skill summary: {e}")
 
 
+def verify_and_show_pm_skills():
+    """Verify PM skills and display status.
+
+    WHY: PM skills are essential for PM agent operation.
+    Shows deployment status and auto-deploys if missing.
+    """
+    try:
+        from pathlib import Path
+
+        from ..services.pm_skills_deployer import PMSkillsDeployerService
+
+        deployer = PMSkillsDeployerService()
+        project_dir = Path.cwd()
+
+        result = deployer.verify_pm_skills(project_dir)
+
+        if result.verified:
+            # Show verified status
+            print(f"✓ PM skills: {result.skill_count} verified", flush=True)
+        else:
+            # Auto-deploy if missing
+            print("Deploying PM skills...", end="", flush=True)
+            deploy_result = deployer.deploy_pm_skills(project_dir)
+            if deploy_result.success:
+                total = len(deploy_result.deployed) + len(deploy_result.skipped)
+                print(f"\r✓ PM skills: {total} deployed" + " " * 20, flush=True)
+            else:
+                print("\r⚠ PM skills: deployment failed" + " " * 20, flush=True)
+
+    except ImportError:
+        # PM skills deployer not available - skip silently
+        pass
+    except Exception as e:
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+        logger.debug(f"PM skills verification failed: {e}")
+
+
 def auto_install_chrome_devtools_on_startup():
     """
     Automatically install chrome-devtools-mcp on startup if enabled.
@@ -1123,6 +1456,7 @@ def run_background_services():
     sync_remote_skills_on_startup()  # Override layer: Git-based skills (takes precedence)
     discover_and_link_runtime_skills()  # Discovery: user-added skills
     show_skill_summary()  # Display skill counts after deployment
+    verify_and_show_pm_skills()  # PM skills verification and status
 
     deploy_output_style_on_startup()
 
@@ -1256,18 +1590,10 @@ def verify_mcp_gateway_startup():
     DESIGN DECISION: This is non-blocking - failures are logged but don't prevent
     startup to ensure claude-mpm remains functional even if MCP gateway has issues.
     """
-    # Quick verification of MCP services installation
-    try:
-        from ..core.logger import get_logger
-        from ..services.mcp_service_verifier import verify_mcp_services_on_startup
-
-        logger = get_logger("mcp_verify")
-        all_ok, message = verify_mcp_services_on_startup()
-        if not all_ok:
-            logger.warning(message)
-    except Exception:
-        # Non-critical - continue with startup
-        pass
+    # DISABLED: MCP service verification removed - Claude Code handles MCP natively
+    # The previous check warned about missing MCP services, but users should configure
+    # MCP servers through Claude Code's native MCP management, not through claude-mpm.
+    # See: https://docs.anthropic.com/en/docs/claude-code/mcp
 
     try:
         import asyncio