claude-mpm 4.4.0__py3-none-any.whl → 4.4.4__py3-none-any.whl

claude_mpm/core/framework/formatters/content_formatter.py

@@ -0,0 +1,288 @@
+"""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"
+
+            # Add agent memories if available
+            if framework_content.get("agent_memories"):
+                agent_memories = framework_content["agent_memories"]
+                if agent_memories:
+                    instructions += "\n\n## Agent Memories\n\n"
+                    instructions += "**The following are accumulated memories from specialized agents:**\n\n"
+
+                    for agent_name in sorted(agent_memories.keys()):
+                        memory_content = agent_memories[agent_name]
+                        if memory_content:
+                            instructions += f"### {agent_name.replace('_', ' ').title()} Agent Memory\n\n"
+                            instructions += memory_content
+                            instructions += "\n\n"
+
+            # 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.
+"""

claude_mpm/core/framework/formatters/context_generator.py

@@ -0,0 +1,184 @@
+"""Temporal and user context generator for framework instructions."""
+
+import getpass
+import locale
+import os
+import platform
+import time as time_module
+from datetime import datetime, timezone
+
+from claude_mpm.core.logging_utils import get_logger
+
+
+class ContextGenerator:
+    """Generates temporal and user context for better PM awareness."""
+
+    def __init__(self):
+        """Initialize the context generator."""
+        self.logger = get_logger("context_generator")
+
+    def generate_temporal_user_context(self) -> str:
+        """Generate enhanced temporal and user context for better PM awareness.
+
+        Returns:
+            Formatted context string with datetime, user, and system information
+        """
+        context_lines = ["\n\n## Temporal & User Context\n"]
+
+        try:
+            # Get current datetime with timezone awareness
+            now = datetime.now(timezone.utc)
+
+            # Try to get timezone info - fallback to UTC offset if timezone name not available
+            try:
+                if hasattr(time_module, "tzname"):
+                    tz_name = time_module.tzname[time_module.daylight]
+                    tz_offset = time_module.strftime("%z")
+                    if tz_offset:
+                        # Format UTC offset properly (e.g., -0800 to -08:00)
+                        tz_offset = (
+                            f"{tz_offset[:3]}:{tz_offset[3:]}"
+                            if len(tz_offset) >= 4
+                            else tz_offset
+                        )
+                        tz_info = f"{tz_name} (UTC{tz_offset})"
+                    else:
+                        tz_info = tz_name
+                else:
+                    tz_info = "Local Time"
+            except Exception:
+                tz_info = "Local Time"
+
+            # Format datetime components
+            date_str = now.strftime("%Y-%m-%d")
+            time_str = now.strftime("%H:%M:%S")
+            day_name = now.strftime("%A")
+
+            context_lines.append(
+                f"**Current DateTime**: {date_str} {time_str} {tz_info}\n"
+            )
+            context_lines.append(f"**Day**: {day_name}\n")
+
+        except Exception as e:
+            # Fallback to basic date if enhanced datetime fails
+            self.logger.debug(f"Error generating enhanced datetime context: {e}")
+            context_lines.append(
+                f"**Today's Date**: {datetime.now(timezone.utc).strftime('%Y-%m-%d')}\n"
+            )
+
+        # Get user information
+        self._add_user_context(context_lines)
+
+        # Get system information
+        self._add_system_context(context_lines)
+
+        # Get environment information
+        self._add_environment_context(context_lines)
+
+        # Add instruction for applying context
+        context_lines.append(
+            "\nApply temporal and user awareness to all tasks, "
+            "decisions, and interactions.\n"
+        )
+        context_lines.append(
+            "Use this context for personalized responses and "
+            "time-sensitive operations.\n"
+        )
+
+        return "".join(context_lines)
+
+    def _add_user_context(self, context_lines: list) -> None:
+        """Add user information to context.
+
+        Args:
+            context_lines: List to append context lines to
+        """
+        try:
+            # Get user information with safe fallbacks
+            username = None
+
+            # Try multiple methods to get username
+            methods = [
+                lambda: os.environ.get("USER"),
+                lambda: os.environ.get("USERNAME"),  # Windows fallback
+                lambda: getpass.getuser(),
+            ]
+
+            for method in methods:
+                try:
+                    username = method()
+                    if username:
+                        break
+                except Exception:
+                    continue
+
+            if username:
+                context_lines.append(f"**User**: {username}\n")
+
+                # Add home directory if available
+                try:
+                    home_dir = os.path.expanduser("~")
+                    if home_dir and home_dir != "~":
+                        context_lines.append(f"**Home Directory**: {home_dir}\n")
+                except Exception:
+                    pass
+
+        except Exception as e:
+            # User detection is optional, don't fail
+            self.logger.debug(f"Could not detect user information: {e}")
+
+    def _add_system_context(self, context_lines: list) -> None:
+        """Add system information to context.
+
+        Args:
+            context_lines: List to append context lines to
+        """
+        try:
+            # Get system information
+            system_info = platform.system()
+            if system_info:
+                # Enhance system name for common platforms
+                system_names = {
+                    "Darwin": "Darwin (macOS)",
+                    "Linux": "Linux",
+                    "Windows": "Windows",
+                }
+                system_display = system_names.get(system_info, system_info)
+                context_lines.append(f"**System**: {system_display}\n")
+
+                # Add platform version if available
+                try:
+                    platform_version = platform.release()
+                    if platform_version:
+                        context_lines.append(
+                            f"**System Version**: {platform_version}\n"
+                        )
+                except Exception:
+                    pass
+
+        except Exception as e:
+            # System info is optional
+            self.logger.debug(f"Could not detect system information: {e}")
+
+    def _add_environment_context(self, context_lines: list) -> None:
+        """Add environment information to context.
+
+        Args:
+            context_lines: List to append context lines to
+        """
+        try:
+            # Add current working directory
+            cwd = os.getcwd()
+            if cwd:
+                context_lines.append(f"**Working Directory**: {cwd}\n")
+        except Exception:
+            pass
+
+        try:
+            # Add locale information if available
+            current_locale = locale.getlocale()
+            if current_locale and current_locale[0]:
+                context_lines.append(f"**Locale**: {current_locale[0]}\n")
+        except Exception:
+            # Locale is optional
+            pass

