claude-mpm 0.3.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

claude_mpm/services/framework_claude_md_generator/section_generators/todo_task_tools.py

@@ -25,31 +25,56 @@ class TodoTaskToolsGenerator(BaseSectionGenerator):
 ### Agent Name Prefix System
 
 **Standard TodoWrite Entry Format:**
-- **Research tasks** → `Researcher: [task description]`
-- **Documentation tasks** → `Documentater: [task description]`
-- **Changelog tasks** → `Documentater: [changelog description]`
-- **QA tasks** → `QA: [task description]`
-- **DevOps tasks** → `Ops: [task description]`
-- **Security tasks** → `Security: [task description]`
-- **Version Control tasks** → `Versioner: [task description]`
-- **Version Management tasks** → `Versioner: [version management description]`
-- **Code Implementation tasks** → `Engineer: [implementation description]`
-- **Data Operations tasks** → `Data Engineer: [data management description]`
+- **Research tasks** → `[Research] Analyze patterns and investigate implementation`
+- **Documentation tasks** → `[Documentation] Update API reference and user guide`
+- **Changelog tasks** → `[Documentation] Generate changelog for version 2.0`
+- **QA tasks** → `[QA] Execute test suite and validate functionality`
+- **DevOps tasks** → `[Ops] Configure deployment pipeline`
+- **Security tasks** → `[Security] Perform vulnerability assessment`
+- **Version Control tasks** → `[Version Control] Create feature branch and manage tags`
+- **Version Management tasks** → `[Version Control] Apply semantic version bump`
+- **Code Implementation tasks** → `[Engineer] Implement authentication system`
+- **Data Operations tasks** → `[Data Engineer] Optimize database queries`
 
 ### Task Tool Subprocess Naming Conventions
 
-**Template Pattern:**
+**Task Tool Usage Pattern:**
 ```
-**[Agent Nickname]**: [Specific task description with clear deliverables]
+Task(description="[task description]", subagent_type="[agent-type]")
 ```
 
-**Examples of Proper Naming:**
-- ✅ **Documentationer**: Update framework/CLAUDE.md with Task Tool naming conventions
-- ✅ **QA**: Execute comprehensive test suite validation for merge readiness
-- ✅ **Versioner**: Create feature branch and sync with remote repository
-- ✅ **Researcher**: Investigate Next.js 14 performance optimization patterns
-- ✅ **Engineer**: Implement user authentication system with JWT tokens
-- ✅ **Data Engineer**: Configure PostgreSQL database and optimize query performance
+**Valid subagent_type values (both formats accepted):**
+
+**Lowercase-hyphenated format (traditional):**
+- `subagent_type="research"` - For investigation and analysis
+- `subagent_type="engineer"` - For coding and implementation
+- `subagent_type="qa"` - For testing and quality assurance
+- `subagent_type="documentation"` - For docs and guides
+- `subagent_type="security"` - For security assessments
+- `subagent_type="ops"` - For deployment and infrastructure
+- `subagent_type="version-control"` - For git and version management
+- `subagent_type="data-engineer"` - For data processing and APIs
+
+**Capitalized format (matching TodoWrite prefixes - also accepted):**
+- `subagent_type="Research"` - For investigation and analysis
+- `subagent_type="Engineer"` - For coding and implementation
+- `subagent_type="QA"` - For testing and quality assurance
+- `subagent_type="Documentation"` - For docs and guides
+- `subagent_type="Security"` - For security assessments
+- `subagent_type="Ops"` - For deployment and infrastructure
+- `subagent_type="Version Control"` - For git and version management
+- `subagent_type="Data Engineer"` - For data processing and APIs
+
+**Examples of Proper Task Tool Usage (both formats work):**
+- ✅ `Task(description="Update framework documentation", subagent_type="documentation")`
+- ✅ `Task(description="Execute test suite validation", subagent_type="qa")`
+- ✅ `Task(description="Create feature branch and sync", subagent_type="version-control")`
+- ✅ `Task(description="Investigate performance patterns", subagent_type="research")`
+- ✅ `Task(description="Implement authentication system", subagent_type="engineer")`
+- ✅ `Task(description="Configure database and optimize queries", subagent_type="data-engineer")`
+- ✅ `Task(description="Analyze code patterns", subagent_type="Research")` (capitalized format)
+- ✅ `Task(description="Update API docs", subagent_type="Documentation")` (capitalized format)
+- ✅ `Task(description="Create release tags", subagent_type="Version Control")` (capitalized format)
 
 ### 🚨 MANDATORY: THREE SHORTCUT COMMANDS
 
