SuperClaude/Framework-Hooks/docs/Configuration/orchestrator.yaml.md

Orchestrator Configuration (orchestrator.yaml)

Overview

The orchestrator.yaml file defines intelligent routing patterns and coordination strategies for the SuperClaude-Lite framework. This configuration implements the ORCHESTRATOR.md patterns through automated MCP server selection, hybrid intelligence coordination, and performance optimization strategies.

Purpose and Role

The orchestrator configuration serves as:

• Intelligent Routing Engine: Automatically selects optimal MCP servers based on task characteristics
• Hybrid Intelligence Coordinator: Manages coordination between Morphllm and Serena for optimal editing strategies
• Performance Optimizer: Implements caching, parallel processing, and resource management strategies
• Fallback Manager: Provides graceful degradation when preferred servers are unavailable
• Learning Coordinator: Tracks routing effectiveness and adapts selection strategies

Configuration Structure

1. MCP Server Routing Patterns (routing_patterns)

UI Components Routing

ui_components:
  triggers: ["component", "button", "form", "modal", "dialog", "card", "input", "design", "frontend", "ui", "interface"]
  mcp_server: "magic"
  persona: "frontend-specialist"
  confidence_threshold: 0.8
  priority: "high"
  performance_profile: "standard"
  capabilities: ["ui_generation", "design_systems", "component_patterns"]

Purpose: Routes UI-related requests to Magic MCP server with frontend persona activation Triggers: Comprehensive UI terminology detection Performance: Standard performance profile with high priority routing

Deep Analysis Routing

deep_analysis:
  triggers: ["analyze", "complex", "system-wide", "architecture", "debug", "troubleshoot", "investigate", "root cause"]
  mcp_server: "sequential"
  thinking_mode: "--think-hard"
  confidence_threshold: 0.75
  priority: "high"
  performance_profile: "intensive"
  capabilities: ["complex_reasoning", "systematic_analysis", "hypothesis_testing"]
  context_expansion: true

Purpose: Routes complex analysis requests to Sequential with enhanced thinking modes Thinking Integration: Automatically activates --think-hard for systematic analysis Context Expansion: Enables broader context analysis for complex problems

Library Documentation Routing

library_documentation:
  triggers: ["library", "framework", "package", "import", "dependency", "documentation", "docs", "api", "reference"]
  mcp_server: "context7"
  persona: "architect"
  confidence_threshold: 0.85
  priority: "medium"
  performance_profile: "standard"
  capabilities: ["documentation_access", "framework_patterns", "best_practices"]

Purpose: Routes documentation requests to Context7 with architect persona High Confidence: 85% threshold ensures precise documentation routing Best Practices: Integrates framework patterns and best practices into responses

Testing Automation Routing

testing_automation:
  triggers: ["test", "testing", "e2e", "end-to-end", "browser", "automation", "validation", "verify"]
  mcp_server: "playwright"
  confidence_threshold: 0.8
  priority: "medium"
  performance_profile: "intensive"
  capabilities: ["browser_automation", "testing_frameworks", "performance_testing"]

Purpose: Routes testing requests to Playwright for browser automation Manual Preference: No auto-activation, prefers manual confirmation for testing operations Intensive Profile: Uses intensive performance profile for testing workloads

Intelligent Editing Routing

intelligent_editing:
  triggers: ["edit", "modify", "refactor", "update", "change", "fix", "improve"]
  mcp_server: "morphllm"
  confidence_threshold: 0.7
  priority: "medium"
  performance_profile: "lightweight"
  capabilities: ["pattern_application", "fast_apply", "intelligent_editing"]
  complexity_threshold: 0.6
  file_count_threshold: 10

Purpose: Routes editing requests to Morphllm for fast, intelligent modifications Thresholds: Complexity ≤0.6 and file count ≤10 for optimal Morphllm performance Lightweight Profile: Optimized for speed and efficiency

Semantic Analysis Routing

semantic_analysis:
  triggers: ["semantic", "symbol", "reference", "find", "search", "navigate", "explore"]
  mcp_server: "serena"
  confidence_threshold: 0.8
  priority: "high"
  performance_profile: "standard"
  capabilities: ["semantic_understanding", "project_context", "memory_management"]

Purpose: Routes semantic analysis to Serena for deep project understanding High Priority: Essential for project navigation and context management Symbol Operations: Optimal for symbol-level operations and refactoring

