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

claude_mpm/commands/mpm-version.md

@@ -4,119 +4,25 @@ command: version
 aliases: [mpm-version]
 migration_target: /mpm/system:version
 category: system
-deprecated_aliases: []
-description: Show comprehensive version information for Claude MPM
+description: Show version information
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-version"
 ---
-# Display Claude MPM Version Information
 
-Show comprehensive version information for Claude MPM project, agents, and skills.
+> **Deprecated:** This command file is deprecated in favor of the `mpm-version` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-version` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
 
-## Usage
-
-```
-/mpm-version
-```
-
-## Description
-
-Display version information including:
-- Project version and build number
-- All deployed agents with their versions (grouped by tier: system/user/project)
-- All available skills with their versions (grouped by source: bundled/user/project)
-- Summary statistics
-
-## Implementation
+# /mpm-version
 
-When you run `/mpm-version`, the PM will:
-
-1. **Collect Version Information**
-   - Use VersionService to gather all version data
-   - Project version from pyproject.toml
-   - Build number from BUILD_NUMBER file
-   - Agent versions from AgentRegistry
-   - Skills versions from SkillRegistry
-
-2. **Format Output**
-   - Hierarchical display: Project → Agents → Skills
-   - Grouped by tier/source for clarity
-   - Sorted alphabetically within groups
-   - Summary statistics at the end
-
-3. **Display Results**
-   - Well-formatted tree structure
-   - Easy to scan and read
-   - Includes totals and counts
-
-## Example Output
+Display version information for MPM, agents, and skills.
 
+## Usage
 ```