@@ -72,18 +97,19 @@ class TodoTaskToolsGenerator(BaseSectionGenerator):
 
 **Example Integration:**
 ```
-TodoWrite: Create prefixed todos for "Push release"
-- ☐ Documentation Agent: Generate changelog and analyze version impact
-- ☐ QA Agent: Execute full test suite and quality validation
-- ☐ Data Engineer Agent: Validate data integrity and verify API connectivity
-- ☐ Version Control Agent: Apply semantic version bump and create release tags
-
-Task Tool → Documentation Agent: Generate changelog and analyze version impact
-Task Tool → QA Agent: Execute full test suite and quality validation
-Task Tool → Data Engineer Agent: Validate data integrity and verify API connectivity
-Task Tool → Version Control Agent: Apply semantic version bump and create release tags
-
-Update TodoWrite status based on agent completions
+# TodoWrite entries with proper agent prefixes:
+- ☐ [Documentation] Generate changelog and analyze version impact
+- ☐ [QA] Execute full test suite and quality validation
+- ☐ [Data Engineer] Validate data integrity and verify API connectivity
+- ☐ [Version Control] Apply semantic version bump and create release tags
+
+# Corresponding Task Tool delegations:
+Task(description="Generate changelog and analyze version impact", subagent_type="documentation")
+Task(description="Execute full test suite and quality validation", subagent_type="qa")
+Task(description="Validate data integrity and verify API connectivity", subagent_type="data-engineer")
+Task(description="Apply semantic version bump and create release tags", subagent_type="version-control")
+
+# Update TodoWrite status based on agent completions
 ```
 
 ---"""

claude_mpm/utils/error_handler.py

@@ -0,0 +1,247 @@
+"""
+Enhanced error handling utilities for claude-mpm.
+
+Inspired by awesome-claude-code's comprehensive error handling approach.
+"""
+
+import logging
+import sys
+from typing import Optional, Type, Callable, Any, Dict
+from functools import wraps
+import traceback
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class MPMError(Exception):
+    """Base exception for claude-mpm errors."""
+    
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None, 
+                 suggestions: Optional[List[str]] = None):
+        """Initialize MPM error with details and suggestions."""
+        super().__init__(message)
+        self.details = details or {}
+        self.suggestions = suggestions or []
+        self.timestamp = datetime.now()
+    
+    def get_user_friendly_message(self) -> str:
+        """Get a user-friendly error message."""
+        lines = [f"❌ Error: {str(self)}"]
+        
+        if self.details:
+            lines.append("\nDetails:")
+            for key, value in self.details.items():
+                lines.append(f"  {key}: {value}")
+        
+        if self.suggestions:
+            lines.append("\n💡 Suggestions:")
+            for suggestion in self.suggestions:
+                lines.append(f"  - {suggestion}")
+        
+        return '\n'.join(lines)
+
+
+class AgentLoadError(MPMError):
+    """Raised when agent loading fails."""
+    pass
+
+
+class ValidationError(MPMError):
+    """Raised when validation fails."""
+    pass
+
+
+class ExecutionError(MPMError):
+    """Raised when agent execution fails."""
+    pass
+
+
+class ConfigurationError(MPMError):
+    """Raised when configuration is invalid."""
+    pass
+
+
+def handle_errors(error_type: Type[Exception] = Exception, 
+                 fallback_value: Any = None,
+                 log_level: int = logging.ERROR) -> Callable:
+    """
+    Decorator for handling errors with detailed logging and user feedback.
+    
+    Args:
+        error_type: Type of exception to catch
+        fallback_value: Value to return on error
+        log_level: Logging level for errors
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except error_type as e:
+                # Log the error with full traceback
+                logger.log(log_level, f"Error in {func.__name__}: {e}", exc_info=True)
+                
+                # Provide user-friendly feedback
+                if isinstance(e, MPMError):
+                    print(e.get_user_friendly_message(), file=sys.stderr)
+                else:
+                    print(f"❌ Error: {e}", file=sys.stderr)
+                
+                return fallback_value
+            except Exception as e:
+                # Catch unexpected errors
+                logger.critical(f"Unexpected error in {func.__name__}: {e}", exc_info=True)
+                print(f"❌ Unexpected error: {e}", file=sys.stderr)
+                print("💡 This might be a bug. Please report it.", file=sys.stderr)
+                return fallback_value
+        
+        return wrapper
+    return decorator
+
+
+class ErrorContext:
+    """Context manager for enhanced error reporting."""
+    
+    def __init__(self, operation: str, details: Optional[Dict[str, Any]] = None):
+        """Initialize error context."""
+        self.operation = operation
+        self.details = details or {}
+    
+    def __enter__(self):
+        """Enter the context."""
+        logger.debug(f"Starting operation: {self.operation}")
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit the context, handling any errors."""
+        if exc_type is None:
+            logger.debug(f"Completed operation: {self.operation}")
+            return
+        
+        # Log the error with context
+        logger.error(
+            f"Error during {self.operation}: {exc_val}",
+            extra={'operation': self.operation, 'details': self.details},
+            exc_info=True
+        )
+        
+        # Don't suppress the exception
+        return False
+
+
+def retry_on_error(max_attempts: int = 3, 
+                  delay: float = 1.0,
+                  backoff_factor: float = 2.0,
+                  exceptions: tuple = (Exception,)) -> Callable:
+    """
+    Decorator for retrying operations on error.
+    
+    Args:
+        max_attempts: Maximum number of attempts
+        delay: Initial delay between attempts
+        backoff_factor: Multiplier for delay after each failure
+        exceptions: Tuple of exceptions to retry on
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            import asyncio
+            
+            last_exception = None
+            current_delay = delay
+            
+            for attempt in range(max_attempts):
+                try:
+                    return await func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if attempt < max_attempts - 1:
+                        logger.warning(
+                            f"Attempt {attempt + 1}/{max_attempts} failed for {func.__name__}: {e}"
+                        )
+                        await asyncio.sleep(current_delay)
+                        current_delay *= backoff_factor
+                    else:
+                        logger.error(
+                            f"All {max_attempts} attempts failed for {func.__name__}"
+                        )
+            
+            raise last_exception
+        
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            import time
+            
+            last_exception = None
+            current_delay = delay
+            
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if attempt < max_attempts - 1:
+                        logger.warning(
+                            f"Attempt {attempt + 1}/{max_attempts} failed for {func.__name__}: {e}"
+                        )
+                        time.sleep(current_delay)
+                        current_delay *= backoff_factor
+                    else:
+                        logger.error(
+                            f"All {max_attempts} attempts failed for {func.__name__}"
+                        )
+            
+            raise last_exception
+        
+        # Return appropriate wrapper based on function type
+        import asyncio
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        else:
+            return sync_wrapper
+    
+    return decorator
+
+
+def format_exception_chain(exc: Exception) -> str:
+    """Format an exception chain for display."""
+    lines = []
+    current = exc
+    level = 0
+    
+    while current is not None:
+        indent = "  " * level
+        lines.append(f"{indent}{'└─' if level > 0 else ''}{type(current).__name__}: {current}")
+        
+        if hasattr(current, '__cause__'):
+            current = current.__cause__
+            level += 1
+        else:
+            break
+    
+    return '\n'.join(lines)
+
+
+# Setup patterns from awesome-claude-code
+def suggest_setup_fix(error: Exception) -> List[str]:
+    """Suggest fixes for common setup errors."""
+    suggestions = []
+    error_msg = str(error).lower()
+    
+    if 'git' in error_msg and 'not found' in error_msg:
+        suggestions.append("Install git from https://git-scm.com/downloads")
+    
+    if 'python' in error_msg and 'module' in error_msg:
+        suggestions.append("Ensure you're in a virtual environment")
+        suggestions.append("Run: pip install -e .")
+    
+    if 'permission' in error_msg:
+        suggestions.append("Check file permissions")
+        suggestions.append("You may need to run with appropriate privileges")
+    
+    if 'config' in error_msg or 'configuration' in error_msg:
+        suggestions.append("Check your configuration files")
+        suggestions.append("Run: mpm validate-config")
+    
+    return suggestions

