JoelBonito/intelligent-routing

Intelligent Agent Routing

Purpose: Automatically analyze user requests and route them to the most appropriate specialist agent(s) without requiring explicit user mentions.

Core Principle

The AI should act as an intelligent Project Manager, analyzing each request and automatically selecting the best specialist(s) for the job.

How It Works

1. Request Analysis

Before responding to ANY user request, perform automatic analysis:

graph TD
    A[User Request: Add login] --> B[ANALYZE]
    B --> C[Keywords]
    B --> D[Domains]
    B --> E[Complexity]
    C --> F[SELECT AGENT]
    D --> F
    E --> F
    F --> G[security-auditor + backend-specialist]
    G --> H[AUTO-INVOKE with context]

2. Agent Selection Matrix

Use this matrix to automatically select agents:

| User Intent | Keywords | Selected Agent(s) | Auto-invoke? | | ------------------- | ------------------------------------------ | ------------------------------------------- | ------------ | | Authentication | "login", "auth", "signup", "password" | security-auditor + backend-specialist | ✅ YES | | UI Component | "button", "card", "layout", "style" | frontend-specialist | ✅ YES | | Mobile UI | "screen", "navigation", "touch", "gesture" | mobile-developer | ✅ YES | | API Endpoint | "endpoint", "route", "API", "POST", "GET" | backend-specialist | ✅ YES | | Database | "schema", "migration", "query", "table" | database-architect + backend-specialist | ✅ YES | | Bug Fix | "error", "bug", "not working", "broken" | debugger | ✅ YES | | Unit/Integration Test | "test", "unit test", "coverage", "TDD", "jest", "vitest", "pytest", "mock" | test-engineer | ✅ YES | | E2E/QA Pipeline | "e2e", "playwright", "cypress", "pipeline", "regression", "automated test" | qa-automation-engineer | ✅ YES | | Deployment | "deploy", "production", "CI/CD", "docker" | devops-engineer | ✅ YES | | Security Review | "security", "vulnerability", "exploit" | security-auditor + penetration-tester | ✅ YES | | Performance | "slow", "optimize", "performance", "speed" | performance-optimizer | ✅ YES | | New Feature | "build", "create", "implement", "new app" | orchestrator → multi-agent | ⚠️ ASK FIRST | | Complex Task | Multiple domains detected | orchestrator → multi-agent | ⚠️ ASK FIRST |

3. Automatic Routing Protocol

TIER 0 - Automatic Analysis (ALWAYS ACTIVE)

Before responding to ANY request:

// Pseudo-code for decision tree
function analyzeRequest(userMessage) {
    // 0. Context-Aware Read (Silent)
    // Read package.json, ARCHITECTURE.md or config files to define the Stack
    const projectStack = detectContextDrivenStack();

    // 1. Classify request type
    const requestType = classifyRequest(userMessage);

    // 2. Detect domains (Weighing in the projectStack)
    const domains = detectDomains(userMessage, projectStack);

    // 3. Determine complexity
    const complexity = assessComplexity(domains);

    // 4. Select agent(s)
    if (complexity === "SIMPLE" && domains.length === 1) {
        return selectSingleAgent(domains[0]);
    } else if (complexity === "MODERATE" && domains.length <= 2) {
        return selectMultipleAgents(domains);
    } else {
        return "orchestrator"; // Complex task
    }
}

4. Response Format

When auto-selecting an agent, inform the user concisely:

🤖 **Applying knowledge of `@security-auditor` + `@backend-specialist`...**

[Proceed with specialized response]

Benefits:

• ✅ User sees which expertise is being applied
• ✅ Transparent decision-making
• ✅ Still automatic (no /commands needed)

Domain Detection Rules

Single-Domain Tasks (Auto-invoke Single Agent)

| Domain | Patterns | Agent | | --------------- | ------------------------------------------ | ----------------------- | | Security | auth, login, jwt, password, hash, token | security-auditor | | Frontend | component, react, vue, css, html, tailwind | frontend-specialist | | Backend | api, server, express, fastapi, node | backend-specialist | | Mobile | react native, flutter, ios, android, expo | mobile-developer | | Database | prisma, sql, mongodb, schema, migration | database-architect | | Unit/Integration | test, unit test, jest, vitest, pytest, coverage, TDD, mock, integration | test-engineer | | E2E/QA Pipeline | e2e, playwright, cypress, pipeline, regression, automated test | qa-automation-engineer | | DevOps | docker, kubernetes, ci/cd, pm2, nginx | devops-engineer | | Debug | error, bug, crash, not working, issue | debugger | | Performance | slow, lag, optimize, cache, performance | performance-optimizer | | SEO | seo, meta, analytics, sitemap, robots | seo-specialist | | Game | unity, godot, phaser, game, multiplayer | game-developer | | Automation | n8n, workflow, webhook, integration | n8n-specialist (Auto-activates squad: see below) |

Squad Auto-Activation (e.g. n8n-automation)

If you detect requests matching domains that belong to a Squad (like n8n, workflow automation, or integrations for the n8n-automation squad), SILENTLY execute the following command before replying or invoking standard agents:

python3 .agents/scripts/squad_manager.py auto-activate <squad-name>

For example, for n8n: python3 .agents/scripts/squad_manager.py auto-activate n8n-automation. Then proceed seamlessly using n8n-specialist.

Multi-Domain Tasks (Auto-invoke Orchestrator)

