@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/scripts/hooks/prompt-router.js

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+
+/**
+ * Prompt Router Hook - Intelligent Prompt Preprocessing
+ *
+ * This hook runs on UserPromptSubmit to:
+ * 1. Detect user intent from natural language
+ * 2. Suggest or auto-convert to optimal commands
+ * 3. Track workflow state and warn about skipped phases
+ * 4. Log routing decisions for analytics
+ *
+ * Performance Target: <100ms (non-blocking)
+ *
+ * Hook Type: UserPromptSubmit
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Import utilities
+const { readStdinJson, log, output, getClaudeDir, ensureDir } = require('../lib/utils');
+
+// Import router components
+const { classifyIntent, INTENT_TYPES, THRESHOLDS } = require('../lib/intent-classifier');
+const { matchCommand, formatCommand } = require('../lib/command-matcher');
+const {
+  getWorkflowState,
+  startWorkflow,
+  advancePhase,
+  checkSkippedPhases,
+  getNextPhase,
+  isCriticalPhase,
+  detectWorkflowType,
+} = require('../lib/workflow-state');
+
+// Configuration defaults
+const DEFAULT_CONFIG = {
+  enabled: true,
+  autoConvertThreshold: 0.8,
+  suggestionThreshold: 0.5,
+  workflowEnforcement: 'warn', // 'suggest' | 'warn' | 'block'
+  analytics: {
+    enabled: true,
+    logFile: null, // Will be set dynamically
+  },
+  debug: false,
+};
+
+/**
+ * Load configuration from file or use defaults
+ */
+function loadConfig() {
+  const configPath = path.join(__dirname, '..', '..', 'config', 'prompt-router.json');
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, 'utf8');
+      const userConfig = JSON.parse(content);
+      return { ...DEFAULT_CONFIG, ...userConfig };
+    }
+  } catch (err) {
+    // Config error - use defaults
+    log(`[PromptRouter] Config error: ${err.message}, using defaults`);
+  }
+
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Check if routing is disabled via environment variable
+ */
+function isDisabled() {
+  return process.env.DISABLE_PROMPT_ROUTER === 'true';
+}
+
+/**
+ * Log routing decision for analytics
+ */
+function logRoutingDecision(decision) {
+  const config = loadConfig();
+
+  if (!config.analytics?.enabled) {
+    return;
+  }
+
+  try {
+    const analyticsDir = path.join(getClaudeDir(), 'analytics');
+    ensureDir(analyticsDir);
+
+    const logFile = path.join(analyticsDir, 'routing-decisions.json');
+
+    // Read existing log or create new
+    let logData = [];
+    if (fs.existsSync(logFile)) {
+      try {
+        const content = fs.readFileSync(logFile, 'utf8');
+        logData = JSON.parse(content);
+      } catch {
+        logData = [];
+      }
+    }
+
+    // Add new decision (keep last 1000 entries)
+    logData.push({
+      ...decision,
+      timestamp: new Date().toISOString(),
+    });
+
+    if (logData.length > 1000) {
+      logData = logData.slice(-1000);
+    }
+
+    fs.writeFileSync(logFile, JSON.stringify(logData, null, 2));
+  } catch (err) {
+    // Silent fail - don't block on analytics errors
+  }
+}
+
+/**
+ * Model reason explanations - helps users understand WHY a model is suggested
+ */
+const MODEL_REASONS = {
+  opus: {
+    PLANNING: 'complex planning requires deep reasoning',
+    ARCHITECTURE: 'system design needs comprehensive analysis',
+    SECURITY: 'security review requires thorough examination',
+    COMPLIANCE: 'regulatory compliance needs careful attention',
+    ZOHO: 'Zoho architecture decisions are complex',
+  },
+  sonnet: {
+    TESTING: 'test execution is well-defined',
+    REVIEW: 'code review is routine work',
+    DEBUG: 'build fixes follow clear patterns',
+    REFACTOR: 'cleanup is straightforward',
+    DEPLOY: 'deployment verification is procedural',
+  },
+};
+
+/**
+ * Intent to workflow sequence mapping
+ * Returns the recommended workflow phases for a given intent
+ */
+const INTENT_WORKFLOWS = {
+  PLANNING: 'plan → tdd → review → verify',
+  TESTING: 'tdd → verify',
+  REVIEW: 'review → verify',
+  SECURITY: 'security-review → verify',
+  COMPLIANCE: 'compliance-check → review → verify',
+  DEBUG: 'investigate → fix → verify',
+  REFACTOR: 'plan → refactor → review → verify',
+  ZOHO: 'architect → deluge-review → deploy → verify',
+  DEPLOY: 'verify → deploy',
+};
+
+/**
+ * Get workflow sequence for an intent
+ */
+function getWorkflowSequence(intent) {
+  return INTENT_WORKFLOWS[intent] || 'proceed directly';
+}
+
+/**
+ * Format routing message for user
+ */
+function formatRoutingMessage(classification, commandMapping, workflowWarnings) {
+  const messages = [];
+
+  // Intent detection message
+  if (classification.autoConvert && commandMapping) {
+    messages.push(
+      `[Router] Detected ${classification.primaryIntent} intent (${Math.round(classification.confidence * 100)}% confidence)`
+    );
+    messages.push(
+      `[Router] Suggested: ${commandMapping.command} with ${commandMapping.agent} agent`
+    );
+
+    // Add model suggestion with reason
+    const modelReasons = MODEL_REASONS[commandMapping.model] || {};
+    const reason = modelReasons[classification.primaryIntent] || 'optimal for this task';
+    messages.push(`[Router] Optimal model: ${commandMapping.model} - ${reason}`);
+    messages.push(`[Router] Tip: Switch models in Claude settings for best results`);
+  } else if (classification.suggestOnly && commandMapping) {
+    messages.push(
+      `[Router] Detected ${classification.primaryIntent} intent (${Math.round(classification.confidence * 100)}% confidence)`
+    );
+    messages.push(`[Router] Suggestion: Consider using ${commandMapping.command} for this task`);
+
+    // Add model suggestion for suggestions too
+    const modelReasons = MODEL_REASONS[commandMapping.model] || {};
+    const reason = modelReasons[classification.primaryIntent] || 'optimal for this task';
+    messages.push(`[Router] Optimal model: ${commandMapping.model} - ${reason}`);
+  }
+
+  // Workflow warnings
+  if (workflowWarnings && workflowWarnings.length > 0) {
+    for (const warning of workflowWarnings) {
+      messages.push(`[Router] Warning: ${warning}`);
+    }
+  }
+
+  // Secondary intents
+  if (classification.secondaryIntents && classification.secondaryIntents.length > 0) {
+    messages.push(`[Router] Also detected: ${classification.secondaryIntents.join(', ')}`);
+  }
+
+  return messages;
+}
+
+/**
+ * Check workflow state and generate warnings
+ */
+function checkWorkflow(classification) {
+  const warnings = [];
+  const config = loadConfig();
+
+  if (config.workflowEnforcement === 'suggest' || !classification.primaryIntent) {
+    return warnings;
+  }
+
+  const workflowState = getWorkflowState();
+  const suggestedWorkflow = detectWorkflowType(classification.primaryIntent);
+
+  // If no active workflow but we detected a workflow-related intent
+  if (!workflowState && suggestedWorkflow) {
+    // Start a new workflow
+    startWorkflow(suggestedWorkflow, 'Auto-detected from prompt');
+  }
+
+  if (workflowState) {
+    // Map intent to phase
+    const intentToPhase = {
+      PLANNING: 'plan',
+      TESTING: 'tdd',
+      REVIEW: 'review',
+      DEBUG: 'fix',
+      DEPLOY: 'verify',
+      REFACTOR: 'refactor',
+    };
+
+    const targetPhase = intentToPhase[classification.primaryIntent];
+
+    if (targetPhase) {
+      const skippedPhases = checkSkippedPhases(targetPhase);
+
+      for (const skipped of skippedPhases) {
+        if (isCriticalPhase(skipped, workflowState.type)) {
+          warnings.push(
+            `Skipping critical phase '${skipped}' - consider running /${skipped} first`
+          );
+        }
+      }
+
+      // Advance to this phase
+      advancePhase(targetPhase);
+    }
+
+    // Suggest next phase
+    const nextPhase = getNextPhase();
+    if (nextPhase && classification.primaryIntent !== 'UNKNOWN') {
+      // Only suggest if we're not at the suggested phase
+      const currentPhaseFromIntent = intentToPhase[classification.primaryIntent];
+      if (currentPhaseFromIntent !== nextPhase) {
+        warnings.push(`Next recommended phase: /${nextPhase}`);
+      }
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Main hook execution
+ */
+async function main() {
+  const startTime = Date.now();
+
+  try {
+    // Check if disabled
+    if (isDisabled()) {
+      // Pass through unchanged
+      const input = await readStdinJson();
+      output(JSON.stringify(input));
+      return;
+    }
+
+    // Load config
+    const config = loadConfig();
+
+    if (!config.enabled) {
+      const input = await readStdinJson();
+      output(JSON.stringify(input));
+      return;
+    }
+
+    // Read hook input from stdin
+    const input = await readStdinJson();
+
+    // Get the user's prompt
+    const userPrompt = input.user_prompt || input.prompt || '';
+
+    // Classify the intent
+    const classification = classifyIntent(userPrompt);
+
+    // If routing should be skipped, pass through
+    if (classification.skipRouting) {
+      if (config.debug) {
+        log(`[PromptRouter] Skipping routing: ${classification.reason}`);
+      }
+      output(JSON.stringify(input));
+      return;
+    }
+
+    // Match to command if we have a valid intent
+    let commandMapping = null;
+    if (classification.primaryIntent !== INTENT_TYPES.UNKNOWN) {
+      commandMapping = matchCommand(classification.primaryIntent);
+    }
+
+    // Check workflow state
+    const workflowWarnings = checkWorkflow(classification);
+
+    // Log routing decision
+    logRoutingDecision({
+      prompt: userPrompt.substring(0, 200), // Truncate for privacy
+      intent: classification.primaryIntent,
+      confidence: classification.confidence,
+      autoConvert: classification.autoConvert,
+      suggestOnly: classification.suggestOnly,
+      command: commandMapping?.command || null,
+      workflowWarnings: workflowWarnings.length,
+      processingTime: Date.now() - startTime,
+    });
+
+    // Format messages
+    const messages = formatRoutingMessage(classification, commandMapping, workflowWarnings);
+
+    // Output messages to stderr (visible to user)
+    if (
+      messages.length > 0 &&
+      (classification.autoConvert || classification.suggestOnly || workflowWarnings.length > 0)
+    ) {
+      for (const msg of messages) {
+        log(msg);
+      }
+    }
+
+    // Debug mode - output decision without acting
+    if (config.debug) {
+      log(
+        `[PromptRouter] DEBUG: ${JSON.stringify({
+          intent: classification.primaryIntent,
+          confidence: classification.confidence,
+          command: commandMapping?.command,
+          autoConvert: classification.autoConvert,
+          processingTime: Date.now() - startTime,
+        })}`
+      );
+    }
+
+    // Output structured routing suggestion block for Claude to parse and act on
+    // This block is picked up by the hook-awareness and prompt-routing rules
+    if ((classification.autoConvert || classification.suggestOnly) && commandMapping) {
+      const confidencePercent = Math.round(classification.confidence * 100);
+      const workflow = getWorkflowSequence(classification.primaryIntent);
+
+      // Output structured suggestion block that Claude will see and act on
+      log('');
+      log('[ROUTING SUGGESTION]');
+      log(`Intent: ${classification.primaryIntent} (${confidencePercent}% confidence)`);
+      log(
+        `Recommended: ${commandMapping.command} with ${commandMapping.agent} agent (${commandMapping.model})`
+      );
+      log(`Workflow: ${workflow}`);
+
+      // Include secondary intents if detected (multi-intent prompt)
+      if (classification.secondaryIntents && classification.secondaryIntents.length > 0) {
+        log(`Additional intents: ${classification.secondaryIntents.join(', ')}`);
+      }
+
+      log('');
+      log('ACTION REQUIRED: Use AskUserQuestion to present routing options to user');
+      log('Options to present:');
+      log(
+        `  1. "Use ${commandMapping.agent} agent (Recommended)" - Specialized ${classification.primaryIntent.toLowerCase()} handling`
+      );
+      log('  2. "Proceed directly" - Quick response without specialized agent');
+      log('  3. "Show workflow details" - See full workflow sequence');
+      log('[/ROUTING SUGGESTION]');
+      log('');
+
+      // Also add metadata to input for potential programmatic use
+      input._routerSuggestion = {
+        command: commandMapping.command,
+        agent: commandMapping.agent,
+        model: commandMapping.model,
+        originalPrompt: userPrompt,
+        formattedCommand: formatCommand(classification.primaryIntent, userPrompt),
+        workflow: workflow,
+        confidence: classification.confidence,
+        secondaryIntents: classification.secondaryIntents || [],
+        actionRequired: true,
+      };
+    }
+
+    // Pass through the input (potentially modified)
+    output(JSON.stringify(input));
+
+    // Log performance
+    const elapsed = Date.now() - startTime;
+    if (elapsed > 100) {
+      log(`[PromptRouter] Performance warning: ${elapsed}ms (target: <100ms)`);
+    }
+  } catch (err) {
+    // On error, log but don't block
+    log(`[PromptRouter] Error: ${err.message}`);
+    // Pass through empty to avoid blocking
+    output('{}');
+  }
+}
+
+// Run
+main();