--- allowed-tools: all description: Critical microservice architecture implementation with systematic service decomposition and minimal footprint design for distributed system optimization --- # 🚨🚨🚨 CRITICAL REQUIREMENT: MICROSERVICE ARCHITECTURE IMPLEMENTATION! 🚨🚨🚨 **THIS IS NOT A SIMPLE CODE REFACTORING TASK - THIS IS A CRITICAL MICROSERVICE DECOMPOSITION AND DISTRIBUTED SYSTEM ARCHITECTURE TASK!** When you run `\/service-split`, you are REQUIRED to: 1. **DECOMPOSE** monolithic file structures into focused, independent service modules with clear boundaries 2. **IMPLEMENT** minimal core system with plugin architecture and dynamic service loading capabilities 3. **ESTABLISH** service registry and discovery mechanisms with fault tolerance and health monitoring 4. **OPTIMIZE** resource isolation and communication patterns between distributed service components 5. **USE MULTIPLE AGENTS** for comprehensive microservice implementation: - Spawn one agent for systematic service boundary identification and decomposition planning - Spawn another for minimal core system implementation and plugin architecture design - Spawn more agents for service registry development and inter-service communication optimization - Say: "I'll spawn multiple agents to implement critical microservice architecture with distributed system coordination" ## 🎯 USE MULTIPLE AGENTS FOR MICROSERVICE IMPLEMENTATION **MANDATORY AGENT SPAWNING FOR MICROSERVICE ARCHITECTURE:** ``` "I'll spawn multiple microservice implementation agents to handle distributed system architecture: - Service Decomposition Agent: Systematically identify service boundaries and decompose monolithic structures - Core Architecture Agent: Implement minimal core system with plugin architecture and dynamic loading - Service Registry Agent: Develop service discovery and registration with health monitoring capabilities - Communication Optimization Agent: Design inter-service communication patterns and fault tolerance - Resource Isolation Agent: Implement resource management and service isolation mechanisms" ``` ## 🚨 FORBIDDEN BEHAVIORS **NEVER:** - ❌ "Simple code splitting is enough" → NO! Systematic service decomposition with clear boundaries required! - ❌ "Skip service registry implementation" → NO! Service discovery and health monitoring mandatory! - ❌ "Manual service coordination" → NO! Automated service orchestration and fault tolerance required! - ❌ "Ignore resource isolation" → NO! Proper service isolation and resource management critical! - ❌ "No inter-service communication design" → NO! Robust communication patterns required! - ❌ "Accept service coupling" → NO! Complete service independence and loose coupling mandatory! **MANDATORY MICROSERVICE IMPLEMENTATION WORKFLOW:** ``` 1. Service boundary analysis → Identify independent service domains and decomposition opportunities 2. IMMEDIATELY spawn agents for parallel microservice architecture implementation 3. Core system implementation → Build minimal core with plugin architecture and service loading 4. Service registry deployment → Implement discovery, registration, and health monitoring systems 5. Communication pattern optimization → Design fault-tolerant inter-service communication 6. VERIFY complete service independence and system fault tolerance through comprehensive testing ``` **YOU ARE NOT DONE UNTIL:** - ✅ Complete service decomposition with clear boundaries and independent deployment capability - ✅ Multi-agent microservice implementation deployed and coordinating effectively - ✅ Minimal core system implemented with plugin architecture and dynamic service loading - ✅ Service registry and discovery mechanisms deployed with health monitoring capabilities - ✅ Inter-service communication patterns optimized with fault tolerance and resilience - ✅ Complete service independence validated through isolation and deployment testing --- 🛑 **MANDATORY MICROSERVICE ARCHITECTURE VALIDATION CHECK** 🛑 1. Re-read ~\/.claude\/CLAUDE.md RIGHT NOW 2. Validate current monolithic structure and identify critical service decomposition requirements 3. Confirm distributed system architecture principles and microservice implementation criteria Execute comprehensive microservice implementation with ZERO tolerance for service coupling or monolithic patterns. **FORBIDDEN MICROSERVICE PATTERNS:** - "Distributed monolith is acceptable" → NO, true service independence required - "Shared databases between services" → NO, complete data isolation mandatory - "Synchronous communication everywhere" → NO, asynchronous patterns with fault tolerance required - "No service health monitoring" → NO, comprehensive observability required - "Manual service deployment" → NO, automated orchestration and deployment required You are implementing microservice architecture for: $ARGUMENTS Let me execute critical microservice decomposition with distributed system architecture implementation. 🚨 **REMEMBER: Effective microservices require complete service independence, not simple code splitting!** 🚨 **Comprehensive Microservice Architecture Implementation Protocol:** ## Step 0: Service Boundary Analysis and Decomposition Planning **Analyze Monolithic Structure for Service Decomposition:** ```bash # Critical service boundary analysis analyze_service_boundaries() { echo "=== Microservice Decomposition Analysis ===" # Identify current monolithic components local monolithic_analysis=".service-split\/monolithic-analysis.json" echo "Analyzing monolithic structure for service boundaries..." # Functional domain analysis analyze_functional_domains # Data flow and dependency analysis analyze_data_dependencies # Communication pattern analysis analyze_communication_patterns # Resource utilization analysis analyze_resource_patterns echo "✅ Service boundary analysis complete" } analyze_functional_domains() { echo "🔍 Analyzing functional domain boundaries..." # Identify core domain areas identify_core_domains # Map subdomain relationships map_subdomain_relationships # Analyze domain coupling patterns analyze_domain_coupling # Generate service decomposition recommendations generate_decomposition_plan echo "✅ Functional domain analysis complete" } ``` **Service Architecture Design Framework:** ```yaml microservice_architecture: service_identification: domain_driven_design: true bounded_contexts: "strict_enforcement" data_ownership: "service_exclusive" service_catalog: core_services: - name: "claude-core" responsibility: "Core orchestration and plugin management" data_ownership: ["system_config", "plugin_registry"] dependencies: [] - name: "template-service" responsibility: "Template management and generation" data_ownership: ["templates", "template_metadata"] dependencies: ["claude-core"] - name: "command-service" responsibility: "Command execution and workflow management" data_ownership: ["command_definitions", "execution_logs"] dependencies: ["claude-core", "template-service"] - name: "git-service" responsibility: "Git operations and repository management" data_ownership: ["git_state", "repository_metadata"] dependencies: ["claude-core"] - name: "documentation-service" responsibility: "Documentation generation and management" data_ownership: ["doc_content", "doc_structure"] dependencies: ["claude-core", "template-service"] communication_patterns: inter_service: "asynchronous_messaging" service_discovery: "registry_based" fault_tolerance: "circuit_breaker_pattern" data_consistency: "eventual_consistency" ``` ## Step 1: Critical Microservice Implementation Deployment **Deploy Microservice Implementation Agents:** ```bash deploy_microservice_agents() { local project_path=$1 echo "🚨 Deploying critical microservice implementation agents for: $project_path" # Service Decomposition Agent register_agent "service-decomposer" "service_decomposition" "$project_path" spawn_service_decomposition_agent "$project_path" & # Core Architecture Agent register_agent "core-architect" "core_architecture" "$project_path" spawn_core_architecture_agent "$project_path" & # Service Registry Agent register_agent "service-registry" "service_registry" "$project_path" spawn_service_registry_agent "$project_path" & # Communication Optimization Agent register_agent "comm-optimizer" "communication_optimization" "$project_path" spawn_communication_optimization_agent "$project_path" & # Resource Isolation Agent register_agent "resource-isolator" "resource_isolation" "$project_path" spawn_resource_isolation_agent "$project_path" & echo "✅ All critical microservice implementation agents deployed" } ``` ## Step 2: Service Decomposition and Boundary Implementation **Service Decomposition Agent:** ```bash spawn_service_decomposition_agent() { local project_path=$1 echo "⚡ Service Decomposition Agent: Implementing systematic service separation" # Execute service boundary extraction extract_service_boundaries "$project_path" # Implement service isolation implement_service_isolation "$project_path" # Create independent service modules create_service_modules "$project_path" # Validate service independence validate_service_independence "$project_path" echo "✅ Service Decomposition Agent: Independent services implemented" } extract_service_boundaries() { local project_path=$1 echo "🔪 Extracting service boundaries with surgical precision..." # Create service-specific directories mkdir -p "$project_path\/services\/claude-core" mkdir -p "$project_path\/services\/template-service" mkdir -p "$project_path\/services\/command-service" mkdir -p "$project_path\/services\/git-service" mkdir -p "$project_path\/services\/documentation-service" # Extract core service functionality extract_core_service "$project_path" # Extract template service functionality extract_template_service "$project_path" # Extract command service functionality extract_command_service "$project_path" # Extract git service functionality extract_git_service "$project_path" # Extract documentation service functionality extract_documentation_service "$project_path" echo "✅ Service boundary extraction complete" } extract_core_service() { local project_path=$1 local core_service="$project_path\/services\/claude-core" echo "🏗️ Extracting claude-core service..." # Create core service structure cat > "$core_service\/service.yaml" << EOF service: name: "claude-core" version: "1.0.0" type: "core_orchestrator" responsibilities: - "System initialization and configuration" - "Plugin lifecycle management" - "Service discovery and registration" - "Inter-service communication coordination" - "Health monitoring and fault recovery" api: internal: - "\/core\/plugins\/register" - "\/core\/plugins\/discover" - "\/core\/health\/check" - "\/core\/config\/get" - "\/core\/config\/set" dependencies: [] data_ownership: - "system_configuration" - "plugin_registry" - "service_registry" - "health_metrics" deployment: type: "singleton" resources: memory: "64MB" cpu: "0.1 cores" health_check: "\/health" restart_policy: "always" EOF # Implement core service functionality implement_core_service_logic "$core_service" echo "✅ claude-core service extracted" } ``` ## Step 3: Minimal Core System with Plugin Architecture **Core Architecture Agent:** ```bash spawn_core_architecture_agent() { local project_path=$1 echo "🏗️ Core Architecture Agent: Implementing minimal core with plugin architecture" # Design plugin architecture framework design_plugin_architecture "$project_path" # Implement dynamic service loading implement_dynamic_loading "$project_path" # Create service lifecycle management implement_lifecycle_management "$project_path" # Optimize core system footprint optimize_core_footprint "$project_path" echo "✅ Core Architecture Agent: Minimal core system with plugin architecture complete" } design_plugin_architecture() { local project_path=$1 echo "🧩 Designing plugin architecture framework..." # Plugin interface specification cat > "$project_path\/services\/claude-core\/plugin-interface.py" << 'EOF' #!\/usr\/bin\/env python3 # Plugin interface specification for claude-core microservice architecture from abc import ABC, abstractmethod from typing import Dict, List, Any import asyncio class ServicePlugin(ABC): """Base interface for all claude service plugins""" @abstractmethod def get_service_info(self) -> Dict[str, Any]: """Return service metadata and capabilities""" pass @abstractmethod async def initialize(self, core_api: 'CoreAPI') -> bool: """Initialize service with core system integration""" pass @abstractmethod async def start(self) -> bool: """Start service operations""" pass @abstractmethod async def stop(self) -> bool: """Stop service operations gracefully""" pass @abstractmethod async def health_check(self) -> Dict[str, Any]: """Return current service health status""" pass @abstractmethod def get_api_endpoints(self) -> List[Dict[str, str]]: """Return available API endpoints""" pass class CoreAPI: """Core system API available to all plugins""" def __init__(self): self.service_registry = {} self.config_manager = None self.health_monitor = None async def register_service(self, service_name: str, plugin: ServicePlugin): """Register a service plugin with the core system""" self.service_registry[service_name] = plugin await plugin.initialize(self) async def discover_service(self, service_name: str) -> ServicePlugin: """Discover and return a registered service""" return self.service_registry.get(service_name) async def get_config(self, config_key: str) -> Any: """Get configuration value from core system""" return self.config_manager.get(config_key) async def set_config(self, config_key: str, value: Any): """Set configuration value in core system""" await self.config_manager.set(config_key, value) async def health_check_all(self) -> Dict[str, Dict]: """Check health of all registered services""" health_status = {} for service_name, plugin in self.service_registry.items(): health_status[service_name] = await plugin.health_check() return health_status EOF echo "✅ Plugin architecture framework designed" } implement_dynamic_loading() { local project_path=$1 echo "🔄 Implementing dynamic service loading..." # Dynamic service loader cat > "$project_path\/services\/claude-core\/service-loader.py" << 'EOF' #!\/usr\/bin\/env python3 # Dynamic service loading system for microservice architecture import importlib import os import sys from pathlib import Path from typing import Dict, List import asyncio import json from plugin_interface import ServicePlugin, CoreAPI class ServiceLoader: """Dynamic service loading and lifecycle management""" def __init__(self, services_directory: str): self.services_dir = Path(services_directory) self.core_api = CoreAPI() self.loaded_services = {} async def discover_services(self) -> List[str]: """Discover available services in services directory""" services = [] for service_dir in self.services_dir.iterdir(): if service_dir.is_dir() and (service_dir \/ 'service.yaml').exists(): services.append(service_dir.name) return services async def load_service(self, service_name: str) -> bool: """Dynamically load a service plugin""" service_path = self.services_dir \/ service_name # Add service path to Python path sys.path.insert(0, str(service_path)) try: # Import service module service_module = importlib.import_module(f'{service_name}.main') # Instantiate service plugin plugin_class = getattr(service_module, 'ServicePlugin') plugin = plugin_class() # Register with core API await self.core_api.register_service(service_name, plugin) self.loaded_services[service_name] = plugin # Start service await plugin.start() print(f"✅ Service loaded and started: {service_name}") return True except Exception as e: print(f"❌ Failed to load service {service_name}: {e}") return False finally: sys.path.remove(str(service_path)) async def unload_service(self, service_name: str) -> bool: """Gracefully unload a service plugin""" if service_name in self.loaded_services: plugin = self.loaded_services[service_name] await plugin.stop() del self.loaded_services[service_name] print(f"✅ Service unloaded: {service_name}") return True return False async def reload_service(self, service_name: str) -> bool: """Reload a service plugin""" await self.unload_service(service_name) return await self.load_service(service_name) async def start_all_services(self): """Discover and start all available services""" services = await self.discover_services() for service_name in services: await self.load_service(service_name) async def health_check_all(self) -> Dict[str, Dict]: """Check health of all loaded services""" return await self.core_api.health_check_all() EOF echo "✅ Dynamic service loading implemented" } ``` ## Step 4: Service Registry and Discovery Implementation **Service Registry Agent:** ```bash spawn_service_registry_agent() { local project_path=$1 echo "📋 Service Registry Agent: Implementing service discovery and health monitoring" # Implement service registry system implement_service_registry "$project_path" # Create service discovery mechanisms implement_service_discovery "$project_path" # Deploy health monitoring system implement_health_monitoring "$project_path" # Optimize registry performance optimize_registry_performance "$project_path" echo "✅ Service Registry Agent: Service discovery and monitoring complete" } implement_service_registry() { local project_path=$1 echo "📊 Implementing comprehensive service registry..." # Service registry implementation cat > "$project_path\/services\/claude-core\/service-registry.py" << 'EOF' #!\/usr\/bin\/env python3 # Service registry with discovery and health monitoring import asyncio import json import time from typing import Dict, List, Optional from dataclasses import dataclass, asdict from pathlib import Path @dataclass class ServiceMetadata: name: str version: str status: str # 'starting', 'healthy', 'unhealthy', 'stopped' endpoints: List[str] dependencies: List[str] health_check_url: str last_health_check: float registration_time: float class ServiceRegistry: """Centralized service registry with health monitoring""" def __init__(self, registry_file: str = ".service-registry.json"): self.registry_file = Path(registry_file) self.services: Dict[str, ServiceMetadata] = {} self.health_check_interval = 30 # seconds self.health_check_timeout = 5 # seconds self.load_registry() def load_registry(self): """Load service registry from persistent storage""" if self.registry_file.exists(): try: with open(self.registry_file, 'r') as f: data = json.load(f) for name, service_data in data.items(): self.services[name] = ServiceMetadata(**service_data) except Exception as e: print(f"Warning: Could not load service registry: {e}") def save_registry(self): """Save service registry to persistent storage""" try: registry_data = { name: asdict(metadata) for name, metadata in self.services.items() } with open(self.registry_file, 'w') as f: json.dump(registry_data, f, indent=2) except Exception as e: print(f"Warning: Could not save service registry: {e}") async def register_service(self, metadata: ServiceMetadata) -> bool: """Register a new service""" metadata.registration_time = time.time() metadata.last_health_check = time.time() metadata.status = 'starting' self.services[metadata.name] = metadata self.save_registry() print(f"✅ Service registered: {metadata.name}") return True async def unregister_service(self, service_name: str) -> bool: """Unregister a service""" if service_name in self.services: del self.services[service_name] self.save_registry() print(f"✅ Service unregistered: {service_name}") return True return False async def discover_service(self, service_name: str) -> Optional[ServiceMetadata]: """Discover a service by name""" return self.services.get(service_name) async def list_services(self, status_filter: str = None) -> List[ServiceMetadata]: """List all services with optional status filter""" services = list(self.services.values()) if status_filter: services = [s for s in services if s.status == status_filter] return services async def health_check_service(self, service_name: str) -> bool: """Perform health check on a specific service""" if service_name not in self.services: return False service = self.services[service_name] try: # Simulate health check (replace with actual HTTP call) await asyncio.sleep(0.1) # Simulate network delay # Update health check timestamp service.last_health_check = time.time() service.status = 'healthy' self.save_registry() return True except Exception as e: print(f"Health check failed for {service_name}: {e}") service.status = 'unhealthy' self.save_registry() return False async def health_check_all(self) -> Dict[str, bool]: """Perform health check on all registered services""" results = {} for service_name in self.services: results[service_name] = await self.health_check_service(service_name) return results async def start_health_monitoring(self): """Start continuous health monitoring""" while True: await self.health_check_all() await asyncio.sleep(self.health_check_interval) EOF echo "✅ Service registry system implemented" } ``` ## Step 5: Inter-Service Communication and Fault Tolerance **Communication Optimization Agent:** ```bash spawn_communication_optimization_agent() { local project_path=$1 echo "🔗 Communication Optimization Agent: Implementing fault-tolerant inter-service communication" # Design communication patterns design_communication_patterns "$project_path" # Implement circuit breaker pattern implement_circuit_breaker "$project_path" # Create message queuing system implement_message_queuing "$project_path" # Optimize communication performance optimize_communication_performance "$project_path" echo "✅ Communication Optimization Agent: Fault-tolerant communication complete" } implement_circuit_breaker() { local project_path=$1 echo "⚡ Implementing circuit breaker pattern for fault tolerance..." # Circuit breaker implementation cat > "$project_path\/services\/claude-core\/circuit-breaker.py" << 'EOF' #!\/usr\/bin\/env python3 # Circuit breaker pattern for fault-tolerant microservice communication import asyncio import time from enum import Enum from typing import Callable, Any from dataclasses import dataclass class CircuitState(Enum): CLOSED = "closed" # Normal operation OPEN = "open" # Failure state, reject requests HALF_OPEN = "half_open" # Testing if service recovered @dataclass class CircuitBreakerConfig: failure_threshold: int = 5 # Failures before opening circuit recovery_timeout: int = 60 # Seconds before trying half-open success_threshold: int = 3 # Successes needed to close circuit timeout: int = 5 # Request timeout seconds class CircuitBreaker: """Circuit breaker for fault-tolerant service communication""" def __init__(self, service_name: str, config: CircuitBreakerConfig): self.service_name = service_name self.config = config self.state = CircuitState.CLOSED self.failure_count = 0 self.success_count = 0 self.last_failure_time = 0 async def call(self, func: Callable, *args, **kwargs) -> Any: """Execute function call through circuit breaker""" if self.state == CircuitState.OPEN: if time.time() - self.last_failure_time > self.config.recovery_timeout: self.state = CircuitState.HALF_OPEN self.success_count = 0 print(f"Circuit breaker for {self.service_name}: HALF_OPEN") else: raise Exception(f"Circuit breaker OPEN for {self.service_name}") try: # Execute function with timeout result = await asyncio.wait_for( func(*args, **kwargs), timeout=self.config.timeout ) # Handle success await self._on_success() return result except Exception as e: # Handle failure await self._on_failure() raise e async def _on_success(self): """Handle successful call""" if self.state == CircuitState.HALF_OPEN: self.success_count += 1 if self.success_count >= self.config.success_threshold: self.state = CircuitState.CLOSED self.failure_count = 0 print(f"Circuit breaker for {self.service_name}: CLOSED") elif self.state == CircuitState.CLOSED: self.failure_count = 0 async def _on_failure(self): """Handle failed call""" self.failure_count += 1 self.last_failure_time = time.time() if self.failure_count >= self.config.failure_threshold: self.state = CircuitState.OPEN print(f"Circuit breaker for {self.service_name}: OPEN") def get_status(self) -> dict: """Get current circuit breaker status""" return { 'service': self.service_name, 'state': self.state.value, 'failure_count': self.failure_count, 'success_count': self.success_count, 'last_failure_time': self.last_failure_time } class ServiceCommunicator: """Fault-tolerant communication manager for microservices""" def __init__(self): self.circuit_breakers = {} self.default_config = CircuitBreakerConfig() def get_circuit_breaker(self, service_name: str) -> CircuitBreaker: """Get or create circuit breaker for service""" if service_name not in self.circuit_breakers: self.circuit_breakers[service_name] = CircuitBreaker( service_name, self.default_config ) return self.circuit_breakers[service_name] async def call_service(self, service_name: str, func: Callable, *args, **kwargs) -> Any: """Call service through circuit breaker""" circuit_breaker = self.get_circuit_breaker(service_name) return await circuit_breaker.call(func, *args, **kwargs) def get_all_status(self) -> dict: """Get status of all circuit breakers""" return { name: breaker.get_status() for name, breaker in self.circuit_breakers.items() } EOF echo "✅ Circuit breaker pattern implemented" } ``` ## Step 6: Microservice Architecture Quality Checklist **Microservice Implementation Validation:** - [ ] Complete service decomposition with clear boundaries and independent deployment capability - [ ] Minimal core system implemented with plugin architecture and dynamic service loading - [ ] Service registry and discovery mechanisms deployed with comprehensive health monitoring - [ ] Inter-service communication patterns optimized with circuit breaker fault tolerance - [ ] Resource isolation implemented with proper service boundary enforcement - [ ] Complete service independence validated through isolation and deployment testing - [ ] Distributed system resilience demonstrated through fault injection testing - [ ] Service orchestration and lifecycle management automated and optimized **Agent Coordination Checklist:** - [ ] Service decomposition proceeding with systematic boundary identification - [ ] Core architecture implementation creating minimal footprint with plugin support - [ ] Service registry deployment providing discovery and health monitoring capabilities - [ ] Communication optimization implementing fault-tolerant inter-service patterns - [ ] Resource isolation ensuring complete service independence and boundary enforcement **Microservice Architecture Success Metrics:** - [ ] 90%+ reduction in core system footprint achieved through service separation - [ ] Independent deployability demonstrated for all service components - [ ] Sub-50ms service loading time maintained for dynamic service activation - [ ] Circuit breaker fault tolerance preventing cascade failures effectively - [ ] Service health monitoring providing comprehensive observability and alerting **Anti-Patterns to Avoid:** - ❌ Distributed monolith with shared databases and tight coupling - ❌ Synchronous communication patterns creating failure cascade risks - ❌ Missing health monitoring and service discovery capabilities - ❌ No resource isolation allowing services to interfere with each other - ❌ Manual service deployment and orchestration defeating automation benefits - ❌ Shared state between services violating independence principles **Final Verification:** Before completing microservice architecture implementation: - Have services been completely decomposed with clear boundaries and responsibilities? - Is the core system minimal with proper plugin architecture and dynamic loading? - Are service registry and discovery mechanisms providing comprehensive health monitoring? - Do communication patterns include fault tolerance with circuit breaker protection? - Has complete service independence been validated through isolation testing? - Does the architecture demonstrate resilience through distributed system fault tolerance? **Final Microservice Architecture Commitment:** - **I will**: Execute comprehensive microservice decomposition with distributed system architecture - **I will**: Implement multi-agent coordination for parallel service development and deployment - **I will**: Maintain complete service independence with proper resource isolation and communication patterns - **I will**: Ensure fault tolerance and resilience through circuit breaker patterns and health monitoring - **I will NOT**: Accept distributed monolith patterns or service coupling - **I will NOT**: Skip health monitoring or service discovery implementation - **I will NOT**: Ignore fault tolerance or distributed system resilience requirements **REMEMBER:** This is MICROSERVICE ARCHITECTURE IMPLEMENTATION mode - complete service decomposition, distributed system design, and fault-tolerant communication. The goal is to achieve radical footprint reduction through service separation while maintaining system resilience and independence. Executing comprehensive microservice architecture implementation protocol for distributed system optimization...