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

claude_mpm/cli/startup.py

@@ -14,6 +14,52 @@ import warnings
 from pathlib import Path
 
 
+def sync_hooks_on_startup(quiet: bool = False) -> bool:
+    """Ensure hooks are up-to-date on startup.
+
+    WHY: Users can have stale hook configurations in settings.json that cause errors.
+    Reinstalling hooks ensures the hook format matches the current code.
+
+    DESIGN DECISION: Shows brief status message on success for user awareness.
+    Failures are logged but don't prevent startup to ensure claude-mpm remains functional.
+
+    Args:
+        quiet: If True, suppress all output (used internally)
+
+    Returns:
+        bool: True if hooks were synced successfully, False otherwise
+    """
+    try:
+        from ..hooks.claude_hooks.installer import HookInstaller
+
+        installer = HookInstaller()
+
+        # Show brief status (hooks sync is fast)
+        if not quiet:
+            print("Syncing Claude Code hooks...", end=" ", flush=True)
+
+        # Reinstall hooks (force=True ensures update)
+        success = installer.install_hooks(force=True)
+
+        if not quiet:
+            if success:
+                print("✓")
+            else:
+                print("(skipped)")
+
+        return success
+
+    except Exception as e:
+        if not quiet:
+            print("(error)")
+        # Log but don't fail startup
+        from ..core.logger import get_logger
+
+        logger = get_logger("startup")
+        logger.warning(f"Hook sync failed (non-fatal): {e}")
+        return False
+
+
 def check_legacy_cache() -> None:
     """Check for legacy cache/agents/ directory and warn user.
 
@@ -294,6 +340,84 @@ def deploy_output_style_on_startup():
         # Continue execution - output style deployment shouldn't block startup
 
 
+def _cleanup_orphaned_agents(deploy_target: Path, deployed_agents: list[str]) -> int:
+    """Remove agents that are managed by claude-mpm but no longer deployed.
+
+    WHY: When agent configurations change, old agents should be removed to avoid
+    confusion and stale agent references. Only removes claude-mpm managed agents,
+    leaving user-created agents untouched.
+
+    SAFETY: Only removes files with claude-mpm ownership markers in frontmatter.
+    Files without frontmatter or without ownership indicators are preserved.
+
+    Args:
+        deploy_target: Path to .claude/agents/ directory
+        deployed_agents: List of agent filenames that should remain
+
+    Returns:
+        Number of agents removed
+    """
+    import re
+
+    import yaml
+
+    from ..core.logger import get_logger
+
+    logger = get_logger("cli")
+    removed_count = 0
+    deployed_set = set(deployed_agents)
+
+    if not deploy_target.exists():
+        return 0
+
+    # Scan all .md files in agents directory
+    for agent_file in deploy_target.glob("*.md"):
+        # Skip hidden files
+        if agent_file.name.startswith("."):
+            continue
+
+        # Skip if this agent should remain deployed
+        if agent_file.name in deployed_set:
+            continue
+
+        # Check if this is a claude-mpm managed agent
+        try:
+            content = agent_file.read_text(encoding="utf-8")
+
+            # Parse YAML frontmatter
+            if content.startswith("---"):
+                match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+                if match:
+                    frontmatter = yaml.safe_load(match.group(1))
+
+                    # Check ownership indicators
+                    is_ours = False
+                    if frontmatter:
+                        author = frontmatter.get("author", "")
+                        source = frontmatter.get("source", "")
+                        agent_id = frontmatter.get("agent_id", "")
+
+                        # It's ours if it has any of these markers
+                        if (
+                            "Claude MPM" in str(author)
+                            or source == "remote"
+                            or agent_id
+                        ):
+                            is_ours = True
+
+                    if is_ours:
+                        # Safe to remove - it's our agent but not deployed
+                        agent_file.unlink()
+                        removed_count += 1
+                        logger.info(f"Removed orphaned agent: {agent_file.name}")
+
+        except Exception as e:
+            logger.debug(f"Could not check agent {agent_file.name}: {e}")
+            # Don't remove if we can't verify ownership
+
+    return removed_count
+
+
 def sync_remote_agents_on_startup():
     """
     Synchronize agent templates from remote sources on startup.
@@ -309,7 +433,8 @@ def sync_remote_agents_on_startup():
     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. Log deployment results
