How Cortex Routes Tasks to Specialist Masters

The Coordinator Master is Cortex’s brain - it decides which specialist master should handle each task. But how does it make these decisions?

Let’s dive into the routing algorithm.

The Challenge

Given a task like: “Fix authentication bug causing login failures”

Which master should handle it?

• Development Master - It’s a bug fix (code changes)
• Security Master - It’s auth-related (security concern)
• CI/CD Master - Might need testing after fix

The answer isn’t obvious. Traditional rule-based systems would struggle. Cortex’s MoE routing solves this elegantly.

The Routing Pipeline

The routing pipeline consists of 5 stages that transform a task description into a master assignment:

graph TD
    A[Task Received] --> B[Stage 1: Task Analysis]
    B --> C[Stage 2: Pattern Matching]
    C --> D[Stage 3: Confidence Calculation]
    D --> E[Stage 4: Master Selection]
    E --> F[Stage 5: Outcome Tracking]
    F --> G[Future Routing Improvement]

    style A fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style B fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style C fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style D fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style E fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style F fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style G fill:#30363d,stroke:#00d084,stroke-width:2px

Stage 1: Task Analysis

First, extract task characteristics:

function analyzeTask(taskDescription) {
  return {
    keywords: extractKeywords(taskDescription),
    category: categorizeTask(taskDescription),
    complexity: estimateComplexity(taskDescription),
    domains: identifyDomains(taskDescription),
    urgency: assessUrgency(taskDescription)
  };
}

For our example:

{
  keywords: ['fix', 'authentication', 'bug', 'login', 'failures'],
  category: 'bugfix',
  complexity: 'medium',
  domains: ['development', 'security'],
  urgency: 'high'
}

Stage 2: Pattern Matching

Check historical patterns:

function matchPatterns(taskAnalysis, historicalPatterns) {
  const matches = [];

  for (const pattern of historicalPatterns) {
    const similarity = calculateSimilarity(
      taskAnalysis.keywords,
      pattern.keywords
    );

    if (similarity > 0.7) {
      matches.push({
        pattern: pattern,
        similarity: similarity,
        master: pattern.successful_master,
        confidence: pattern.success_rate
      });
    }
  }

  return matches.sort((a, b) => b.confidence - a.confidence);
}

Historical patterns might show:

[
  {
    keywords: ['auth', 'bug', 'fix'],
    successful_master: 'development-master',
    success_rate: 0.89,
    sample_size: 23
  },
  {
    keywords: ['authentication', 'security'],
    successful_master: 'security-master',
    success_rate: 0.76,
    sample_size: 15
  }
]

Stage 3: Confidence Calculation

The confidence score combines multiple factors with different weights:

graph LR
    A[Task Input] --> B[Pattern Match<br/>40% weight]
    A --> C[Domain Expertise<br/>20% weight]
    A --> D[Complexity Match<br/>10% weight]
    A --> E[Workload Penalty<br/>-10% penalty]

    B --> F[Final Confidence]
    C --> F
    D --> F
    E --> F

    F --> G{Confidence >= 0.6?}
    G -->|Yes| H[Assign to Master]
    G -->|No| I[Use Fallback]

    style A fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style F fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style G fill:#30363d,stroke:#ff6900,stroke-width:2px
    style H fill:#30363d,stroke:#00d084,stroke-width:2px
    style I fill:#30363d,stroke:#cf2e2e,stroke-width:2px

Calculate confidence score for each master:

function calculateConfidence(task, master, patterns) {
  let confidence = 0.5; // Base confidence

  // Pattern matching contribution
  const matchingPatterns = patterns.filter(p => p.master === master.id);
  if (matchingPatterns.length > 0) {
    const avgSimilarity = average(matchingPatterns.map(p => p.similarity));
    const avgSuccessRate = average(matchingPatterns.map(p => p.confidence));
    confidence += (avgSimilarity * avgSuccessRate) * 0.4;
  }

  // Domain expertise contribution
  if (task.domains.includes(master.domain)) {
    confidence += 0.2;
  }

  // Complexity match contribution
  if (task.complexity === master.preferred_complexity) {
    confidence += 0.1;
  }

  // Workload penalty
  const workloadPenalty = master.current_workers / master.max_workers;
  confidence -= workloadPenalty * 0.1;

  return Math.max(0, Math.min(1, confidence));
}

For our task:

{
  'development-master': 0.85,
  'security-master': 0.65,
  'ci-cd-master': 0.15,
  'inventory-master': 0.05
}

Stage 4: Master Selection

Select the master with highest confidence:

