intelligent-router

🎯 Intelligent Router - Smart Agent/Skill/Plugin Dispatch

Overview

The Intelligent Router is an automatic orchestration system that analyzes user questions and intelligently selects the optimal combination of:

• 🤖 Agents (specialized subagents)
• 🎯 Skills (knowledge bundles)
• 🔌 Plugins (global tools)
• 📚 Docs (project documentation)
• 🛠️ Tools (native Claude tools)

Design Philosophy: B - Medium Router

• ✅ Auto-loads relevant skills
• ✅ Auto-dispatches primary agent
• 💡 Suggests optional agents (you choose)
• 📊 Transparent reporting (you see everything)

When This Skill Activates

Smart Auto-Detect triggers on:

• ✅ Questions with 5+ words
• ✅ Action verbs: "maak", "bouw", "fix", "deploy", "test", etc.
• ✅ Complex requests (multiple domains)

Skips on:

• ❌ Simple questions: "Wat is X?", "Hoe werkt Y?"
• ❌ Short queries (< 5 words)
• ❌ Informational requests

How It Works

Phase 1: Analysis

User Question
    ↓
Intent Detection (analyze-intent.js)
    ↓
Match Against Routing Matrix
    ↓
Calculate Match Scores
    ↓
Identify Domains & Complexity

Phase 2: Resource Collection

Collect ALL Matched Routes
    ↓
Primary Route = Highest Score
    ↓
Gather:
  - Skills from all matches
  - Plugins from all matches
  - Docs from all matches
  - Tools from primary route
  - Optional agents from secondary matches

Phase 3: Dispatch

Auto-Load:
  ✅ Skills (via skill-loader.js)
  ✅ Docs (loaded into context)
  ✅ Plugins (activated)

Auto-Dispatch:
  ✅ Primary Agent (Task tool)

Suggest:
  💡 Optional Agents (you choose to dispatch)
  💡 Additional tools
  💡 Memory check (episodic-memory)

Phase 4: Transparent Reporting

Display Formatted Analysis:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 INTELLIGENT ROUTER ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Detected Intent: [...]
📁 Complexity: [SIMPLE|MEDIUM|HIGH|COMPLEX]
🎯 Domains: [...]

✅ AUTO-LOADED SKILLS: [...]
✅ AUTO-DISPATCHED: [agent] → [reason]
💡 OPTIONAL DISPATCH: [suggestions]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Routing Matrix

The router uses routing-matrix.json with 20+ predefined routes:

Critical Routes (Always Priority)

• memory_recall - Episodic memory search
• security_review - OWASP compliance, vulnerability scanning
• authentication - User auth, login systems
• complex_feature - Multi-domain features → master-orchestrator

High Priority Routes

• backend_api - REST/GraphQL API development
• backend_database - SQL, schema design, queries
• frontend_ui - React/Vue components, UI work
• testing_unit - TDD, unit/integration tests
• architecture - System design, tech stack decisions
• debugging - Bug fixes, error resolution

Medium Priority Routes

• ux_design - UI/UX, dashboards, premium interfaces
• testing_e2e - Playwright, browser automation
• data_engineering - ETL pipelines, data warehouses
• deployment - CI/CD, production deploys
• ai_ml_integration - LLM, RAG, vector databases
• accessibility - WCAG compliance, inclusive design

Specialized Routes

• code_search - Finding code, codebase analysis
• browser_automation - Web scraping, UI testing
• git_operations - Worktrees, branching
• documentation - Writing docs, README files

Complexity Assessment

Router automatically determines complexity:

Simple (1 domain, < 10 words)

• Single file edit
• Small bug fix
• Quick query → Auto-dispatch: Direct to specialist agent

Medium (2 domains, 10-30 words)

• New feature in one area
• Moderate refactoring
• Standard API endpoint → Auto-dispatch: Primary agent + suggest related agents

High (3 domains, 30-50 words)

• Cross-cutting feature
• Security + functionality
• Multiple file changes → Auto-dispatch: Primary agent + optional specialists

Complex (3+ domains, complex requirements)

• Complete new module
• System redesign
• Multi-domain integration → Requires: master-orchestrator with sub-agents

Progressive Context Loading

Router uses 3 levels for skills:

Level 1: Always Load

• Core principles (2-5KB)
• Quick reference
• Essential patterns

Level 2: Load on Request

• Detailed patterns (10-15KB)
• Complete examples
• Architecture guidance

Level 3: Full Context

• All scripts
• Templates
• Automation tools

Default: Router loads Level 1 for all matched skills Escalation: Request Level 2/3 if needed

Example Routing Scenarios

Example 1: Simple Bug Fix

User: "Fix deze error in login.ts"

Router Analysis:
  Intent: Bug fixing
  Complexity: SIMPLE
  Domains: debugging, backend

Auto-Loaded:
  - systematic-debugging skill
  - testing-fundamentals skill

Auto-Dispatched:
  - senior-fullstack-developer

Optional:
  - qa-testing-engineer (regression tests)

Example 2: Authentication System

User: "Maak een login systeem met registratie"

Router Analysis:
  Intent: User authentication
  Complexity: HIGH
  Domains: security, backend, frontend

Auto-Loaded:
  - security-essentials skill
  - backend-development-patterns skill
  - testing-fundamentals skill

