@girardmedia/bootspring 2.0.36 → 2.0.37

package/intelligence/agent-router.js

@@ -0,0 +1,795 @@
+/**
+ * Intelligent Agent Router
+ *
+ * Analyzes tasks and routes them to the most appropriate agent(s).
+ * Supports single-agent routing and multi-agent collaboration planning.
+ *
+ * @package bootspring
+ * @module intelligence/agent-router
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Expertise domains and their indicators
+ */
+const EXPERTISE_DOMAINS = {
+  database: {
+    name: 'Database & Data Modeling',
+    keywords: ['database', 'schema', 'model', 'migration', 'prisma', 'sql', 'table', 'relation', 'index', 'query'],
+    filePatterns: ['prisma/**', 'models/**', 'schema/**', 'migrations/**'],
+    agents: ['database-expert', 'prisma-expert', 'sql-expert']
+  },
+  security: {
+    name: 'Security & Authentication',
+    keywords: ['auth', 'security', 'password', 'token', 'jwt', 'session', 'permission', 'role', 'csrf', 'xss', 'encryption'],
+    filePatterns: ['**/auth/**', '**/security/**', 'middleware/**'],
+    agents: ['security-expert', 'auth-expert', 'crypto-expert']
+  },
+  frontend: {
+    name: 'Frontend & UI',
+    keywords: ['component', 'ui', 'react', 'vue', 'angular', 'css', 'style', 'responsive', 'animation', 'layout'],
+    filePatterns: ['components/**', 'pages/**', 'views/**', 'styles/**', '**/*.tsx', '**/*.jsx'],
+    agents: ['frontend-expert', 'react-expert', 'ui-expert', 'css-expert']
+  },
+  backend: {
+    name: 'Backend & API',
+    keywords: ['api', 'endpoint', 'route', 'controller', 'service', 'rest', 'graphql', 'server', 'middleware'],
+    filePatterns: ['api/**', 'routes/**', 'controllers/**', 'services/**'],
+    agents: ['backend-expert', 'api-expert', 'nodejs-expert']
+  },
+  testing: {
+    name: 'Testing & QA',
+    keywords: ['test', 'spec', 'mock', 'jest', 'vitest', 'cypress', 'coverage', 'e2e', 'unit', 'integration'],
+    filePatterns: ['**/*.test.*', '**/*.spec.*', '__tests__/**', 'tests/**'],
+    agents: ['testing-expert', 'qa-expert', 'e2e-expert']
+  },
+  devops: {
+    name: 'DevOps & Deployment',
+    keywords: ['deploy', 'docker', 'kubernetes', 'ci', 'cd', 'pipeline', 'aws', 'vercel', 'netlify', 'nginx'],
+    filePatterns: ['Dockerfile', 'docker-compose.*', '.github/**', 'deploy/**', 'infra/**'],
+    agents: ['devops-expert', 'docker-expert', 'aws-expert']
+  },
+  performance: {
+    name: 'Performance & Optimization',
+    keywords: ['performance', 'optimize', 'cache', 'lazy', 'bundle', 'speed', 'memory', 'profil', 'benchmark'],
+    filePatterns: [],
+    agents: ['performance-expert', 'optimization-expert']
+  },
+  architecture: {
+    name: 'Architecture & Design',
+    keywords: ['architecture', 'design', 'pattern', 'structure', 'refactor', 'module', 'layer', 'clean', 'solid'],
+    filePatterns: [],
+    agents: ['architect', 'design-expert', 'refactoring-expert']
+  },
+  payment: {
+    name: 'Payments & Commerce',
+    keywords: ['payment', 'stripe', 'checkout', 'subscription', 'billing', 'invoice', 'cart', 'order', 'commerce'],
+    filePatterns: ['**/payment/**', '**/checkout/**', '**/billing/**'],
+    agents: ['payment-expert', 'stripe-expert', 'ecommerce-expert']
+  },
+  realtime: {
+    name: 'Real-time & WebSockets',
+    keywords: ['websocket', 'socket', 'realtime', 'live', 'stream', 'push', 'notification', 'sse'],
+    filePatterns: ['**/socket/**', '**/realtime/**', '**/ws/**'],
+    agents: ['realtime-expert', 'websocket-expert']
+  }
+};
+
+/**
+ * Complexity assessment factors
+ */
+const COMPLEXITY_FACTORS = {
+  scope: {
+    single_file: 1,
+    few_files: 2,
+    module: 3,
+    cross_module: 4,
+    system_wide: 5
+  },
+  expertise: {
+    single_domain: 1,
+    two_domains: 2,
+    multi_domain: 3,
+    specialized: 4
+  },
+  risk: {
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4
+  },
+  dependencies: {
+    none: 1,
+    few: 2,
+    many: 3,
+    complex: 4
+  }
+};
+
+/**
+ * Collaboration patterns
+ */
+const COLLABORATION_PATTERNS = {
+  sequential: {
+    name: 'Sequential',
+    description: 'Agents work one after another, passing results forward',
+    bestFor: ['layered implementations', 'dependency chains', 'build pipelines']
+  },
+  parallel: {
+    name: 'Parallel',
+    description: 'Agents work simultaneously on independent parts',
+    bestFor: ['independent components', 'multi-module features', 'test suites']
+  },
+  iterative: {
+    name: 'Iterative',
+    description: 'Agents collaborate in review cycles until quality met',
+    bestFor: ['security reviews', 'performance optimization', 'refactoring']
+  },
+  hierarchical: {
+    name: 'Hierarchical',
+    description: 'Lead agent coordinates specialist agents',
+    bestFor: ['complex features', 'full-stack implementations', 'major refactors']
+  }
+};
+
+/**
+ * IntelligentAgentRouter class
+ */
+class IntelligentAgentRouter {
+  /**
+   * @param {Object} options - Configuration options
+   */
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.agentsDir = options.agentsDir || path.join(this.projectRoot, 'agents');
+    this.availableAgents = [];
+  }
+
+  /**
+   * Initialize the router by loading available agents
+   */
+  async initialize() {
+    await this.loadAvailableAgents();
+    return this;
+  }
+
+  /**
+   * Load available agents from the agents directory
+   */
+  async loadAvailableAgents() {
+    try {
+      const files = await fs.readdir(this.agentsDir);
+      const agentFiles = files.filter(f => f.endsWith('.json'));
+
+      this.availableAgents = [];
+      for (const file of agentFiles) {
+        try {
+          const content = await fs.readFile(path.join(this.agentsDir, file), 'utf-8');
+          const agent = JSON.parse(content);
+          this.availableAgents.push({
+            id: path.basename(file, '.json'),
+            ...agent
+          });
+        } catch {
+          // Skip invalid agent files
+        }
+      }
+    } catch {
+      this.availableAgents = [];
+    }
+  }
+
+  /**
+   * Route a task to appropriate agent(s)
+   * @param {string} task - Task description
+   * @param {Object} context - Additional context
+   */
+  async route(task, context = {}) {
+    // Analyze the task
+    const complexity = await this.assessComplexity(task, context);
+    const expertise = await this.identifyExpertise(task, context);
+
+    // Check if collaboration is needed
+    const needsCollaboration = this.needsMultipleAgents(task, expertise, complexity);
+
+    if (needsCollaboration) {
+      return this.planAgentCollaboration(task, expertise, complexity, context);
+    }
+
+    // Single agent routing
+    return this.routeToSingleAgent(task, expertise, complexity, context);
+  }
+
+  /**
+   * Assess task complexity
+   * @param {string} task - Task description
+   * @param {Object} context - Additional context
+   */
+  async assessComplexity(task, context = {}) {
+    const analysis = {
+      score: 0,
+      factors: {},
+      level: 'low'
+    };
+
+    const taskLower = task.toLowerCase();
+
+    // Assess scope
+    if (taskLower.includes('entire') || taskLower.includes('all') || taskLower.includes('system')) {
+      analysis.factors.scope = COMPLEXITY_FACTORS.scope.system_wide;
+    } else if (taskLower.includes('module') || taskLower.includes('feature')) {
+      analysis.factors.scope = COMPLEXITY_FACTORS.scope.cross_module;
+    } else if (taskLower.includes('component') || taskLower.includes('file')) {
+      analysis.factors.scope = COMPLEXITY_FACTORS.scope.few_files;
+    } else {
+      analysis.factors.scope = COMPLEXITY_FACTORS.scope.single_file;
+    }
+
+    // Assess expertise breadth
+    const expertiseAreas = this.detectExpertiseAreas(task);
+    if (expertiseAreas.length > 2) {
+      analysis.factors.expertise = COMPLEXITY_FACTORS.expertise.multi_domain;
+    } else if (expertiseAreas.length === 2) {
+      analysis.factors.expertise = COMPLEXITY_FACTORS.expertise.two_domains;
+    } else {
+      analysis.factors.expertise = COMPLEXITY_FACTORS.expertise.single_domain;
+    }
+
+    // Assess risk
+    const riskKeywords = ['security', 'payment', 'data', 'migration', 'production', 'delete', 'remove'];
+    const hasRiskKeywords = riskKeywords.some(kw => taskLower.includes(kw));
+    if (hasRiskKeywords) {
+      analysis.factors.risk = COMPLEXITY_FACTORS.risk.high;
+    } else if (taskLower.includes('refactor') || taskLower.includes('change')) {
+      analysis.factors.risk = COMPLEXITY_FACTORS.risk.medium;
+    } else {
+      analysis.factors.risk = COMPLEXITY_FACTORS.risk.low;
+    }
+
+    // Assess dependencies
+    const depKeywords = ['integrate', 'connect', 'sync', 'depend', 'require'];
+    if (depKeywords.some(kw => taskLower.includes(kw))) {
+      analysis.factors.dependencies = COMPLEXITY_FACTORS.dependencies.many;
+    } else {
+      analysis.factors.dependencies = COMPLEXITY_FACTORS.dependencies.few;
+    }
+
+    // Calculate total score
+    analysis.score = Object.values(analysis.factors).reduce((sum, val) => sum + val, 0);
+
+    // Determine level
+    if (analysis.score >= 12) {
+      analysis.level = 'very_high';
+    } else if (analysis.score >= 9) {
+      analysis.level = 'high';
+    } else if (analysis.score >= 6) {
+      analysis.level = 'medium';
+    } else {
+      analysis.level = 'low';
+    }
+
+    // Determine context needed
+    analysis.contextNeeded = analysis.level === 'very_high' ? 'deep' :
+                             analysis.level === 'high' ? 'standard' : 'minimal';
+
+    return analysis;
+  }
+
+  /**
+   * Detect expertise areas from task
+   * @param {string} task - Task description
+   */
+  detectExpertiseAreas(task) {
+    const taskLower = task.toLowerCase();
+    const areas = [];
+
+    for (const [domain, config] of Object.entries(EXPERTISE_DOMAINS)) {
+      const matchCount = config.keywords.filter(kw => taskLower.includes(kw)).length;
+      if (matchCount > 0) {
+        areas.push({
+          domain,
+          name: config.name,
+          matchCount,
+          confidence: Math.min(1.0, matchCount / 3)
+        });
+      }
+    }
+
+    return areas.sort((a, b) => b.matchCount - a.matchCount);
+  }
+
+  /**
+   * Identify required expertise for a task
+   * @param {string} task - Task description
+   * @param {Object} context - Additional context
+   */
+  async identifyExpertise(task, context = {}) {
+    const areas = this.detectExpertiseAreas(task);
+    const affectedFiles = context.affectedFiles || [];
+
+    // Enhance with file pattern matching
+    for (const file of affectedFiles) {
+      for (const [domain, config] of Object.entries(EXPERTISE_DOMAINS)) {
+        for (const pattern of config.filePatterns) {
+          const regex = this.globToRegex(pattern);
+          if (regex.test(file)) {
+            const existing = areas.find(a => a.domain === domain);
+            if (existing) {
+              existing.confidence = Math.min(1.0, existing.confidence + 0.2);
+            } else {
+              areas.push({
+                domain,
+                name: config.name,
+                matchCount: 1,
+                confidence: 0.5
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      primary: areas[0] || null,
+      secondary: areas.slice(1, 3),
+      all: areas,
+      isMultiDomain: areas.length > 1
+    };
+  }
+
+  /**
+   * Convert glob pattern to regex
+   * @param {string} glob - Glob pattern
+   */
+  globToRegex(glob) {
+    const escaped = glob
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*\*/g, '.*')
+      .replace(/\*/g, '[^/]*');
+    return new RegExp(escaped);
+  }
+
+  /**
+   * Check if task needs multiple agents
+   * @param {string} task - Task description
+   * @param {Object} expertise - Expertise analysis
+   * @param {Object} complexity - Complexity analysis
+   */
+  needsMultipleAgents(task, expertise, complexity) {
+    // Multi-domain tasks need collaboration
+    if (expertise.isMultiDomain && expertise.all.length >= 2) {
+      return true;
+    }
+
+    // High complexity tasks may need collaboration
+    if (complexity.level === 'very_high' || complexity.level === 'high') {
+      return true;
+    }
+
+    // Risk-heavy tasks benefit from review
+    if (complexity.factors.risk >= 3) {
+      return true;
+    }
+
+    // System-wide scope needs coordination
+    if (complexity.factors.scope >= 4) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Route to a single agent
+   * @param {string} task - Task description
+   * @param {Object} expertise - Expertise analysis
+   * @param {Object} complexity - Complexity analysis
+   * @param {Object} context - Additional context
+   */
+  routeToSingleAgent(task, expertise, complexity, context) {
+    const primaryDomain = expertise.primary?.domain || 'backend';
+    const domainConfig = EXPERTISE_DOMAINS[primaryDomain];
+
+    // Find best matching available agent
+    const primaryAgent = this.findBestAgent(domainConfig.agents, expertise);
+
+    // Find fallback agents
+    const fallbackAgents = this.findFallbackAgents(domainConfig.agents, primaryAgent);
+
+    return {
+      mode: 'single',
+      primaryAgent,
+      fallbackAgents,
+      expertise: expertise.primary,
+      complexity,
+      contextLevel: complexity.contextNeeded,
+      suggestedApproach: this.planApproach(task, complexity),
+      estimatedEffort: this.estimateEffort(complexity)
+    };
+  }
+
+  /**
+   * Plan multi-agent collaboration
+   * @param {string} task - Task description
+   * @param {Object} expertise - Expertise analysis
+   * @param {Object} complexity - Complexity analysis
+   * @param {Object} context - Additional context
+   */
+  planAgentCollaboration(task, expertise, complexity, context) {
+    // Determine collaboration pattern
+    const pattern = this.selectCollaborationPattern(task, expertise, complexity);
+
+    // Build agent sequence
+    const agents = this.buildAgentSequence(expertise, pattern, context);
+
+    // Define handoff points
+    const handoffs = this.defineHandoffs(agents, pattern);
+
+    return {
+      mode: 'collaboration',
+      collaborationType: pattern.name.toLowerCase(),
+      pattern,
+      agents,
+      handoffPoints: handoffs,
+      coordinatorAgent: this.selectCoordinator(agents, complexity),
+      complexity,
+      suggestedApproach: this.planCollaborativeApproach(task, pattern, agents),
+      estimatedEffort: this.estimateCollaborativeEffort(agents, complexity)
+    };
+  }
+
+  /**
+   * Select best collaboration pattern
+   * @param {string} task - Task description
+   * @param {Object} expertise - Expertise analysis
+   * @param {Object} complexity - Complexity analysis
+   */
+  selectCollaborationPattern(task, expertise, complexity) {
+    const taskLower = task.toLowerCase();
+
+    // Security or review tasks -> iterative
+    if (taskLower.includes('review') || taskLower.includes('security') || taskLower.includes('audit')) {
+      return COLLABORATION_PATTERNS.iterative;
+    }
+
+    // Independent components -> parallel
+    if (taskLower.includes('component') || expertise.all.length >= 3) {
+      return COLLABORATION_PATTERNS.parallel;
+    }
+
+    // Complex full-stack -> hierarchical
+    if (complexity.level === 'very_high') {
+      return COLLABORATION_PATTERNS.hierarchical;
+    }
+
+    // Default to sequential
+    return COLLABORATION_PATTERNS.sequential;
+  }
+
+  /**
+   * Build agent sequence for collaboration
+   * @param {Object} expertise - Expertise analysis
+   * @param {Object} pattern - Collaboration pattern
+   * @param {Object} context - Additional context
+   */
+  buildAgentSequence(expertise, pattern, context) {
+    const agents = [];
+    let phase = 1;
+
+    // Add agents based on expertise areas
+    for (const area of expertise.all) {
+      const domainConfig = EXPERTISE_DOMAINS[area.domain];
+      const agent = this.findBestAgent(domainConfig.agents, expertise);
+
+      if (agent && !agents.find(a => a.agent === agent)) {
+        agents.push({
+          agent,
+          domain: area.domain,
+          phase: pattern.name === 'Parallel' ? 1 : phase++,
+          focus: `Handle ${area.name} aspects`,
+          confidence: area.confidence,
+          input: phase > 1 ? agents[agents.length - 1]?.output : null,
+          output: `${area.domain} implementation`
+        });
+      }
+    }
+
+    // Ensure at least 2 agents for collaboration
+    if (agents.length < 2 && expertise.primary) {
+      const reviewAgent = this.findReviewAgent(expertise.primary.domain);
+      if (reviewAgent) {
+        agents.push({
+          agent: reviewAgent,
+          domain: 'review',
+          phase: agents.length + 1,
+          focus: 'Review and validate implementation',
+          input: agents[agents.length - 1]?.output,
+          output: 'Validated implementation'
+        });
+      }
+    }
+
+    return agents;
+  }
+
+  /**
+   * Find best matching agent from candidates
+   * @param {Array} candidates - Candidate agent names
+   * @param {Object} expertise - Expertise analysis
+   */
+  findBestAgent(candidates, expertise) {
+    // Check against available agents
+    for (const candidate of candidates) {
+      const available = this.availableAgents.find(a =>
+        a.id === candidate ||
+        a.name?.toLowerCase().includes(candidate.replace('-expert', '')) ||
+        a.expertise?.includes(expertise.primary?.domain)
+      );
+      if (available) {
+        return available.id;
+      }
+    }
+
+    // Return first candidate as default
+    return candidates[0] || 'general-expert';
+  }
+
+  /**
+   * Find fallback agents
+   * @param {Array} candidates - Candidate agent names
+   * @param {string} primaryAgent - Primary agent already selected
+   */
+  findFallbackAgents(candidates, primaryAgent) {
+    return candidates
+      .filter(c => c !== primaryAgent)
+      .slice(0, 2);
+  }
+
+  /**
+   * Find a review agent for a domain
+   * @param {string} domain - Primary domain
+   */
+  findReviewAgent(domain) {
+    const reviewAgents = {
+      database: 'database-reviewer',
+      security: 'security-auditor',
+      frontend: 'ui-reviewer',
+      backend: 'code-reviewer',
+      default: 'code-reviewer'
+    };
+
+    return reviewAgents[domain] || reviewAgents.default;
+  }
+
+  /**
+   * Define handoff points between agents
+   * @param {Array} agents - Agent sequence
+   * @param {Object} pattern - Collaboration pattern
+   */
+  defineHandoffs(agents, pattern) {
+    const handoffs = [];
+
+    if (pattern.name === 'Sequential' || pattern.name === 'Hierarchical') {
+      for (let i = 0; i < agents.length - 1; i++) {
+        handoffs.push({
+          from: agents[i].agent,
+          to: agents[i + 1].agent,
+          artifact: agents[i].output,
+          validation: this.getHandoffValidation(agents[i], agents[i + 1])
+        });
+      }
+    } else if (pattern.name === 'Iterative') {
+      // Create review loop
+      if (agents.length >= 2) {
+        handoffs.push({
+          from: agents[0].agent,
+          to: agents[1].agent,
+          artifact: 'Implementation',
+          validation: 'Review and feedback'
+        });
+        handoffs.push({
+          from: agents[1].agent,
+          to: agents[0].agent,
+          artifact: 'Feedback',
+          validation: 'Address feedback',
+          isLoop: true
+        });
+      }
+    }
+
+    return handoffs;
+  }
+
+  /**
+   * Get validation requirements for a handoff
+   * @param {Object} fromAgent - Source agent
+   * @param {Object} toAgent - Target agent
+   */
+  getHandoffValidation(fromAgent, toAgent) {
+    const validations = {
+      'database-review': 'Schema validation and migration check',
+      'security-review': 'Security audit and vulnerability scan',
+      'code-review': 'Code quality and pattern compliance',
+      'test-review': 'Test coverage and passing status'
+    };
+
+    return validations[`${fromAgent.domain}-${toAgent.domain}`] ||
+           `Validate ${fromAgent.output}`;
+  }
+
+  /**
+   * Select coordinator for hierarchical collaboration
+   * @param {Array} agents - Agent sequence
+   * @param {Object} complexity - Complexity analysis
+   */
+  selectCoordinator(agents, complexity) {
+    // For very complex tasks, use architect
+    if (complexity.level === 'very_high') {
+      return 'architect';
+    }
+
+    // Otherwise, the first agent coordinates
+    return agents[0]?.agent || 'project-lead';
+  }
+
+  /**
+   * Plan approach for single agent
+   * @param {string} task - Task description
+   * @param {Object} complexity - Complexity analysis
+   */
+  planApproach(task, complexity) {
+    if (complexity.level === 'low') {
+      return {
+        steps: ['Implement directly', 'Test', 'Complete'],
+        reviewNeeded: false
+      };
+    }
+
+    return {
+      steps: [
+        'Analyze existing code',
+        'Plan implementation',
+        'Implement changes',
+        'Write/update tests',
+        'Review and refine',
+        'Complete'
+      ],
+      reviewNeeded: complexity.factors.risk >= 2
+    };
+  }
+
+  /**
+   * Plan collaborative approach
+   * @param {string} task - Task description
+   * @param {Object} pattern - Collaboration pattern
+   * @param {Array} agents - Agent sequence
+   */
+  planCollaborativeApproach(task, pattern, agents) {
+    return {
+      pattern: pattern.name,
+      steps: agents.map(a => ({
+        agent: a.agent,
+        phase: a.phase,
+        action: a.focus
+      })),
+      coordination: pattern.name === 'Hierarchical' ? 'Lead agent coordinates' : 'Self-coordinated',
+      reviewCycles: pattern.name === 'Iterative' ? 2 : 1
+    };
+  }
+
+  /**
+   * Estimate effort for single agent
+   * @param {Object} complexity - Complexity analysis
+   */
+  estimateEffort(complexity) {
+    const baseHours = {
+      low: 1,
+      medium: 3,
+      high: 8,
+      very_high: 16
+    };
+
+    const hours = baseHours[complexity.level] || 4;
+
+    return {
+      hours,
+      range: `${Math.round(hours * 0.7)}-${Math.round(hours * 1.5)} hours`,
+      confidence: complexity.level === 'low' ? 'high' : 'medium'
+    };
+  }
+
+  /**
+   * Estimate effort for collaboration
+   * @param {Array} agents - Agent sequence
+   * @param {Object} complexity - Complexity analysis
+   */
+  estimateCollaborativeEffort(agents, complexity) {
+    const singleEstimate = this.estimateEffort(complexity);
+    const agentCount = agents.length;
+
+    // Collaboration overhead
+    const overheadFactor = 1 + (agentCount - 1) * 0.3;
+
+    const hours = singleEstimate.hours * overheadFactor;
+
+    return {
+      hours: Math.round(hours),
+      range: `${Math.round(hours * 0.7)}-${Math.round(hours * 1.5)} hours`,
+      confidence: 'medium',
+      breakdown: agents.map(a => ({
+        agent: a.agent,
+        estimatedHours: Math.round(hours / agentCount)
+      }))
+    };
+  }
+
+  /**
+   * Get routing recommendation for a task
+   * @param {string} task - Task description
+   * @param {Object} context - Additional context
+   */
+  async getRecommendation(task, context = {}) {
+    const routing = await this.route(task, context);
+
+    return {
+      routing,
+      reasoning: this.explainRouting(routing),
+      alternatives: this.suggestAlternatives(routing)
+    };
+  }
+
+  /**
+   * Explain routing decision
+   * @param {Object} routing - Routing result
+   */
+  explainRouting(routing) {
+    const reasons = [];
+
+    if (routing.mode === 'single') {
+      reasons.push(`Task matches ${routing.expertise?.name || 'general'} expertise`);
+      reasons.push(`Complexity level: ${routing.complexity.level}`);
+      reasons.push(`Single agent sufficient for this task`);
+    } else {
+      reasons.push(`Multi-domain task requires collaboration`);
+      reasons.push(`${routing.pattern.name} pattern selected: ${routing.pattern.description}`);
+      reasons.push(`${routing.agents.length} agents involved`);
+    }
+
+    return reasons;
+  }
+
+  /**
+   * Suggest alternative routing options
+   * @param {Object} routing - Current routing result
+   */
+  suggestAlternatives(routing) {
+    const alternatives = [];
+
+    if (routing.mode === 'single' && routing.complexity.level !== 'low') {
+      alternatives.push({
+        mode: 'collaboration',
+        reason: 'Consider adding a reviewer for higher quality',
+        agents: [routing.primaryAgent, 'code-reviewer']
+      });
+    }
+
+    if (routing.mode === 'collaboration' && routing.agents.length > 2) {
+      alternatives.push({
+        mode: 'single',
+        reason: 'Could simplify by using primary expert only',
+        agent: routing.agents[0]?.agent
+      });
+    }
+
+    return alternatives;
+  }
+}
+
+module.exports = {
+  IntelligentAgentRouter,
+  EXPERTISE_DOMAINS,
+  COMPLEXITY_FACTORS,
+  COLLABORATION_PATTERNS
+};