claude-mpm 4.14.6__py3-none-any.whl → 4.14.8__py3-none-any.whl

claude_mpm/core/enums.py

@@ -0,0 +1,322 @@
+"""
+Centralized enums for type-safe string constants across Claude MPM.
+
+This module provides enumerated types to replace magic strings throughout the codebase,
+improving type safety, IDE autocomplete, and preventing typos.
+
+Created: 2025-10-25
+Priority: Phase 1 of systematic enum migration (3-4 week plan)
+Impact: Replaces 2,050+ magic string occurrences
+
+Usage:
+    from claude_mpm.core.enums import OperationResult, OutputFormat, ServiceState
+
+    # Type-safe operation results
+    result = OperationResult.SUCCESS
+    if result == OperationResult.SUCCESS:
+        print("Operation completed successfully")
+
+    # Type-safe output formatting
+    format_type = OutputFormat.JSON
+
+    # Type-safe service state management
+    state = ServiceState.RUNNING
+"""
+
+from enum import StrEnum
+
+
+class OperationResult(StrEnum):
+    """
+    Standard result codes for operations throughout Claude MPM.
+
+    Replaces 876+ occurrences of magic strings like "success", "error", "failed".
+    Used in: CLI commands, service operations, API responses, hook handlers.
+
+    Migration Priority: HIGH (Week 1)
+    Coverage: ~42% of all magic strings
+    """
+
+    SUCCESS = "success"
+    """Operation completed successfully."""
+
+    ERROR = "error"
+    """Operation encountered an error."""
+
+    FAILED = "failed"
+    """Operation failed to complete."""
+
+    PENDING = "pending"
+    """Operation is waiting to execute."""
+
+    COMPLETED = "completed"
+    """Operation has been completed."""
+
+    TIMEOUT = "timeout"
+    """Operation exceeded time limit."""
+
+    CANCELLED = "cancelled"
+    """Operation was cancelled before completion."""
+
+    CONTEXT_READY = "context_ready"
+    """Context is prepared and ready for use."""
+
+    SKIPPED = "skipped"
+    """Operation was intentionally skipped."""
+
+    RETRY = "retry"
+    """Operation should be retried."""
+
+    PARTIAL = "partial"
+    """Operation completed partially."""
+
+    UNKNOWN = "unknown"
+    """Operation result is unknown or indeterminate."""
+
+
+class OutputFormat(StrEnum):
+    """
+    Output format options for CLI commands and logging.
+
+    Replaces 200+ occurrences of format strings.
+    Used in: CLI output, logging, configuration exports, API responses.
+
+    Migration Priority: HIGH (Week 1)
+    Coverage: ~10% of all magic strings
+    """
+
+    JSON = "json"
+    """JavaScript Object Notation format."""
+
+    YAML = "yaml"
+    """YAML Ain't Markup Language format."""
+
+    TEXT = "text"
+    """Plain text format."""
+
+    MARKDOWN = "markdown"
+    """Markdown formatted text."""
+
+    RAW = "raw"
+    """Raw unformatted output."""
+
+    TABLE = "table"
+    """Tabular format for display."""
+
+    CSV = "csv"
+    """Comma-separated values format."""
+
+    HTML = "html"
+    """HyperText Markup Language format."""
+
+    XML = "xml"
+    """eXtensible Markup Language format."""
+
+
+class ServiceState(StrEnum):
+    """
+    Service lifecycle states for all Claude MPM services.
+
+    Replaces 150+ occurrences of service state strings.
+    Used in: Hook services, MCP servers, monitoring, health checks.
+
+    Migration Priority: HIGH (Week 1)
+    Coverage: ~7% of all magic strings
+    """
+
+    STOPPED = "stopped"
+    """Service is completely stopped."""
+
+    STARTING = "starting"
+    """Service is in the process of starting."""
+
+    RUNNING = "running"
+    """Service is actively running."""
+
+    STOPPING = "stopping"
+    """Service is in the process of stopping."""
+
+    RESTARTING = "restarting"
+    """Service is restarting."""
+
+    ERROR = "error"
+    """Service encountered an error."""
+
+    UNKNOWN = "unknown"
+    """Service state cannot be determined."""
+
+    DEGRADED = "degraded"
+    """Service is running but with reduced functionality."""
+
+    IDLE = "idle"
+    """Service is running but not actively processing."""
+
+
+class ValidationSeverity(StrEnum):
+    """
+    Severity levels for validation and error reporting.
+
+    Replaces validation severity strings across validators and error handlers.
+    Used in: Frontmatter validation, API validation, config validation.
+
+    Migration Priority: MEDIUM (Week 2)
+    Coverage: ~5% of all magic strings
+    """
+
+    INFO = "info"
+    """Informational message, no action required."""
+
+    WARNING = "warning"
+    """Warning that should be addressed but not critical."""
+
+    ERROR = "error"
+    """Error that prevents operation completion."""
+
+    CRITICAL = "critical"
+    """Critical error requiring immediate attention."""
+
+    DEBUG = "debug"
+    """Debug-level information for troubleshooting."""
+
+
+class ModelTier(StrEnum):
+    """
+    Claude model tier classifications and identifiers.
+
+    Replaces model name strings and enables model normalization.
+    Used in: Agent configuration, API calls, capability detection.
+
+    Migration Priority: MEDIUM (Week 2)
+    Coverage: ~4% of all magic strings
+
+    Notes:
+        - Replaces manual model normalization code
+        - Enables type-safe model selection
+        - Provides both tier names and full model identifiers
+    """
+
+    # Tier names (simplified)
+    OPUS = "opus"
+    """Claude Opus tier (highest capability)."""
+
+    SONNET = "sonnet"
+    """Claude Sonnet tier (balanced)."""
+
+    HAIKU = "haiku"
+    """Claude Haiku tier (fastest)."""
+
+    # Full model identifiers (Claude 4.x)
+    OPUS_4 = "claude-opus-4-20250514"
+    """Claude 4 Opus - May 2025 release."""
+
+    SONNET_4 = "claude-sonnet-4-20250514"
+    """Claude 4 Sonnet - May 2025 release."""
+
+    SONNET_4_5 = "claude-sonnet-4-5-20250929"
+    """Claude 4.5 Sonnet - September 2025 release."""
+
+    # Legacy model identifiers (Claude 3.x)
+    OPUS_3 = "claude-3-opus-20240229"
+    """Claude 3 Opus - February 2024 release."""
+
+    SONNET_3_5 = "claude-3-5-sonnet-20241022"
+    """Claude 3.5 Sonnet - October 2024 release."""
+
+    HAIKU_3 = "claude-3-haiku-20240307"
+    """Claude 3 Haiku - March 2024 release."""
+
+    @classmethod
+    def normalize(cls, model_name: str) -> "ModelTier":
+        """
+        Normalize a model name to its canonical tier.
+
+        Args:
+            model_name: Any model name variant (e.g., "opus", "claude-opus-4", "OPUS")
+
+        Returns:
+            Normalized ModelTier enum value
+
+        Examples:
+            >>> ModelTier.normalize("OPUS")
+            ModelTier.OPUS
+            >>> ModelTier.normalize("claude-sonnet-4-20250514")
+            ModelTier.SONNET_4
+            >>> ModelTier.normalize("sonnet")
+            ModelTier.SONNET
+        """
+        normalized = model_name.lower().strip()
+
+        # Direct enum value match
+        for tier in cls:
+            if tier.value == normalized:
+                return tier
+
+        # Tier name extraction
+        if "opus" in normalized:
+            return cls.OPUS
+        if "sonnet" in normalized:
+            return cls.SONNET
+        if "haiku" in normalized:
+            return cls.HAIKU
+
+        # Default to sonnet for unknown models
+        return cls.SONNET
+
+
+class AgentCategory(StrEnum):
+    """
+    Agent specialization categories for classification and routing.
+
+    Replaces category strings in agent configurations and routing logic.
+    Used in: Agent templates, capability detection, routing decisions.
+
+    Migration Priority: MEDIUM (Week 3)
+    Coverage: ~3% of all magic strings
+    """
+
+    RESEARCH = "research"
+    """Research and analysis agents."""
+
+    ENGINEERING = "engineering"
+    """Software engineering and implementation agents."""
+
+    QA = "qa"
+    """Quality assurance and testing agents."""
+
+    SECURITY = "security"
+    """Security analysis and vulnerability assessment agents."""
+
+    DOCUMENTATION = "documentation"
+    """Documentation and technical writing agents."""
+
+    OPERATIONS = "operations"
+    """DevOps and infrastructure management agents."""
+
+    DATA = "data"
+    """Data engineering and analytics agents."""
+
+    VERSION_CONTROL = "version_control"
+    """Version control and release management agents."""
+
+    GENERAL = "general"
+    """General-purpose agents without specific specialization."""
+
+    CUSTOM = "custom"
+    """User-defined custom agent categories."""
+
+    PROJECT_MANAGEMENT = "project_management"
+    """Project management and coordination agents."""
+
+    DESIGN = "design"
+    """UI/UX design and frontend agents."""
+
+
+# Export all enums for convenient access
+__all__ = [
+    "AgentCategory",
+    "ModelTier",
+    "OperationResult",
+    "OutputFormat",
+    "ServiceState",
+    "ValidationSeverity",
+]

