claude-mpm 0.3.0__py3-none-any.whl

claude_mpm/services/framework_agent_loader.py

@@ -0,0 +1,337 @@
+"""
+Framework Agent Loader Service
+
+Implements agent profile loading logic based on directory hierarchy:
+1. Framework .claude-pm (next to agents/INSTRUCTIONS.md or CLAUDE.md): system, trained, user agents
+2. Project .claude-pm (in project root): project agents
+
+Loading precedence: Project → Framework (user → trained → system)
+"""
+
+import os
+import json
+from pathlib import Path
+from typing import Dict, Optional, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+class FrameworkAgentLoader:
+    """Loads agent profiles from framework and project .claude-pm directories"""
+    
+    def __init__(self):
+        self.framework_agents_dir = None
+        self.project_agents_dir = None
+        self._profile_cache = {}
+        
+    def initialize(self, framework_claude_md_path: Optional[str] = None):
+        """
+        Initialize loader with framework and project directory detection
+        
+        Args:
+            framework_claude_md_path: Optional explicit path to agents/INSTRUCTIONS.md or CLAUDE.md
+        """
+        # Find framework .claude-pm directory (next to framework/CLAUDE.md)
+        if framework_claude_md_path:
+            framework_dir = Path(framework_claude_md_path).parent.parent
+        else:
+            framework_dir = self._find_framework_directory()
+            
+        if framework_dir:
+            self.framework_agents_dir = framework_dir / ".claude-pm" / "agents"
+            logger.info(f"Framework agents directory: {self.framework_agents_dir}")
+        
+        # Find project .claude-pm directory
+        project_dir = self._find_project_directory()
+        if project_dir:
+            self.project_agents_dir = project_dir / ".claude-pm" / "agents"
+            logger.info(f"Project agents directory: {self.project_agents_dir}")
+    
+    def _find_framework_directory(self) -> Optional[Path]:
+        """Find directory containing agents/INSTRUCTIONS.md (or legacy CLAUDE.md)"""
+        # Check if we're running from a wheel installation
+        try:
+            import claude_pm
+            package_path = Path(claude_pm.__file__).parent
+            path_str = str(package_path.resolve())
+            if 'site-packages' in path_str or 'dist-packages' in path_str:
+                # For wheel installations, check data directory
+                data_instructions = package_path / "data" / "agents" / "INSTRUCTIONS.md"
+                data_claude = package_path / "data" / "agents" / "CLAUDE.md"
+                if data_instructions.exists() or data_claude.exists():
+                    return package_path / "data"
+        except Exception:
+            pass
+        
+        current = Path.cwd()
+        
+        # Check current directory and parents
+        for path in [current] + list(current.parents):
+            framework_instructions = path / "agents" / "INSTRUCTIONS.md"
+            framework_claude = path / "agents" / "CLAUDE.md"  # Legacy
+            if framework_instructions.exists() or framework_claude.exists():
+                return path
+                
+        return None
+    
+    def _find_project_directory(self) -> Optional[Path]:
+        """Find project directory containing .claude-pm"""
+        current = Path.cwd()
+        
+        # Check current directory and parents for .claude-pm
+        for path in [current] + list(current.parents):
+            claude_pm_dir = path / ".claude-pm"
+            if claude_pm_dir.exists():
+                return path
+                
+        return None
+    
+    def load_agent_profile(self, agent_type: str) -> Optional[Dict[str, Any]]:
+        """
+        Load agent profile with precedence: Project → Framework (user → trained → system)
+        
+        Args:
+            agent_type: Agent type (Engineer, Documenter, QA, etc.)
+            
+        Returns:
+            Agent profile dictionary or None if not found
+        """
+        # Check cache first
+        cache_key = agent_type.lower()
+        if cache_key in self._profile_cache:
+            return self._profile_cache[cache_key]
+        
+        profile = None
+        
+        # 1. Try project agents first (highest precedence)
+        if self.project_agents_dir:
+            profile = self._load_profile_from_directory(
+                self.project_agents_dir / "project", agent_type
+            )
+        
+        # 2. Try framework agents (user → trained → system)
+        if not profile and self.framework_agents_dir:
+            # Framework user agents
+            profile = self._load_profile_from_directory(
+                self.framework_agents_dir / "user", agent_type
+            )
+            
+            # Framework trained agents
+            if not profile:
+                profile = self._load_profile_from_directory(
+                    self.framework_agents_dir / "trained", agent_type
+                )
+            
+            # Framework system agents (fallback)
+            if not profile:
+                profile = self._load_profile_from_directory(
+                    self.framework_agents_dir / "system", agent_type
+                )
+        
+        # Cache result
+        if profile:
+            self._profile_cache[cache_key] = profile
+            
+        return profile
+    
+    def _load_profile_from_directory(self, directory: Path, agent_type: str) -> Optional[Dict[str, Any]]:
+        """Load agent profile from specific directory"""
+        if not directory.exists():
+            return None
+            
+        profile_file = directory / f"{agent_type}.md"
+        if not profile_file.exists():
+            return None
+            
+        try:
+            content = profile_file.read_text(encoding='utf-8')
+            return self._parse_agent_profile(content, str(profile_file))
+        except Exception as e:
+            logger.error(f"Error loading profile {profile_file}: {e}")
+            return None
+    
+    def _parse_agent_profile(self, content: str, source_path: str) -> Dict[str, Any]:
+        """Parse agent profile markdown into structured data"""
+        profile = {
+            'source_path': source_path,
+            'raw_content': content,
+            'role': '',
+            'capabilities': [],
+            'context_preferences': {},
+            'authority_scope': [],
+            'quality_standards': [],
+            'escalation_criteria': [],
+            'integration_patterns': {}
+        }
+        
+        lines = content.split('\n')
+        current_section = None
+        current_content = []
+        
+        for line in lines:
+            line = line.strip()
+            
+            # Detect sections
+            if line.startswith('## Role'):
+                # Process previous section
+                if current_section and current_content:
+                    self._process_section(profile, current_section, current_content)
+                current_section = 'role'
+                current_content = []
+            elif line.startswith('## Capabilities'):
+                if current_section and current_content:
+                    self._process_section(profile, current_section, current_content)
+                current_section = 'capabilities'
+                current_content = []
+            elif line.startswith('## Context Preferences'):
+                if current_section and current_content:
+                    self._process_section(profile, current_section, current_content)
+                current_section = 'context_preferences'
+                current_content = []
+            elif line.startswith('## Authority Scope'):
+                if current_section and current_content:
+                    self._process_section(profile, current_section, current_content)
+                current_section = 'authority_scope'
+                current_content = []
+            elif line.startswith('## Quality Standards'):
+                if current_section and current_content:
+                    self._process_section(profile, current_section, current_content)
+                current_section = 'quality_standards'
+                current_content = []
+            elif line.startswith('## Escalation Criteria'):
+                if current_section and current_content:
+                    self._process_section(profile, current_section, current_content)
+                current_section = 'escalation_criteria'
+                current_content = []
+            elif line.startswith('## Integration Patterns'):
+                if current_section and current_content:
+                    self._process_section(profile, current_section, current_content)
+                current_section = 'integration_patterns'
+                current_content = []
+            elif line.startswith('#'):
+                # Process previous section before starting new one
+                if current_section and current_content:
+                    self._process_section(profile, current_section, current_content)
+                current_section = None
+                current_content = []
+            elif current_section and line:
+                current_content.append(line)
+        
+        # Process final section
+        if current_section and current_content:
+            self._process_section(profile, current_section, current_content)
+            
+        return profile
+    
+    def _process_section(self, profile: Dict[str, Any], section: str, content: list):
+        """Process section content into profile structure"""
+        text = '\n'.join(content).strip()
+        
+        if section == 'role':
+            profile['role'] = text
+        elif section == 'capabilities':
+            # Extract bullet points
+            capabilities = []
+            for line in content:
+                if line.startswith('- **') and '**:' in line:
+                    cap = line.split('**:')[0].replace('- **', '').strip()
+                    capabilities.append(cap)
+            profile['capabilities'] = capabilities
+        elif section == 'context_preferences':
+            # Extract Include/Exclude/Focus
+            prefs = {}
+            for line in content:
+                if line.startswith('- **Include**:'):
+                    prefs['include'] = line.replace('- **Include**:', '').strip()
+                elif line.startswith('- **Exclude**:'):
+                    prefs['exclude'] = line.replace('- **Exclude**:', '').strip()
+                elif line.startswith('- **Focus**:'):
+                    prefs['focus'] = line.replace('- **Focus**:', '').strip()
+            profile['context_preferences'] = prefs
+        elif section in ['authority_scope', 'quality_standards', 'escalation_criteria']:
+            # Extract bullet points
+            items = []
+            for line in content:
+                if line.startswith('- **') and '**:' in line:
+                    item = line.split('**:')[0].replace('- **', '').strip()
+                    items.append(item)
+            profile[section] = items
+        elif section == 'integration_patterns':
+            # Extract With X: patterns
+            patterns = {}
+            for line in content:
+                if line.startswith('- **With ') and '**:' in line:
+                    agent = line.split('**:')[0].replace('- **With ', '').replace('**', '').strip()
+                    desc = line.split('**:')[1].strip()
+                    patterns[agent] = desc
+            profile['integration_patterns'] = patterns
+    
+    def get_available_agents(self) -> Dict[str, list]:
+        """Get list of available agents by tier"""
+        agents = {
+            'project': [],
+            'framework_user': [],
+            'framework_trained': [],
+            'framework_system': []
+        }
+        
+        # Project agents
+        if self.project_agents_dir:
+            project_dir = self.project_agents_dir / "project"
+            if project_dir.exists():
+                agents['project'] = [f.stem for f in project_dir.glob("*.md")]
+        
+        # Framework agents
+        if self.framework_agents_dir:
+            for tier in ['user', 'trained', 'system']:
+                tier_dir = self.framework_agents_dir / tier
+                if tier_dir.exists():
+                    agents[f'framework_{tier}'] = [f.stem for f in tier_dir.glob("*.md")]
+        
+        return agents
+    
+    def generate_profile_loading_instruction(self, agent_type: str) -> str:
+        """Generate instruction for subprocess to load its own profile"""
+        profile = self.load_agent_profile(agent_type)
+        
+        if not profile:
+            return f"""
+**{agent_type} Agent**: No profile found. Operating with basic capabilities.
+
+**Task Context**: Please proceed with the assigned task using standard practices.
+"""
+        
+        instruction = f"""
+**{agent_type} Agent Profile Loaded**
+
+**Agent Identity**: {agent_type} Agent
+**Profile Source**: {profile.get('source_path', 'Unknown')}
+**Primary Role**: {profile.get('role', 'Not specified')}
+
+**Core Capabilities**:
+"""
+        
+        for capability in profile.get('capabilities', [])[:5]:  # Top 5 capabilities
+            instruction += f"- **{capability}**: Primary capability area\n"
+        
+        instruction += f"""
+**Context Preferences**:
+- **Include**: {profile.get('context_preferences', {}).get('include', 'Not specified')}
+- **Exclude**: {profile.get('context_preferences', {}).get('exclude', 'Not specified')}
+- **Focus**: {profile.get('context_preferences', {}).get('focus', 'Not specified')}
+
+**Authority Scope**:
+"""
+        
+        for authority in profile.get('authority_scope', [])[:3]:  # Top 3 authorities
+            instruction += f"- **{authority}**: Authorized operation area\n"
+        
+        instruction += f"""
+**Quality Standards**: {len(profile.get('quality_standards', []))} standards defined
+**Escalation Triggers**: {len(profile.get('escalation_criteria', []))} criteria defined
+**Integration Partners**: {len(profile.get('integration_patterns', {}))} agent coordination patterns
+
+Please operate according to your profile specifications and maintain quality standards.
+"""
+        
+        return instruction.strip()

