@girardmedia/bootspring 1.1.0

package/intelligence/orchestrator.js

@@ -0,0 +1,964 @@
+#!/usr/bin/env node
+
+/**
+ * Bootspring Intelligence Orchestrator
+ *
+ * Coordinates agent execution based on:
+ * - Project lifecycle phase
+ * - Detected events and triggers
+ * - Task requirements
+ * - Agent collaboration patterns
+ *
+ * @package bootspring
+ * @module intelligence/orchestrator
+ */
+
+const fs = require('fs');
+const path = require('path');
+const telemetry = require('../core/telemetry');
+
+// Paths (resolved relative to bootspring package)
+function getPaths() {
+  // Find the bootspring directory
+  let bootspringDir = __dirname;
+  while (!fs.existsSync(path.join(bootspringDir, 'package.json')) && bootspringDir !== '/') {
+    bootspringDir = path.dirname(bootspringDir);
+  }
+
+  const projectRoot = process.cwd();
+
+  return {
+    bootspringDir,
+    projectRoot,
+    agentsDir: path.join(bootspringDir, 'agents', 'profiles'),
+    statePath: path.join(projectRoot, '.bootspring', 'orchestrator-state.json'),
+    roadmapPath: path.join(projectRoot, 'ROADMAP.md')
+  };
+}
+
+// Colors
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m'
+};
+
+/**
+ * Agent lifecycle phase mapping
+ * Maps project phases to recommended agents
+ */
+const PHASE_AGENTS = {
+  1: {
+    name: 'Foundation',
+    description: 'Initial setup, planning, and architecture decisions',
+    primary: ['architecture-expert', 'database-expert'],
+    supporting: ['security-expert', 'devops-expert']
+  },
+  2: {
+    name: 'Requirements',
+    description: 'Data modeling, research, and specification',
+    primary: ['database-expert', 'api-expert'],
+    supporting: ['testing-expert']
+  },
+  3: {
+    name: 'Design',
+    description: 'UI/UX, database schema, API contracts',
+    primary: ['frontend-expert', 'ui-ux-expert', 'database-expert', 'api-expert'],
+    supporting: ['security-expert']
+  },
+  4: {
+    name: 'Implementation',
+    description: 'Core feature development',
+    primary: ['backend-expert', 'frontend-expert', 'database-expert'],
+    supporting: ['performance-expert', 'code-review-expert']
+  },
+  5: {
+    name: 'Testing',
+    description: 'Quality assurance and security review',
+    primary: ['testing-expert', 'security-expert', 'code-review-expert'],
+    supporting: ['performance-expert']
+  },
+  6: {
+    name: 'Deployment',
+    description: 'CI/CD, infrastructure, and monitoring',
+    primary: ['devops-expert', 'vercel-expert'],
+    supporting: ['security-expert', 'performance-expert']
+  },
+  7: {
+    name: 'Launch',
+    description: 'Go-live and post-launch optimization',
+    primary: ['devops-expert', 'performance-expert'],
+    supporting: ['security-expert']
+  }
+};
+
+/**
+ * Technical context triggers
+ * Maps keywords to recommended agents
+ */
+const TECHNICAL_TRIGGERS = {
+  'api': {
+    agents: ['api-expert', 'backend-expert', 'security-expert'],
+    indicators: ['api', 'endpoint', 'REST', 'GraphQL', 'route', 'handler'],
+    skills: ['api/route-handler', 'api/server-action']
+  },
+  'database': {
+    agents: ['database-expert', 'backend-expert'],
+    indicators: ['database', 'schema', 'prisma', 'migration', 'query', 'model', 'sql'],
+    skills: ['database/prisma']
+  },
+  'frontend': {
+    agents: ['frontend-expert', 'ui-ux-expert'],
+    indicators: ['component', 'react', 'tailwind', 'ui', 'ux', 'page', 'layout', 'css'],
+    skills: []
+  },
+  'authentication': {
+    agents: ['security-expert', 'backend-expert'],
+    indicators: ['auth', 'login', 'signup', 'session', 'clerk', 'jwt', 'oauth', 'password'],
+    skills: ['auth/clerk', 'auth/nextauth']
+  },
+  'security': {
+    agents: ['security-expert'],
+    indicators: ['security', 'vulnerability', 'OWASP', 'xss', 'csrf', 'injection', 'sanitize'],
+    skills: []
+  },
+  'performance': {
+    agents: ['performance-expert', 'database-expert'],
+    indicators: ['performance', 'speed', 'optimization', 'cache', 'slow', 'memory', 'bundle'],
+    skills: []
+  },
+  'deployment': {
+    agents: ['devops-expert', 'vercel-expert'],
+    indicators: ['deploy', 'CI/CD', 'docker', 'kubernetes', 'production', 'vercel', 'hosting'],
+    skills: []
+  },
+  'testing': {
+    agents: ['testing-expert', 'code-review-expert'],
+    indicators: ['test', 'jest', 'vitest', 'playwright', 'coverage', 'spec', 'mock'],
+    skills: ['testing/vitest']
+  },
+  'payments': {
+    agents: ['backend-expert', 'security-expert'],
+    indicators: ['stripe', 'payment', 'subscription', 'checkout', 'billing', 'invoice'],
+    skills: ['payments/stripe']
+  }
+};
+
+/**
+ * Predefined workflows for common scenarios
+ */
+const WORKFLOWS = {
+  'feature-development': {
+    name: 'Feature Development',
+    description: 'End-to-end feature implementation workflow',
+    tier: 'free',
+    pack: null,
+    outcomes: ['Feature shipped with tests and review complete'],
+    completionSignals: ['PR merged', 'Tests passing in CI', 'Security/perf review completed'],
+    phases: [
+      { name: 'Design', agents: ['ui-ux-expert', 'frontend-expert', 'api-expert'], duration: '1-2 days' },
+      { name: 'Implementation', agents: ['backend-expert', 'frontend-expert', 'database-expert'], duration: '2-5 days' },
+      { name: 'Testing', agents: ['testing-expert', 'code-review-expert'], duration: '1-2 days' },
+      { name: 'Review', agents: ['security-expert', 'performance-expert'], duration: '1 day' }
+    ]
+  },
+  'security-audit': {
+    name: 'Security Audit',
+    description: 'Comprehensive security review',
+    tier: 'free',
+    pack: null,
+    outcomes: ['Critical/high vulnerabilities remediated'],
+    completionSignals: ['Security findings closed', 'Post-fix verification complete'],
+    phases: [
+      { name: 'Code Review', agents: ['code-review-expert', 'security-expert'], duration: '2-3 days' },
+      { name: 'Vulnerability Scan', agents: ['security-expert'], duration: '1 day' },
+      { name: 'Remediation', agents: ['security-expert', 'backend-expert'], duration: '2-5 days' }
+    ]
+  },
+  'performance-optimization': {
+    name: 'Performance Optimization',
+    description: 'Full performance review and optimization',
+    tier: 'free',
+    pack: null,
+    outcomes: ['Performance regressions reduced and hotspots addressed'],
+    completionSignals: ['Baseline captured', 'Improvement report documented'],
+    phases: [
+      { name: 'Analysis', agents: ['performance-expert'], duration: '1-2 days' },
+      { name: 'Database', agents: ['database-expert', 'performance-expert'], duration: '2-3 days' },
+      { name: 'Frontend', agents: ['frontend-expert', 'performance-expert'], duration: '2-3 days' },
+      { name: 'Infrastructure', agents: ['devops-expert'], duration: '1-2 days' }
+    ]
+  },
+  'api-development': {
+    name: 'API Development',
+    description: 'Design and implement new API endpoints',
+    tier: 'free',
+    pack: null,
+    outcomes: ['API endpoints delivered with security and test coverage'],
+    completionSignals: ['Contract approved', 'API tests passing', 'Auth/rate limits verified'],
+    phases: [
+      { name: 'Design', agents: ['api-expert', 'database-expert'], duration: '1 day' },
+      { name: 'Implementation', agents: ['backend-expert', 'api-expert'], duration: '2-3 days' },
+      { name: 'Security', agents: ['security-expert'], duration: '1 day' },
+      { name: 'Testing', agents: ['testing-expert'], duration: '1 day' }
+    ]
+  },
+  'database-migration': {
+    name: 'Database Migration',
+    description: 'Schema changes and data migration',
+    tier: 'free',
+    pack: null,
+    outcomes: ['Migration completed safely with rollback readiness'],
+    completionSignals: ['Migration rehearsed', 'Rollback tested', 'Data integrity checks passing'],
+    phases: [
+      { name: 'Schema Design', agents: ['database-expert'], duration: '1 day' },
+      { name: 'Migration Plan', agents: ['database-expert', 'devops-expert'], duration: '1 day' },
+      { name: 'Implementation', agents: ['database-expert', 'backend-expert'], duration: '2-3 days' },
+      { name: 'Verification', agents: ['testing-expert'], duration: '1 day' }
+    ]
+  },
+  'launch-preparation': {
+    name: 'Launch Preparation',
+    description: 'Pre-launch checklist and deployment',
+    tier: 'free',
+    pack: null,
+    outcomes: ['Launch readiness validated across quality, security, and ops'],
+    completionSignals: ['Release checklist complete', 'Monitoring configured', 'Rollback plan confirmed'],
+    phases: [
+      { name: 'Testing', agents: ['testing-expert', 'performance-expert'], duration: '2-3 days' },
+      { name: 'Security', agents: ['security-expert'], duration: '1-2 days' },
+      { name: 'Deployment', agents: ['devops-expert', 'vercel-expert'], duration: '1 day' },
+      { name: 'Monitoring', agents: ['devops-expert', 'performance-expert'], duration: '1 day' }
+    ]
+  },
+  'launch-pack': {
+    name: 'Launch Pack',
+    description: 'Premium guided launch workflow from freeze to production validation',
+    tier: 'pro',
+    pack: 'launch',
+    outcomes: ['Production launch completed with no P0 regressions in first 48h'],
+    completionSignals: ['Change freeze checklist complete', 'Launch playbook executed', 'Post-launch metrics healthy'],
+    phases: [
+      { name: 'Readiness Gate', agents: ['testing-expert', 'security-expert', 'performance-expert'], duration: '1-2 days' },
+      { name: 'Cutover Plan', agents: ['devops-expert', 'architecture-expert'], duration: '1 day' },
+      { name: 'Go-Live', agents: ['devops-expert', 'vercel-expert'], duration: 'same day' },
+      { name: 'Stabilization', agents: ['performance-expert', 'backend-expert'], duration: '2 days' }
+    ]
+  },
+  'reliability-pack': {
+    name: 'Reliability Pack',
+    description: 'Premium reliability hardening workflow for incidents and regressions',
+    tier: 'pro',
+    pack: 'reliability',
+    outcomes: ['Error budget burn reduced and top incident classes mitigated'],
+    completionSignals: ['SLOs defined', 'Top 3 failure modes mitigated', 'Runbooks verified in drill'],
+    phases: [
+      { name: 'Reliability Baseline', agents: ['performance-expert', 'devops-expert'], duration: '1 day' },
+      { name: 'Failure Mode Audit', agents: ['security-expert', 'backend-expert'], duration: '1-2 days' },
+      { name: 'Resilience Implementation', agents: ['backend-expert', 'database-expert'], duration: '2-4 days' },
+      { name: 'Game Day Validation', agents: ['testing-expert', 'devops-expert'], duration: '1 day' }
+    ]
+  },
+  'growth-pack': {
+    name: 'Growth Pack',
+    description: 'Premium experimentation workflow for activation and conversion improvements',
+    tier: 'pro',
+    pack: 'growth',
+    outcomes: ['Primary growth KPI improved with statistically valid experiment result'],
+    completionSignals: ['North-star metric selected', 'Experiment shipped', 'Readout documented with decision'],
+    phases: [
+      { name: 'Metric Design', agents: ['architecture-expert', 'frontend-expert'], duration: '1 day' },
+      { name: 'Instrumentation', agents: ['backend-expert', 'api-expert'], duration: '1-2 days' },
+      { name: 'Experiment Build', agents: ['frontend-expert', 'backend-expert'], duration: '2-3 days' },
+      { name: 'Analysis & Decision', agents: ['code-review-expert', 'architecture-expert'], duration: '1 day' }
+    ]
+  }
+};
+
+/**
+ * Load orchestrator state from project
+ */
+function loadState() {
+  const paths = getPaths();
+
+  if (fs.existsSync(paths.statePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(paths.statePath, 'utf8'));
+    } catch (e) {
+      return createDefaultState();
+    }
+  }
+  return createDefaultState();
+}
+
+/**
+ * Create default orchestrator state
+ */
+function createDefaultState() {
+  return {
+    lastAnalysis: null,
+    currentPhase: 1,
+    activeWorkflow: null,
+    workflowStep: 0,
+    workflowSignals: {},
+    recentAgents: [],
+    suggestions: [],
+    history: []
+  };
+}
+
+function emitWorkflowTelemetry(event, payload = {}) {
+  const paths = getPaths();
+  try {
+    telemetry.emitEvent(event, payload, { projectRoot: paths.projectRoot });
+  } catch {
+    // Telemetry should not block workflow execution.
+  }
+}
+
+function getWorkflowSignalProgress(workflowName, state = null) {
+  const workflow = WORKFLOWS[workflowName];
+  if (!workflow) return null;
+
+  const activeState = state || loadState();
+  const completed = new Set(activeState.workflowSignals?.[workflowName] || []);
+  const signals = workflow.completionSignals || [];
+  const pending = signals.filter(signal => !completed.has(signal));
+
+  return {
+    workflow: workflowName,
+    totalSignals: signals.length,
+    completedSignals: Array.from(completed),
+    pendingSignals: pending
+  };
+}
+
+function resolveSignal(workflow, signalRef, stateSignals = []) {
+  const signals = workflow.completionSignals || [];
+  if (signals.length === 0) return null;
+
+  const completedSet = new Set(stateSignals);
+  const trimmed = String(signalRef || '').trim();
+  if (!trimmed) {
+    return signals.find(signal => !completedSet.has(signal)) || null;
+  }
+
+  const byIndex = Number(trimmed);
+  if (Number.isInteger(byIndex) && byIndex >= 1 && byIndex <= signals.length) {
+    return signals[byIndex - 1];
+  }
+
+  const lower = trimmed.toLowerCase();
+  return signals.find(signal => signal.toLowerCase().includes(lower)) || null;
+}
+
+/**
+ * Save orchestrator state
+ */
+function saveState(state) {
+  const paths = getPaths();
+
+  // Ensure .bootspring directory exists
+  const stateDir = path.dirname(paths.statePath);
+  if (!fs.existsSync(stateDir)) {
+    fs.mkdirSync(stateDir, { recursive: true });
+  }
+
+  state.lastUpdated = new Date().toISOString();
+  fs.writeFileSync(paths.statePath, JSON.stringify(state, null, 2));
+}
+
+/**
+ * Get current phase from ROADMAP.md
+ */
+function getCurrentPhase() {
+  const paths = getPaths();
+
+  try {
+    if (!fs.existsSync(paths.roadmapPath)) return 1;
+
+    const content = fs.readFileSync(paths.roadmapPath, 'utf8');
+
+    for (let i = 1; i <= 7; i++) {
+      const phaseRegex = new RegExp(`## Phase ${i}[\\s\\S]*?(?=## Phase|$)`, 'i');
+      const match = content.match(phaseRegex);
+      if (match) {
+        const incomplete = match[0].match(/- \[ \]/g);
+        if (incomplete && incomplete.length > 0) {
+          return i;
+        }
+      }
+    }
+    return 7;
+  } catch (e) {
+    return 1;
+  }
+}
+
+/**
+ * Get the AGENTS object from cli/agent.js
+ */
+function getAgentsRegistry() {
+  try {
+    const agentModule = require('../cli/agent');
+    return agentModule.AGENTS || {};
+  } catch (e) {
+    // Fallback to checking files
+    return null;
+  }
+}
+
+/**
+ * Check if an agent exists
+ */
+function agentExists(agentName) {
+  // First try the AGENTS registry
+  const registry = getAgentsRegistry();
+  if (registry) {
+    return agentName in registry;
+  }
+
+  // Fallback to checking files
+  const paths = getPaths();
+  const agentFile = path.join(paths.agentsDir, `${agentName}.md`);
+  return fs.existsSync(agentFile);
+}
+
+/**
+ * Get list of available agents
+ */
+function getAvailableAgents() {
+  // First try the AGENTS registry
+  const registry = getAgentsRegistry();
+  if (registry) {
+    return Object.keys(registry);
+  }
+
+  // Fallback to checking files
+  const paths = getPaths();
+
+  if (!fs.existsSync(paths.agentsDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(paths.agentsDir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace('.md', ''));
+}
+
+/**
+ * Analyze context and suggest agents
+ */
+function analyzeContext(input = '') {
+  const state = loadState();
+  const currentPhase = getCurrentPhase();
+  const suggestions = [];
+  const matchedSkills = [];
+
+  // Add phase-based agents
+  const phaseConfig = PHASE_AGENTS[currentPhase];
+  if (phaseConfig) {
+    phaseConfig.primary.forEach(agent => {
+      if (agentExists(agent)) {
+        suggestions.push({
+          agent,
+          reason: `Phase ${currentPhase} (${phaseConfig.name}) - primary agent`,
+          priority: 'high',
+          source: 'phase'
+        });
+      }
+    });
+  }
+
+  // Analyze input for technical triggers
+  const inputLower = input.toLowerCase();
+
+  Object.entries(TECHNICAL_TRIGGERS).forEach(([context, config]) => {
+    const matches = config.indicators.filter(ind => inputLower.includes(ind.toLowerCase()));
+    if (matches.length > 0) {
+      config.agents.forEach(agent => {
+        if (agentExists(agent) && !suggestions.find(s => s.agent === agent)) {
+          suggestions.push({
+            agent,
+            reason: `Detected ${context} context (matched: ${matches.join(', ')})`,
+            priority: matches.length >= 2 ? 'high' : 'medium',
+            source: 'trigger'
+          });
+        }
+      });
+
+      // Collect matching skills
+      if (config.skills) {
+        matchedSkills.push(...config.skills);
+      }
+    }
+  });
+
+  // Sort by priority
+  const priorityOrder = { high: 0, medium: 1, low: 2 };
+  suggestions.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+
+  // Update state
+  state.currentPhase = currentPhase;
+  state.lastAnalysis = new Date().toISOString();
+  state.suggestions = suggestions;
+  saveState(state);
+
+  return {
+    phase: currentPhase,
+    phaseConfig,
+    suggestions,
+    skills: [...new Set(matchedSkills)],
+    input: input.substring(0, 100)
+  };
+}
+
+/**
+ * Get workflow by name
+ */
+function getWorkflow(name) {
+  return WORKFLOWS[name] || null;
+}
+
+/**
+ * List all workflows
+ */
+function listWorkflows() {
+  return Object.entries(WORKFLOWS).map(([key, workflow]) => ({
+    key,
+    name: workflow.name,
+    description: workflow.description,
+    phaseCount: workflow.phases.length,
+    tier: workflow.tier || 'free',
+    pack: workflow.pack || null,
+    outcomes: workflow.outcomes || [],
+    completionSignals: workflow.completionSignals || []
+  }));
+}
+
+/**
+ * Start a workflow
+ */
+function startWorkflow(workflowName) {
+  const workflow = WORKFLOWS[workflowName];
+
+  if (!workflow) {
+    return { success: false, error: `Unknown workflow: ${workflowName}` };
+  }
+
+  const state = loadState();
+  state.activeWorkflow = workflowName;
+  state.workflowStep = 0;
+  state.workflowSignals = state.workflowSignals || {};
+  state.workflowSignals[workflowName] = state.workflowSignals[workflowName] || [];
+  state.history.push({
+    action: 'workflow_start',
+    workflow: workflowName,
+    timestamp: new Date().toISOString()
+  });
+  saveState(state);
+  emitWorkflowTelemetry('workflow_started', {
+    workflow: workflowName,
+    tier: workflow.tier || 'free',
+    pack: workflow.pack || null,
+    phaseCount: workflow.phases.length
+  });
+  if ((workflow.tier || 'free') !== 'free') {
+    emitWorkflowTelemetry('premium_unlocked', {
+      capability: 'workflow_pack',
+      workflow: workflowName,
+      tier: workflow.tier || 'free',
+      pack: workflow.pack || null,
+      source: 'workflow_start'
+    });
+  }
+
+  return {
+    success: true,
+    workflowKey: workflowName,
+    workflow: workflow.name,
+    currentPhase: workflow.phases[0],
+    totalPhases: workflow.phases.length,
+    completionSignals: workflow.completionSignals || []
+  };
+}
+
+/**
+ * Advance workflow to next step
+ */
+function advanceWorkflow() {
+  const state = loadState();
+
+  if (!state.activeWorkflow) {
+    return { success: false, error: 'No active workflow' };
+  }
+
+  const workflow = WORKFLOWS[state.activeWorkflow];
+  const activeWorkflowName = state.activeWorkflow;
+  state.workflowStep += 1;
+
+  if (state.workflowStep >= workflow.phases.length) {
+    // Workflow complete
+    state.history.push({
+      action: 'workflow_complete',
+      workflow: state.activeWorkflow,
+      timestamp: new Date().toISOString()
+    });
+    state.activeWorkflow = null;
+    state.workflowStep = 0;
+    saveState(state);
+    const signalProgress = getWorkflowSignalProgress(activeWorkflowName, state);
+    emitWorkflowTelemetry('workflow_completed', {
+      workflow: activeWorkflowName,
+      tier: workflow.tier || 'free',
+      pack: workflow.pack || null,
+      phaseCount: workflow.phases.length,
+      completedSignalCount: signalProgress?.completedSignals?.length || 0,
+      totalSignalCount: signalProgress?.totalSignals || 0
+    });
+
+    return { success: true, complete: true };
+  }
+
+  saveState(state);
+  emitWorkflowTelemetry('workflow_step_advanced', {
+    workflow: activeWorkflowName,
+    tier: workflow.tier || 'free',
+    pack: workflow.pack || null,
+    step: state.workflowStep + 1,
+    totalSteps: workflow.phases.length,
+    phaseName: workflow.phases[state.workflowStep]?.name
+  });
+
+  return {
+    success: true,
+    complete: false,
+    currentPhase: workflow.phases[state.workflowStep],
+    step: state.workflowStep + 1,
+    totalSteps: workflow.phases.length
+  };
+}
+
+function markWorkflowCheckpoint(workflowName, signalRef = '') {
+  const state = loadState();
+  const targetWorkflow = workflowName || state.activeWorkflow;
+  if (!targetWorkflow) {
+    return { success: false, error: 'No workflow provided and no active workflow' };
+  }
+
+  const workflow = WORKFLOWS[targetWorkflow];
+  if (!workflow) {
+    return { success: false, error: `Unknown workflow: ${targetWorkflow}` };
+  }
+
+  state.workflowSignals = state.workflowSignals || {};
+  const existing = state.workflowSignals[targetWorkflow] || [];
+  const signal = resolveSignal(workflow, signalRef, existing);
+  if (!signal) {
+    return {
+      success: false,
+      error: `Signal not found for workflow: ${targetWorkflow}`,
+      availableSignals: workflow.completionSignals || []
+    };
+  }
+
+  const alreadyCompleted = existing.includes(signal);
+  if (!alreadyCompleted) {
+    existing.push(signal);
+    state.workflowSignals[targetWorkflow] = existing;
+    state.history.push({
+      action: 'workflow_checkpoint',
+      workflow: targetWorkflow,
+      signal,
+      timestamp: new Date().toISOString()
+    });
+    saveState(state);
+    emitWorkflowTelemetry('workflow_checkpoint_completed', {
+      workflow: targetWorkflow,
+      tier: workflow.tier || 'free',
+      pack: workflow.pack || null,
+      signal
+    });
+    if (workflow.pack) {
+      emitWorkflowTelemetry('pack_signal_checkpoint', {
+        workflow: targetWorkflow,
+        pack: workflow.pack,
+        signal
+      });
+    }
+  }
+
+  return {
+    success: true,
+    workflow: targetWorkflow,
+    signal,
+    alreadyCompleted,
+    progress: getWorkflowSignalProgress(targetWorkflow, state)
+  };
+}
+
+/**
+ * Display analysis results
+ */
+function displayAnalysis(analysis) {
+  console.log(`\n${c.cyan}+--------------------------------------------------------+${c.reset}`);
+  console.log(`${c.cyan}|${c.reset}${c.bold}           Bootspring Intelligence Analysis             ${c.reset}${c.cyan}|${c.reset}`);
+  console.log(`${c.cyan}+--------------------------------------------------------+${c.reset}\n`);
+
+  console.log(`${c.bold}Current Phase:${c.reset} ${analysis.phase} - ${analysis.phaseConfig?.name || 'Unknown'}`);
+  if (analysis.phaseConfig?.description) {
+    console.log(`${c.dim}${analysis.phaseConfig.description}${c.reset}`);
+  }
+  console.log('');
+
+  if (analysis.suggestions.length === 0) {
+    console.log(`${c.yellow}No specific agent suggestions for this context${c.reset}`);
+    console.log(`${c.dim}Try adding more context about what you're working on${c.reset}`);
+    return;
+  }
+
+  console.log(`${c.bold}Suggested Agents:${c.reset}\n`);
+
+  const high = analysis.suggestions.filter(s => s.priority === 'high');
+  const medium = analysis.suggestions.filter(s => s.priority === 'medium');
+
+  if (high.length > 0) {
+    console.log(`  ${c.green}High Priority:${c.reset}`);
+    high.forEach(s => {
+      console.log(`    ${c.green}*${c.reset} ${s.agent}`);
+      console.log(`      ${c.dim}${s.reason}${c.reset}`);
+    });
+    console.log('');
+  }
+
+  if (medium.length > 0) {
+    console.log(`  ${c.yellow}Medium Priority:${c.reset}`);
+    medium.forEach(s => {
+      console.log(`    ${c.yellow}*${c.reset} ${s.agent}`);
+      console.log(`      ${c.dim}${s.reason}${c.reset}`);
+    });
+    console.log('');
+  }
+
+  if (analysis.skills.length > 0) {
+    console.log(`${c.bold}Relevant Skills:${c.reset}`);
+    analysis.skills.forEach(skill => {
+      console.log(`  ${c.cyan}*${c.reset} ${skill}`);
+    });
+    console.log('');
+  }
+
+  console.log(`${c.dim}Invoke an agent: bootspring agent invoke <name>${c.reset}`);
+}
+
+/**
+ * Display workflow details
+ */
+function displayWorkflow(workflowName) {
+  const workflow = WORKFLOWS[workflowName];
+
+  if (!workflow) {
+    console.log(`${c.red}Unknown workflow: ${workflowName}${c.reset}`);
+    console.log('Available: ' + Object.keys(WORKFLOWS).join(', '));
+    return;
+  }
+
+  console.log(`\n${c.cyan}+--------------------------------------------------------+${c.reset}`);
+  console.log(`${c.cyan}|${c.reset}${c.bold}  Workflow: ${workflow.name.padEnd(41)}${c.reset}${c.cyan}|${c.reset}`);
+  console.log(`${c.cyan}+--------------------------------------------------------+${c.reset}\n`);
+
+  console.log(`${c.bold}Description:${c.reset} ${workflow.description}\n`);
+  console.log(`${c.bold}Phases:${c.reset}\n`);
+
+  workflow.phases.forEach((phase, i) => {
+    const isLast = i === workflow.phases.length - 1;
+    const prefix = isLast ? '\\--' : '|--';
+    const line = isLast ? '   ' : '|  ';
+
+    console.log(`  ${prefix} ${c.cyan}${phase.name}${c.reset} ${c.dim}(${phase.duration})${c.reset}`);
+    phase.agents.forEach((agent, j) => {
+      const agentPrefix = j === phase.agents.length - 1 ? '\\-' : '|-';
+      const exists = agentExists(agent);
+      const status = exists ? `${c.green}*${c.reset}` : `${c.red}o${c.reset}`;
+      console.log(`  ${line} ${agentPrefix} ${status} ${agent}`);
+    });
+  });
+
+  console.log('');
+}
+
+/**
+ * Display orchestrator status
+ */
+function displayStatus() {
+  const state = loadState();
+  const currentPhase = getCurrentPhase();
+  const availableAgents = getAvailableAgents();
+
+  console.log(`\n${c.cyan}+--------------------------------------------------------+${c.reset}`);
+  console.log(`${c.cyan}|${c.reset}${c.bold}              Orchestrator Status                       ${c.reset}${c.cyan}|${c.reset}`);
+  console.log(`${c.cyan}+--------------------------------------------------------+${c.reset}\n`);
+
+  console.log(`${c.bold}Current Phase:${c.reset} ${currentPhase} - ${PHASE_AGENTS[currentPhase]?.name || 'Unknown'}`);
+  console.log(`${c.bold}Last Analysis:${c.reset} ${state.lastAnalysis || 'Never'}`);
+  console.log(`${c.bold}Active Workflow:${c.reset} ${state.activeWorkflow || 'None'}`);
+
+  if (state.activeWorkflow) {
+    const workflow = WORKFLOWS[state.activeWorkflow];
+    console.log(`${c.bold}Workflow Step:${c.reset} ${state.workflowStep + 1}/${workflow.phases.length}`);
+  }
+
+  if (state.suggestions.length > 0) {
+    console.log(`\n${c.bold}Last Suggestions:${c.reset}`);
+    state.suggestions.slice(0, 5).forEach(s => {
+      console.log(`  * ${s.agent} (${s.priority})`);
+    });
+  }
+
+  console.log(`\n${c.bold}Agent Inventory:${c.reset} ${availableAgents.length} agents available`);
+  console.log('');
+}
+
+/**
+ * Show help
+ */
+function showHelp() {
+  console.log(`
+${c.bold}Bootspring Intelligence Orchestrator${c.reset}
+
+${c.cyan}Usage:${c.reset}
+  node orchestrator.js <command> [options]
+
+${c.cyan}Commands:${c.reset}
+  analyze [context]     Analyze context and suggest agents
+  suggest [context]     Alias for analyze
+  workflow <name>       Show workflow details
+  workflows             List available workflows
+  start <workflow>      Start a workflow
+  next                  Advance to next workflow step
+  status                Show orchestrator status
+  agents                List available agents
+  help                  Show this help
+
+${c.cyan}Examples:${c.reset}
+  node orchestrator.js analyze "building authentication api"
+  node orchestrator.js workflow feature-development
+  node orchestrator.js start feature-development
+  node orchestrator.js status
+`);
+}
+
+// CLI execution
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+
+  switch (command) {
+    case 'analyze':
+    case 'suggest': {
+      const context = args.slice(1).join(' ');
+      const analysis = analyzeContext(context);
+      displayAnalysis(analysis);
+      break;
+    }
+
+    case 'workflow': {
+      const workflowName = args[1];
+      if (!workflowName) {
+        console.log(`\n${c.bold}Available Workflows:${c.reset}\n`);
+        listWorkflows().forEach(w => {
+          console.log(`  ${c.cyan}${w.key}${c.reset} - ${w.description}`);
+        });
+        console.log('');
+      } else {
+        displayWorkflow(workflowName);
+      }
+      break;
+    }
+
+    case 'workflows':
+      console.log(`\n${c.bold}Available Workflows:${c.reset}\n`);
+      listWorkflows().forEach(w => {
+        console.log(`  ${c.cyan}${w.key}${c.reset}`);
+        console.log(`    ${w.description}`);
+        console.log(`    ${c.dim}${w.phaseCount} phases${c.reset}\n`);
+      });
+      break;
+
+    case 'start': {
+      const startName = args[1];
+      if (!startName) {
+        console.log(`${c.red}Usage: orchestrator.js start <workflow-name>${c.reset}`);
+      } else {
+        const result = startWorkflow(startName);
+        if (result.success) {
+          console.log(`${c.green}Started workflow:${c.reset} ${result.workflow}`);
+          console.log(`${c.bold}Current Phase:${c.reset} ${result.currentPhase.name}`);
+          console.log(`${c.bold}Agents:${c.reset} ${result.currentPhase.agents.join(', ')}`);
+        } else {
+          console.log(`${c.red}Error: ${result.error}${c.reset}`);
+        }
+      }
+      break;
+    }
+
+    case 'next': {
+      const advanceResult = advanceWorkflow();
+      if (advanceResult.success) {
+        if (advanceResult.complete) {
+          console.log(`${c.green}Workflow complete!${c.reset}`);
+        } else {
+          console.log(`${c.green}Advanced to step ${advanceResult.step}/${advanceResult.totalSteps}${c.reset}`);
+          console.log(`${c.bold}Phase:${c.reset} ${advanceResult.currentPhase.name}`);
+          console.log(`${c.bold}Agents:${c.reset} ${advanceResult.currentPhase.agents.join(', ')}`);
+        }
+      } else {
+        console.log(`${c.red}Error: ${advanceResult.error}${c.reset}`);
+      }
+      break;
+    }
+
+    case 'status':
+      displayStatus();
+      break;
+
+    case 'agents': {
+      const agents = getAvailableAgents();
+      console.log(`\n${c.bold}Available Agents (${agents.length}):${c.reset}\n`);
+      agents.forEach(agent => {
+        console.log(`  * ${agent}`);
+      });
+      console.log('');
+      break;
+    }
+
+    case 'help':
+    default:
+      showHelp();
+  }
+}
+
+// Export for use as module
+module.exports = {
+  analyzeContext,
+  getWorkflow,
+  listWorkflows,
+  startWorkflow,
+  advanceWorkflow,
+  markWorkflowCheckpoint,
+  getWorkflowSignalProgress,
+  loadState,
+  saveState,
+  getCurrentPhase,
+  agentExists,
+  getAvailableAgents,
+  PHASE_AGENTS,
+  TECHNICAL_TRIGGERS,
+  WORKFLOWS
+};