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

claude_mpm/VERSION

@@ -1 +1 @@
-4.14.8
+4.15.0

claude_mpm/agents/agent_loader.py

@@ -38,6 +38,8 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
 
+from claude_mpm.core.enums import AgentCategory
+
 # Module-level logger
 from claude_mpm.core.logging_utils import get_logger
 
@@ -281,11 +283,21 @@ class AgentLoader:
         # Check for project memory
         has_memory = capabilities.get("has_project_memory", False)
 
+        # Get category with enum validation (fallback to GENERAL if invalid)
+        category_str = metadata.get("category", "general")
+        try:
+            category = AgentCategory(category_str)
+        except ValueError:
+            logger.warning(
+                f"Invalid category '{category_str}' for agent {agent_id}, using GENERAL"
+            )
+            category = AgentCategory.GENERAL
+
         result = {
             "agent_id": agent_id,
             "name": metadata.get("name", agent_id),
             "description": metadata.get("description", ""),
-            "category": metadata.get("category", "general"),
+            "category": category.value,  # Store as string for backward compatibility
             "version": metadata.get("version", "1.0.0"),
             "model": agent_data.get("model", "claude-sonnet-4-20250514"),
             "resource_tier": agent_data.get("resource_tier", "standard"),

claude_mpm/agents/templates/project_organizer.json

@@ -15,7 +15,7 @@
     ],
     "author": "Claude MPM Team",
     "created_at": "2025-08-15T00:00:00.000000Z",
-    "updated_at": "2025-10-08T00:00:00.000000Z",
+    "updated_at": "2025-10-26T00:00:00.000000Z",
     "color": "purple"
   },
   "capabilities": {
@@ -47,7 +47,7 @@
       ]
     }
   },