function selectMaster(confidenceScores, threshold = 0.6) {
  const sorted = Object.entries(confidenceScores)
    .sort(([,a], [,b]) => b - a);

  const [bestMaster, bestConfidence] = sorted[0];

  // If confidence too low, use fallback routing
  if (bestConfidence < threshold) {
    return {
      master: 'development-master', // Fallback
      confidence: bestConfidence,
      fallback: true
    };
  }

  return {
    master: bestMaster,
    confidence: bestConfidence,
    fallback: false
  };
}

Result: Development Master (0.85 confidence)

Stage 5: Outcome Tracking

After execution, record the outcome:

function recordOutcome(task, selectedMaster, result) {
  const pattern = {
    keywords: task.keywords,
    category: task.category,
    complexity: task.complexity,
    master: selectedMaster,
    predicted_confidence: task.routing.confidence,
    actual_success: result.success,
    quality_score: result.quality,
    duration_minutes: result.duration,
    timestamp: new Date()
  };

  // Store for future routing
  patterns.append(pattern);

  // Update master performance metrics
  updateMasterMetrics(selectedMaster, result);
}

This feeds back into pattern matching for future tasks.

The Learning Loop

Over time, routing improves as the system learns from successful patterns:

graph TD
    A[Iteration 1<br/>No Prior Data] -->|Confidence: 0.70| B[Task Success]
    B --> C[Pattern Recorded]
    C --> D[Iteration 5<br/>1 Pattern Match]
    D -->|Confidence: 0.78| E[Task Success]
    E --> F[Pattern Strengthened]
    F --> G[Iteration 10<br/>4 Pattern Matches]
    G -->|Confidence: 0.85| H[Task Success]
    H --> I[Pattern Reinforced]
    I --> J[Iteration 20<br/>9 Pattern Matches]
    J -->|Confidence: 0.92| K[Task Success]

    style A fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style D fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style G fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style J fill:#30363d,stroke:#00d084,stroke-width:2px
    style K fill:#30363d,stroke:#00d084,stroke-width:3px

Iteration 1 (No prior data)

Task: "Fix auth bug"
Routing: Development (0.70) - Based on keywords
Result: Success

Iteration 5 (Some learning)

Task: "Fix auth bug"
Routing: Development (0.78) - Pattern match: 1 success
Result: Success

Iteration 10 (More learning)

Task: "Fix auth bug"
Routing: Development (0.85) - Pattern match: 4 successes
Result: Success

Iteration 20 (Well-trained)

Task: "Fix auth bug"
Routing: Development (0.92) - Pattern match: 9 successes
Result: Success

The confidence increases as more similar tasks succeed.

Advanced Routing Scenarios

Multi-Master Workflows

Some tasks need multiple masters working in sequence:

sequenceDiagram
    participant C as Coordinator
    participant D as Development Master
    participant S as Security Master
    participant CI as CI/CD Master

    C->>D: Task: Implement rate limiting
    Note over D: Confidence: 0.88
    D->>D: Code implementation
    D-->>C: Implementation complete

    C->>S: Handoff: Security audit
    Note over S: Confidence: 0.82
    S->>S: Security review
    S-->>C: Audit passed

    C->>CI: Handoff: Deploy changes
    Note over CI: Confidence: 0.75
    CI->>CI: Deploy to production
    CI-->>C: Deployment successful

Task: "Implement rate limiting with security audit"

Analysis:
  Primary concern: Implementation
  Secondary concern: Security review

Routing:
  1. Development-Master (implement)
     Confidence: 0.88
  2. Security-Master (audit)
     Confidence: 0.82
  3. CI/CD-Master (deploy)
     Confidence: 0.75

Workflow: Sequential execution with handoffs

Confidence-Based Parallel Execution

When confidence is similar, execute in parallel:

Task: "Optimize database performance"

Confidence scores:
  Development: 0.78
  CI/CD: 0.76

Decision: Both masters work in parallel
  Development: Code optimization
  CI/CD: Load testing

Merge results at the end

Fallback Chains

If first master fails, try alternatives in sequence:

graph TD
    A[Task: Complex refactoring] --> B[Primary: Development Master<br/>Confidence: 0.82]
    B --> C{Success?}
    C -->|Worker Timeout| D[Fallback 1: Retry Development<br/>Confidence: 0.75]
    D --> E{Success?}
    E -->|Still Fails| F[Fallback 2: Coordinator Meta-Routing<br/>Confidence: 0.65]
    F --> G{Success?}
    G -->|Confidence < 0.5| H[Manual Escalation]
    C -->|Yes| I[Task Complete]
    E -->|Yes| I
    G -->|Yes| I

    style A fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style B fill:#30363d,stroke:#58a6ff,stroke-width:2px
    style D fill:#30363d,stroke:#ff6900,stroke-width:2px
    style F fill:#30363d,stroke:#ff6900,stroke-width:2px
    style H fill:#30363d,stroke:#cf2e2e,stroke-width:2px
    style I fill:#30363d,stroke:#00d084,stroke-width:2px