-Claude MPM Version Information
-==============================
-
-Project Version: 4.16.3
-Build: 481
-
-Agents (35 total)
------------------
-
-System Agents (30):
-  ├─ agent-manager (1.0.0)
-  ├─ engineer (3.9.1)
-  ├─ research-agent (4.5.1)
-  ├─ documentation (2.1.0)
-  ├─ qa (2.0.3)
-  └─ ... (25 more)
-
-User Agents (3):
-  ├─ custom-agent (1.0.0)
-  ├─ testing-agent (0.5.0)
-  └─ prototype-agent (0.1.0)
-
-Project Agents (2):
-  ├─ project-specific (2.0.0)
-  └─ domain-expert (1.1.0)
-
-Skills (20 total)
------------------
-
-Bundled Skills (20):
-  ├─ test-driven-development (0.1.0)
-  ├─ systematic-debugging (0.1.0)
-  ├─ async-testing (0.1.0)
-  ├─ performance-profiling (0.1.0)
-  ├─ security-scanning (0.1.0)
-  └─ ... (15 more)
-
-User Skills (0):
-  (none)
-
-Project Skills (0):
-  (none)
-
-Summary
--------
-• Project: v4.16.3 (build 481)
-• Agents: 35 total (30 system, 3 user, 2 project)
-• Skills: 20 total (20 bundled, 0 user, 0 project)
+/mpm-version
 ```
 
-## PM Implementation Instructions
-
-To execute this command, PM should:
-
-1. Import and use VersionService:
-   ```python
-   from claude_mpm.services.version_service import VersionService
-
-   service = VersionService()
-   summary = service.get_version_summary()
-   ```
-
-2. Format output following the example structure above
-3. Handle missing data gracefully (show "unknown" for missing versions)
-4. Include all tiers/sources even if counts are zero
-
-## Related Commands
+Shows project version, build number, all agents (by tier), all skills (by source).
 
-- `/mpm-help` - Show all available MPM commands
-- `/mpm-status` - Show system status information
+See docs/commands/version.md for details.

claude_mpm/commands/mpm.md

@@ -6,7 +6,15 @@ migration_target: /mpm
 category: system
 deprecated_aliases: []
 description: Access Claude MPM functionality and manage multi-agent orchestration
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # Claude MPM - Multi-Agent Project Manager
 
 Access Claude MPM functionality and manage your multi-agent orchestration.

claude_mpm/config/agent_presets.py

@@ -25,12 +25,17 @@ from typing import Any, Callable, Dict, List, Union
 PresetResolver = Union[List[str], Callable[[], List[str]]]
 
 # Core agents included in ALL presets (MIN and MAX)
+# Standard 9 core agents for essential PM workflow functionality
 CORE_AGENTS = [
     "claude-mpm/mpm-agent-manager",  # Agent lifecycle management
     "claude-mpm/mpm-skills-manager",  # Skills management
-    "universal/research",  # Codebase investigation
+    "engineer/core/engineer",  # General-purpose implementation
+    "universal/research",  # Codebase exploration and analysis
+    "qa/qa",  # Testing and quality assurance
+    "qa/web-qa",  # Browser-based testing specialist
     "documentation/documentation",  # Documentation generation
-    "engineer/core/engineer",  # General-purpose engineering
+    "ops/core/ops",  # Basic deployment operations
+    "documentation/ticketing",  # Ticket tracking (essential for PM workflow)
 ]
 
 PRESETS: Dict[str, Dict[str, Any]] = {
@@ -39,11 +44,7 @@ PRESETS: Dict[str, Dict[str, Any]] = {
     # ========================================
     "minimal": {
         "description": "Core agents only - universal starter kit",
-        "agents": CORE_AGENTS
-        + [
-            "qa/qa",
-            "ops/core/ops",
-        ],
+        "agents": CORE_AGENTS,  # All 8 core agents (no additional needed)
         "use_cases": ["Any project type", "Quick start", "Learning"],
     },
     # ========================================

claude_mpm/config/agent_sources.py

@@ -316,6 +316,33 @@ class AgentSourceConfiguration:
 
         return errors
 
+    def list_sources(self) -> list[dict]:
+        """Return list of source configurations as dictionaries.
+
+        This method converts GitRepository objects to dictionaries for CLI
+        and API compatibility. Called by GitSourceManager and CLI commands.
+
+        Returns:
+            List of dicts with keys: identifier, url, subdirectory, enabled, priority
+
+        Example:
+            >>> config = AgentSourceConfiguration()
+            >>> sources = config.list_sources()
+            >>> for source in sources:
+            ...     print(f"{source['identifier']} (priority: {source['priority']})")
+        """
+        repos = self.get_enabled_repositories()
+        return [
+            {
+                "identifier": repo.identifier,
+                "url": repo.url,
+                "subdirectory": repo.subdirectory,
+                "enabled": repo.enabled,
+                "priority": repo.priority,
+            }
+            for repo in repos
+        ]
+
     def __repr__(self) -> str:
         """Return string representation of configuration."""
         return (

claude_mpm/config/skill_sources.py

@@ -54,6 +54,7 @@ class SkillSource:
         branch: Git branch to use (default: "main")
         priority: Priority for skill resolution (lower = higher precedence)
         enabled: Whether this source should be synced
+        token: Optional GitHub token or env var reference (e.g., "$MY_TOKEN")
 
     Priority System:
         - 0: Reserved for system repository (highest precedence)
@@ -61,6 +62,12 @@ class SkillSource:
         - 100-999: Normal priority custom sources
         - 1000+: Low priority custom sources
 
+    Token Authentication:
+        - Direct token: "ghp_xxxxx" (stored in config, not recommended)
+        - Env var reference: "$PRIVATE_REPO_TOKEN" (resolved at runtime)
+        - If None, falls back to GITHUB_TOKEN or GH_TOKEN env vars
+        - Priority: source.token > GITHUB_TOKEN > GH_TOKEN
+
     Example:
         >>> source = SkillSource(
         ...     id="system",
@@ -70,6 +77,12 @@ class SkillSource:
         ... )
         >>> source.validate()
         []
+        >>> private_source = SkillSource(
+        ...     id="private",
+        ...     type="git",
+        ...     url="https://github.com/myorg/private-skills",
+        ...     token="$PRIVATE_REPO_TOKEN"
+        ... )
     """
 
     id: str
@@ -78,6 +91,7 @@ class SkillSource:
     branch: str = "main"
     priority: int = 100
     enabled: bool = True
+    token: Optional[str] = None
 
     def __post_init__(self):
         """Validate skill source configuration after initialization.
@@ -262,6 +276,7 @@ class SkillSourceConfiguration:
                         branch=source_data.get("branch", "main"),
                         priority=source_data.get("priority", 100),
                         enabled=source_data.get("enabled", True),
+                        token=source_data.get("token"),
                     )
                     sources.append(source)
                 except (KeyError, ValueError) as e:
@@ -326,6 +341,7 @@ class SkillSourceConfiguration:
                     "branch": source.branch,
                     "priority": source.priority,
                     "enabled": source.enabled,
+                    **({"token": source.token} if source.token else {}),
                 }
                 for source in sources
             ]

claude_mpm/constants.py

@@ -169,6 +169,7 @@ class SkillsCommands(str, Enum):
     INFO = "info"
     CONFIG = "config"
     CONFIGURE = "configure"  # Interactive skills selection (like agents configure)
+    SELECT = "select"  # Interactive topic-grouped skill selector
     # GitHub deployment commands
     DEPLOY_FROM_GITHUB = "deploy-github"
     LIST_AVAILABLE = "list-available"

claude_mpm/core/claude_runner.py

@@ -1,5 +1,7 @@
 """Claude runner with both exec and subprocess launch methods."""
 
+import hashlib
+import json
 import os
 from pathlib import Path
 from typing import Optional
@@ -211,9 +213,146 @@ class ClaudeRunner:
                 }
             )
 
+    def _get_deployment_state_path(self) -> Path:
+        """Get path to deployment state file.
+
+        CRITICAL: Must match path used by startup.py::_save_deployment_state_after_reconciliation()
+        Located at: .claude-mpm/cache/deployment_state.json
+        """
+        return Path.cwd() / ".claude-mpm" / "cache" / "deployment_state.json"
+
+    def _calculate_deployment_hash(self, agents_dir: Path) -> str:
+        """Calculate hash of all agent files for change detection.
+
+        Args:
+            agents_dir: Directory containing agent .md files
+
+        Returns:
+            SHA256 hash of agent file contents
+        """
+        if not agents_dir.exists():
+            return ""
+
+        # Get all .md files sorted for consistent hashing
+        agent_files = sorted(agents_dir.glob("*.md"))
+
+        hash_obj = hashlib.sha256()
+        for agent_file in agent_files:
+            # Include filename and content in hash
+            hash_obj.update(agent_file.name.encode())
+            try:
+                hash_obj.update(agent_file.read_bytes())
+            except Exception as e:
+                self.logger.debug(f"Error reading {agent_file} for hash: {e}")
+
+        return hash_obj.hexdigest()
+
+    def _check_deployment_state(self) -> bool:
+        """Check if agents are already deployed and up-to-date.
+
+        Returns:
+            True if agents are already deployed and match current version, False otherwise
+        """
+        state_file = self._get_deployment_state_path()
+        agents_dir = Path.cwd() / ".claude" / "agents"
+
+        # If state file doesn't exist, need to deploy
+        if not state_file.exists():
+            return False
+
+        # If agents directory doesn't exist, need to deploy
+        if not agents_dir.exists():
+            return False
+
+        try:
+            # Load deployment state
+            state_data = json.loads(state_file.read_text())
+
+            # Get current version from package
+            from claude_mpm import __version__
+
+            # Check if version matches
+            if state_data.get("version") != __version__:
+                self.logger.debug(
+                    f"Version mismatch: {state_data.get('version')} != {__version__}"
+                )
+                return False
+
+            # Check if agent count and hash match
+            current_hash = self._calculate_deployment_hash(agents_dir)
+            stored_hash = state_data.get("deployment_hash", "")
+
+            if current_hash != stored_hash:
+                self.logger.debug("Agent deployment hash mismatch")
+                return False
+
+            # All checks passed - agents are already deployed
+            agent_count = state_data.get("agent_count", 0)
+            self.logger.debug(
+                f"Agents already deployed: {agent_count} agents (v{__version__})"
+            )
+            return True
+
+        except Exception as e:
+            self.logger.debug(f"Error checking deployment state: {e}")
+            return False
+
+    def _save_deployment_state(self, agent_count: int) -> None:
+        """Save current deployment state.
+
+        Args:
+            agent_count: Number of agents deployed
+        """
+        state_file = self._get_deployment_state_path()
+        agents_dir = Path.cwd() / ".claude" / "agents"
+
+        try:
+            import time
+
+            from claude_mpm import __version__
+
+            # Calculate deployment hash
+            deployment_hash = self._calculate_deployment_hash(agents_dir)
+
+            # Create state data
+            state_data = {
+                "version": __version__,
+                "agent_count": agent_count,
+                "deployment_hash": deployment_hash,
+                "deployed_at": time.time(),
+            }
+
+            # Ensure directory exists
+            state_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write state file
+            state_file.write_text(json.dumps(state_data, indent=2))
+            self.logger.debug(f"Saved deployment state: {agent_count} agents")
+
+        except Exception as e:
+            self.logger.debug(f"Error saving deployment state: {e}")
+
     def setup_agents(self) -> bool:
         """Deploy native agents to .claude/agents/."""
         try:
+            # SIMPLE CHECK: If agents already exist from reconciliation, skip deployment
+            # This ensures reconciliation's user-configured agents are never overwritten
+            agents_dir = Path.cwd() / ".claude" / "agents"
+            if agents_dir.exists():
+                existing_agents = list(agents_dir.glob("*.md"))
+                if len(existing_agents) > 0:
+                    # Reconciliation already deployed agents - skip
+                    self.logger.debug(
+                        f"Skipping setup_agents: {len(existing_agents)} agents already deployed by reconciliation"
+                    )
+                    if self.project_logger:
+                        self.project_logger.log_system(
+                            f"Agents already deployed via reconciliation: {len(existing_agents)} agents",
+                            level="DEBUG",
+                            component="deployment",
+                        )
+                    return True
+
             if self.project_logger:
                 self.project_logger.log_system(
                     "Starting agent deployment", level="INFO", component="deployment"
@@ -239,6 +378,12 @@ class ClaudeRunner:
 
                 # Set Claude environment
                 self.deployment_service.set_claude_environment()
+
+                # Save deployment state for future runs
+                agents_dir = Path.cwd() / ".claude" / "agents"
+                total_agents = len(list(agents_dir.glob("*.md")))
+                self._save_deployment_state(total_agents)
+
                 return True
             self.logger.info("All agents already up to date")
             if self.project_logger:
@@ -247,6 +392,13 @@ class ClaudeRunner:
                     level="INFO",
                     component="deployment",
                 )
+
+            # Save deployment state even if no changes
+            agents_dir = Path.cwd() / ".claude" / "agents"
+            if agents_dir.exists():
+                total_agents = len(list(agents_dir.glob("*.md")))
+                self._save_deployment_state(total_agents)
+
             return True
 
         except PermissionError as e:
@@ -730,7 +882,7 @@ Use these agents to delegate specialized work via the Task tool.
                     import json
 
                     settings = json.loads(settings_file.read_text())
-                    if settings.get("activeOutputStyle") == "claude-mpm":
+                    if settings.get("activeOutputStyle") == "Claude MPM":
                         # Already active, check if file exists
                         output_style_file = (
                             Path.home() / ".claude" / "output-styles" / "claude-mpm.md"
@@ -740,7 +892,7 @@ Use these agents to delegate specialized work via the Task tool.
                                 "Output style 'Claude MPM' already deployed and active"
                             )
                             return
-                except Exception:
+                except Exception:  # nosec B110
                     pass  # Continue with deployment if we can't read settings
 
             # Read the OUTPUT_STYLE.md content if it exists

claude_mpm/core/config.py

@@ -12,11 +12,10 @@ import threading
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-import yaml
-
 from claude_mpm.core.logging_utils import get_logger
 
-from ..utils.config_manager import ConfigurationManager
+# Lazy import ConfigurationManager to avoid importing yaml at module level
+# This prevents hook errors when yaml isn't available in the execution environment
 from .exceptions import ConfigurationError, FileOperationError
 from .unified_paths import get_path_manager
 
@@ -104,6 +103,9 @@ class Config:
             Config._initialized = True
             logger.debug("Initializing Config singleton for the first time")
 
+            # Lazy import ConfigurationManager at runtime to avoid yaml import at module level
+            from ..utils.config_manager import ConfigurationManager
+
             # Initialize instance variables inside the lock to ensure thread safety
             self._config: Dict[str, Any] = {}
             self._env_prefix = env_prefix
@@ -224,21 +226,6 @@ class Config:
                             f"Response logging format: {response_logging.get('format', 'json')}"
                         )
 
-        except yaml.YAMLError as e:
-            logger.error(f"YAML syntax error in {file_path}: {e}")
-            if hasattr(e, "problem_mark"):
-                mark = e.problem_mark
-                logger.error(f"Error at line {mark.line + 1}, column {mark.column + 1}")
-            logger.info(
-                "TIP: Validate your YAML at https://www.yamllint.com/ or run: python scripts/validate_configuration.py"
-            )
-            logger.info(
-                "TIP: Common issue - YAML requires spaces, not tabs. Fix with: sed -i '' 's/\t/    /g' "
-                + str(file_path)
-            )
-            # Store error for later retrieval
-            self._config["_load_error"] = str(e)
-
         except json.JSONDecodeError as e:
             logger.error(f"JSON syntax error in {file_path}: {e}")
             logger.error(f"Error at line {e.lineno}, column {e.colno}")
@@ -255,7 +242,28 @@ class Config:
                 },
             ) from e
         except Exception as e:
-            # Catch any remaining unexpected errors and wrap them as configuration errors
+            # Handle YAML errors without importing yaml at module level
+            # ConfigurationManager.load_yaml raises yaml.YAMLError, but we don't want to import yaml
+            # Check if it's a YAML error by class name to avoid import
+            if e.__class__.__name__ == "YAMLError":
+                logger.error(f"YAML syntax error in {file_path}: {e}")
+                if hasattr(e, "problem_mark"):
+                    mark = e.problem_mark
+                    logger.error(
+                        f"Error at line {mark.line + 1}, column {mark.column + 1}"
+                    )
+                logger.info(
+                    "TIP: Validate your YAML at https://www.yamllint.com/ or run: python scripts/validate_configuration.py"
+                )
+                logger.info(
+                    "TIP: Common issue - YAML requires spaces, not tabs. Fix with: sed -i '' 's/\t/    /g' "
+                    + str(file_path)
+                )
+                # Store error for later retrieval
+                self._config["_load_error"] = str(e)
+                return  # Don't re-raise, we handled it
+
+            # Not a YAML error, wrap as configuration error
             raise ConfigurationError(
                 f"Unexpected error loading configuration from {file_path}: {e}",
                 context={
@@ -491,7 +499,7 @@ class Config:
             # Socket.IO server health and recovery configuration
             "socketio_server": {
                 "host": "localhost",
-                "port": 8765,
+                "port": 8768,  # Default SocketIO port (from network_config.NetworkPorts)
                 "enable_health_monitoring": True,
                 "enable_recovery": True,
                 "health_monitoring": {
@@ -532,7 +540,7 @@ class Config:
             # Monitor server configuration (decoupled from dashboard)
             "monitor_server": {
                 "host": "localhost",
-                "port": 8765,  # Default monitor port (shared with dashboard)
+                "port": 8765,  # Default monitor port (from network_config.NetworkPorts.MONITOR_DEFAULT)
                 "enable_health_monitoring": True,
                 "auto_start": False,  # Don't auto-start with dashboard by default
                 "event_buffer_size": 2000,  # Larger buffer for monitor server
@@ -541,7 +549,7 @@ class Config:
             # Dashboard server configuration (connects to monitor)
             "dashboard_server": {
                 "host": "localhost",
-                "port": 8765,  # Dashboard UI port
+                "port": 8767,  # Dashboard UI port (from network_config.NetworkPorts.DASHBOARD_DEFAULT)
                 "monitor_host": "localhost",  # Monitor server host to connect to
                 "monitor_port": 8765,  # Monitor server port to connect to
                 "auto_connect_monitor": True,  # Automatically connect to monitor
@@ -563,7 +571,7 @@ class Config:
             # Instruction reinforcement system configuration
             "instruction_reinforcement": {
                 "enabled": True,
-                "test_mode": True,
+                "test_mode": False,
                 "injection_interval": 5,
                 "test_messages": [
                     "[TEST-REMINDER] This is an injected instruction reminder",
@@ -603,9 +611,12 @@ class Config:
                     }
                 ],
                 "sync_interval": "startup",  # Options: "startup", "hourly", "daily", "manual"
-                "cache_dir": str(
-                    Path.home() / ".claude-mpm" / "cache" / "remote-agents"
-                ),
+                "cache_dir": str(Path.home() / ".claude-mpm" / "cache" / "agents"),
+            },
+            # Autotodos configuration
+            "autotodos": {
+                "auto_inject_on_startup": True,  # Auto-inject pending todos on PM session start
+                "max_todos_per_session": 10,  # Max todos to inject per session
             },
         }