claude_mpm/validation/__init__.py

@@ -0,0 +1,5 @@
+"""Validation framework for claude-mpm."""
+
+from .agent_validator import AgentValidator, ValidationResult
+
+__all__ = ['AgentValidator', 'ValidationResult']

claude_mpm/validation/agent_validator.py

@@ -0,0 +1,175 @@
+"""
+Agent validation framework inspired by awesome-claude-code validation patterns.
+
+This module provides comprehensive validation for agent configurations with
+override support, field locking, and detailed error reporting.
+"""
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Tuple, Optional, Set, Any
+import yaml
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ValidationResult:
+    """Result of agent validation."""
+    is_valid: bool
+    errors: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    locked_fields: Set[str] = field(default_factory=set)
+    applied_overrides: Dict[str, Any] = field(default_factory=dict)
+
+
+class AgentValidator:
+    """Validates agent configurations with override support."""
+    
+    REQUIRED_FIELDS = ['name', 'version', 'description', 'agents']
+    AGENT_REQUIRED_FIELDS = ['name', 'role', 'prompt_template']
+    
+    def __init__(self, override_file: Optional[Path] = None):
+        """Initialize the validator with optional override configuration."""
+        self.overrides = {}
+        if override_file and override_file.exists():
+            self.overrides = self._load_overrides(override_file)
+    
+    def _load_overrides(self, override_file: Path) -> Dict[str, Any]:
+        """Load override configuration from YAML file."""
+        try:
+            with open(override_file, 'r') as f:
+                data = yaml.safe_load(f)
+                return data.get('overrides', {})
+        except Exception as e:
+            logger.warning(f"Failed to load overrides from {override_file}: {e}")
+            return {}
+    
+    def validate_agent_config(self, config: Dict[str, Any], agent_id: str) -> ValidationResult:
+        """Validate a single agent configuration."""
+        result = ValidationResult(is_valid=True)
+        
+        # Apply overrides
+        config, locked_fields, skip_validation = self._apply_overrides(config, agent_id)
+        result.locked_fields = locked_fields
+        
+        if skip_validation:
+            logger.info(f"Skipping validation for agent {agent_id} - marked as skip_validation")
+            return result
+        
+        # Validate required fields
+        for field in self.AGENT_REQUIRED_FIELDS:
+            if field not in locked_fields and field not in config:
+                result.errors.append(f"Missing required field: {field}")
+                result.is_valid = False
+        
+        # Validate prompt template
+        if 'prompt_template' in config and 'prompt_template' not in locked_fields:
+            template_result = self._validate_prompt_template(config['prompt_template'])
+            if not template_result[0]:
+                result.errors.extend(template_result[1])
+                result.is_valid = False
+        
+        # Validate tools if present
+        if 'tools' in config:
+            tools_result = self._validate_tools(config['tools'])
+            if not tools_result[0]:
+                result.errors.extend(tools_result[1])
+                result.is_valid = False
+        
+        return result
+    
+    def _apply_overrides(self, config: Dict[str, Any], agent_id: str) -> Tuple[Dict[str, Any], Set[str], bool]:
+        """Apply overrides to an agent configuration."""
+        if agent_id not in self.overrides:
+            return config, set(), False
+        
+        override_config = self.overrides[agent_id]
+        locked_fields = set()
+        skip_validation = override_config.get('skip_validation', False)
+        
+        # Apply each override
+        for field, value in override_config.items():
+            if field.endswith('_locked'):
+                base_field = field.replace('_locked', '')
+                if override_config.get(field, False):
+                    locked_fields.add(base_field)
+            elif field not in ['notes', 'skip_validation']:
+                config[field] = value
+        
+        return config, locked_fields, skip_validation
+    
+    def _validate_prompt_template(self, template: str) -> Tuple[bool, List[str]]:
+        """Validate prompt template format and placeholders."""
+        errors = []
+        
+        if not template or not isinstance(template, str):
+            errors.append("Prompt template must be a non-empty string")
+            return False, errors
+        
+        # Check for common placeholders
+        expected_placeholders = ['{context}', '{task}', '{constraints}']
+        missing_placeholders = []
+        
+        for placeholder in expected_placeholders:
+            if placeholder not in template:
+                missing_placeholders.append(placeholder)
+        
+        if missing_placeholders:
+            errors.append(f"Prompt template missing placeholders: {', '.join(missing_placeholders)}")
+        
+        return len(errors) == 0, errors
+    
+    def _validate_tools(self, tools: List[str]) -> Tuple[bool, List[str]]:
+        """Validate agent tools configuration."""
+        errors = []
+        
+        if not isinstance(tools, list):
+            errors.append("Tools must be a list")
+            return False, errors
+        
+        # Known valid tools
+        valid_tools = {
+            'file_operations', 'code_analysis', 'git_operations',
+            'testing', 'documentation', 'security_scan'
+        }
+        
+        for tool in tools:
+            if tool not in valid_tools:
+                errors.append(f"Unknown tool: {tool}")
+        
+        return len(errors) == 0, errors
+    
+    def validate_profile(self, profile_path: Path) -> ValidationResult:
+        """Validate an entire agent profile."""
+        result = ValidationResult(is_valid=True)
+        
+        try:
+            with open(profile_path, 'r') as f:
+                profile_data = yaml.safe_load(f)
+        except Exception as e:
+            result.errors.append(f"Failed to load profile: {e}")
+            result.is_valid = False
+            return result
+        
+        # Validate top-level fields
+        for field in self.REQUIRED_FIELDS:
+            if field not in profile_data:
+                result.errors.append(f"Missing required top-level field: {field}")
+                result.is_valid = False
+        
+        # Validate each agent
+        if 'agents' in profile_data:
+            for agent_config in profile_data['agents']:
+                agent_id = agent_config.get('name', 'unknown')
+                agent_result = self.validate_agent_config(agent_config, agent_id)
+                
+                if not agent_result.is_valid:
+                    result.is_valid = False
+                    result.errors.extend([f"Agent '{agent_id}': {e}" for e in agent_result.errors])
+                
+                result.warnings.extend([f"Agent '{agent_id}': {w}" for w in agent_result.warnings])
+                result.locked_fields.update(agent_result.locked_fields)
+        
+        return result