Task: "Complex refactoring"
Primary: Development-Master (0.82)
Result: Worker timeout

Fallback chain:
1. Retry with Development-Master (0.75 confidence after adjustment)
2. Try Coordinator-Master meta-routing (0.65)
3. Manual escalation (confidence < 0.5)

Real Example from Production

Let’s trace an actual task from Cortex development:

Task: “Scan repository for CVE-2024-12345 vulnerability”

Stage 1: Analysis

{
  keywords: ['scan', 'repository', 'CVE', 'vulnerability'],
  category: 'security_scan',
  complexity: 'low',
  domains: ['security'],
  urgency: 'high'
}

Stage 2: Pattern Matching

Found 12 similar patterns:
- All routed to Security-Master
- 11/12 successful
- Average duration: 8 minutes

Stage 3: Confidence

{
  'security-master': 0.94, // Domain match + strong patterns
  'development-master': 0.22,
  'ci-cd-master': 0.18,
  'inventory-master': 0.15
}

Stage 4: Selection

Selected: Security-Master
Confidence: 0.94
Fallback: false

Stage 5: Execution

Security-Master spawned scan-worker-001
Worker found CVE in 3 files
Duration: 6 minutes
Result: Success (quality: 0.96)

Stage 6: Learning

Pattern updated:
  "CVE scan" tasks → Security-Master
  Success rate: 12/13 = 0.923
  Next confidence: 0.95 ✓

Routing Metrics

Cortex tracks routing performance:

{
  "total_tasks": 1247,
  "routing_accuracy": 0.87,  // % correct on first try
  "avg_confidence": 0.82,
  "fallback_rate": 0.08,     // % using fallback
  "multi_master_tasks": 0.12, // % needing multiple masters

  "by_master": {
    "development-master": {
      "tasks": 623,
      "success_rate": 0.91,
      "avg_confidence": 0.84
    },
    "security-master": {
      "tasks": 312,
      "success_rate": 0.89,
      "avg_confidence": 0.86
    }
  }
}

Tuning the Routing Algorithm

Threshold Adjustment

// Conservative (fewer errors, more fallbacks)
threshold = 0.75;

// Balanced (default)
threshold = 0.60;

// Aggressive (fewer fallbacks, more risk)
threshold = 0.45;

Pattern Weight Tuning

// Emphasize recent patterns
const timeDecay = Math.exp(-age_days / 30);
pattern.weight = pattern.success_rate * timeDecay;

// Emphasize frequent patterns
pattern.weight = pattern.success_rate * Math.log(pattern.sample_size);

Domain Bias

// Increase domain expertise weight
if (task.domains.includes(master.domain)) {
  confidence += 0.3; // Increased from 0.2
}

Comparison to Alternatives

Rule-Based Routing

if (task.includes('security')) {
  route_to('security-master');
} else if (task.includes('deploy')) {
  route_to('cicd-master');
}
// Rigid, doesn't learn

Pure ML Routing

model.predict(task_embedding)
// Black box, hard to debug

Cortex Hybrid

confidence = pattern_match(task) * 0.6 +
             ml_score(task) * 0.3 +
             domain_match(task) * 0.1;
// Best of both worlds

Future Enhancements

Transfer Learning

Learn routing patterns from one project
Apply to another similar project
Faster bootstrap for new deployments

Meta-Learning

Learn how to learn routing better
Adapt learning rate based on performance
Automatically tune thresholds

Ensemble Routing

Multiple routing algorithms vote
Confidence from agreement level
Fallback to ensemble on disagreement

Key Takeaways

1. Routing is multi-stage: Analysis → Patterns → Confidence → Selection
2. Hybrid approach works best: Patterns + ML + domain knowledge
3. Learning is continuous: Every task improves future routing
4. Confidence matters: Know when you don’t know
5. Metrics guide tuning: Track accuracy, adjust thresholds

The routing algorithm is the heart of Cortex’s MoE system. Get it right, and the system improves itself. Get it wrong, and you have expensive chaos.

Tomorrow, we’ll explore the Learning Loop - how Cortex extracts patterns and improves routing over time.

Learn More About Cortex

Want to dive deeper into how Cortex works? Visit the Meet Cortex page to learn about its architecture, capabilities, and how it scales from 1 to 100+ agents on-demand.

---

Part 6 of the Cortex series. Next: The Learning Loop: How Cortex Improves Itself