🧭 Intelligent Routing

The Route system uses Q-Learning to automatically assign tasks to the best agent based on learned performance patterns.

How Routing Works

┌─────────────────────────────────────────────────────────────────────┐
│                     INTELLIGENT ROUTING                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Task: "Fix authentication bug"                                     │
│           │                                                         │
│           ▼                                                         │
│  ┌─────────────────┐                                                │
│  │ Analyze Task    │ ← Complexity, domain, keywords                 │
│  └────────┬────────┘                                                │
│           │                                                         │
│           ▼                                                         │
│  ┌─────────────────┐                                                │
│  │ Q-Learning      │ ← Historical success rates per agent           │
│  │ Lookup          │                                                │
│  └────────┬────────┘                                                │
│           │                                                         │
│           ▼                                                         │
│  ┌─────────────────┐                                                │
│  │ Recommend:      │                                                │
│  │ security-arch   │ → 94% confidence (auth domain expert)          │
│  └─────────────────┘                                                │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Route Commands

Command	What It Does	Example
route task	Get agent recommendation	npx ruflo@latest route task "implement OAuth2"
route explain	Understand routing decision	npx ruflo@latest route explain "task"
route coverage	Route based on test coverage	npx ruflo@latest route coverage

Example: Route a Task

bash
npx ruflo@latest route task "refactor authentication to use JWT"

# Output:
# ╔══════════════════════════════════════════════════════════════╗
# ║                    ROUTING RECOMMENDATION                     ║
# ╠══════════════════════════════════════════════════════════════╣
# ║ Task: "refactor authentication to use JWT"                    ║
# ║                                                                ║
# ║ Recommended Agent: security-architect                         ║
# ║ Confidence: 94%                                                ║
# ║                                                                ║
# ║ Why this agent?                                                ║
# ║ • Domain match: authentication, security                       ║
# ║ • Historical success: 12/13 similar tasks (92%)                ║
# ║ • Expertise: JWT, OAuth, session management                    ║
# ║                                                                ║
# ║ Alternative agents:                                            ║
# ║ • coder (78% confidence) - general implementation              ║
# ║ • backend-dev (71% confidence) - API expertise                 ║
# ╚══════════════════════════════════════════════════════════════╝

Coverage-Aware Routing

Routes tasks to agents based on test coverage gaps:

bash
npx ruflo@latest route coverage

# Finds untested code and routes to tester agent:
# • src/auth/jwt.ts - 23% coverage → tester
# • src/api/users.ts - 45% coverage → tester
# • src/utils/crypto.ts - 0% coverage → security-architect + tester

Routing Hooks

bash
# Route via hooks (preferred)
npx ruflo@latest hooks route "implement caching layer" --include-explanation

# Record outcome for learning
npx ruflo@latest hooks post-task --task-id "task-123" --success true --agent coder

How Q-Learning Improves Over Time

Iteration	Action	Result
1	Route "auth task" → coder	❌ Failed (missing security context)
2	Route "auth task" → security-architect	✅ Success
3	Route "auth task" → security-architect	✅ Success
N	Route "auth task" → security-architect	94% confidence (learned)

The system remembers what works and applies it to future similar tasks.