claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/core/framework/__init__.py

@@ -0,0 +1,25 @@
+"""Framework module for Claude MPM.
+
+This module provides the modular framework loading system with specialized components
+for handling different aspects of framework initialization and management.
+"""
+
+from .formatters import CapabilityGenerator, ContentFormatter, ContextGenerator
+from .loaders import AgentLoader, FileLoader, InstructionLoader, PackagedLoader
+from .processors import MemoryProcessor, MetadataProcessor, TemplateProcessor
+
+__all__ = [
+    "AgentLoader",
+    "CapabilityGenerator",
+    # Formatters
+    "ContentFormatter",
+    "ContextGenerator",
+    # Loaders
+    "FileLoader",
+    "InstructionLoader",
+    "MemoryProcessor",
+    # Processors
+    "MetadataProcessor",
+    "PackagedLoader",
+    "TemplateProcessor",
+]

claude_mpm/core/framework/formatters/__init__.py

@@ -0,0 +1,11 @@
+"""Framework formatters for content generation and formatting."""
+
+from .capability_generator import CapabilityGenerator
+from .content_formatter import ContentFormatter
+from .context_generator import ContextGenerator
+
+__all__ = [
+    "CapabilityGenerator",
+    "ContentFormatter",
+    "ContextGenerator",
+]

claude_mpm/core/framework/formatters/capability_generator.py