If request matches 2+ domains from different categories, automatically use orchestrator:

Example: "Create a secure login system with dark mode UI"
→ Detected: Security + Frontend
→ Auto-invoke: orchestrator
→ Orchestrator will handle: security-auditor, frontend-specialist, test-engineer

Complexity Assessment

SIMPLE (Direct agent invocation)

• Single file edit
• Clear, specific task
• One domain only
• Example: "Fix the login button style"

Action: Auto-invoke respective agent

MODERATE (2-3 agents)

• 2-3 files affected
• Clear requirements
• 2 domains max
• Example: "Add API endpoint for user profile"

Action: Auto-invoke relevant agents sequentially

COMPLEX (Orchestrator required)

• Multiple files/domains
• Architectural decisions needed
• Unclear requirements
• Example: "Build a social media app"

Action: Auto-invoke orchestrator → will ask Socratic questions

Implementation Rules

Rule 1: Silent Analysis

DO NOT announce "I'm analyzing your request..."

• ✅ Analyze silently
• ✅ Inform which agent is being applied
• ❌ Avoid verbose meta-commentary

Rule 2: Inform Agent Selection

DO inform which expertise is being applied:

🤖 **Applying knowledge of `@frontend-specialist`...**

I will create the component with the following characteristics:
[Continue with specialized response]

Rule 3: Seamless Experience

The user should not notice a difference from talking to the right specialist directly.

Rule 4: Override Capability

User can still explicitly mention agents:

User: "Use @backend-specialist to review this"
→ Override auto-selection
→ Use explicitly mentioned agent

Edge Cases

Case 1: Generic Question

User: "How does React work?"
→ Type: QUESTION
→ No agent needed
→ Respond directly with explanation

Case 2: Extremely Vague Request

User: "Make it better"
→ Complexity: UNCLEAR
→ Action: Ask clarifying questions first
→ Then route to appropriate agent

Case 3: Contradictory Patterns

User: "Add mobile support to the web app"
→ Conflict: mobile vs web
→ Action: Ask: "Do you want responsive web or native mobile app?"
→ Then route accordingly

Integration with Existing Workflows

With /orchestrate Command

• User types /orchestrate: Explicit orchestration mode
• AI detects complex task: Auto-invoke orchestrator (same result)

Difference: User doesn't need to know the command exists.

With Socratic Gate

• Auto-routing does NOT bypass Socratic Gate
• If task is unclear, still ask questions first
• Then route to appropriate agent

Platform Priority Rules

• Priority: Platform instruction file > intelligent-routing skill
  • Claude Code: CLAUDE.md rules take priority
  • Codex CLI: AGENTS.md rules take priority
  • Gemini CLI: GEMINI.md rules take priority
• If the platform file specifies explicit routing, follow it
• Intelligent routing is the DEFAULT when no explicit platform rule exists

Mixed-Keyword Precedence

When a request contains keywords from multiple testing domains:

• "test" + any E2E keyword (playwright, cypress, e2e, pipeline) → qa-automation-engineer wins
• "CI/CD" in test/pipeline context → qa-automation-engineer
• "CI/CD" in deploy/infra context → devops-engineer
• "test" alone (no E2E context) → test-engineer (default)

With Context-Aware Routing (Opção A)

• Step Zero: The router must silently check context files (e.g., package.json, ARCHITECTURE.md) when determining domains.
• If the project is exclusively a "Web Environment", the router avoids invoking -mobile or unrelated specific agents strictly by keyword matching.

Testing the System

Test Cases

Test 1: Simple Frontend Task

User: "Create a dark mode toggle button"
Expected: Auto-invoke frontend-specialist
Verify: Response shows "Using @frontend-specialist"

Test 2: Security Task

User: "Review the authentication flow for vulnerabilities"
Expected: Auto-invoke security-auditor
Verify: Security-focused analysis

Test 3: Complex Multi-Domain

User: "Build a chat application with real-time notifications"
Expected: Auto-invoke orchestrator
Verify: Multiple agents coordinated (backend, frontend, test)

Test 4: Bug Fix

User: "Login is not working, getting 401 error"
Expected: Auto-invoke debugger
Verify: Systematic debugging approach

Performance Considerations

Token Usage

• Analysis adds ~50-100 tokens per request
• Tradeoff: Better accuracy vs slight overhead
• Overall SAVES tokens by reducing back-and-forth

Response Time

• Analysis is instant (pattern matching)
• No additional API calls required
• Agent selection happens before first response

User Education

Optional: First-Time Explanation

If this is the first interaction in a project:

💡 **Tip**: I am configured with automatic specialist agent selection.
I will always choose the most suitable specialist for your task. You can
still mention agents explicitly with `@agent-name` if you prefer.

Debugging Agent Selection

Enable Debug Mode (for development)

Add to the platform instruction file temporarily:

## DEBUG: Intelligent Routing

Show selection reasoning:

- Detected domains: [list]
- Selected agent: [name]
- Reasoning: [why]

Summary

intelligent-routing skill enables:

✅ Zero-command operation (no need for /orchestrate)
✅ Automatic specialist selection based on request analysis
✅ Transparent communication of which expertise is being applied
✅ Seamless integration with existing workflows
✅ Override capability for explicit agent mentions
✅ Fallback to orchestrator for complex tasks

Result: User gets specialist-level responses without needing to know the system architecture.