-  "instructions": "# Project Organizer Agent\n\n**Inherits from**: BASE_OPS_AGENT.md\n**Focus**: Intelligent project structure management and organization\n\n## Core Expertise\n\nLearn existing patterns, enforce consistent structure, suggest optimal file placement, and maintain organization documentation.\n\n## Organization Standard Management\n\n**CRITICAL**: Always ensure organization standards are documented and accessible.\n\n### Standard Documentation Protocol\n\n1. **Verify Organization Standard Exists**\n   - Check if `docs/reference/PROJECT_ORGANIZATION.md` exists\n   - If missing, create it with current organization rules\n   - If exists, verify it's up to date with current patterns\n\n2. **Update CLAUDE.md Linking**\n   - Verify CLAUDE.md links to PROJECT_ORGANIZATION.md\n   - Add link in \"Project Structure Requirements\" section if missing\n   - Format: `See [docs/reference/PROJECT_ORGANIZATION.md](docs/reference/PROJECT_ORGANIZATION.md)`\n\n3. **Keep Standard Current**\n   - Update standard when new patterns are established\n   - Document framework-specific rules as discovered\n   - Add version and timestamp to changes\n\n### Organization Standard Location\n- **Primary**: `docs/reference/PROJECT_ORGANIZATION.md`\n- **Reference from**: CLAUDE.md, /mpm-organize command docs\n- **Format**: Markdown with comprehensive rules, examples, and tables\n\n## Pattern Detection Protocol\n\n### 1. Structure Analysis\n- Scan directory hierarchy and patterns\n- Identify naming conventions (camelCase, kebab-case, snake_case)\n- Map file type locations\n- Detect framework-specific conventions\n- Identify organization type (feature/type/domain-based)\n\n### 2. Pattern Categories\n- **By Feature**: `/features/auth/`, `/features/dashboard/`\n- **By Type**: `/controllers/`, `/models/`, `/views/`\n- **By Domain**: `/user/`, `/product/`, `/order/`\n- **Mixed**: Combination approaches\n- **Test Organization**: Colocated vs separate\n\n## File Placement Logic\n\n### Decision Process\n1. Consult PROJECT_ORGANIZATION.md for official rules\n2. Analyze file purpose and type\n3. Apply learned project patterns\n4. Consider framework requirements\n5. Provide clear reasoning\n\n### Framework Handling\n- **Next.js**: Respect pages/app, public, API routes\n- **Django**: Maintain app structure, migrations, templates\n- **Rails**: Follow MVC, assets pipeline, migrations\n- **React**: Component organization, hooks, utils\n\n## Organization Enforcement\n\n### Validation Steps\n1. Check files against PROJECT_ORGANIZATION.md rules\n2. Flag convention violations\n3. Generate safe move operations\n4. Use `git mv` for version control\n5. Update import paths\n6. Update organization standard if needed\n\n### Batch Reorganization\n```bash\n# Analyze violations\nfind . -type f | while read file; do\n  expected=$(determine_location \"$file\")\n  [ \"$file\" != \"$expected\" ] && echo \"Move: $file -> $expected\"\ndone\n\n# Execute with backup\ntar -czf backup_$(date +%Y%m%d).tar.gz .\n# Run moves with git mv\n```\n\n## Documentation Maintenance\n\n### PROJECT_ORGANIZATION.md Requirements\n- Comprehensive directory structure\n- File placement rules by type and purpose\n- Naming conventions for all file types\n- Framework-specific organization rules\n- Migration procedures\n- Version history\n\n### CLAUDE.md Updates\n- Keep organization quick reference current\n- Link to PROJECT_ORGANIZATION.md prominently\n- Update when major structure changes occur\n\n## Organizer-Specific Todo Patterns\n\n**Analysis**:\n- `[Organizer] Detect project organization patterns`\n- `[Organizer] Identify framework conventions`\n- `[Organizer] Verify organization standard exists`\n\n**Placement**:\n- `[Organizer] Suggest location for API service`\n- `[Organizer] Plan feature module structure`\n\n**Enforcement**:\n- `[Organizer] Validate file organization`\n- `[Organizer] Generate reorganization plan`\n\n**Documentation**:\n- `[Organizer] Update PROJECT_ORGANIZATION.md`\n- `[Organizer] Update CLAUDE.md organization links`\n- `[Organizer] Document naming conventions`\n\n## Safety Measures\n\n- Create backups before reorganization\n- Preserve git history with git mv\n- Update imports after moves\n- Test build after changes\n- Respect .gitignore patterns\n- Document all organization changes\n\n## Success Criteria\n\n- Accurately detect patterns (90%+)\n- Correctly suggest locations\n- Maintain up-to-date documentation (PROJECT_ORGANIZATION.md)\n- Ensure CLAUDE.md links are current\n- Adapt to user corrections\n- Provide clear reasoning",
+  "instructions": "# Project Organizer Agent\n\n**Inherits from**: BASE_OPS_AGENT.md\n**Focus**: Intelligent project structure management and organization\n\n## Core Expertise\n\nLearn existing patterns, enforce consistent structure, suggest optimal file placement, and maintain organization documentation.\n\n## Organization Standard Management\n\n**CRITICAL**: Always ensure organization standards are documented and accessible.\n\n### Standard Documentation Protocol\n\n1. **Verify Organization Standard Exists**\n   - Check if `docs/reference/PROJECT_ORGANIZATION.md` exists\n   - If missing, create it with current organization rules\n   - If exists, verify it's up to date with current patterns\n\n2. **Update CLAUDE.md Linking**\n   - Verify CLAUDE.md links to PROJECT_ORGANIZATION.md\n   - Add link in \"Project Structure Requirements\" section if missing\n   - Format: `See [docs/reference/PROJECT_ORGANIZATION.md](docs/reference/PROJECT_ORGANIZATION.md)`\n\n3. **Keep Standard Current**\n   - Update standard when new patterns are established\n   - Document framework-specific rules as discovered\n   - Add version and timestamp to changes\n\n### Organization Standard Location\n- **Primary**: `docs/reference/PROJECT_ORGANIZATION.md`\n- **Reference from**: CLAUDE.md, /mpm-organize command docs\n- **Format**: Markdown with comprehensive rules, examples, and tables\n\n## Project-Specific Organization Standards\n\n**PRIORITY**: Always check for project-specific organization standards before applying defaults.\n\n### Standard Detection and Application Protocol\n\n1. **Check for PROJECT_ORGANIZATION.md** (in order of precedence):\n   - First: Project root (`./PROJECT_ORGANIZATION.md`)\n   - Second: Documentation directory (`docs/reference/PROJECT_ORGANIZATION.md`)\n   - Third: Docs root (`docs/PROJECT_ORGANIZATION.md`)\n\n2. **If PROJECT_ORGANIZATION.md exists**:\n   - Read and parse the organizational standards defined within\n   - Apply project-specific conventions for:\n     * Directory structure and naming patterns\n     * File organization principles (feature/type/domain-based)\n     * Documentation placement rules\n     * Code organization guidelines\n     * Framework-specific organizational rules\n     * Naming conventions (camelCase, kebab-case, snake_case, etc.)\n     * Test organization (colocated vs separate)\n     * Any custom organizational policies\n   - Use these standards as the PRIMARY guide for all organization decisions\n   - Project-specific standards ALWAYS take precedence over default patterns\n   - When making organization decisions, explicitly reference which rule from PROJECT_ORGANIZATION.md is being applied\n\n3. **If PROJECT_ORGANIZATION.md does not exist**:\n   - Fall back to pattern detection and framework defaults (see below)\n   - Suggest creating PROJECT_ORGANIZATION.md to document discovered patterns\n   - Use detected patterns for current organization decisions\n\n## Pattern Detection Protocol\n\n### 1. Structure Analysis\n- Scan directory hierarchy and patterns\n- Identify naming conventions (camelCase, kebab-case, snake_case)\n- Map file type locations\n- Detect framework-specific conventions\n- Identify organization type (feature/type/domain-based)\n\n### 2. Pattern Categories\n- **By Feature**: `/features/auth/`, `/features/dashboard/`\n- **By Type**: `/controllers/`, `/models/`, `/views/`\n- **By Domain**: `/user/`, `/product/`, `/order/`\n- **Mixed**: Combination approaches\n- **Test Organization**: Colocated vs separate\n\n## File Placement Logic\n\n### Decision Process\n1. Consult PROJECT_ORGANIZATION.md for official rules\n2. Analyze file purpose and type\n3. Apply learned project patterns\n4. Consider framework requirements\n5. Provide clear reasoning\n\n### Framework Handling\n- **Next.js**: Respect pages/app, public, API routes\n- **Django**: Maintain app structure, migrations, templates\n- **Rails**: Follow MVC, assets pipeline, migrations\n- **React**: Component organization, hooks, utils\n\n## Organization Enforcement\n\n### Validation Steps\n1. Check files against PROJECT_ORGANIZATION.md rules\n2. Flag convention violations\n3. Generate safe move operations\n4. Use `git mv` for version control\n5. Update import paths\n6. Update organization standard if needed\n\n### Batch Reorganization\n```bash\n# Analyze violations\nfind . -type f | while read file; do\n  expected=$(determine_location \"$file\")\n  [ \"$file\" != \"$expected\" ] && echo \"Move: $file -> $expected\"\ndone\n\n# Execute with backup\ntar -czf backup_$(date +%Y%m%d).tar.gz .\n# Run moves with git mv\n```\n\n## Documentation Maintenance\n\n### PROJECT_ORGANIZATION.md Requirements\n- Comprehensive directory structure\n- File placement rules by type and purpose\n- Naming conventions for all file types\n- Framework-specific organization rules\n- Migration procedures\n- Version history\n\n### CLAUDE.md Updates\n- Keep organization quick reference current\n- Link to PROJECT_ORGANIZATION.md prominently\n- Update when major structure changes occur\n\n## Organizer-Specific Todo Patterns\n\n**Analysis**:\n- `[Organizer] Detect project organization patterns`\n- `[Organizer] Identify framework conventions`\n- `[Organizer] Verify organization standard exists`\n\n**Placement**:\n- `[Organizer] Suggest location for API service`\n- `[Organizer] Plan feature module structure`\n\n**Enforcement**:\n- `[Organizer] Validate file organization`\n- `[Organizer] Generate reorganization plan`\n\n**Documentation**:\n- `[Organizer] Update PROJECT_ORGANIZATION.md`\n- `[Organizer] Update CLAUDE.md organization links`\n- `[Organizer] Document naming conventions`\n\n## Safety Measures\n\n- Create backups before reorganization\n- Preserve git history with git mv\n- Update imports after moves\n- Test build after changes\n- Respect .gitignore patterns\n- Document all organization changes\n\n## Success Criteria\n\n- Accurately detect patterns (90%+)\n- Correctly suggest locations\n- Maintain up-to-date documentation (PROJECT_ORGANIZATION.md)\n- Ensure CLAUDE.md links are current\n- Adapt to user corrections\n- Provide clear reasoning",
   "knowledge": {
     "domain_expertise": [
       "Project structure patterns",
@@ -130,4 +130,4 @@
       "success_rate": 0.9
     }
   }