Multi-File Operations Routing

multi_file_operations:
  triggers: ["multiple files", "batch", "bulk", "project-wide", "codebase", "entire"]
  mcp_server: "serena"
  confidence_threshold: 0.9
  priority: "high"
  performance_profile: "intensive"
  capabilities: ["multi_file_coordination", "project_analysis"]

Purpose: Routes large-scale operations to Serena for comprehensive project handling High Confidence: 90% threshold ensures accurate detection of multi-file operations Intensive Profile: Resources allocated for complex project-wide operations

2. Hybrid Intelligence Selection (hybrid_intelligence)

Morphllm vs Serena Decision Matrix

morphllm_vs_serena:
  decision_factors:
    - file_count
    - complexity_score
    - operation_type
    - symbol_operations_required
    - project_size
  
  morphllm_criteria:
    file_count_max: 10
    complexity_max: 0.6
    preferred_operations: ["edit", "modify", "update", "pattern_application"]
    optimization_focus: "token_efficiency"
  
  serena_criteria:
    file_count_min: 5
    complexity_min: 0.4
    preferred_operations: ["analyze", "refactor", "navigate", "symbol_operations"]
    optimization_focus: "semantic_understanding"
  
  fallback_strategy:
    - try_primary_choice
    - fallback_to_alternative
    - use_native_tools

Decision Logic: Multi-factor analysis determines optimal server selection Clear Boundaries: Morphllm for simple edits, Serena for complex analysis Fallback Chain: Graceful degradation through alternative servers to native tools

3. Auto-Activation Rules (auto_activation)

Complexity Thresholds

complexity_thresholds:
  enable_sequential:
    complexity_score: 0.6
    file_count: 5
    operation_types: ["analyze", "debug", "complex"]
  
  enable_delegation:
    file_count: 3
    directory_count: 2
    complexity_score: 0.4
  
  enable_validation:
    is_production: true
    risk_level: ["high", "critical"]
    operation_types: ["deploy", "refactor", "delete"]

Sequential Activation: Complex operations with 0.6+ complexity or 5+ files Delegation Triggers: Multi-file operations exceeding thresholds Validation Requirements: Production and high-risk operations

4. Performance Optimization (performance_optimization)

Parallel Execution Strategy

parallel_execution:
  file_threshold: 3
  estimated_speedup_min: 1.4
  max_concurrency: 7

Threshold Management: 3+ files required for parallel processing Performance Guarantee: Minimum 1.4x speedup required for activation Concurrency Limits: Maximum 7 concurrent operations for resource management

Caching Strategy

caching_strategy:
  enable_for_operations: ["documentation_lookup", "analysis_results", "pattern_matching"]
  cache_duration_minutes: 30
  max_cache_size_mb: 100

Selective Caching: Focuses on high-benefit operations Duration Management: 30-minute cache lifetime balances freshness with performance Size Limits: 100MB cache prevents excessive memory usage

Resource Management

resource_management:
  memory_threshold_percent: 85
  token_threshold_percent: 75
  fallback_to_lightweight: true

Memory Protection: 85% memory threshold triggers resource optimization Token Management: 75% token usage threshold activates efficiency mode Automatic Fallback: Switches to lightweight alternatives under pressure

5. Quality Gates Integration (quality_gates)

Validation Levels

validation_levels:
  basic: ["syntax_validation"]
  standard: ["syntax_validation", "type_analysis", "code_quality"]
  comprehensive: ["syntax_validation", "type_analysis", "code_quality", "security_assessment", "performance_analysis"]
  production: ["syntax_validation", "type_analysis", "code_quality", "security_assessment", "performance_analysis", "integration_testing", "deployment_validation"]

Progressive Validation: Escalating validation complexity based on operation risk Production Standards: Comprehensive 7-step validation for production operations

Trigger Conditions

trigger_conditions:
  comprehensive:
    - is_production: true
    - complexity_score: ">0.7"
    - operation_types: ["refactor", "architecture"]
  
  production:
    - is_production: true
    - operation_types: ["deploy", "release"]

Comprehensive Triggers: Production context or high complexity operations Production Triggers: Deploy and release operations receive maximum validation

6. Fallback Strategies (fallback_strategies)

MCP Server Unavailable