claude_mpm/services/framework_claude_md_generator/README.md

@@ -0,0 +1,92 @@
+# Framework CLAUDE.md Generator
+
+This directory contains the refactored framework CLAUDE.md generator service, originally a single 1,267-line file.
+
+## Structure
+
+### Core Modules
+
+- **`__init__.py`** (~250 lines) - Main facade class that coordinates all functionality
+- **`version_manager.py`** (~100 lines) - Handles version parsing, incrementing, and comparison
+- **`content_assembler.py`** (~120 lines) - Assembles sections and applies template variables
+- **`content_validator.py`** (~80 lines) - Validates generated content structure and completeness
+- **`deployment_manager.py`** (~80 lines) - Handles deployment to parent directories
+- **`section_manager.py`** (~60 lines) - Manages section registration, ordering, and updates
+
+### Section Generators
+
+The `section_generators/` subdirectory contains individual generators for each section:
+
+- **`__init__.py`** - Base classes and registry
+- **`header.py`** - Header with version metadata
+- **`role_designation.py`** - AI Assistant role designation
+- **`agents.py`** (~570 lines) - Comprehensive agents documentation (largest section)
+- **`todo_task_tools.py`** - Todo and Task Tools integration
+- **`claude_pm_init.py`** - Claude-PM initialization procedures
+- **`orchestration_principles.py`** - Core orchestration principles
+- **`subprocess_validation.py`** - Subprocess validation protocol
+- **`delegation_constraints.py`** - Critical delegation constraints
+- **`environment_config.py`** - Environment configuration
+- **`troubleshooting.py`** - Troubleshooting guide
+- **`core_responsibilities.py`** - Core responsibilities list
+- **`footer.py`** - Footer with metadata
+
+## Usage
+
+The API remains unchanged from the original implementation:
+
+```python
+from claude_pm.services.framework_claude_md_generator import FrameworkClaudeMdGenerator
+
+# Create generator instance
+generator = FrameworkClaudeMdGenerator()
+
+# Generate content
+content = generator.generate(
+    current_content=existing_content,  # Optional: for version auto-increment
+    template_variables={'PLATFORM': 'darwin', 'PYTHON_CMD': 'python3'}
+)
+
+# Deploy to parent directory
+success, message = generator.deploy_to_parent(Path('/parent/dir'))
+
+# Update a section
+generator.update_section('agents', 'Custom agents content')
+
+# Add custom section
+generator.add_custom_section('custom', 'Custom content', after='agents')
+```
+
+## Design Benefits
+
+1. **Modularity**: Each concern is separated into its own module
+2. **Maintainability**: Smaller, focused modules are easier to understand and modify
+3. **Testability**: Individual components can be tested in isolation
+4. **Extensibility**: New section generators can be added easily
+5. **Performance**: Section generators are loaded on demand
+6. **Backward Compatibility**: Original API preserved through facade pattern
+
+## Section Generator Pattern
+
+To add a new section generator:
+
+1. Create a new file in `section_generators/`
+2. Inherit from `BaseSectionGenerator`
+3. Implement the `generate()` method
+4. Register in `section_generators/__init__.py`
+
+Example:
+```python
+from . import BaseSectionGenerator
+
+class CustomSectionGenerator(BaseSectionGenerator):
+    def generate(self, data: Dict[str, Any]) -> str:
+        return "## Custom Section\n\nContent here..."
+```
+
+## Refactoring Summary
+
+- **Original**: 1,267 lines in a single file
+- **Refactored**: ~250 lines in main module + well-organized submodules
+- **Total line reduction**: Main module reduced by 80%
+- **Improved organization**: 13 focused modules instead of 1 large file