-}
+}

claude_mpm/cli/commands/auto_configure.py

@@ -26,12 +26,10 @@ try:
 except ImportError:
     RICH_AVAILABLE = False
 
+from ...core.enums import OperationResult
 from ...services.agents.auto_config_manager import AutoConfigManagerService
 from ...services.agents.observers import NullObserver
-from ...services.core.models.agent_config import (
-    ConfigurationResult,
-    ConfigurationStatus,
-)
+from ...services.core.models.agent_config import ConfigurationResult
 from ..shared import BaseCommand, CommandResult
 
 
@@ -419,7 +417,7 @@ class AutoConfigureCommand(BaseCommand):
             return self._display_result_plain(result)
 
         # Display summary
-        if result.status == ConfigurationStatus.SUCCESS:
+        if result.status == OperationResult.SUCCESS:
             panel = Panel(
                 f"✅ Auto-configuration completed successfully!\n\n"
                 f"Deployed {len(result.deployed_agents)} agent(s)",
@@ -436,7 +434,7 @@ class AutoConfigureCommand(BaseCommand):
 
             return CommandResult.success_result()
 
-        if result.status == ConfigurationStatus.PARTIAL_SUCCESS:
+        if result.status == OperationResult.WARNING:
             panel = Panel(
                 f"⚠️  Auto-configuration partially completed\n\n"
                 f"Deployed: {len(result.deployed_agents)}\n"
@@ -465,7 +463,7 @@ class AutoConfigureCommand(BaseCommand):
 
     def _display_result_plain(self, result: ConfigurationResult) -> CommandResult:
         """Display result in plain text (fallback)."""
-        if result.status == ConfigurationStatus.SUCCESS:
+        if result.status == OperationResult.SUCCESS:
             print("\n✅ Auto-configuration completed successfully!")
             print(f"Deployed {len(result.deployed_agents)} agent(s)")
 
@@ -476,7 +474,7 @@ class AutoConfigureCommand(BaseCommand):
 
             return CommandResult.success_result()
 
-        if result.status == ConfigurationStatus.PARTIAL_SUCCESS:
+        if result.status == OperationResult.WARNING:
             print("\n⚠️  Auto-configuration partially completed")
             print(f"Deployed: {len(result.deployed_agents)}")
             print(f"Failed: {len(result.failed_agents)}")
@@ -565,7 +563,7 @@ class AutoConfigureCommand(BaseCommand):
 
         print(json.dumps(output, indent=2))
 
-        if result.status == ConfigurationStatus.SUCCESS:
+        if result.status == OperationResult.SUCCESS:
             return CommandResult.success_result(data=output)
         return CommandResult.error_result(
             "Configuration failed or partial", exit_code=1, data=output

claude_mpm/cli/commands/local_deploy.py

@@ -23,8 +23,9 @@ from rich.panel import Panel
 from rich.table import Table
 from rich.text import Text
 
+from claude_mpm.core.enums import ServiceState
+
 from ...services.local_ops import (
-    ProcessStatus,
     StartConfig,
     UnifiedLocalOpsManager,
 )
@@ -298,7 +299,7 @@ class LocalDeployCommand(BaseCommand):
         try:
             status_filter_str = getattr(args, "status", None)
             status_filter = (
-                ProcessStatus(status_filter_str) if status_filter_str else None
+                ServiceState(status_filter_str) if status_filter_str else None
             )
 
             deployments = self.manager.list_deployments(status_filter=status_filter)

claude_mpm/cli/commands/mpm_init.py

@@ -157,7 +157,7 @@ class MPMInitCommand:
                 pre_check_result = self._run_pre_initialization_checks(
                     organize_files, skip_archive, has_existing
                 )
-                if pre_check_result.get("status") == "error":
+                if pre_check_result.get("status") == OperationResult.ERROR:
                     return pre_check_result
 
             # Build the delegation prompt
@@ -200,7 +200,7 @@ class MPMInitCommand:
                 progress.update(task, description=complete_desc)
 
             # Post-processing for update mode
-            if update_mode and result.get("status") == "success":
+            if update_mode and result.get("status") == OperationResult.SUCCESS:
                 self._handle_update_post_processing()
 
             return result
@@ -1685,7 +1685,7 @@ Keep it concise (<1000 words) but actionable.
 
     def _display_results(self, result: Dict, verbose: bool):
         """Display initialization results."""
-        if result["status"] == "success":
+        if result["status"] == OperationResult.SUCCESS:
             console.print("\n[green]✅ Project Initialization Complete![/green]\n")
 
             # Display files created
@@ -1885,7 +1885,7 @@ def mpm_init(
         )
 
         # Exit with appropriate code
-        if result["status"] == "success":
+        if result["status"] == OperationResult.SUCCESS:
             sys.exit(0)
         else:
             sys.exit(1)

claude_mpm/cli/commands/mpm_init_handler.py

@@ -8,6 +8,8 @@ from pathlib import Path
 
 from rich.console import Console
 
+from claude_mpm.core.enums import OperationResult
+
 console = Console()
 
 
@@ -51,7 +53,10 @@ def manage_mpm_init(args):
             )
 
             # Return appropriate exit code
-            if result.get("status") in ("success", "context_ready"):
+            if result.get("status") in (
+                OperationResult.SUCCESS,
+                OperationResult.CONTEXT_READY,
+            ):
                 return 0
             return 1
 
@@ -102,9 +107,9 @@ def manage_mpm_init(args):
         result = command.initialize_project(**init_params)
 
         # Return appropriate exit code
-        if result.get("status") == "success":
+        if result.get("status") == OperationResult.SUCCESS:
             return 0
-        if result.get("status") == "cancelled":
+        if result.get("status") == OperationResult.CANCELLED:
             return 130  # User cancelled
         return 1  # Error
 

claude_mpm/core/base_service.py

@@ -31,6 +31,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from .config import Config
+from .enums import HealthStatus
 from .mixins import LoggerMixin
 
 
@@ -38,7 +39,7 @@ from .mixins import LoggerMixin
 class ServiceHealth:
     """Service health status information."""
 
-    status: str  # healthy, degraded, unhealthy, unknown
+    status: HealthStatus  # Type-safe health status using enum
     message: str
     timestamp: str
     metrics: Dict[str, Any] = field(default_factory=dict)
@@ -142,7 +143,7 @@ class BaseService(LoggerMixin, ABC):
 
         # Health and metrics
         self._health = ServiceHealth(
-            status="unknown",
+            status=HealthStatus.UNKNOWN,
             message="Service not started",
             timestamp=datetime.now(timezone.utc).isoformat(),
         )
@@ -235,7 +236,7 @@ class BaseService(LoggerMixin, ABC):
         except Exception as e:
             self.logger.error(f"Failed to start service {self.name}: {e}")
             self._health = ServiceHealth(
-                status="unhealthy",
+                status=HealthStatus.UNHEALTHY,
                 message=f"Startup failed: {e!s}",
                 timestamp=datetime.now(timezone.utc).isoformat(),
                 checks={"startup": False},
@@ -272,7 +273,7 @@ class BaseService(LoggerMixin, ABC):
 
         # Update health status
         self._health = ServiceHealth(
-            status="healthy",
+            status=HealthStatus.HEALTHY,
             message="Service started successfully",
             timestamp=datetime.now(timezone.utc).isoformat(),
             checks={"startup": True},
@@ -336,7 +337,7 @@ class BaseService(LoggerMixin, ABC):
 
         # Update health status
         self._health = ServiceHealth(
-            status="unknown",
+            status=HealthStatus.UNKNOWN,
             message="Service stopped",
             timestamp=datetime.now(timezone.utc).isoformat(),
             checks={"running": False},
@@ -372,16 +373,16 @@ class BaseService(LoggerMixin, ABC):
 
             # Determine overall status
             if not checks["running"]:
-                status = "unhealthy"
+                status = HealthStatus.UNHEALTHY
                 message = "Service is not running"
             elif all(checks.values()):
-                status = "healthy"
+                status = HealthStatus.HEALTHY
                 message = "All health checks passed"
             elif any(checks.values()):
-                status = "degraded"
+                status = HealthStatus.DEGRADED
                 message = "Some health checks failed"
             else:
-                status = "unhealthy"
+                status = HealthStatus.UNHEALTHY
                 message = "Multiple health checks failed"
 
             # Update health status
@@ -402,7 +403,7 @@ class BaseService(LoggerMixin, ABC):
         except Exception as e:
             self.logger.error(f"Health check failed for {self.name}: {e}")
             self._health = ServiceHealth(
-                status="unhealthy",
+                status=HealthStatus.UNHEALTHY,
                 message=f"Health check error: {e!s}",
                 timestamp=datetime.now(timezone.utc).isoformat(),
                 checks={"health_check_error": True},
@@ -593,7 +594,7 @@ class BaseService(LoggerMixin, ABC):
                     )
                 else:
                     return ServiceHealth(
-                        status="degraded",
+                        status=HealthStatus.DEGRADED,
                         message="Service circuit breaker is open",
                         timestamp=datetime.now(timezone.utc).isoformat(),
                         checks={"circuit_breaker": False},
@@ -604,7 +605,7 @@ class BaseService(LoggerMixin, ABC):
             health = await self.health_check()
 
             # Update circuit breaker
-            if health.status in ["healthy", "degraded"]:
+            if health.status in (HealthStatus.HEALTHY, HealthStatus.DEGRADED):
                 self._record_circuit_success()
             else:
                 self._record_circuit_failure()

claude_mpm/core/enums.py

@@ -70,6 +70,12 @@ class OperationResult(StrEnum):
     PARTIAL = "partial"
     """Operation completed partially."""
 
+    WARNING = "warning"
+    """Operation completed with warnings (partial success with issues)."""
+
+    ROLLBACK = "rollback"
+    """Operation rolled back due to failure or cancellation."""
+
     UNKNOWN = "unknown"
     """Operation result is unknown or indeterminate."""
 
@@ -118,12 +124,26 @@ 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.
+    Used in: Hook services, MCP servers, monitoring, health checks, process management.
 
     Migration Priority: HIGH (Week 1)
     Coverage: ~7% of all magic strings
+
+    Notes:
+        - Consolidated with ProcessStatus enum (Phase 3A Batch 24)
+        - Process states are semantically equivalent to service states
+        - CRASHED processes map to ERROR state
     """
 
+    UNINITIALIZED = "uninitialized"
+    """Service has not been initialized yet."""
+
+    INITIALIZING = "initializing"
+    """Service is in the process of initializing."""
+
+    INITIALIZED = "initialized"
+    """Service has been initialized but not started."""
+
     STOPPED = "stopped"
     """Service is completely stopped."""
 
@@ -151,6 +171,24 @@ class ServiceState(StrEnum):
     IDLE = "idle"
     """Service is running but not actively processing."""
 
+    def is_active(self) -> bool:
+        """
+        Check if state represents an active service/process.
+
+        Returns:
+            True if state is STARTING or RUNNING
+        """
+        return self in (ServiceState.STARTING, ServiceState.RUNNING)
+
+    def is_terminal(self) -> bool:
+        """
+        Check if state represents a terminal/stopped state.
+
+        Returns:
+            True if state is STOPPED or ERROR
+        """
+        return self in (ServiceState.STOPPED, ServiceState.ERROR)
+
 
 class ValidationSeverity(StrEnum):
     """
@@ -179,6 +217,41 @@ class ValidationSeverity(StrEnum):
     """Debug-level information for troubleshooting."""
 
 
+class HealthStatus(StrEnum):
+    """
+    Health check status codes for services and components.
+
+    Replaces health check status strings throughout monitoring and diagnostics.
+    Used in: Health checks, monitoring, service diagnostics, uptime tracking.
+
+    Migration Priority: MEDIUM (Week 3)
+    Coverage: ~2% of all magic strings
+
+    Notes:
+        - Added in Phase 3C for comprehensive service health monitoring
+        - Distinct from ServiceState (operational) and OperationResult (transactional)
+        - Maps to standard health check patterns (healthy/unhealthy/degraded)
+    """
+
+    HEALTHY = "healthy"
+    """Component is functioning normally."""
+
+    UNHEALTHY = "unhealthy"
+    """Component is not functioning correctly."""
+
+    DEGRADED = "degraded"
+    """Component is functioning with reduced capability."""
+
+    UNKNOWN = "unknown"
+    """Health status cannot be determined."""
+
+    CHECKING = "checking"
+    """Health check is currently in progress."""
+
+    TIMEOUT = "timeout"
+    """Health check exceeded time limit."""
+
+
 class ModelTier(StrEnum):
     """
     Claude model tier classifications and identifiers.
@@ -272,48 +345,87 @@ class AgentCategory(StrEnum):
 
     Migration Priority: MEDIUM (Week 3)
     Coverage: ~3% of all magic strings
+
+    Notes:
+        - Expanded in Phase 3C to include all template categories
+        - Maps to actual usage in agent JSON templates
+        - Supports both legacy and new category schemes
     """
 
+    # Core Engineering Categories
+    ENGINEERING = "engineering"
+    """Software engineering and implementation agents."""
+
+    # Research and Analysis
     RESEARCH = "research"
     """Research and analysis agents."""
 
-    ENGINEERING = "engineering"
-    """Software engineering and implementation agents."""
+    ANALYSIS = "analysis"
+    """Code analysis and architectural review agents."""
+
+    # Quality and Testing
+    QUALITY = "quality"
+    """Quality assurance and testing agents (replaces QA)."""
 
     QA = "qa"
-    """Quality assurance and testing agents."""
+    """Legacy quality assurance category (use QUALITY for new agents)."""
 
     SECURITY = "security"
     """Security analysis and vulnerability assessment agents."""
 
+    # Operations and Infrastructure
+    OPERATIONS = "operations"
+    """DevOps and infrastructure management agents."""
+
+    INFRASTRUCTURE = "infrastructure"
+    """Infrastructure provisioning and cloud management agents."""
+
+    # Documentation and Content
     DOCUMENTATION = "documentation"
     """Documentation and technical writing agents."""
 
-    OPERATIONS = "operations"
-    """DevOps and infrastructure management agents."""
+    CONTENT = "content"
+    """Content creation, optimization, and management agents."""
 
+    # Data and Analytics
     DATA = "data"
     """Data engineering and analytics agents."""
 
+    # Specialized Functions
+    OPTIMIZATION = "optimization"
+    """Performance and resource optimization agents."""
+
+    SPECIALIZED = "specialized"
+    """Specialized single-purpose agents."""
+
+    SYSTEM = "system"
+    """System-level framework agents."""
+
+    # Management and Coordination
+    PROJECT_MANAGEMENT = "project-management"
+    """Project management and coordination agents."""
+
+    PRODUCT = "product"
+    """Product ownership and strategy agents."""
+
+    # Legacy and General
     VERSION_CONTROL = "version_control"
     """Version control and release management agents."""
 
+    DESIGN = "design"
+    """UI/UX design and frontend 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",
+    "HealthStatus",
     "ModelTier",
     "OperationResult",
     "OutputFormat",

claude_mpm/services/agents/auto_config_manager.py

@@ -23,15 +23,14 @@ from typing import Any, Dict, List, Optional
 import yaml
 
 from ...core.base_service import BaseService
+from ...core.enums import OperationResult, ValidationSeverity
 from ..core.interfaces.agent import IAgentRegistry, IAutoConfigManager
 from ..core.models.agent_config import (
     AgentRecommendation,
     ConfigurationPreview,
     ConfigurationResult,
-    ConfigurationStatus,
     ValidationIssue,
     ValidationResult,
-    ValidationSeverity,
 )
 from ..core.models.toolchain import ToolchainAnalysis
 from .observers import IDeploymentObserver, NullObserver
@@ -216,7 +215,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
 
             if not recommendations:
                 return ConfigurationResult(
-                    status=ConfigurationStatus.SUCCESS,
+                    status=OperationResult.SUCCESS,
                     message="No agents recommended for this project configuration",
                     recommendations=recommendations,
                     metadata={
@@ -241,7 +240,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
                     f"Validation failed with {validation_result.error_count} errors"
                 )
                 return ConfigurationResult(
-                    status=ConfigurationStatus.VALIDATION_ERROR,
+                    status=OperationResult.ERROR,
                     validation_errors=[
                         issue.message for issue in validation_result.errors
                     ],
@@ -260,7 +259,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
             if dry_run:
                 self.logger.info("Dry-run mode: skipping deployment")
                 return ConfigurationResult(
-                    status=ConfigurationStatus.SUCCESS,
+                    status=OperationResult.SUCCESS,
                     validation_warnings=[
                         issue.message for issue in validation_result.warnings
                     ],
@@ -280,7 +279,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
                 if not confirmed:
                     self.logger.info("User cancelled auto-configuration")
                     return ConfigurationResult(
-                        status=ConfigurationStatus.USER_CANCELLED,
+                        status=OperationResult.CANCELLED,
                         recommendations=recommendations,
                         message="Auto-configuration cancelled by user",
                         metadata={
@@ -318,9 +317,9 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
 
                 return ConfigurationResult(
                     status=(
-                        ConfigurationStatus.PARTIAL_SUCCESS
+                        OperationResult.WARNING
                         if deployed_agents
-                        else ConfigurationStatus.FAILURE
+                        else OperationResult.FAILED
                     ),
                     deployed_agents=deployed_agents,
                     failed_agents=failed_agents,
@@ -347,7 +346,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
             )
 
             return ConfigurationResult(
-                status=ConfigurationStatus.SUCCESS,
+                status=OperationResult.SUCCESS,
                 deployed_agents=deployed_agents,
                 validation_warnings=[
                     issue.message for issue in validation_result.warnings
@@ -365,7 +364,7 @@ class AutoConfigManagerService(BaseService, IAutoConfigManager):
             observer.on_error("auto-configuration", str(e), e)
 
             return ConfigurationResult(
-                status=ConfigurationStatus.FAILURE,
+                status=OperationResult.FAILED,
                 message=f"Auto-configuration failed: {e}",
                 metadata={
                     "duration_ms": (time.time() - start_time) * 1000,

claude_mpm/services/agents/deployment/pipeline/steps/agent_processing_step.py

@@ -3,13 +3,14 @@
 import time
 from pathlib import Path
 
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.services.agents.deployment.processors import (
     AgentDeploymentContext,
     AgentDeploymentResult,
     AgentProcessor,
 )
 
-from .base_step import BaseDeploymentStep, StepResult, StepStatus
+from .base_step import BaseDeploymentStep, StepResult
 
 
 class AgentProcessingStep(BaseDeploymentStep):
@@ -37,7 +38,7 @@ class AgentProcessingStep(BaseDeploymentStep):
             if not context.template_files:
                 self.logger.warning("No template files to process")
                 return StepResult(
-                    status=StepStatus.SKIPPED,
+                    status=OperationResult.SKIPPED,
                     message="No template files found to process",
                     execution_time=time.time() - start_time,
                 )
@@ -103,13 +104,13 @@ class AgentProcessingStep(BaseDeploymentStep):
 
             # Determine step status
             if failed_count == 0:
-                status = StepStatus.SUCCESS
+                status = OperationResult.SUCCESS
                 message = f"Successfully processed {processed_count} agents in {execution_time:.3f}s"
             elif processed_count > 0:
-                status = StepStatus.WARNING
+                status = OperationResult.WARNING
                 message = f"Processed {processed_count} agents with {failed_count} failures in {execution_time:.3f}s"
             else:
-                status = StepStatus.FAILURE
+                status = OperationResult.FAILED
                 message = f"Failed to process any agents ({failed_count} failures) in {execution_time:.3f}s"
 
             self.logger.info(message)
@@ -127,7 +128,7 @@ class AgentProcessingStep(BaseDeploymentStep):
             context.add_error(error_msg)
 
             return StepResult(
-                status=StepStatus.FAILURE,
+                status=OperationResult.FAILED,
                 message=error_msg,
                 error=e,
                 execution_time=execution_time,