mcp_server_unavailable:
  context7: ["web_search", "cached_documentation", "native_analysis"]
  sequential: ["native_step_by_step", "basic_analysis"]
  magic: ["manual_component_generation", "template_suggestions"]
  playwright: ["manual_testing_suggestions", "test_case_generation"]
  morphllm: ["native_edit_tools", "manual_editing"]
  serena: ["basic_file_operations", "simple_search"]

Graceful Degradation: Each server has specific fallback alternatives Functionality Preservation: Maintains core functionality even with server failures User Guidance: Provides manual alternatives when automation unavailable

Performance Degradation

performance_degradation:
  high_latency: ["reduce_analysis_depth", "enable_caching", "parallel_processing"]
  resource_constraints: ["lightweight_alternatives", "compression_mode", "minimal_features"]

Latency Management: Reduces analysis depth and increases caching Resource Protection: Switches to lightweight alternatives and compression

Quality Issues

quality_issues:
  validation_failures: ["increase_validation_depth", "manual_review", "rollback_capability"]
  error_rates_high: ["enable_pre_validation", "reduce_complexity", "step_by_step_execution"]

Quality Recovery: Increases validation and enables manual review Error Prevention: Pre-validation and complexity reduction strategies

7. Learning Integration (learning_integration)

Effectiveness Tracking

effectiveness_tracking:
  track_server_performance: true
  track_routing_decisions: true
  track_user_satisfaction: true

Performance Monitoring: Tracks server performance and routing accuracy User Feedback: Incorporates user satisfaction into learning algorithms Decision Analysis: Analyzes routing decision effectiveness over time

Adaptation Triggers

adaptation_triggers:
  effectiveness_threshold: 0.6
  confidence_threshold: 0.7
  usage_count_min: 3

Effectiveness Gates: 60% effectiveness threshold triggers adaptation Confidence Requirements: 70% confidence required for routing changes Statistical Significance: Minimum 3 usage instances for pattern recognition

Optimization Feedback

optimization_feedback:
  performance_degradation: "adjust_routing_weights"
  user_preference_detected: "update_server_priorities"
  error_patterns_found: "enhance_fallback_strategies"

Dynamic Optimization: Adjusts routing weights based on performance Personalization: Updates priorities based on user preferences Error Learning: Enhances fallback strategies based on error patterns

8. Mode Integration (mode_integration)

Brainstorming Mode

brainstorming:
  preferred_servers: ["sequential", "context7"]
  thinking_modes: ["--think", "--think-hard"]

Server Preference: Sequential for reasoning, Context7 for documentation Enhanced Thinking: Activates thinking modes for deeper analysis

Task Management Mode

task_management:
  coordination_servers: ["serena", "morphllm"]
  delegation_strategies: ["files", "folders", "auto"]

Coordination Focus: Serena for analysis, Morphllm for execution Delegation Options: Multiple strategies for different operation types

Token Efficiency Mode

token_efficiency:
  optimization_servers: ["morphllm"]
  compression_strategies: ["symbol_systems", "abbreviations"]

Efficiency Focus: Morphllm for token-optimized operations Compression Integration: Symbol systems and abbreviation strategies

Performance Implications

1. Routing Decision Overhead

Decision Time Analysis

• Pattern Matching: 10-50ms per routing pattern evaluation
• Confidence Calculation: 5-20ms per server option
• Total Routing Decision: 50-200ms for complete routing analysis

Memory Usage

• Pattern Storage: 20-50KB for all routing patterns
• Decision State: 10-20KB during routing evaluation
• Cache Storage: Up to 100MB for cached results

2. MCP Server Coordination

Server Communication

• Activation Time: 100-500ms per MCP server activation
• Coordination Overhead: 50-200ms for multi-server operations
• Fallback Detection: 100-300ms to detect and switch to fallback

Resource Allocation

• Memory Per Server: 50-200MB depending on server type
• CPU Usage: 20-60% during intensive server operations
• Network Usage: Varies by server, cached where possible

3. Learning System Impact

Learning Overhead

• Effectiveness Tracking: 5-20ms per operation for metrics collection
• Pattern Analysis: 100-500ms for pattern recognition updates
• Adaptation Application: 200ms-2s for routing weight adjustments

Storage Requirements