claude_mpm/services/framework_claude_md_generator/__init__.py

@@ -0,0 +1,206 @@
+"""
+Framework INSTRUCTIONS.md Generator Service
+
+This service provides structured generation of the framework INSTRUCTIONS.md template
+(legacy: CLAUDE.md) with auto-versioning, section management, and deployment capabilities.
+"""
+
+from typing import Dict, Optional, Any, List, Tuple
+from pathlib import Path
+
+from .version_manager import VersionManager
+from .content_validator import ContentValidator
+from .content_assembler import ContentAssembler
+from .deployment_manager import DeploymentManager
+from .section_manager import SectionManager
+from .section_generators import section_registry
+
+
+class FrameworkClaudeMdGenerator:
+    """
+    Generates and manages the framework INSTRUCTIONS.md template (legacy: CLAUDE.md) 
+    with structured sections, auto-versioning, and deployment capabilities.
+    
+    This is the main facade class that coordinates all the submodules.
+    """
+    
+    def __init__(self):
+        """Initialize the generator with current framework version."""
+        # Initialize managers
+        self.version_manager = VersionManager()
+        self.validator = ContentValidator()
+        self.assembler = ContentAssembler()
+        self.section_manager = SectionManager()
+        
+        # Initialize deployment manager with dependencies
+        self.deployment_manager = DeploymentManager(
+            self.version_manager, 
+            self.validator
+        )
+        
+        # Get framework version
+        self.framework_version = self.version_manager.framework_version
+        
+        # Initialize sections
+        self._initialize_sections()
+    
+    def _initialize_sections(self):
+        """Initialize all sections in the required order."""
+        # Register all default sections with their generators
+        section_order = [
+            'header',
+            'role_designation',
+            'agents',
+            'todo_task_tools',
+            'claude_pm_init',
+            'orchestration_principles',
+            'subprocess_validation',
+            'delegation_constraints',
+            'environment_config',
+            'troubleshooting',
+            'core_responsibilities',
+            'footer'
+        ]
+        
+        for section_name in section_order:
+            generator_class = section_registry.get(section_name)
+            if generator_class:
+                generator_instance = generator_class(self.framework_version)
+                self.section_manager.register_section(
+                    section_name,
+                    generator_instance.generate
+                )
+    
+    def generate(self, 
+                current_content: Optional[str] = None,
+                template_variables: Optional[Dict[str, str]] = None) -> str:
+        """
+        Generate the complete INSTRUCTIONS.md/CLAUDE.md content.
+        
+        Args:
+            current_content: Current INSTRUCTIONS.md/CLAUDE.md content for version parsing
+            template_variables: Variables to substitute in the template
+            
+        Returns:
+            str: Complete INSTRUCTIONS.md/CLAUDE.md content
+        """
+        # Auto-increment version if current content provided
+        version = self.version_manager.auto_increment_version(current_content)
+        
+        # Create metadata for header
+        metadata = self.assembler.create_metadata_dict(
+            version=version,
+            framework_version=self.framework_version
+        )
+        
+        # Update header section with metadata
+        sections = self.section_manager.get_sections()
+        if 'header' in sections:
+            generator_func, _ = sections['header']
+            sections['header'] = (generator_func, metadata)
+        
+        # Assemble content
+        content = self.assembler.assemble_content(
+            sections,
+            template_variables
+        )
+        
+        return content
+    
+    def validate_content(self, content: str) -> Tuple[bool, List[str]]:
+        """
+        Validate that generated content has all required sections.
+        
+        Args:
+            content: Content to validate
+            
+        Returns:
+            Tuple of (is_valid, list_of_issues)
+        """
+        return self.validator.validate_content(content)
+    
+    def deploy_to_parent(self, parent_path: Path, force: bool = False) -> Tuple[bool, str]:
+        """
+        Deploy generated content to a parent directory.
+        
+        Args:
+            parent_path: Path to parent directory
+            force: Force deployment even if versions match
+            
+        Returns:
+            Tuple of (success, message)
+        """
+        # Check if we need to read existing content
+        # Try INSTRUCTIONS.md first, fallback to CLAUDE.md for compatibility
+        target_file = parent_path / "INSTRUCTIONS.md"
+        if not target_file.exists() and (parent_path / "CLAUDE.md").exists():
+            target_file = parent_path / "CLAUDE.md"
+        current_content = None
+        
+        if target_file.exists():
+            with open(target_file, 'r') as f:
+                current_content = f.read()
+        
+        # Generate new content
+        new_content = self.generate(current_content=current_content)
+        
+        # Deploy using deployment manager
+        return self.deployment_manager.deploy_to_parent(
+            new_content,
+            parent_path,
+            force
+        )
+    
+    def get_section_list(self) -> List[str]:
+        """
+        Get list of all section names in order.
+        
+        Returns:
+            List of section names
+        """
+        return self.section_manager.get_section_list()
+    
+    def update_section(self, section_name: str, content: str) -> bool:
+        """
+        Update a specific section's generator to return custom content.
+        
+        Args:
+            section_name: Name of section to update
+            content: New content for the section
+            
+        Returns:
+            bool: Success status
+        """
+        return self.section_manager.update_section(section_name, content)
+    
+    def add_custom_section(self, section_name: str, content: str, after: Optional[str] = None):
+        """
+        Add a custom section to the generator.
+        
+        Args:
+            section_name: Name for the new section
+            content: Content for the section
+            after: Section name to insert after (None = append at end)
+        """
+        self.section_manager.add_custom_section(section_name, content, after)
+    
+    # Compatibility methods to match original API
+    def _get_framework_version(self) -> str:
+        """Get framework version (compatibility method)."""
+        return self.version_manager._get_framework_version()
+    
+    def _parse_current_version(self, content: str) -> Tuple[str, int]:
+        """Parse current version (compatibility method)."""
+        return self.version_manager.parse_current_version(content)
+    
+    def _auto_increment_version(self, current_content: Optional[str] = None) -> str:
+        """Auto-increment version (compatibility method)."""
+        return self.version_manager.auto_increment_version(current_content)
+    
+    def _generate_content_hash(self) -> str:
+        """Generate content hash (compatibility method)."""
+        return self.assembler.generate_content_hash()
+
+
+# Export the main class
+__all__ = ['FrameworkClaudeMdGenerator']