{claude_mpm-0.3.0.dist-info → claude_mpm-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 0.3.0
+Version: 1.1.0
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -44,6 +44,8 @@ Dynamic: requires-python
 
 # Claude MPM - Multi-Agent Project Manager
 
+> **Note**: This project is a fork of [claude-multiagent-pm](https://github.com/kfsone/claude-multiagent-pm), enhanced to integrate with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v1.0.60+'s native agent system. This integration enables seamless orchestration of Claude Code's built-in agents (research, engineer, qa, documentation, security, ops, version_control, data_engineer) through a unified project management interface.
+
 A framework for Claude that enables multi-agent workflows and extensible capabilities through a modular architecture.
 
 
@@ -117,17 +119,52 @@ Claude MPM provides a modular framework for extending Claude's capabilities:
 
 ## Installation
 
-### From Source
+### Quick Install Options
+
+#### Option 1: Using UV (Recommended - Fast)
+UV is a lightning-fast Python package manager written in Rust, offering 10-100x speed improvements over pip.
+
+```bash
+# Install UV (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install claude-mpm with UV
+uv pip install claude-mpm
+
+# Or install from git
+uv pip install git+https://github.com/bobmatnyc/claude-mpm.git
+```
+
+#### Option 2: Using pip (Traditional)
+```bash
+# Install from PyPI
+pip install claude-mpm
+
+# Or install from git
+pip install git+https://github.com/bobmatnyc/claude-mpm.git
+```
+
+#### Option 3: Using npm (Wrapper)
+**Note**: This installs a wrapper that still requires Python. It's provided for convenience but the Python package is the primary distribution method.
+
+```bash
+npm install -g @bobmatnyc/claude-mpm
+```
+
+### From Source (Development)
 
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/claude-mpm.git
+git clone https://github.com/bobmatnyc/claude-mpm.git
 cd claude-mpm
 
-# Run development installation script
-./install_dev.sh
+# Option A: Using UV (Recommended - Much faster)
+uv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+uv pip install -e .
 
-# Activate virtual environment
+# Option B: Traditional approach
+./install_dev.sh
 source venv/bin/activate
 ```
 
@@ -135,7 +172,7 @@ source venv/bin/activate
 
 #### Core Requirements
 - Python 3.8+
-- Claude CLI (must be installed and in PATH)
+- Claude Code CLI 1.0.60+ (must be installed and in PATH)
 
 #### Automatically Installed
 - tree-sitter & language packs (for code analysis)