tomevault-io 🎯 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:
- User asks question with 5+ words
- Question contains action verbs
- 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+
Converted and distributed by TomeVault — claim your Tome and manage your conversions.