• Learning Data: 500KB-2MB per session for effectiveness tracking
• Pattern Storage: 100KB-1MB for persistent patterns
• Cache Data: Up to 100MB for performance optimization

Configuration Best Practices

1. Production Orchestrator Configuration

# Optimize for reliability and performance
routing_patterns:
  ui_components:
    confidence_threshold: 0.9  # Higher confidence for production
auto_activation:
  enable_validation:
    is_production: true
    risk_level: ["medium", "high", "critical"]  # More conservative

2. Development Orchestrator Configuration

# Enable more experimentation and learning
learning_integration:
  adaptation_triggers:
    effectiveness_threshold: 0.4  # More aggressive learning
    usage_count_min: 1  # Learn from fewer samples

3. Performance-Optimized Configuration

# Minimize overhead for performance-critical environments
performance_optimization:
  parallel_execution:
    file_threshold: 5  # Higher threshold to reduce overhead
  caching_strategy:
    cache_duration_minutes: 60  # Longer cache for better performance

4. Learning-Optimized Configuration

# Maximum learning and adaptation
learning_integration:
  effectiveness_tracking:
    detailed_analytics: true
    user_interaction_tracking: true
  optimization_feedback:
    continuous_adaptation: true

Troubleshooting

Common Orchestration Issues

Wrong Server Selected

• Symptoms: Suboptimal server choice for task type
• Analysis: Review trigger patterns and confidence thresholds
• Solution: Adjust routing patterns or increase confidence thresholds
• Testing: Test routing with sample inputs and monitor effectiveness

Server Unavailable Issues

• Symptoms: Frequent fallback activation, degraded functionality
• Diagnosis: Check MCP server availability and network connectivity
• Resolution: Verify server configurations and fallback strategies
• Prevention: Implement server health monitoring

Performance Degradation

• Symptoms: Slow routing decisions, high overhead
• Analysis: Profile routing decision time and resource usage
• Optimization: Adjust confidence thresholds, enable caching
• Monitoring: Track routing performance metrics

Fallback Chain Failures

• Symptoms: Complete functionality loss when primary server fails
• Investigation: Review fallback strategy completeness
• Enhancement: Add more fallback options and manual alternatives
• Testing: Test fallback chains under various failure scenarios

Learning System Troubleshooting

No Learning Observed

• Check: Learning integration enabled and collecting data
• Verify: Effectiveness metrics being calculated and stored
• Debug: Review adaptation trigger thresholds
• Fix: Ensure learning data persistence and pattern recognition

Poor Routing Decisions

• Analysis: Review routing effectiveness metrics and user feedback
• Adjustment: Modify confidence thresholds and trigger patterns
• Validation: Test routing decisions with controlled scenarios
• Monitoring: Track long-term routing accuracy trends

Resource Usage Issues

• Monitoring: Track memory and CPU usage during orchestration
• Optimization: Adjust cache sizes and parallel processing limits
• Tuning: Optimize resource thresholds and fallback triggers
• Balancing: Balance learning sophistication with resource constraints

Integration with Other Configurations

1. MCP Server Coordination

The orchestrator configuration works closely with:

• superclaude-config.json: MCP server definitions and capabilities
• performance.yaml: Performance targets and optimization strategies
• modes.yaml: Mode-specific server preferences and coordination

2. Hook Integration

Orchestrator patterns are implemented through:

• Pre-Tool Use Hook: Server selection and routing decisions
• Post-Tool Use Hook: Effectiveness tracking and learning
• Session Start Hook: Initial server availability assessment

3. Quality Gates Coordination

Quality validation levels integrate with:

• validation.yaml: Specific validation rules and standards
• **Trigger conditions for comprehensive and production validation
• **Performance monitoring for validation effectiveness

Related Documentation

• ORCHESTRATOR.md: Framework orchestration patterns and principles
• MCP Server Documentation: Individual server capabilities and integration
• Hook Documentation: Implementation details for orchestration hooks
• Performance Configuration: Performance targets and optimization strategies

Version History

• v1.0.0: Initial orchestrator configuration
• Comprehensive MCP server routing with 6 server types
• Hybrid intelligence coordination between Morphllm and Serena
• Multi-level quality gates integration with production safeguards
• Learning system integration with effectiveness tracking
• Performance optimization with caching and parallel processing
• Robust fallback strategies for graceful degradation