Auto-Dispatched:
  - backend-specialist (primary)

Optional:
  - security-specialist (OWASP review)
  - frontend-specialist (login UI)
  - qa-testing-engineer (security tests)

Docs Loaded:
  - docs/security.md
  - docs/backend.md

Example 3: Complete Feature

User: "Bouw een dashboard met gebruikers, data visualisatie en export"

Router Analysis:
  Intent: Multi-domain feature
  Complexity: COMPLEX
  Domains: frontend, backend, data, ux

Auto-Loaded:
  - backend-development-patterns skill
  - testing-fundamentals skill
  - brainstorming skill

Auto-Dispatched:
  - master-orchestrator
    Sub-agents (parallel):
      - backend-specialist (API)
      - frontend-specialist (Dashboard UI)
      - data-engineer (Data pipeline)
      - ux-design-expert (Charts/UX)
      - qa-testing-engineer (Test strategy)

Example 4: Database Query

User: "Optimaliseer deze SQL query die te langzaam is"

Router Analysis:
  Intent: Database optimization
  Complexity: MEDIUM
  Domains: data-engineering, backend

Auto-Loaded:
  - backend-development-patterns skill

Auto-Dispatched:
  - data-engineer

Tools Activated:
  - sql-universal-expert

Optional:
  - senior-fullstack-developer (code refactor)

Docs Loaded:
  - docs/backend.md

Usage

Automatic (Recommended)

Router activates automatically when:

1. User asks question with 5+ words
2. Question contains action verbs
3. Question seems like a task (not just info)

No manual activation needed!

Manual Testing

Test router analysis before dispatching:

# Analyze a question
node .claude/skills/intelligent-router/scripts/analyze-intent.js analyze "Maak een API"

# Get JSON output
node .claude/skills/intelligent-router/scripts/analyze-intent.js analyze "Fix bug" --json

Integration with Hooks

Router integrates via .claude/hooks/pre-prompt.sh (optional):

#!/bin/bash
# Activate intelligent-router for every question
# Router internally checks if it should activate

Configuration

Customize Routing Matrix

Edit routing-matrix.json to:

• Add new routes
• Modify trigger keywords
• Adjust priorities
• Add custom agents/skills

Customize Auto-Detect

Edit auto_detect_config in routing-matrix.json:

{
  "min_word_count": 5,
  "action_verbs": ["maak", "bouw", "fix", ...],
  "skip_keywords": ["wat is", "hoe werkt", ...],
  "always_check_memory": true
}

Complexity Thresholds

Adjust in complexity_thresholds:

{
  "simple": {
    "max_words": 10,
    "max_domains": 1,
    "auto_dispatch": true
  },
  ...
}

Router Decision Tree

User Question
    ↓
[Should Activate?]
    ├─ No → Normal response (skip router)
    └─ Yes → Continue
         ↓
    [Find Matches]
         ↓
    [No Matches?]
         ├─ Yes → Normal response
         └─ No → Continue
              ↓
         [Analyze Complexity]
              ↓
         [Simple/Medium/High] → Auto-dispatch primary agent
         [Complex] → Dispatch master-orchestrator
              ↓
         [Display Analysis]
              ↓
         [Execute Dispatch]

Best Practices

For Users

• ✅ Be specific in your questions (better matching)
• ✅ Use action verbs when you want work done
• ✅ Trust the router's suggestions
• ✅ Dispatch optional agents if they make sense

For Developers

• ✅ Keep routing-matrix.json updated
• ✅ Add new routes for new capabilities
• ✅ Test routes with analyze-intent.js
• ✅ Monitor which routes get triggered most
• ✅ Refine trigger keywords based on usage

Troubleshooting

Router Not Activating

# Check question meets criteria
node scripts/analyze-intent.js analyze "your question"

# If "activate: false", question too simple
# Solution: Add more context or action verbs

Wrong Agent Dispatched

# Check routing matrix matches
cat routing-matrix.json | grep -A 5 "your_keyword"

# Update triggers if needed

Skills Not Loading

# Verify skills exist
node ../skill-loader.js list

# Check skill names in routing-matrix.json match

Metrics & Improvement

Track router effectiveness:

• Activation rate - How often it activates vs skips
• Accuracy - Did it pick right agent/skills?
• User satisfaction - Did suggestions help?
• Iteration count - How many back-and-forth needed?

Store in: .claude-memory/router-metrics.md

Version History

v1.0.0 (Initial Release)

• Smart auto-detect activation
• 20+ predefined routes
• Complexity assessment
• Multi-level skill loading
• Transparent reporting
• Optional agent suggestions

Future Enhancements

Planned features:

• [ ] Learning from past routing decisions
• [ ] User preference tracking
• [ ] Route effectiveness scoring
• [ ] Dynamic route creation
• [ ] Integration with episodic-memory for pattern learning
• [ ] Web UI for route visualization

Resources

• Routing Matrix: routing-matrix.json
• Intent Analyzer: scripts/analyze-intent.js
• Examples: examples/routing-scenarios.md
• Tests: examples/test-cases.md

---

Version: 1.0.0 Author: CLAUDE Framework Team License: MIT Compatibility: Claude Code 1.0+, Claude 3.5 Sonnet+