@@ -0,0 +1,367 @@
+"""Agent capability generator for dynamic agent discovery."""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from claude_mpm.core.logging_utils import get_logger
+
+# Import resource handling for packaged installations
+try:
+    from importlib.resources import files
+except ImportError:
+    try:
+        from importlib_resources import files
+    except ImportError:
+        files = None
+
+
+class CapabilityGenerator:
+    """Generates agent capability sections from deployed agents."""
+
+    def __init__(self):
+        """Initialize the capability generator."""
+        self.logger = get_logger("capability_generator")
+
+    def generate_capabilities_section(
+        self,
+        deployed_agents: List[Dict[str, Any]],
+        local_agents: Dict[str, Dict[str, Any]],
+    ) -> str:
+        """Generate dynamic agent capabilities section.
+
+        Args:
+            deployed_agents: List of deployed agent metadata
+            local_agents: Dictionary of local JSON template agents
+
+        Returns:
+            Formatted capabilities section string
+        """
+        # Build capabilities section
+        section = "\n\n## Available Agent Capabilities\n\n"
+
+        # Combine deployed and local agents
+        all_agents = {}  # key: agent_id, value: (agent_data, priority)
+
+        # Add local agents first (highest priority)
+        for agent_id, agent_data in local_agents.items():
+            all_agents[agent_id] = (agent_data, -1)  # Priority -1 for local agents
+
+        # Add deployed agents with lower priority
+        for priority, agent_data in enumerate(deployed_agents):
+            agent_id = agent_data["id"]
+            # Only add if not already present
+            if agent_id not in all_agents:
+                all_agents[agent_id] = (agent_data, priority)
+
+        # Extract just the agent data and sort
+        final_agents = [agent_data for agent_data, _ in all_agents.values()]
+
+        if not final_agents:
+            return self.get_fallback_capabilities()
+
+        # Sort agents alphabetically by ID
+        final_agents.sort(key=lambda x: x["id"])
+
+        # Display all agents with their rich descriptions
+        for agent in final_agents:
+            # Clean up display name - handle common acronyms
+            display_name = agent.get("display_name", agent["id"])
+            display_name = (
+                display_name.replace("Qa ", "QA ")
+                .replace("Ui ", "UI ")
+                .replace("Api ", "API ")
+            )
+            if display_name.lower() == "qa agent":
+                display_name = "QA Agent"
+
+            # Add local indicator if this is a local agent
+            if agent.get("is_local"):
+                tier_label = f" [LOCAL-{agent.get('tier', 'PROJECT').upper()}]"
+                section += f"\n### {display_name} (`{agent['id']}`) {tier_label}\n"
+            else:
+                section += f"\n### {display_name} (`{agent['id']}`)\n"
+
+            section += f"{agent.get('description', 'Specialized agent')}\n"
+
+            # Add routing information if available
+            if agent.get("routing"):
+                routing = agent["routing"]
+                routing_hints = []
+
+                if routing.get("keywords"):
+                    # Show first 5 keywords for brevity
+                    keywords = routing["keywords"][:5]
+                    routing_hints.append(f"Keywords: {', '.join(keywords)}")
+
+                if routing.get("paths"):
+                    # Show first 3 paths for brevity
+                    paths = routing["paths"][:3]
+                    routing_hints.append(f"Paths: {', '.join(paths)}")
+
+                if routing.get("priority"):
+                    routing_hints.append(f"Priority: {routing['priority']}")
+
+                if routing_hints:
+                    section += f"- **Routing**: {' | '.join(routing_hints)}\n"
+
+                # Add when_to_use if present
+                if routing.get("when_to_use"):
+                    section += f"- **When to use**: {routing['when_to_use']}\n"
+
+            # Add any additional metadata if present
+            if agent.get("authority"):
+                section += f"- **Authority**: {agent['authority']}\n"
+            if agent.get("primary_function"):
+                section += f"- **Primary Function**: {agent['primary_function']}\n"
+            if agent.get("handoff_to"):
+                section += f"- **Handoff To**: {agent['handoff_to']}\n"
+            if agent.get("tools") and agent["tools"] != "standard":
+                section += f"- **Tools**: {agent['tools']}\n"
+            if agent.get("model") and agent["model"] != "opus":
+                section += f"- **Model**: {agent['model']}\n"
+
+            # Add memory routing information if available
+            if agent.get("memory_routing"):
+                memory_routing = agent["memory_routing"]
+                if memory_routing.get("description"):
+                    section += (
+                        f"- **Memory Routing**: {memory_routing['description']}\n"
+                    )
+
+        # Add simple Context-Aware Agent Selection
+        section += "\n## Context-Aware Agent Selection\n\n"
+        section += "Select agents based on their descriptions above. Key principles:\n"
+        section += "- **PM questions** → Answer directly (only exception)\n"
+        section += "- Match task requirements to agent descriptions and authority\n"
+        section += "- Consider agent handoff recommendations\n"
+        section += "- Use the agent ID in parentheses when delegating via Task tool\n"
+
+        # Add summary
+        section += f"\n**Total Available Agents**: {len(final_agents)}\n"
+
+        return section
+
+    def parse_agent_metadata(self, agent_file: Path) -> Optional[Dict[str, Any]]:
+        """Parse agent metadata from deployed agent file.
+
+        Args:
+            agent_file: Path to deployed agent file
+
+        Returns:
+            Dictionary with agent metadata or None
+        """
+        try:
+            with agent_file.open() as f:
+                content = f.read()
+
+            # Default values
+            agent_data = {
+                "id": agent_file.stem,
+                "display_name": agent_file.stem.replace("_", " ")
+                .replace("-", " ")
+                .title(),
+                "description": "Specialized agent",
+            }
+
+            # Extract YAML frontmatter if present
+            if content.startswith("---"):
+                end_marker = content.find("---", 3)
+                if end_marker > 0:
+                    frontmatter = content[3:end_marker]
+                    metadata = yaml.safe_load(frontmatter)
+                    if metadata:
+                        # Use name as ID for Task tool
+                        agent_data["id"] = metadata.get("name", agent_data["id"])
+                        agent_data["display_name"] = (
+                            metadata.get("name", agent_data["display_name"])
+                            .replace("-", " ")
+                            .title()
+                        )
+
+                        # Copy all metadata fields directly
+                        for key, value in metadata.items():
+                            if key not in ["name"]:  # Skip already processed fields
+                                agent_data[key] = value
+
+            # Try to load routing metadata from JSON template if not in YAML frontmatter
+            if "routing" not in agent_data:
+                routing_data = self.load_routing_from_template(agent_file.stem)
+                if routing_data:
+                    agent_data["routing"] = routing_data
+
+            # Try to load memory routing metadata from JSON template
+            if "memory_routing" not in agent_data:
+                memory_routing_data = self.load_memory_routing_from_template(
+                    agent_file.stem
+                )
+                if memory_routing_data:
+                    agent_data["memory_routing"] = memory_routing_data
+
+            return agent_data
+
+        except Exception as e:
+            self.logger.debug(f"Could not parse metadata from {agent_file}: {e}")
+            return None
+
+    def load_routing_from_template(
+        self, agent_name: str, framework_path: Optional[Path] = None
+    ) -> Optional[Dict[str, Any]]:
+        """Load routing metadata from agent JSON template.
+
+        Args:
+            agent_name: Name of the agent
+            framework_path: Path to framework installation
+
+        Returns:
+            Dictionary with routing metadata or None if not found
+        """
+        try:
+            # Check if we have a framework path
+            if not framework_path or framework_path == Path("__PACKAGED__"):
+                # For packaged installations, try to load from package resources
+                if files:
+                    try:
+                        templates_package = files("claude_mpm.agents.templates")
+                        template_file = templates_package / f"{agent_name}.json"
+
+                        if template_file.is_file():
+                            template_content = template_file.read_text()
+                            template_data = json.loads(template_content)
+                            return template_data.get("routing")
+                    except Exception as e:
+                        self.logger.debug(
+                            f"Could not load routing from packaged template for {agent_name}: {e}"
+                        )
+                return None
+
+            # For development mode, load from filesystem
+            templates_dir = (
+                framework_path / "src" / "claude_mpm" / "agents" / "templates"
+            )
+            template_file = templates_dir / f"{agent_name}.json"
+
+            if template_file.exists():
+                with template_file.open() as f:
+                    template_data = json.load(f)
+                    return template_data.get("routing")
+
+            # Also check for variations in naming (underscore vs dash)
+            alternative_names = list(
+                {
+                    agent_name.replace("-", "_"),
+                    agent_name.replace("_", "-"),
+                    agent_name.replace("-", ""),
+                    agent_name.replace("_", ""),
+                }
+            )
+
+            for alt_name in alternative_names:
+                if alt_name != agent_name:
+                    alt_file = templates_dir / f"{alt_name}.json"
+                    if alt_file.exists():
+                        with alt_file.open() as f:
+                            template_data = json.load(f)
+                            return template_data.get("routing")
+
+            return None
+
+        except Exception as e:
+            self.logger.debug(f"Could not load routing metadata for {agent_name}: {e}")
+            return None
+
+    def load_memory_routing_from_template(
+        self, agent_name: str, framework_path: Optional[Path] = None
+    ) -> Optional[Dict[str, Any]]:
+        """Load memory routing metadata from agent JSON template.
+
+        Args:
+            agent_name: Name of the agent
+            framework_path: Path to framework installation
+
+        Returns:
+            Dictionary with memory routing metadata or None if not found
+        """
+        try:
+            # Check if we have a framework path
+            if not framework_path or framework_path == Path("__PACKAGED__"):
+                # For packaged installations, try to load from package resources
+                if files:
+                    try:
+                        templates_package = files("claude_mpm.agents.templates")
+                        template_file = templates_package / f"{agent_name}.json"
+
+                        if template_file.is_file():
+                            template_content = template_file.read_text()
+                            template_data = json.loads(template_content)
+                            return template_data.get("memory_routing")
+                    except Exception as e:
+                        self.logger.debug(
+                            f"Could not load memory routing from packaged template for {agent_name}: {e}"
+                        )
+                return None
+
+            # For development mode, load from filesystem
+            templates_dir = (
+                framework_path / "src" / "claude_mpm" / "agents" / "templates"
+            )
+            template_file = templates_dir / f"{agent_name}.json"
+
+            if template_file.exists():
+                with template_file.open() as f:
+                    template_data = json.load(f)
+                    return template_data.get("memory_routing")
+
+            # Also check for variations in naming
+            alternative_names = list(
+                {
+                    agent_name.replace("-", "_"),
+                    agent_name.replace("_", "-"),
+                    agent_name.replace("-agent", ""),
+                    agent_name.replace("_agent", ""),
+                    agent_name + "_agent",
+                    agent_name + "-agent",
+                }
+            )
+
+            for alt_name in alternative_names:
+                if alt_name != agent_name:
+                    alt_file = templates_dir / f"{alt_name}.json"
+                    if alt_file.exists():
+                        with alt_file.open() as f:
+                            template_data = json.load(f)
+                            return template_data.get("memory_routing")
+
+            return None
+
+        except Exception as e:
+            self.logger.debug(
+                f"Could not load memory routing from template for {agent_name}: {e}"
+            )
+            return None
+
+    def get_fallback_capabilities(self) -> str:
+        """Return fallback capabilities when dynamic discovery fails.
+
+        Returns:
+            Fallback agent capabilities section
+        """
+        return """
+
+## Available Agent Capabilities
+
+You have the following specialized agents available for delegation:
+
+- **Engineer** (`engineer`): Code implementation and development
+- **Research** (`research-agent`): Investigation and analysis
+- **QA** (`qa-agent`): Testing and quality assurance
+- **Documentation** (`documentation-agent`): Documentation creation and maintenance
+- **Security** (`security-agent`): Security analysis and protection
+- **Data Engineer** (`data-engineer`): Data management and pipelines
+- **Ops** (`ops-agent`): Deployment and operations
+- **Version Control** (`version-control`): Git operations and version management
+
+**IMPORTANT**: Use the exact agent ID in parentheses when delegating tasks.
+"""