+    3. Cleanup orphaned agents (ours but no longer deployed) - Phase 3
+    4. Log deployment results
     """
     # Check for legacy cache and warn user if found
     check_legacy_cache()
@@ -408,14 +533,6 @@ def sync_remote_agents_on_startup():
                     agent_count = len(agent_files)
 
                 if agent_count > 0:
-                    # Create progress bar for deployment phase
-                    deploy_progress = ProgressBar(
-                        total=agent_count,
-                        prefix="Deploying agents",
-                        show_percentage=True,
-                        show_counter=True,
-                    )
-
                     # Deploy agents to project-level directory where Claude Code expects them
                     deploy_target = Path.cwd() / ".claude" / "agents"
                     deployment_result = deployment_service.deploy_agents(
@@ -424,23 +541,80 @@ def sync_remote_agents_on_startup():
                         deployment_mode="update",  # Version-aware updates
                     )
 
-                    # Update progress bar (single increment since deploy_agents is batch)
-                    deploy_progress.update(agent_count)
-
-                    # Finish deployment progress bar
+                    # Get actual counts from deployment result (reflects configured agents)
                     deployed = len(deployment_result.get("deployed", []))
                     updated = len(deployment_result.get("updated", []))
                     skipped = len(deployment_result.get("skipped", []))
-                    total_available = deployed + updated + skipped
+                    total_configured = deployed + updated + skipped
+
+                    # FALLBACK: If deployment result doesn't track skipped agents (async path),
+                    # count existing agents in target directory as "already deployed"
+                    # This ensures accurate reporting when agents are already up-to-date
+                    if total_configured == 0 and deploy_target.exists():
+                        existing_agents = list(deploy_target.glob("*.md"))
+                        # Filter out non-agent files (e.g., README.md, INSTRUCTIONS.md)
+                        agent_count_in_target = len(
+                            [
+                                f
+                                for f in existing_agents
+                                if not f.name.startswith(("README", "INSTRUCTIONS"))
+                            ]
+                        )
+                        if agent_count_in_target > 0:
+                            # All agents already deployed - count them as skipped
+                            skipped = agent_count_in_target
+                            total_configured = agent_count_in_target
 
-                    # Show total available agents (deployed + updated + already existing)
+                    # Create progress bar with actual configured agent count (not raw file count)
+                    deploy_progress = ProgressBar(
+                        total=total_configured if total_configured > 0 else 1,
+                        prefix="Deploying agents",
+                        show_percentage=True,
+                        show_counter=True,
+                    )
+
+                    # Update progress bar to completion
+                    deploy_progress.update(
+                        total_configured if total_configured > 0 else 1
+                    )
+
+                    # Cleanup orphaned agents (ours but no longer deployed)
+                    # Get list of deployed agent filenames (what should remain)
+                    deployed_filenames = []
+                    for agent_name in deployment_result.get("deployed", []):
+                        deployed_filenames.append(f"{agent_name}.md")
+                    for agent_name in deployment_result.get("updated", []):
+                        deployed_filenames.append(f"{agent_name}.md")
+                    for agent_name in deployment_result.get("skipped", []):
+                        deployed_filenames.append(f"{agent_name}.md")
+
+                    # Run cleanup and get count of removed agents
+                    removed = _cleanup_orphaned_agents(
+                        deploy_target, deployed_filenames
+                    )
+
+                    # Show total configured agents (deployed + updated + already existing)
+                    # Include repo 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)"
+                            )
+                        else:
+                            deploy_progress.finish(
+                                f"Complete: {deployed} new, {updated} updated, {skipped} unchanged "
+                                f"({total_configured} configured from {agent_count} in repo)"
+                            )
+                    elif removed > 0:
                         deploy_progress.finish(
-                            f"Complete: {deployed} deployed, {updated} updated, {skipped} already present ({total_available} total)"
+                            f"Complete: {total_configured} agents ready - all unchanged, "
+                            f"{removed} removed ({agent_count} available in repo)"
                         )
                     else:
                         deploy_progress.finish(
-                            f"Complete: {total_available} agents ready (all up-to-date)"
+                            f"Complete: {total_configured} agents ready - all unchanged "
+                            f"({agent_count} available in repo)"
                         )
 
                     # Display deployment errors to user (not just logs)
@@ -530,6 +704,8 @@ def sync_remote_skills_on_startup():
 
         # Discover total file count across all sources
         total_file_count = 0
+        total_skill_dirs = 0  # Count actual skill directories (folders with SKILL.md)
+
         for source in enabled_sources:
             try:
                 # Parse GitHub URL
@@ -553,15 +729,26 @@ def sync_remote_skills_on_startup():
                     ]
                     total_file_count += len(relevant_files)
 
+                    # Count skill directories (unique directories containing SKILL.md)
+                    skill_dirs = set()
+                    for f in all_files:
+                        if f.endswith("/SKILL.md"):
+                            # Extract directory path
+                            skill_dir = "/".join(f.split("/")[:-1])
+                            skill_dirs.add(skill_dir)
+                    total_skill_dirs += len(skill_dirs)
+
             except Exception as e:
                 logger.debug(f"Failed to discover files for {source.id}: {e}")
                 # Use estimate if discovery fails
                 total_file_count += 150
+                total_skill_dirs += 50  # Estimate ~50 skills
 
         # Create progress bar for sync phase with actual file count
+        # Note: We sync files (md, json, etc.), but will deploy skill directories
         sync_progress = ProgressBar(
             total=total_file_count if total_file_count > 0 else 1,
-            prefix="Syncing skills",
+            prefix="Syncing skill files",
             show_percentage=True,
             show_counter=True,
         )
@@ -578,51 +765,96 @@ def sync_remote_skills_on_startup():
 
         if cached > 0:
             sync_progress.finish(
-                f"Complete: {downloaded} downloaded, {cached} cached ({total_files} total)"
+                f"Complete: {downloaded} downloaded, {cached} cached ({total_files} files, {total_skill_dirs} skills)"
             )
         else:
             # All new downloads (first sync)
-            sync_progress.finish(f"Complete: {downloaded} files downloaded")
+            sync_progress.finish(
+                f"Complete: {downloaded} files downloaded ({total_skill_dirs} skills)"
+            )
 
         # Phase 2: Deploy skills to ~/.claude/skills/
         # This flattens nested Git structure (e.g., collaboration/parallel-agents/SKILL.md)
         # into flat deployment (e.g., collaboration-dispatching-parallel-agents/SKILL.md)
         if results["synced_count"] > 0:
-            # Get all skills to determine deployment count
+            # Get required skills from deployed agents (selective deployment)
+            from ..services.skills.selective_skill_deployer import (
+                get_required_skills_from_agents,
+            )
+
+            agents_dir = Path.cwd() / ".claude" / "agents"
+            required_skills = get_required_skills_from_agents(agents_dir)
+
+            # Get all skills to determine counts
             all_skills = manager.get_all_skills()
-            skill_count = len(all_skills)
+            total_skill_count = len(all_skills)
 
-            if skill_count > 0:
-                # Create progress bar for deployment phase
-                deploy_progress = ProgressBar(
-                    total=skill_count,
-                    prefix="Deploying skill directories",
-                    show_percentage=True,
-                    show_counter=True,
-                )
+            # Determine skill count based on whether we have agent requirements
+            if required_skills:
+                # Selective deployment: only skills required by deployed agents
+                skill_count = len(required_skills)
+            else:
+                # No agent requirements found - deploy all skills
+                skill_count = total_skill_count
 
-                # Deploy skills with progress callback
+            if skill_count > 0:
+                # Deploy skills with selective filter (if agent requirements exist)
                 # Deploy to project directory (like agents), not user directory
                 deployment_result = manager.deploy_skills(
                     target_dir=Path.cwd() / ".claude" / "skills",
                     force=False,
-                    progress_callback=deploy_progress.update,
+                    skill_filter=required_skills if required_skills else None,
                 )
 
-                # Finish deployment progress bar
+                # 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
 
+                # 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)
-                # This is more user-friendly than just showing newly deployed count
+                # Include filtered count if selective deployment was used
+                # Note: total_skill_count is from the repo, total_available is what's deployed/needed
                 if deployed > 0:
+                    if filtered > 0:
+                        deploy_progress.finish(
+                            f"Complete: {deployed} new, {skipped} unchanged "
+                            f"({total_available} required by agents, {filtered} available in repo)"
+                        )
+                    else:
+                        deploy_progress.finish(
+                            f"Complete: {deployed} new, {skipped} unchanged "
+                            f"({total_available} skills deployed from {total_skill_count} in repo)"
+                        )
+                elif filtered > 0:
+                    # Skills filtered means agents require fewer skills than available
                     deploy_progress.finish(
-                        f"Complete: {deployed} deployed, {skipped} already present ({total_available} total)"
+                        f"Agents require no skills ({total_skill_count} available in repo)"
                     )
                 else:
                     deploy_progress.finish(
-                        f"Complete: {total_available} skills ready (all up-to-date)"
+                        f"Complete: {total_available} skills deployed for agents "
+                        f"({total_skill_count} available in repo)"
                     )
 
                 # Log deployment errors if any
@@ -663,6 +895,11 @@ def run_background_services():
     file creation in project .claude/ directories.
     See: SystemInstructionsDeployer and agent_deployment.py line 504-509
     """