claude_mpm/core/instruction_reinforcement_hook.py

@@ -21,6 +21,7 @@ import threading
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
+from ..core.enums import OperationResult
 from ..core.logger import get_logger
 
 
@@ -158,7 +159,7 @@ class InstructionReinforcementHook:
         # Create reminder todo
         reminder_todo = {
             "content": message,
-            "status": "pending",
+            "status": OperationResult.PENDING,
             "activeForm": "Processing instruction reminder",
         }
 

claude_mpm/core/interactive_session.py

@@ -11,6 +11,7 @@ import uuid
 from pathlib import Path
 from typing import Any, Dict, Optional, Tuple
 
+from claude_mpm.core.enums import ServiceState
 from claude_mpm.core.logger import get_logger
 
 
@@ -179,7 +180,8 @@ class InteractiveSession:
             # Notify WebSocket if connected
             if self.runner.websocket_server:
                 self.runner.websocket_server.claude_status_changed(
-                    status="starting", message="Launching Claude interactive session"
+                    status=ServiceState.STARTING,
+                    message="Launching Claude interactive session",
                 )
 
             # Launch using selected method
@@ -454,7 +456,8 @@ class InteractiveSession:
         # Notify WebSocket before exec
         if self.runner.websocket_server:
             self.runner.websocket_server.claude_status_changed(
-                status="running", message="Claude process started (exec mode)"
+                status=ServiceState.RUNNING,
+                message="Claude process started (exec mode)",
             )
 
         # This will not return if successful