claude_mpm/core/framework/formatters/content_formatter.py

@@ -0,0 +1,278 @@
+"""Framework content formatter for generating instructions."""
+
+import re
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+
+class ContentFormatter:
+    """Formats framework content for injection into prompts."""
+
+    def __init__(self):
+        """Initialize the content formatter."""
+        self.logger = get_logger("content_formatter")
+
+    def strip_metadata_comments(self, content: str) -> str:
+        """Strip metadata HTML comments from content.
+
+        Removes comments like:
+        <!-- FRAMEWORK_VERSION: 0010 -->
+        <!-- LAST_MODIFIED: 2025-08-10T00:00:00Z -->
+
+        Args:
+            content: Content to clean
+
+        Returns:
+            Cleaned content without metadata comments
+        """
+        # Remove HTML comments that contain metadata
+        cleaned = re.sub(
+            r"<!--\s*(FRAMEWORK_VERSION|LAST_MODIFIED|WORKFLOW_VERSION|PROJECT_WORKFLOW_VERSION|CUSTOM_PROJECT_WORKFLOW)[^>]*-->\n?",
+            "",
+            content,
+        )
+        # Also remove any leading blank lines that might result
+        return cleaned.lstrip("\n")
+
+    def format_full_framework(
+        self,
+        framework_content: Dict[str, Any],
+        capabilities_section: str,
+        context_section: str,
+        inject_output_style: bool = False,
+        output_style_content: Optional[str] = None,
+    ) -> str:
+        """Format complete framework instructions.
+
+        Args:
+            framework_content: Dictionary containing framework content
+            capabilities_section: Generated agent capabilities section
+            context_section: Generated temporal/user context section
+            inject_output_style: Whether to inject output style content
+            output_style_content: Output style content to inject (if needed)
+
+        Returns:
+            Formatted framework instructions
+        """
+        # If we have the full framework INSTRUCTIONS.md, use it
+        if framework_content.get("framework_instructions"):
+            instructions = self.strip_metadata_comments(
+                framework_content["framework_instructions"]
+            )
+
+            # Add custom INSTRUCTIONS.md if present (overrides or extends framework instructions)
+            if framework_content.get("custom_instructions"):
+                level = framework_content.get("custom_instructions_level", "unknown")
+                instructions += f"\n\n## Custom PM Instructions ({level} level)\n\n"
+                instructions += "**The following custom instructions override or extend the framework defaults:**\n\n"
+                instructions += self.strip_metadata_comments(
+                    framework_content["custom_instructions"]
+                )
+                instructions += "\n"
+
+            # Add WORKFLOW.md after instructions
+            if framework_content.get("workflow_instructions"):
+                workflow_content = self.strip_metadata_comments(
+                    framework_content["workflow_instructions"]
+                )
+                level = framework_content.get("workflow_instructions_level", "system")
+                if level != "system":
+                    instructions += f"\n\n## Workflow Instructions ({level} level)\n\n"
+                    instructions += "**The following workflow instructions override system defaults:**\n\n"
+                instructions += f"{workflow_content}\n"
+
+            # Add MEMORY.md after workflow instructions
+            if framework_content.get("memory_instructions"):
+                memory_content = self.strip_metadata_comments(
+                    framework_content["memory_instructions"]
+                )
+                level = framework_content.get("memory_instructions_level", "system")
+                if level != "system":
+                    instructions += f"\n\n## Memory Instructions ({level} level)\n\n"
+                    instructions += "**The following memory instructions override system defaults:**\n\n"
+                instructions += f"{memory_content}\n"
+
+            # Add actual PM memories after memory instructions
+            if framework_content.get("actual_memories"):
+                instructions += "\n\n## Current PM Memories\n\n"
+                instructions += "**The following are your accumulated memories and knowledge from this project:**\n\n"
+                instructions += framework_content["actual_memories"]
+                instructions += "\n"
+
+            # NOTE: Agent memories are now injected at agent deployment time
+            # in agent_template_builder.py, not in PM instructions.
+            # This ensures each agent gets its own memory, not all memories embedded in PM.
+
+            # Add dynamic agent capabilities section
+            instructions += capabilities_section
+
+            # Add enhanced temporal and user context for better awareness
+            instructions += context_section
+
+            # Add BASE_PM.md framework requirements AFTER INSTRUCTIONS.md
+            if framework_content.get("base_pm_instructions"):
+                base_pm = self.strip_metadata_comments(
+                    framework_content["base_pm_instructions"]
+                )
+                instructions += f"\n\n{base_pm}"
+
+            # Inject output style content if needed (for Claude < 1.0.83)
+            if inject_output_style and output_style_content:
+                instructions += "\n\n## Output Style Configuration\n"
+                instructions += "**Note: The following output style is injected for Claude < 1.0.83**\n\n"
+                instructions += output_style_content
+                instructions += "\n"
+
+            # Clean up any trailing whitespace
+            return instructions.rstrip() + "\n"
+
+        # Otherwise generate minimal framework
+        return self.format_minimal_framework(framework_content)
+
+    def format_minimal_framework(self, framework_content: Dict[str, Any]) -> str:
+        """Format minimal framework instructions when full framework not available.
+
+        Args:
+            framework_content: Dictionary containing framework content
+
+        Returns:
+            Minimal framework instructions
+        """
+        instructions = """# Claude MPM Framework Instructions
+
+You are operating within the Claude Multi-Agent Project Manager (MPM) framework.
+
+## Core Role
+You are a multi-agent orchestrator. Your primary responsibilities are:
+- Delegate all implementation work to specialized agents via Task Tool
+- Coordinate multi-agent workflows and cross-agent collaboration
+- Extract and track TODO/BUG/FEATURE items for ticket creation
+- Maintain project visibility and strategic oversight
+- NEVER perform direct implementation work yourself
+
+"""
+
+        # Add agent definitions if available
+        if framework_content.get("agents"):
+            instructions += "## Available Agents\n\n"
+            instructions += "You have the following specialized agents available for delegation:\n\n"
+
+            # List agents with brief descriptions and correct IDs
+            agent_list = []
+            for agent_name in sorted(framework_content["agents"].keys()):
+                # Use the actual agent_name as the ID (it's the filename stem)
+                agent_id = agent_name
+                clean_name = agent_name.replace("-", " ").replace("_", " ").title()
+                if (
+                    "engineer" in agent_name.lower()
+                    and "data" not in agent_name.lower()
+                ):
+                    agent_list.append(
+                        f"- **Engineer Agent** (`{agent_id}`): Code implementation and development"
+                    )
+                elif "qa" in agent_name.lower():
+                    agent_list.append(
+                        f"- **QA Agent** (`{agent_id}`): Testing and quality assurance"
+                    )
+                elif "documentation" in agent_name.lower():
+                    agent_list.append(
+                        f"- **Documentation Agent** (`{agent_id}`): Documentation creation and maintenance"
+                    )
+                elif "research" in agent_name.lower():
+                    agent_list.append(
+                        f"- **Research Agent** (`{agent_id}`): Investigation and analysis"
+                    )
+                elif "security" in agent_name.lower():
+                    agent_list.append(
+                        f"- **Security Agent** (`{agent_id}`): Security analysis and protection"
+                    )
+                elif "version" in agent_name.lower():
+                    agent_list.append(
+                        f"- **Version Control Agent** (`{agent_id}`): Git operations and version management"
+                    )
+                elif "ops" in agent_name.lower():
+                    agent_list.append(
+                        f"- **Ops Agent** (`{agent_id}`): Deployment and operations"
+                    )
+                elif "data" in agent_name.lower():
+                    agent_list.append(
+                        f"- **Data Engineer Agent** (`{agent_id}`): Data management and AI API integration"
+                    )
+                else:
+                    agent_list.append(
+                        f"- **{clean_name}** (`{agent_id}`): Available for specialized tasks"
+                    )
+
+            instructions += "\n".join(agent_list) + "\n\n"
+
+            # Add full agent details
+            instructions += "### Agent Details\n\n"
+            for agent_name, agent_content in sorted(
+                framework_content["agents"].items()
+            ):
+                instructions += f"#### {agent_name.replace('-', ' ').title()}\n"
+                instructions += agent_content + "\n\n"
+
+        # Add orchestration principles
+        instructions += """
+## Orchestration Principles
+1. **Always Delegate**: Never perform direct work - use Task Tool for all implementation
+2. **Comprehensive Context**: Provide rich, filtered context to each agent
+3. **Track Everything**: Extract all TODO/BUG/FEATURE items systematically
+4. **Cross-Agent Coordination**: Orchestrate workflows spanning multiple agents
+5. **Results Integration**: Actively receive and integrate agent results
+
+## Task Tool Format
+```
+**[Agent Name]**: [Clear task description with deliverables]
+
+TEMPORAL CONTEXT: Today is [date]. Apply date awareness to [specific considerations].
+
+**Task**: [Detailed task breakdown]
+1. [Specific action item 1]
+2. [Specific action item 2]
+3. [Specific action item 3]
+
+**Context**: [Comprehensive filtered context for this agent]
+**Authority**: [Agent's decision-making scope]
+**Expected Results**: [Specific deliverables needed]
+**Integration**: [How results integrate with other work]
+```
+
+## Ticket Extraction Patterns
+Extract tickets from these patterns:
+- TODO: [description] → TODO ticket
+- BUG: [description] → BUG ticket
+- FEATURE: [description] → FEATURE ticket
+- ISSUE: [description] → ISSUE ticket
+- FIXME: [description] → BUG ticket
+
+---
+"""
+
+        return instructions
+
+    def get_fallback_capabilities(self) -> str:
+        """Return fallback capabilities when dynamic discovery fails.
+
+        Returns:
+            Fallback agent capabilities section
+        """
+        return """
+
+## Available Agent Capabilities
+
+You have the following specialized agents available for delegation:
+
+- **Engineer** (`engineer`): Code implementation and development
+- **Research** (`research-agent`): Investigation and analysis
+- **QA** (`qa-agent`): Testing and quality assurance
+- **Documentation** (`documentation-agent`): Documentation creation and maintenance
+- **Security** (`security-agent`): Security analysis and protection
+- **Data Engineer** (`data-engineer`): Data management and pipelines
+- **Ops** (`ops-agent`): Deployment and operations
+- **Version Control** (`version-control`): Git operations and version management
+
+**IMPORTANT**: Use the exact agent ID in parentheses when delegating tasks.
+"""