claude_mpm/core/framework/loaders/__init__.py

@@ -0,0 +1,13 @@
+"""Framework loaders for handling various types of file and content loading."""
+
+from .agent_loader import AgentLoader
+from .file_loader import FileLoader
+from .instruction_loader import InstructionLoader
+from .packaged_loader import PackagedLoader
+
+__all__ = [
+    "AgentLoader",
+    "FileLoader",
+    "InstructionLoader",
+    "PackagedLoader",
+]

claude_mpm/core/framework/loaders/agent_loader.py

@@ -0,0 +1,206 @@
+"""Loader for agent discovery and management."""
+
+from pathlib import Path
+from typing import Any, Dict, Optional, Set, Tuple
+
+from claude_mpm.core.logging_utils import get_logger
+
+
+class AgentLoader:
+    """Handles agent discovery and loading from various sources."""
+
+    def __init__(self, framework_path: Optional[Path] = None):
+        """Initialize the agent loader.
+
+        Args:
+            framework_path: Path to framework installation
+        """
+        self.logger = get_logger("agent_loader")
+        self.framework_path = framework_path
+
+    def get_deployed_agents(self) -> Set[str]:
+        """
+        Get a set of deployed agent names from .claude/agents/ directories.
+
+        Returns:
+            Set of agent names (file stems) that are deployed
+        """
+        self.logger.debug("Scanning for deployed agents")
+        deployed = set()
+
+        # Check multiple locations for deployed agents
+        agents_dirs = [
+            Path.cwd() / ".claude" / "agents",  # Project-specific agents
+            Path.home() / ".claude" / "agents",  # User's system agents
+        ]
+
+        for agents_dir in agents_dirs:
+            if agents_dir.exists():
+                for agent_file in agents_dir.glob("*.md"):
+                    if not agent_file.name.startswith("."):
+                        # Use stem to get agent name without extension
+                        deployed.add(agent_file.stem)
+                        self.logger.debug(
+                            f"Found deployed agent: {agent_file.stem} in {agents_dir}"
+                        )
+
+        self.logger.debug(f"Total deployed agents found: {len(deployed)}")
+        return deployed
+
+    def load_single_agent(
+        self, agent_file: Path
+    ) -> Tuple[Optional[str], Optional[str]]:
+        """
+        Load a single agent file.
+
+        Args:
+            agent_file: Path to the agent file
+
+        Returns:
+            Tuple of (agent_name, agent_content) or (None, None) on failure
+        """
+        try:
+            agent_name = agent_file.stem
+            # Skip README files
+            if agent_name.upper() == "README":
+                return None, None
+            content = agent_file.read_text()
+            self.logger.debug(f"Loaded agent: {agent_name}")
+            return agent_name, content
+        except Exception as e:
+            self.logger.error(f"Failed to load agent {agent_file}: {e}")
+            return None, None
+
+    def load_agents_directory(
+        self,
+        agents_dir: Optional[Path],
+        templates_dir: Optional[Path] = None,
+        main_dir: Optional[Path] = None,
+    ) -> Dict[str, str]:
+        """
+        Load agent definitions from the appropriate directory.
+
+        Args:
+            agents_dir: Primary agents directory to load from
+            templates_dir: Templates directory path
+            main_dir: Main agents directory path
+
+        Returns:
+            Dictionary mapping agent names to their content
+        """
+        agents = {}
+
+        if not agents_dir or not agents_dir.exists():
+            return agents
+
+        # Load all agent files
+        for agent_file in agents_dir.glob("*.md"):
+            agent_name, agent_content = self.load_single_agent(agent_file)
+            if agent_name and agent_content:
+                agents[agent_name] = agent_content
+
+        # If we used templates dir, also check main dir for base_agent.md
+        if agents_dir == templates_dir and main_dir and main_dir.exists():
+            if "base_agent" not in agents:
+                base_agent_file = main_dir / "base_agent.md"
+                if base_agent_file.exists():
+                    agent_name, agent_content = self.load_single_agent(base_agent_file)
+                    if agent_name and agent_content:
+                        agents[agent_name] = agent_content
+
+        return agents
+
+    def discover_local_json_templates(self) -> Dict[str, Dict[str, Any]]:
+        """Discover local JSON agent templates from .claude-mpm/agents/ directories.
+
+        Returns:
+            Dictionary mapping agent IDs to agent metadata
+        """
+        import json
+
+        local_agents = {}
+
+        # Check for local JSON templates in priority order
+        template_dirs = [
+            Path.cwd()
+            / ".claude-mpm"
+            / "agents",  # Project local agents (highest priority)
+            Path.home() / ".claude-mpm" / "agents",  # User local agents
+        ]
+
+        for priority, template_dir in enumerate(template_dirs):
+            if not template_dir.exists():
+                continue
+
+            for json_file in template_dir.glob("*.json"):
+                try:
+                    with open(json_file) as f:
+                        template_data = json.load(f)
+
+                    # Extract agent metadata
+                    agent_id = template_data.get("agent_id", json_file.stem)
+
+                    # Skip if already found at higher priority
+                    if agent_id in local_agents:
+                        continue
+
+                    # Extract metadata
+                    metadata = template_data.get("metadata", {})
+
+                    # Build agent data in expected format
+                    agent_data = {
+                        "id": agent_id,
+                        "display_name": metadata.get(
+                            "name", agent_id.replace("_", " ").title()
+                        ),
+                        "description": metadata.get(
+                            "description", f"Local {agent_id} agent"
+                        ),
+                        "tools": self._extract_tools_from_template(template_data),
+                        "is_local": True,
+                        "tier": "project" if priority == 0 else "user",
+                        "author": template_data.get("author", "local"),
+                        "version": template_data.get("agent_version", "1.0.0"),
+                    }
+
+                    # Add routing data if present
+                    if "routing" in template_data:
+                        agent_data["routing"] = template_data["routing"]
+
+                    # Add memory routing if present
+                    if "memory_routing" in template_data:
+                        agent_data["memory_routing"] = template_data["memory_routing"]
+
+                    local_agents[agent_id] = agent_data
+                    self.logger.debug(
+                        f"Discovered local JSON agent: {agent_id} from {template_dir}"
+                    )
+
+                except Exception as e:
+                    self.logger.warning(
+                        f"Failed to parse local JSON template {json_file}: {e}"
+                    )
+
+        return local_agents
+
+    def _extract_tools_from_template(self, template_data: Dict[str, Any]) -> str:
+        """Extract tools string from template data.
+
+        Args:
+            template_data: JSON template data
+
+        Returns:
+            Tools string for display
+        """
+        capabilities = template_data.get("capabilities", {})
+        tools = capabilities.get("tools", "*")
+
+        if tools == "*":
+            return "All Tools"
+        if isinstance(tools, list):
+            return ", ".join(tools) if tools else "Standard Tools"
+        if isinstance(tools, str):
+            if "," in tools:
+                return tools
+            return tools
+        return "Standard Tools"