@@ -494,7 +497,7 @@ class InteractiveSession:
         # Notify WebSocket of error
         if self.runner.websocket_server:
             self.runner.websocket_server.claude_status_changed(
-                status="error", message=f"Failed to launch Claude: {error}"
+                status=ServiceState.ERROR, message=f"Failed to launch Claude: {error}"
             )
 
     def _handle_keyboard_interrupt(self) -> None:

claude_mpm/core/logging_config.py

@@ -24,6 +24,7 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, Dict, Optional, Union
 
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.core.logger import (
     JsonFormatter,
     finalize_streaming_logs,
@@ -234,7 +235,10 @@ def log_operation(
             execution_time = time.time() - start_time
             logger.info(
                 f"Completed {operation}",
-                extra={"execution_time": execution_time, "status": "success"},
+                extra={
+                    "execution_time": execution_time,
+                    "status": OperationResult.SUCCESS,
+                },
             )
         except Exception as e:
             execution_time = time.time() - start_time
@@ -242,7 +246,7 @@ def log_operation(
                 f"Failed {operation}: {e}",
                 extra={
                     "execution_time": execution_time,
-                    "status": "failure",
+                    "status": OperationResult.FAILED,
                     "error": str(e),
                 },
             )

claude_mpm/core/oneshot_session.py

@@ -12,6 +12,7 @@ import uuid
 from pathlib import Path
 from typing import Any, Dict, Optional, Tuple
 
+from claude_mpm.core.enums import OperationResult, ServiceState
 from claude_mpm.core.logger import get_logger
 
 
@@ -162,7 +163,7 @@ class OneshotSession:
 
         if self.runner.websocket_server:
             self.runner.websocket_server.claude_status_changed(
-                status="running", message="Executing Claude oneshot command"
+                status=ServiceState.RUNNING, message="Executing Claude oneshot command"
             )
 
     def _run_subprocess(
@@ -222,7 +223,7 @@ class OneshotSession:
         # End WebSocket session
         if self.runner.websocket_server:
             self.runner.websocket_server.claude_status_changed(
-                status="stopped", message="Session completed"
+                status=ServiceState.STOPPED, message="Session completed"
             )
             self.runner.websocket_server.session_ended()
 
@@ -299,7 +300,9 @@ class OneshotSession:
                 agent_name = self.runner._extract_agent_from_response(response)
                 if agent_name:
                     self.runner.websocket_server.agent_delegated(
-                        agent=agent_name, task=prompt[:100], status="detected"
+                        agent=agent_name,
+                        task=prompt[:100],
+                        status=OperationResult.PENDING,
                     )
 
         # Log completion
@@ -335,7 +338,8 @@ class OneshotSession:
         if self.runner.websocket_server:
             self.runner.websocket_server.claude_output(error_msg, "stderr")
             self.runner.websocket_server.claude_status_changed(
-                status="error", message=f"Command failed with code {return_code}"
+                status=ServiceState.ERROR,
+                message=f"Command failed with code {return_code}",
             )
 
         # Log error

claude_mpm/core/output_style_manager.py

@@ -160,203 +160,23 @@ class OutputStyleManager:
 
     def extract_output_style_content(self, framework_loader=None) -> str:
         """
-        Extract output style content from framework instructions.
-
-        This extracts PM delegation behavior, tone, communication standards,
-        response formats, TodoWrite requirements, and workflow rules from:
-        - INSTRUCTIONS.md
-        - BASE_PM.md
+        Read output style content from OUTPUT_STYLE.md.
 
         Args:
-            framework_loader: Optional FrameworkLoader instance to reuse loaded content
+            framework_loader: Optional framework loader (kept for compatibility, not used)
 
         Returns:
-            Formatted output style content in YAML frontmatter + markdown format
+            Complete output style content from file
         """
-        # Build the content sections
-        sections = []
-
-        # Add YAML frontmatter
-        sections.append("---")
-        sections.append("name: Claude MPM")
-        sections.append(
-            "description: Multi-Agent Project Manager orchestration mode for delegation and coordination"
-        )
-        sections.append("---")
-        sections.append("")
-
-        # Header
-        sections.append(
-            "You are Claude Multi-Agent PM, a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized agents."
-        )
-        sections.append("")
-
-        # Extract from INSTRUCTIONS.md
-        if framework_loader and framework_loader.framework_content.get(
-            "framework_instructions"
-        ):
-            instructions = framework_loader.framework_content["framework_instructions"]
-            sections.extend(self._extract_instructions_sections(instructions))
-        else:
-            # Load from file if no framework_loader provided
-            instructions_path = (
-                Path(__file__).parent.parent / "agents" / "INSTRUCTIONS.md"
-            )
-            if instructions_path.exists():
-                instructions = instructions_path.read_text()
-                sections.extend(self._extract_instructions_sections(instructions))
-
-        # Extract from BASE_PM.md
-        if framework_loader and framework_loader.framework_content.get(
-            "base_pm_instructions"
-        ):
-            base_pm = framework_loader.framework_content["base_pm_instructions"]
-            sections.extend(self._extract_base_pm_sections(base_pm))
-        else:
-            # Load from file if no framework_loader provided
-            base_pm_path = Path(__file__).parent.parent / "agents" / "BASE_PM.md"
-            if base_pm_path.exists():
-                base_pm = base_pm_path.read_text()
-                sections.extend(self._extract_base_pm_sections(base_pm))
-
-        return "\n".join(sections)
-
-    def _extract_instructions_sections(self, content: str) -> list:
-        """Extract relevant sections from INSTRUCTIONS.md."""
-        sections = []
-
-        # Extract Primary Directive
-        if "## 🔴 PRIMARY DIRECTIVE" in content:
-            sections.append("## 🔴 PRIMARY DIRECTIVE - MANDATORY DELEGATION 🔴")
-            sections.append("")
-            sections.append(
-                "**YOU ARE STRICTLY FORBIDDEN FROM DOING ANY WORK DIRECTLY.**"
-            )
-            sections.append("")
-            sections.append(
-                "Direct implementation is ABSOLUTELY PROHIBITED unless the user EXPLICITLY overrides with phrases like:"
-            )
-            sections.append('- "do this yourself"')
-            sections.append('- "don\'t delegate"')
-            sections.append('- "implement directly"')
-            sections.append('- "you do it"')
-            sections.append('- "no delegation"')
-            sections.append("")
-
-        # Extract Core Identity and Rules
-        if "## Core Identity" in content:
-            sections.append("## Core Operating Rules")
-            sections.append("")
-            sections.append("**DEFAULT BEHAVIOR - ALWAYS DELEGATE**:")
-            sections.append(
-                "- 🔴 You MUST delegate 100% of ALL work to specialized agents by default"
-            )
-            sections.append(
-                "- 🔴 Direct action is STRICTLY FORBIDDEN without explicit user override"
-            )
-            sections.append(
-                "- 🔴 Even the simplest tasks MUST be delegated - NO EXCEPTIONS"
-            )
-            sections.append("- 🔴 When in doubt, ALWAYS DELEGATE - never act directly")
-            sections.append("")
-            sections.append("**Allowed Tools**:")
-            sections.append("- **Task** for delegation (YOUR PRIMARY FUNCTION)")
-            sections.append("- **TodoWrite** for tracking delegation progress ONLY")
-            sections.append(
-                "- **WebSearch/WebFetch** for gathering context BEFORE delegation"
-            )
-            sections.append(
-                "- **Direct answers** ONLY for questions about PM capabilities"
-            )
-            sections.append("")
-
-        # Extract Communication Standards
-        if "## Communication Standards" in content:
-            sections.append("## Communication Standards")
-            sections.append("")
-            sections.append("- **Tone**: Professional, neutral by default")
-            sections.append('- **Use**: "Understood", "Confirmed", "Noted"')
-            sections.append("- **No simplification** without explicit user request")
-            sections.append("- **No mocks** outside test environments")
-            sections.append("- **Complete implementations** only - no placeholders")
-            sections.append(
-                '- **FORBIDDEN**: Overeager enthusiasm ("Excellent!", "Perfect!", "Amazing!")'
-            )
-            sections.append("")
-
-        # Extract Error Handling
-        if "## Error Handling Protocol" in content:
-            sections.append("## Error Handling Protocol")
-            sections.append("")
-            sections.append("**3-Attempt Process**:")
-            sections.append("1. **First Failure**: Re-delegate with enhanced context")
-            sections.append(
-                '2. **Second Failure**: Mark "ERROR - Attempt 2/3", escalate if needed'
-            )
-            sections.append(
-                "3. **Third Failure**: TodoWrite escalation with user decision required"
-            )
-            sections.append("")
-
-        # Extract Standard Operating Procedure
-        if "## Standard Operating Procedure" in content:
-            sections.append("## Standard Operating Procedure")
-            sections.append("")
-            sections.append("1. **Analysis**: Parse request, assess context (NO TOOLS)")
-            sections.append(
-                "2. **Planning**: Agent selection, task breakdown, priority assignment"
-            )
-            sections.append("3. **Delegation**: Task Tool with enhanced format")
-            sections.append("4. **Monitoring**: Track progress via TodoWrite")
-            sections.append("5. **Integration**: Synthesize results, validate, report")
-            sections.append("")
-
-        return sections
-
-    def _extract_base_pm_sections(self, content: str) -> list:
-        """Extract relevant sections from BASE_PM.md."""
-        sections = []
-
-        # Extract TodoWrite Requirements
-        if "## TodoWrite Framework Requirements" in content:
-            sections.append("## TodoWrite Requirements")
-            sections.append("")
-            sections.append("### Mandatory [Agent] Prefix Rules")
-            sections.append("")
-            sections.append("**ALWAYS use [Agent] prefix for delegated tasks**:")
-            sections.append("- ✅ `[Research] Analyze authentication patterns`")
-            sections.append("- ✅ `[Engineer] Implement user registration`")
-            sections.append("- ✅ `[QA] Test payment flow`")
-            sections.append("- ✅ `[Documentation] Update API docs`")
-            sections.append("")
-            sections.append("**NEVER use [PM] prefix for implementation tasks**")
-            sections.append("")
-            sections.append("### Task Status Management")
-            sections.append("")
-            sections.append("- `pending` - Task not yet started")
-            sections.append(
-                "- `in_progress` - Currently being worked on (ONE at a time)"
-            )
-            sections.append("- `completed` - Task finished successfully")
-            sections.append("")
-
-        # Extract PM Response Format
-        if "## PM Response Format" in content:
-            sections.append("## Response Format")
-            sections.append("")
-            sections.append(
-                "When completing delegations, provide structured summaries including:"
-            )
-            sections.append("- Request summary")
-            sections.append("- Agents used and task counts")
-            sections.append("- Tasks completed with [Agent] prefixes")
-            sections.append("- Files affected across all agents")
-            sections.append("- Blockers encountered and resolutions")
-            sections.append("- Next steps for user")
-            sections.append("- Key information to remember")
-            sections.append("")
-
-        return sections
+        # Always read from the complete OUTPUT_STYLE.md file
+        if self.mpm_output_style_path.exists():
+            content = self.mpm_output_style_path.read_text()
+            self.logger.info(f"Read OUTPUT_STYLE.md directly ({len(content)} chars)")
+            return content
+        # Fallback error
+        error_msg = f"OUTPUT_STYLE.md not found at {self.mpm_output_style_path}"
+        self.logger.error(error_msg)
+        raise FileNotFoundError(error_msg)
 
     def save_output_style(self, content: str) -> Path:
         """

claude_mpm/core/service_registry.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Type, Union
 from .base_service import BaseService
 from .config import Config
 from .container import DIContainer, ServiceLifetime, get_container
+from .enums import OperationResult
 from .logger import get_logger
 from .shared.config_loader import ConfigLoader
 
@@ -249,7 +250,10 @@ class ServiceRegistry:
                                 "metrics": health.metrics,
                             }
                 except Exception as e:
-                    health_status[name] = {"status": "error", "message": str(e)}
+                    health_status[name] = {
+                        "status": OperationResult.ERROR,
+                        "message": str(e),
+                    }
 
             return health_status