+    # Sync hooks early to ensure up-to-date configuration
+    # RATIONALE: Hooks should be synced before other services to fix stale configs
+    # This is fast (<100ms) and non-blocking, so it doesn't delay startup
+    sync_hooks_on_startup()  # Shows "Syncing Claude Code hooks... ✓"
+
     initialize_project_registry()
     check_mcp_auto_configuration()
     verify_mcp_gateway_startup()

claude_mpm/commands/mpm-config.md

@@ -0,0 +1,266 @@
+---
+namespace: mpm/config
+command: config
+aliases: [mpm-config]
+migration_target: /mpm/config
+category: config
+deprecated_aliases: [mpm-config-view]
+description: Unified configuration management with auto-detection and manual viewing
+---
+# Unified configuration management
+
+Manage Claude MPM configuration with auto-detection, manual viewing, validation, and status checks.
+
+## Usage
+
+```
+/mpm-config [subcommand] [options]
+/mpm-config              # No args = auto (detect + recommend + preview)
+/mpm-config view         # Show current config
+/mpm-config auto         # Auto-configure: detect → recommend → deploy (with confirmation)
+/mpm-config auto --yes   # Auto-deploy without confirmation
+```
+
+## Description
+
+This unified command provides comprehensive configuration management:
+
+1. **Auto-configuration** (default): Detect toolchain and recommend agents/skills
+2. **Manual viewing**: Display current configuration settings
+3. **Validation**: Ensure configuration correctness
+4. **Status checks**: Show system health
+
+## Subcommands
+
+### Auto-Configure (Default)
+
+Automatically detect project toolchain and configure appropriate agents and skills.
+
+```
+/mpm-config              # Preview recommendations (default)
+/mpm-config auto         # Same as no args - detect and preview
+/mpm-config auto --yes   # Auto-deploy without confirmation
+```
+
+**What it does:**
+1. Scans project to detect programming languages, frameworks, and tools
+2. Recommends agents for your stack (e.g., fastapi-engineer, react-engineer)
+3. Recommends skills based on agent types
+4. Shows preview of what will be configured
+5. Deploys with confirmation (unless `--yes` is used)
+
+**Options:**
+- `--yes`: Automatically deploy without prompting
+- `--preview`: Show recommendations without deploying (default when no args)
+- `--min-confidence FLOAT`: Minimum confidence threshold (default: 0.8)
+- `--agents-only`: Only configure agents, skip skills
+- `--skills-only`: Only configure skills, skip agents
+- `--json`: Output results in JSON format
+
+**Examples:**
+```
+/mpm-config                    # Preview auto-configuration
+/mpm-config auto               # Same as above
+/mpm-config auto --yes         # Deploy automatically
+/mpm-config auto --min-confidence 0.7  # Lower threshold
+```
+
+**Detection Capabilities:**
+
+**Languages:**
+- Python (CPython, PyPy)
+- JavaScript/TypeScript (Node.js, Deno, Bun)
+- Rust, Go, Java
+
+**Python Frameworks:**
+- FastAPI, Flask, Django, Starlette, Pyramid
+
+**JavaScript/TypeScript Frameworks:**
+- Next.js, React, Vue, Svelte, Angular
+- Express, Nest.js, Fastify
+
+**Testing Tools:**
+- pytest, unittest (Python)
+- Jest, Vitest (JavaScript)
+- Playwright, Cypress (Browser)
+
+**Example Output:**
+```
+📊 Detected Toolchain:
+  ✓ Python 3.11 (100% confidence)
+  ✓ FastAPI 0.104.0 (95% confidence)
+  ✓ pytest 7.4.0 (90% confidence)
+
+🤖 Recommended Agents:
+  ✓ fastapi-engineer (95% confidence)
+    Reason: FastAPI framework detected
+  ✓ python-engineer (90% confidence)
+    Reason: Python project support
+  ✓ api-qa (85% confidence)
+    Reason: API testing and validation
+
+🎯 Recommended Skills:
+  ✓ toolchains-python-frameworks-fastapi
+  ✓ toolchains-python-testing-pytest
+  ✓ toolchains-universal-api-testing
+
+Deploy 3 agent(s) and 3 skill(s)? (y/n/s for select):
+```
+
+### View Configuration
+
+Display current configuration settings.
+
+```
+/mpm-config view [--section SECTION] [--format FORMAT] [--show-defaults]
+```
+
+**Options:**
+- `--section SECTION`: Specific configuration section to view
+- `--format FORMAT`: Output format (yaml, json, table)
+- `--show-defaults`: Include default values in output
+
+**Examples:**
+```
+/mpm-config view
+/mpm-config view --section agents --format json
+/mpm-config view --show-defaults
+```
+
+### Validate Configuration
+
+Validate configuration files for correctness and completeness.
+
+```
+/mpm-config validate [--config-file PATH] [--strict] [--fix]
+```
+
+**Options:**
+- `--config-file PATH`: Validate specific config file (default: all)
+- `--strict`: Use strict validation rules
+- `--fix`: Attempt to fix validation errors automatically
+
+**Example:**
+```
+/mpm-config validate --strict
+/mpm-config validate --config-file .claude/config.yaml --fix
+```
+
+**Expected Output:**
+```
+Validating configuration files...
+
+✓ .claude/config.yaml: Valid
+✓ .claude/agents/config.yaml: Valid
+✓ Configuration schema: Valid
+
+Configuration is valid and ready to use.
+```
+
+### Configuration Status
+
+Show configuration health and status.
+
+```
+/mpm-config status [--verbose]
+```
+
+**Options:**
+- `--verbose`: Show detailed status information
+
+**Example:**
+```
+/mpm-config status --verbose
+```
+
+**Expected Output:**
+```
+Configuration Status
+====================
+
+Files Found: 2
+  ✓ .claude/config.yaml
+  ✓ .claude/agents/config.yaml
+
+Validation: Passed
+Schema Version: 4.5
+Last Modified: 2025-01-15 14:30:22
+
+Active Settings:
+  - WebSocket Port: 8765
+  - Agent Deploy Mode: project
+  - Logging Level: INFO
+```
+
+## Implementation
+
+This command executes:
+```bash
+claude-mpm config [subcommand] [options]
+```
+
+The slash command passes through to the actual CLI configuration management system.
+
+## Configuration Categories
+
+Configuration is organized into sections:
+
+- **agents**: Agent deployment and management settings
+- **memory**: Memory system configuration
+- **websocket**: WebSocket server settings (port, host)
+- **hooks**: Hook service configuration
+- **logging**: Logging levels and output
+- **tickets**: Ticket tracking settings
+- **monitor**: Dashboard and monitoring settings
+
+## Workflow Examples
+
+### Quick Start (New Project)
+```
+/mpm-config                    # Preview recommendations
+# Review output, then:
+/mpm-config auto --yes         # Deploy recommended agents and skills
+```
+
+### Check Current State
+```
+/mpm-config view               # See current settings
+/mpm-config status             # Verify health
+```
+
+### Validate After Manual Edits
+```
+/mpm-config validate --strict
+```
+
+### Reconfigure After Stack Changes
+```
+/mpm-config auto --force       # Re-run auto-detection
+```
+
+## Default Configuration Fallback
+
+When auto-configuration cannot detect your project's toolchain, it falls back to sensible defaults:
+
+**Default Agents** (moderate confidence 0.7):
+- engineer (general-purpose)
+- research (code exploration)
+- qa (testing)
+- ops (infrastructure)
+- documentation (technical writing)
+
+**Disable defaults:**
+Edit `.claude-mpm/config/agent_capabilities.yaml`:
+```yaml
+default_configuration:
+  enabled: false  # Disable default fallback
+```
+
+## Related Commands
+
+- `/mpm-status`: Show overall system status
+- `/mpm-doctor`: Diagnose configuration issues
+- `/mpm-init`: Initialize project configuration
+- `/mpm-agents`: Manually manage agents
+- `/mpm-agents-detect`: View detected toolchain only
+- `/mpm-agents-recommend`: Show recommendations only