@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/suggest.ts

@@ -0,0 +1,1225 @@
+/**
+ * Bootspring Suggest Command
+ * AI-powered recommendations based on telemetry and learning
+ *
+ * @package bootspring
+ * @command suggest
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Interfaces
+interface ConfigModule {
+  load: () => { _projectRoot: string };
+}
+
+interface UtilsModule {
+  COLORS: {
+    cyan: string;
+    bold: string;
+    reset: string;
+    dim: string;
+    green: string;
+    yellow: string;
+    red: string;
+  };
+  createSpinner: (text: string) => {
+    start: () => SpinnerInstance;
+    stop: () => void;
+  };
+  parseArgs: (args: string[]) => ParsedArgs;
+  print: {
+    error: (msg: string) => void;
+  };
+}
+
+interface SpinnerInstance {
+  stop: () => void;
+  fail: (text: string) => void;
+}
+
+interface IntelligenceModule {
+  [key: string]: unknown;
+}
+
+interface TelemetryModule {
+  [key: string]: unknown;
+}
+
+interface EntitlementsModule {
+  [key: string]: unknown;
+}
+
+interface SkillsModule {
+  listSkills: () => unknown[];
+  getSkillMetadata: () => unknown | null;
+  loadSkill: () => unknown | null;
+  searchSkills: () => unknown[];
+  getCategories: () => unknown[];
+  hasExternalSkillLibrary: () => boolean;
+}
+
+interface RecommendationsEngineFactory {
+  createRecommendationsEngine: (options: RecommendationsEngineOptions) => RecommendationsEngine;
+}
+
+interface RecommendationsEngineOptions {
+  intelligence: IntelligenceModule;
+  telemetry: TelemetryModule;
+  skills: SkillsModule;
+  entitlements: EntitlementsModule;
+}
+
+interface RecommendationsEngine {
+  recommend: (options: RecommendOptions) => RecommendationResult;
+}
+
+interface RecommendOptions {
+  contextText: string;
+  limit: number;
+  accessOptions: Record<string, unknown>;
+}
+
+interface RecommendationResult {
+  context: {
+    phase?: string | undefined;
+    phaseName?: string | undefined;
+  };
+  workflows: WorkflowRecommendation[];
+  skills: SkillRecommendation[];
+  learning?: LearningData | undefined;
+  telemetryWindow: {
+    eventsAnalyzed: number;
+  };
+}
+
+interface WorkflowRecommendation {
+  name: string;
+  key?: string | undefined;
+  tier: string;
+  score: number;
+  reasons: string[];
+  learningImpact?: {
+    adjustment: number;
+    breakdown: {
+      impactBoost: number;
+    };
+  } | undefined;
+}
+
+interface SkillRecommendation {
+  id: string;
+  name?: string | undefined;
+  description?: string | undefined;
+  score: number;
+}
+
+interface LearningData {
+  usingDefaults?: boolean | undefined;
+  antiPatterns: AntiPattern[];
+  insights: Insight[];
+  phaseRecommendation?: PhaseRecommendation | undefined;
+  impact?: {
+    boostedPatterns?: BoostedPattern[] | undefined;
+  } | undefined;
+  generalRecommendations?: string[] | undefined;
+}
+
+interface AntiPattern {
+  decision: string;
+  failure_rate: number;
+  is_default?: boolean | undefined;
+}
+
+interface Insight {
+  message: string;
+  level?: string | undefined;
+}
+
+interface PhaseRecommendation {
+  success_rate: number;
+  is_default?: boolean | undefined;
+}
+
+interface BoostedPattern {
+  type: string;
+  averageImpactScore: number;
+}
+
+interface ParsedArgs {
+  _: string[];
+  help?: boolean;
+  h?: boolean;
+  limit?: number | string;
+  json?: boolean;
+  'enable-auto'?: boolean;
+  'disable-auto'?: boolean;
+  category?: string;
+  suppress?: string;
+  unsuppress?: string;
+  [key: string]: string | boolean | number | string[] | undefined;
+}
+
+interface PatternLearnerModule {
+  analyze: () => PatternAnalysis;
+}
+
+interface PatternAnalysis {
+  using_defaults?: boolean | undefined;
+  analysis_summary?: {
+    total_decisions?: number | undefined;
+    success_rate?: number | undefined;
+    unique_patterns?: number | undefined;
+  } | undefined;
+  insights?: Insight[] | undefined;
+  anti_patterns?: AntiPattern[] | undefined;
+  correlations?: Correlation[] | undefined;
+}
+
+interface Correlation {
+  decision_a: string;
+  decision_b: string;
+  occurrences: number;
+}
+
+interface AutoSuggestModule {
+  new (projectRoot: string): AutoSuggestInstance;
+}
+
+interface AutoSuggestInstance {
+  getStatus: () => AutoSuggestStatus;
+  setEnabled: (enabled: boolean) => void;
+  setCategory: (category: string, enabled: boolean) => void;
+  suppressCommand: (command: string) => void;
+  unsuppressCommand: (command: string) => void;
+  analyze: (text: string) => Suggestion[];
+}
+
+interface AutoSuggestStatus {
+  enabled: boolean;
+  categories: Record<string, boolean>;
+  suppressedCommands: string[];
+}
+
+interface Suggestion {
+  command: string;
+  description: string;
+  confidence: number;
+}
+
+interface Prompt {
+  category: string;
+  priority: string;
+  title: string;
+  prompt: string;
+  command: string | null;
+}
+
+interface ProjectState {
+  checkpoints?: Record<string, { completed?: boolean | undefined }> | undefined;
+  projectType?: string | undefined;
+}
+
+interface PackageJson {
+  dependencies?: Record<string, string> | undefined;
+}
+
+// Lazy load modules
+const config = require('../core/config') as ConfigModule;
+const utils = require('../core/utils') as UtilsModule;
+const intelligence = require('../intelligence') as IntelligenceModule;
+const telemetry = require('../core/telemetry') as TelemetryModule;
+const entitlements = require('../core/entitlements') as EntitlementsModule;
+
+// Thin client: skills module may not exist locally
+// Skills are now served from the API
+let skills: SkillsModule;
+try {
+  skills = require('../skills') as SkillsModule;
+} catch {
+  // Stub for thin client - skills fetched from API
+  skills = {
+    listSkills: () => [],
+    getSkillMetadata: () => null,
+    loadSkill: () => null,
+    searchSkills: () => [],
+    getCategories: () => [],
+    hasExternalSkillLibrary: () => false
+  };
+}
+
+// Lazy load recommendations engine
+let recommendationsEngine: RecommendationsEngine | null = null;
+function getRecommendationsEngine(): RecommendationsEngine {
+  if (!recommendationsEngine) {
+    const { createRecommendationsEngine } = require('../intelligence/recommendations') as RecommendationsEngineFactory;
+    recommendationsEngine = createRecommendationsEngine({
+      intelligence,
+      telemetry,
+      skills,
+      entitlements
+    });
+  }
+  return recommendationsEngine;
+}
+
+/**
+ * Get context from project files
+ */
+function getProjectContext(projectRoot: string): string {
+  const contextParts: string[] = [];
+
+  // Read CLAUDE.md
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+  if (fs.existsSync(claudeMdPath)) {
+    const content = fs.readFileSync(claudeMdPath, 'utf-8');
+    contextParts.push(content.slice(0, 2000));
+  }
+
+  // Read recent todos
+  const todoPath = path.join(projectRoot, 'todo.md');
+  if (fs.existsSync(todoPath)) {
+    const content = fs.readFileSync(todoPath, 'utf-8');
+    const pendingTodos = content.match(/- \[ \].*/g) || [];
+    if (pendingTodos.length > 0) {
+      contextParts.push('Pending tasks: ' + pendingTodos.slice(0, 5).join(', '));
+    }
+  }
+
+  // Read recent workflow state
+  const workflows = ['analyze', 'audit', 'deploy'];
+  for (const workflow of workflows) {
+    const stateFile = path.join(projectRoot, '.bootspring', workflow, 'workflow-state.json');
+    if (fs.existsSync(stateFile)) {
+      try {
+        const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+        const incomplete = Object.entries(state.phases || {})
+          .filter(([, p]) => (p as { status: string }).status !== 'completed')
+          .map(([name]) => name);
+        if (incomplete.length > 0) {
+          contextParts.push(`${workflow} workflow incomplete: ${incomplete.join(', ')}`);
+        }
+      } catch {
+        // Skip invalid state
+      }
+    }
+  }
+
+  return contextParts.join('\n\n');
+}
+
+/**
+ * Format workflow recommendation
+ */
+function formatWorkflow(workflow: WorkflowRecommendation, index: number): string {
+  const tierIcon = workflow.tier === 'free' ?
+    '' : ` ${utils.COLORS.yellow}[${workflow.tier}]${utils.COLORS.reset}`;
+
+  let output = `  ${index + 1}. ${utils.COLORS.cyan}${workflow.name}${utils.COLORS.reset}${tierIcon}\n`;
+  output += `     ${utils.COLORS.dim}Score: ${workflow.score}${utils.COLORS.reset}\n`;
+
+  if (workflow.reasons.length > 0) {
+    const topReasons = workflow.reasons.slice(0, 3);
+    output += `     ${utils.COLORS.dim}${topReasons.join(' • ')}${utils.COLORS.reset}\n`;
+  }
+
+  if (workflow.learningImpact) {
+    const { adjustment, breakdown } = workflow.learningImpact;
+    const sign = adjustment >= 0 ? '+' : '';
+    output += `     ${utils.COLORS.green}Learning: ${sign}${adjustment}${utils.COLORS.reset}`;
+    if (breakdown.impactBoost > 0) {
+      output += ` ${utils.COLORS.dim}(impact: +${breakdown.impactBoost})${utils.COLORS.reset}`;
+    }
+    output += '\n';
+  }
+
+  return output;
+}
+
+/**
+ * Format skill recommendation
+ */
+function formatSkill(skill: SkillRecommendation, index: number): string {
+  let output = `  ${index + 1}. ${utils.COLORS.cyan}${skill.name || skill.id}${utils.COLORS.reset}\n`;
+
+  if (skill.description) {
+    output += `     ${utils.COLORS.dim}${skill.description.slice(0, 60)}${utils.COLORS.reset}\n`;
+  }
+
+  output += `     ${utils.COLORS.dim}Score: ${skill.score}${utils.COLORS.reset}\n`;
+
+  return output;
+}
+
+/**
+ * Show recommendations
+ */
+async function showRecommendations(projectRoot: string, options: { limit?: number | undefined; json?: boolean | undefined } = {}): Promise<RecommendationResult | undefined> {
+  const engine = getRecommendationsEngine();
+
+  const spinner = utils.createSpinner('Analyzing context...').start();
+
+  try {
+    // Get project context
+    const contextText = getProjectContext(projectRoot);
+
+    // Get recommendations
+    const result = engine.recommend({
+      contextText,
+      limit: options.limit || 5,
+      accessOptions: {}
+    });
+
+    spinner.stop();
+
+    console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Smart Suggestions${utils.COLORS.reset}
+${utils.COLORS.dim}Based on your project context and history${utils.COLORS.reset}
+`);
+
+    // Current context
+    if (result.context.phase) {
+      console.log(`${utils.COLORS.bold}Current Phase${utils.COLORS.reset}`);
+      console.log(`  ${result.context.phaseName || result.context.phase}`);
+      console.log();
+    }
+
+    // Workflow recommendations
+    if (result.workflows.length > 0) {
+      console.log(`${utils.COLORS.bold}Recommended Workflows${utils.COLORS.reset}`);
+      for (let i = 0; i < result.workflows.length; i++) {
+        const workflow = result.workflows[i];
+        if (workflow) {
+          console.log(formatWorkflow(workflow, i));
+        }
+      }
+    }
+
+    // Skill recommendations
+    if (result.skills.length > 0) {
+      console.log(`${utils.COLORS.bold}Recommended Skills${utils.COLORS.reset}`);
+      for (let i = 0; i < Math.min(result.skills.length, 3); i++) {
+        const skill = result.skills[i];
+        if (skill) {
+          console.log(formatSkill(skill, i));
+        }
+      }
+    }
+
+    // Learning insights
+    if (result.learning && !result.learning.usingDefaults) {
+      console.log(`${utils.COLORS.bold}Insights from History${utils.COLORS.reset}`);
+
+      // Anti-patterns to avoid
+      if (result.learning.antiPatterns.length > 0) {
+        const ap = result.learning.antiPatterns[0];
+        if (ap && !ap.is_default) {
+          console.log(`  ${utils.COLORS.yellow}⚠${utils.COLORS.reset} Avoid: ${ap.decision} (${(ap.failure_rate * 100).toFixed(0)}% failure rate)`);
+        }
+      }
+
+      // Top insight
+      if (result.learning.insights.length > 0) {
+        const insight = result.learning.insights[0];
+        if (insight) {
+          console.log(`  ${utils.COLORS.green}→${utils.COLORS.reset} ${insight.message}`);
+        }
+      }
+
+      // Phase recommendation
+      if (result.learning.phaseRecommendation && !result.learning.phaseRecommendation.is_default) {
+        const pr = result.learning.phaseRecommendation;
+        console.log(`  ${utils.COLORS.dim}This phase has ${(pr.success_rate * 100).toFixed(0)}% success rate${utils.COLORS.reset}`);
+      }
+
+      // Impact insights
+      if (result.learning.impact?.boostedPatterns && result.learning.impact.boostedPatterns.length > 0) {
+        const topPattern = result.learning.impact.boostedPatterns[0];
+        if (topPattern) {
+          console.log(`  ${utils.COLORS.green}★${utils.COLORS.reset} High-impact pattern: ${topPattern.type} (${topPattern.averageImpactScore.toFixed(1)} impact score)`);
+        }
+      }
+
+      console.log();
+    }
+
+    // General recommendations
+    if (result.learning?.generalRecommendations && result.learning.generalRecommendations.length > 0) {
+      console.log(`${utils.COLORS.bold}Recommendations${utils.COLORS.reset}`);
+      for (const rec of result.learning.generalRecommendations.slice(0, 3)) {
+        console.log(`  ${utils.COLORS.cyan}→${utils.COLORS.reset} ${rec}`);
+      }
+      console.log();
+    }
+
+    // Telemetry summary
+    console.log(`${utils.COLORS.dim}Based on ${result.telemetryWindow.eventsAnalyzed} events${utils.COLORS.reset}`);
+
+    if (options.json) {
+      return result;
+    }
+
+  } catch (error) {
+    spinner.fail('Failed to generate recommendations');
+    utils.print.error((error as Error).message);
+  }
+
+  return undefined;
+}
+
+/**
+ * Show next action suggestion
+ */
+async function showNextAction(projectRoot: string): Promise<void> {
+  const engine = getRecommendationsEngine();
+  const contextText = getProjectContext(projectRoot);
+
+  const result = engine.recommend({
+    contextText,
+    limit: 1,
+    accessOptions: {}
+  });
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Next Action${utils.COLORS.reset}
+`);
+
+  if (result.workflows.length > 0) {
+    const workflow = result.workflows[0];
+    if (workflow) {
+      console.log(`${utils.COLORS.bold}${workflow.name}${utils.COLORS.reset}`);
+
+      if (workflow.reasons.length > 0) {
+        console.log(`${utils.COLORS.dim}${workflow.reasons[0]}${utils.COLORS.reset}`);
+      }
+
+      // Suggest command
+      const commands: Record<string, string> = {
+        'analyze': 'bootspring analyze',
+        'audit': 'bootspring audit',
+        'deploy': 'bootspring deploy',
+        'preseed': 'bootspring preseed init',
+        'seed': 'bootspring seed scaffold',
+        'onboard': 'bootspring onboard'
+      };
+
+      for (const [key, cmd] of Object.entries(commands)) {
+        if (workflow.key?.includes(key) || workflow.name?.toLowerCase().includes(key)) {
+          console.log();
+          console.log(`${utils.COLORS.cyan}Run:${utils.COLORS.reset} ${cmd}`);
+          break;
+        }
+      }
+    }
+  } else {
+    console.log('No specific suggestions at this time.');
+    console.log(`${utils.COLORS.dim}Run 'bootspring health' to check project status${utils.COLORS.reset}`);
+  }
+
+  console.log();
+}
+
+/**
+ * Show learning stats
+ */
+function showLearningStats(): void {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Learning Stats${utils.COLORS.reset}
+`);
+
+  try {
+    const patternLearner = require('../intelligence/learning/pattern-learner') as PatternLearnerModule;
+    const insights = patternLearner.analyze();
+
+    if (insights.using_defaults) {
+      console.log(`${utils.COLORS.yellow}No learning data yet${utils.COLORS.reset}`);
+      console.log(`${utils.COLORS.dim}Use Bootspring more to build up patterns${utils.COLORS.reset}`);
+      return;
+    }
+
+    // Summary
+    if (insights.analysis_summary) {
+      const summary = insights.analysis_summary;
+      console.log(`${utils.COLORS.bold}Summary${utils.COLORS.reset}`);
+      console.log(`  Total decisions: ${summary.total_decisions || 0}`);
+      console.log(`  Success rate: ${((summary.success_rate || 0) * 100).toFixed(0)}%`);
+      console.log(`  Unique patterns: ${summary.unique_patterns || 0}`);
+      console.log();
+    }
+
+    // Top insights
+    if (insights.insights && insights.insights.length > 0) {
+      console.log(`${utils.COLORS.bold}Top Insights${utils.COLORS.reset}`);
+      for (const insight of insights.insights.slice(0, 5)) {
+        const icon = insight.level === 'positive' ?
+          `${utils.COLORS.green}↑${utils.COLORS.reset}` :
+          insight.level === 'negative' ?
+            `${utils.COLORS.red}↓${utils.COLORS.reset}` :
+            `${utils.COLORS.dim}→${utils.COLORS.reset}`;
+        console.log(`  ${icon} ${insight.message}`);
+      }
+      console.log();
+    }
+
+    // Anti-patterns
+    const realAntiPatterns = (insights.anti_patterns || []).filter(ap => !ap.is_default);
+    if (realAntiPatterns.length > 0) {
+      console.log(`${utils.COLORS.bold}Anti-Patterns Detected${utils.COLORS.reset}`);
+      for (const ap of realAntiPatterns.slice(0, 3)) {
+        console.log(`  ${utils.COLORS.yellow}⚠${utils.COLORS.reset} ${ap.decision}: ${(ap.failure_rate * 100).toFixed(0)}% failure rate`);
+      }
+      console.log();
+    }
+
+    // Correlations
+    if (insights.correlations && insights.correlations.length > 0) {
+      console.log(`${utils.COLORS.bold}Pattern Correlations${utils.COLORS.reset}`);
+      for (const corr of insights.correlations.slice(0, 3)) {
+        console.log(`  ${utils.COLORS.dim}${corr.decision_a} → ${corr.decision_b} (${corr.occurrences} times)${utils.COLORS.reset}`);
+      }
+      console.log();
+    }
+
+  } catch (error) {
+    console.log(`${utils.COLORS.dim}Learning data not available: ${(error as Error).message}${utils.COLORS.reset}`);
+  }
+}
+
+/**
+ * Auto-suggest configuration and display
+ */
+function showAutoSuggestConfig(projectRoot: string): void {
+  const { AutoSuggest } = require('../intelligence/auto-suggest') as { AutoSuggest: AutoSuggestModule };
+  const autoSuggest = new AutoSuggest(projectRoot);
+  const status = autoSuggest.getStatus();
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Auto-Suggest Configuration${utils.COLORS.reset}
+
+${utils.COLORS.bold}Status${utils.COLORS.reset}
+  Enabled: ${status.enabled ? `${utils.COLORS.green}Yes${utils.COLORS.reset}` : `${utils.COLORS.red}No${utils.COLORS.reset}`}
+
+${utils.COLORS.bold}Categories${utils.COLORS.reset}`);
+
+  for (const [category, enabled] of Object.entries(status.categories)) {
+    const icon = enabled ? `${utils.COLORS.green}✓${utils.COLORS.reset}` : `${utils.COLORS.dim}○${utils.COLORS.reset}`;
+    console.log(`  ${icon} ${category}`);
+  }
+
+  if (status.suppressedCommands.length > 0) {
+    console.log(`
+${utils.COLORS.bold}Suppressed Commands${utils.COLORS.reset}`);
+    for (const cmd of status.suppressedCommands) {
+      console.log(`  ${utils.COLORS.dim}${cmd}${utils.COLORS.reset}`);
+    }
+  }
+
+  console.log(`
+${utils.COLORS.bold}Commands${utils.COLORS.reset}
+  bootspring suggest --enable-auto       Enable auto-suggestions
+  bootspring suggest --disable-auto      Disable auto-suggestions
+  bootspring suggest --category <name>   Toggle category
+  bootspring suggest --suppress <cmd>    Suppress a command
+`);
+}
+
+/**
+ * Toggle auto-suggest
+ */
+function toggleAutoSuggest(projectRoot: string, enable: boolean): void {
+  const { AutoSuggest } = require('../intelligence/auto-suggest') as { AutoSuggest: AutoSuggestModule };
+  const autoSuggest = new AutoSuggest(projectRoot);
+  autoSuggest.setEnabled(enable);
+
+  if (enable) {
+    console.log(`${utils.COLORS.green}✓${utils.COLORS.reset} Auto-suggest enabled`);
+    console.log(`${utils.COLORS.dim}Bootspring will suggest relevant commands during Claude Code sessions${utils.COLORS.reset}`);
+  } else {
+    console.log(`${utils.COLORS.yellow}○${utils.COLORS.reset} Auto-suggest disabled`);
+    console.log(`${utils.COLORS.dim}Re-enable with: bootspring suggest --enable-auto${utils.COLORS.reset}`);
+  }
+}
+
+/**
+ * Toggle category
+ */
+function toggleCategory(projectRoot: string, category: string): void {
+  const { AutoSuggest } = require('../intelligence/auto-suggest') as { AutoSuggest: AutoSuggestModule };
+  const autoSuggest = new AutoSuggest(projectRoot);
+  const status = autoSuggest.getStatus();
+
+  if (!Object.prototype.hasOwnProperty.call(status.categories, category)) {
+    console.log(`${utils.COLORS.red}Unknown category: ${category}${utils.COLORS.reset}`);
+    console.log(`Available: ${Object.keys(status.categories).join(', ')}`);
+    return;
+  }
+
+  const newState = !status.categories[category];
+  autoSuggest.setCategory(category, newState);
+
+  const icon = newState ? `${utils.COLORS.green}✓${utils.COLORS.reset}` : `${utils.COLORS.dim}○${utils.COLORS.reset}`;
+  console.log(`${icon} Category '${category}' ${newState ? 'enabled' : 'disabled'}`);
+}
+
+/**
+ * Suppress or unsuppress a command
+ */
+function suppressCommand(projectRoot: string, command: string, suppress = true): void {
+  const { AutoSuggest } = require('../intelligence/auto-suggest') as { AutoSuggest: AutoSuggestModule };
+  const autoSuggest = new AutoSuggest(projectRoot);
+
+  if (suppress) {
+    autoSuggest.suppressCommand(command);
+    console.log(`${utils.COLORS.dim}○${utils.COLORS.reset} Suppressed suggestions for: ${command}`);
+  } else {
+    autoSuggest.unsuppressCommand(command);
+    console.log(`${utils.COLORS.green}✓${utils.COLORS.reset} Enabled suggestions for: ${command}`);
+  }
+}
+
+/**
+ * Analyze text for suggestions (for testing/demo)
+ */
+function analyzeText(projectRoot: string, text: string): void {
+  const { AutoSuggest } = require('../intelligence/auto-suggest') as { AutoSuggest: AutoSuggestModule };
+  const autoSuggest = new AutoSuggest(projectRoot);
+  const suggestions = autoSuggest.analyze(text);
+
+  if (suggestions.length === 0) {
+    console.log(`${utils.COLORS.dim}No suggestions for this input${utils.COLORS.reset}`);
+    return;
+  }
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}💡 Suggestions${utils.COLORS.reset}
+`);
+
+  for (const suggestion of suggestions) {
+    console.log(`  ${utils.COLORS.green}→${utils.COLORS.reset} ${utils.COLORS.bold}${suggestion.command}${utils.COLORS.reset}`);
+    console.log(`    ${utils.COLORS.dim}${suggestion.description}${utils.COLORS.reset}`);
+    console.log(`    ${utils.COLORS.dim}Confidence: ${(suggestion.confidence * 100).toFixed(0)}%${utils.COLORS.reset}`);
+    console.log();
+  }
+}
+
+/**
+ * Generate AI-ready prompts based on project analysis
+ */
+async function generatePrompts(projectRoot: string, options: { limit?: number | undefined; json?: boolean | undefined } = {}): Promise<Prompt[] | undefined> {
+  const prompts: Prompt[] = [];
+  const projectState = loadProjectState(projectRoot);
+  const checkpoints = projectState?.checkpoints || {};
+
+  // Analyze what's missing and generate prompts
+
+  // 1. Check for missing planning docs
+  const planningDocs: Array<{ file: string; checkpoint: string; name: string; prompt: string }> = [
+    { file: 'planning/PRD.md', checkpoint: 'prd', name: 'Product Requirements Document',
+      prompt: `Create a comprehensive PRD.md file in the planning/ folder. Include:
+- Product vision and goals
+- Target users and personas
+- Core features and requirements (prioritized)
+- Success metrics and KPIs
+- Timeline and milestones
+- Out of scope items
+
+Base it on the existing project structure and any available context.` },
+    { file: 'planning/TECHNICAL_SPEC.md', checkpoint: 'technical_spec', name: 'Technical Specification',
+      prompt: `Create a TECHNICAL_SPEC.md file in planning/ folder. Include:
+- System architecture overview
+- Technology stack decisions with rationale
+- Data models and schemas
+- API design patterns
+- Security considerations
+- Performance requirements
+- Integration points` },
+    { file: 'planning/ARCHITECTURE.md', checkpoint: 'architecture', name: 'Architecture Document',
+      prompt: `Create an ARCHITECTURE.md file in planning/ folder. Include:
+- High-level system diagram (ASCII or Mermaid)
+- Component breakdown and responsibilities
+- Data flow between components
+- External service integrations
+- Deployment architecture
+- Scalability considerations` },
+    { file: 'planning/DATABASE_SCHEMA.md', checkpoint: 'database_schema', name: 'Database Schema',
+      prompt: `Create a DATABASE_SCHEMA.md file in planning/ folder. Include:
+- Entity relationship diagram (Mermaid or ASCII)
+- Table definitions with columns and types
+- Relationships and foreign keys
+- Indexes for performance
+- Migration strategy
+- Sample queries for common operations` },
+    { file: 'planning/API_CONTRACTS.md', checkpoint: 'api_contracts', name: 'API Contracts',
+      prompt: `Create an API_CONTRACTS.md file in planning/ folder. Include:
+- RESTful endpoint definitions
+- Request/response schemas (with examples)
+- Authentication requirements
+- Rate limiting policies
+- Error response formats
+- Versioning strategy` },
+    { file: 'planning/TEST_PLAN.md', checkpoint: 'tests_planned', name: 'Test Plan',
+      prompt: `Create a TEST_PLAN.md file in planning/ folder. Include:
+- Testing strategy (unit, integration, e2e)
+- Test coverage targets
+- Critical paths to test
+- Test data requirements
+- CI/CD integration plan
+- Performance testing approach` }
+  ];
+
+  for (const doc of planningDocs) {
+    const filePath = path.join(projectRoot, doc.file);
+    if (!fs.existsSync(filePath) && !checkpoints[doc.checkpoint]?.completed) {
+      prompts.push({
+        category: 'Documentation',
+        priority: doc.checkpoint === 'prd' ? 'high' : 'medium',
+        title: `Create ${doc.name}`,
+        prompt: doc.prompt,
+        command: `bootspring checkpoint complete ${doc.checkpoint}`
+      });
+    }
+  }
+
+  // 2. Check for missing test setup
+  const hasTests = fs.existsSync(path.join(projectRoot, '__tests__')) ||
+                   fs.existsSync(path.join(projectRoot, 'tests')) ||
+                   fs.existsSync(path.join(projectRoot, 'test'));
+  const hasTestConfig = fs.existsSync(path.join(projectRoot, 'vitest.config.ts')) ||
+                        fs.existsSync(path.join(projectRoot, 'jest.config.js')) ||
+                        fs.existsSync(path.join(projectRoot, 'vitest.config.js'));
+
+  if (!hasTests || !hasTestConfig) {
+    prompts.push({
+      category: 'Quality',
+      priority: 'high',
+      title: 'Set up test infrastructure',
+      prompt: `Set up a comprehensive testing infrastructure for this project:
+
+1. Install vitest and testing utilities
+2. Create vitest.config.ts with proper configuration
+3. Set up test directory structure (__tests__/ or tests/)
+4. Create example unit tests for existing modules
+5. Add test scripts to package.json
+6. Configure code coverage reporting
+
+Focus on making tests easy to write and maintain.`,
+      command: 'npm install -D vitest @vitest/coverage-v8'
+    });
+  }
+
+  // 3. Check for CI/CD
+  const hasGithubActions = fs.existsSync(path.join(projectRoot, '.github/workflows'));
+  if (!hasGithubActions) {
+    prompts.push({
+      category: 'DevOps',
+      priority: 'medium',
+      title: 'Add GitHub Actions CI/CD',
+      prompt: `Create a GitHub Actions CI/CD pipeline in .github/workflows/ci.yml:
+
+1. Run on push to main and pull requests
+2. Set up Node.js environment
+3. Install dependencies (npm ci)
+4. Run linting (if configured)
+5. Run tests with coverage
+6. Build the project
+7. Add caching for node_modules
+
+Make it fast and reliable for developer productivity.`,
+      command: 'mkdir -p .github/workflows'
+    });
+  }
+
+  // 4. Check for security setup
+  const hasEnvExample = fs.existsSync(path.join(projectRoot, '.env.example'));
+  if (!hasEnvExample && fs.existsSync(path.join(projectRoot, '.env'))) {
+    prompts.push({
+      category: 'Security',
+      priority: 'high',
+      title: 'Create .env.example',
+      prompt: `Create a .env.example file documenting all required environment variables:
+
+1. List all env vars from .env (without actual values)
+2. Add comments explaining each variable
+3. Group by category (database, auth, external services)
+4. Include example/placeholder values where helpful
+5. Document which are required vs optional
+
+This helps new developers set up the project securely.`,
+      command: null
+    });
+  }
+
+  // 5. Check for README quality
+  const readmePath = path.join(projectRoot, 'README.md');
+  let readmeScore = 0;
+  if (fs.existsSync(readmePath)) {
+    const readme = fs.readFileSync(readmePath, 'utf-8');
+    if (readme.includes('## Installation')) readmeScore++;
+    if (readme.includes('## Usage')) readmeScore++;
+    if (readme.includes('## Contributing')) readmeScore++;
+    if (readme.includes('## License')) readmeScore++;
+    if (readme.length > 1000) readmeScore++;
+  }
+
+  if (readmeScore < 3) {
+    prompts.push({
+      category: 'Documentation',
+      priority: 'medium',
+      title: 'Improve README.md',
+      prompt: `Enhance the README.md to be comprehensive and welcoming:
+
+1. Clear project description and value proposition
+2. Installation instructions (step by step)
+3. Quick start / Usage examples
+4. Configuration options
+5. Contributing guidelines
+6. License information
+7. Links to documentation
+8. Badges (build status, version, license)
+
+Make it easy for new users to understand and get started.`,
+      command: null
+    });
+  }
+
+  // 6. Check for TypeScript setup
+  const hasTypeScript = fs.existsSync(path.join(projectRoot, 'tsconfig.json'));
+  const packageJson = loadPackageJson(projectRoot);
+  const hasJsFiles = fs.readdirSync(projectRoot).some(f => f.endsWith('.js') && !f.includes('config'));
+
+  if (!hasTypeScript && hasJsFiles) {
+    prompts.push({
+      category: 'Quality',
+      priority: 'low',
+      title: 'Migrate to TypeScript',
+      prompt: `Convert this JavaScript project to TypeScript:
+
+1. Install typescript and @types packages
+2. Create tsconfig.json with strict settings
+3. Rename .js files to .ts (start with entry points)
+4. Add type annotations to functions and variables
+5. Fix type errors iteratively
+6. Update build scripts
+
+Start with the most critical files and expand gradually.`,
+      command: 'npm install -D typescript @types/node'
+    });
+  }
+
+  // 7. Check for linting
+  const hasEslint = fs.existsSync(path.join(projectRoot, '.eslintrc.js')) ||
+                    fs.existsSync(path.join(projectRoot, '.eslintrc.json')) ||
+                    fs.existsSync(path.join(projectRoot, 'eslint.config.js'));
+
+  if (!hasEslint) {
+    prompts.push({
+      category: 'Quality',
+      priority: 'medium',
+      title: 'Set up ESLint',
+      prompt: `Set up ESLint for code quality and consistency:
+
+1. Install eslint and relevant plugins
+2. Create eslint.config.js (flat config format)
+3. Configure rules appropriate for the project
+4. Add lint script to package.json
+5. Fix any existing linting issues
+6. Consider adding Prettier for formatting
+
+Use sensible defaults that catch real bugs without being annoying.`,
+      command: 'npm install -D eslint'
+    });
+  }
+
+  // 8. Project-specific suggestions based on tech stack
+  if (packageJson?.dependencies?.next) {
+    const hasMiddleware = fs.existsSync(path.join(projectRoot, 'middleware.ts'));
+    if (!hasMiddleware) {
+      prompts.push({
+        category: 'Security',
+        priority: 'medium',
+        title: 'Add Next.js middleware',
+        prompt: `Create a middleware.ts file for Next.js request handling:
+
+1. Set up authentication checks for protected routes
+2. Add rate limiting headers
+3. Configure security headers (CSP, HSTS, etc.)
+4. Handle redirects for legacy URLs
+5. Add request logging for debugging
+
+Keep it performant as middleware runs on every request.`,
+        command: null
+      });
+    }
+  }
+
+  // Group by priority
+  const highPriority = prompts.filter(p => p.priority === 'high');
+  const mediumPriority = prompts.filter(p => p.priority === 'medium');
+  const lowPriority = prompts.filter(p => p.priority === 'low');
+
+  const limit = options.limit || 5;
+  const allPrompts = [...highPriority, ...mediumPriority, ...lowPriority].slice(0, limit);
+
+  // JSON mode - return data only, no display
+  if (options.json) {
+    return allPrompts;
+  }
+
+  // Display prompts
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}📋 AI-Ready Prompts${utils.COLORS.reset}
+${utils.COLORS.dim}Copy and paste into Cursor, Claude Code, Codex, etc.${utils.COLORS.reset}
+`);
+
+  if (prompts.length === 0) {
+    console.log(`${utils.COLORS.green}✓${utils.COLORS.reset} Project looks well set up! No urgent suggestions.`);
+    console.log(`${utils.COLORS.dim}Run 'bootspring health' for detailed analysis.${utils.COLORS.reset}`);
+    return undefined;
+  }
+
+  for (let i = 0; i < allPrompts.length; i++) {
+    const p = allPrompts[i];
+    if (!p) continue;
+    const priorityColor = p.priority === 'high' ? utils.COLORS.red :
+      p.priority === 'medium' ? utils.COLORS.yellow : utils.COLORS.dim;
+    const priorityLabel = p.priority.toUpperCase();
+
+    console.log(`${utils.COLORS.bold}${i + 1}. ${p.title}${utils.COLORS.reset} ${priorityColor}[${priorityLabel}]${utils.COLORS.reset} ${utils.COLORS.dim}(${p.category})${utils.COLORS.reset}`);
+    console.log();
+    console.log(`${utils.COLORS.cyan}┌${'─'.repeat(70)}${utils.COLORS.reset}`);
+    console.log(`${utils.COLORS.cyan}│${utils.COLORS.reset}`);
+
+    // Format prompt for display
+    const lines = p.prompt.split('\n');
+    for (const line of lines) {
+      console.log(`${utils.COLORS.cyan}│${utils.COLORS.reset}  ${line}`);
+    }
+
+    console.log(`${utils.COLORS.cyan}│${utils.COLORS.reset}`);
+    console.log(`${utils.COLORS.cyan}└${'─'.repeat(70)}${utils.COLORS.reset}`);
+
+    if (p.command) {
+      console.log(`${utils.COLORS.dim}  After: ${p.command}${utils.COLORS.reset}`);
+    }
+    console.log();
+  }
+
+  const remaining = prompts.length - limit;
+  if (remaining > 0) {
+    console.log(`${utils.COLORS.dim}+${remaining} more suggestions. Use --limit to see more.${utils.COLORS.reset}`);
+  }
+
+  console.log(`
+${utils.COLORS.bold}Quick Copy:${utils.COLORS.reset} Click a prompt box to copy, then paste into your AI assistant.
+${utils.COLORS.dim}Tip: Use 'bootspring suggest prompts --json' for machine-readable output.${utils.COLORS.reset}
+`);
+
+  return undefined;
+}
+
+/**
+ * Load PROJECT_STATE.json
+ */
+function loadProjectState(projectRoot: string): ProjectState | null {
+  try {
+    const statePath = path.join(projectRoot, 'planning', 'PROJECT_STATE.json');
+    if (fs.existsSync(statePath)) {
+      return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+    }
+  } catch {
+    // Ignore errors
+  }
+  return null;
+}
+
+/**
+ * Load package.json
+ */
+function loadPackageJson(projectRoot: string): PackageJson | null {
+  try {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    }
+  } catch {
+    // Ignore errors
+  }
+  return null;
+}
+
+/**
+ * Show help
+ */
+function showHelp(): void {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Suggest${utils.COLORS.reset}
+${utils.COLORS.dim}AI-powered recommendations and auto-suggestions${utils.COLORS.reset}
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring suggest [command] [options]
+
+${utils.COLORS.bold}Commands:${utils.COLORS.reset}
+  ${utils.COLORS.cyan}(default)${utils.COLORS.reset}         Show all recommendations
+  ${utils.COLORS.cyan}prompts${utils.COLORS.reset}           Generate copy-paste prompts for AI assistants
+  ${utils.COLORS.cyan}next${utils.COLORS.reset}              Show single next action
+  ${utils.COLORS.cyan}learning${utils.COLORS.reset}          Show learning statistics
+  ${utils.COLORS.cyan}workflows${utils.COLORS.reset}         Show workflow recommendations only
+  ${utils.COLORS.cyan}skills${utils.COLORS.reset}            Show skill recommendations only
+  ${utils.COLORS.cyan}config${utils.COLORS.reset}            Show auto-suggest configuration
+  ${utils.COLORS.cyan}analyze <text>${utils.COLORS.reset}    Test auto-suggest on text
+
+${utils.COLORS.bold}Auto-Suggest Options:${utils.COLORS.reset}
+  --enable-auto           Enable proactive suggestions in Claude Code
+  --disable-auto          Disable auto-suggestions
+  --category <name>       Toggle a suggestion category
+  --suppress <cmd>        Stop suggesting a specific command
+  --unsuppress <cmd>      Resume suggesting a command
+
+${utils.COLORS.bold}Other Options:${utils.COLORS.reset}
+  --limit <n>             Number of recommendations (default: 5)
+  --json                  Output as JSON
+
+${utils.COLORS.bold}How Auto-Suggest Works:${utils.COLORS.reset}
+  1. Monitors your messages in Claude Code
+  2. Detects when Bootspring features could help
+  3. Proactively suggests relevant commands
+  4. Learn from your preferences over time
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring suggest                        # Show recommendations
+  bootspring suggest prompts                # AI-ready prompts for Cursor/Claude Code
+  bootspring suggest prompts --limit 10     # Show more prompts
+  bootspring suggest next                   # Single next action
+  bootspring suggest --enable-auto          # Enable auto-suggestions
+  bootspring suggest config                 # View auto-suggest settings
+  bootspring suggest analyze "deploy to vercel"
+`);
+}
+
+/**
+ * Run suggest command
+ */
+export async function run(args: string[]): Promise<void> {
+  const parsedArgs = utils.parseArgs(args);
+  const subcommand = parsedArgs._[0];
+
+  if (subcommand === 'help' || subcommand === '-h' || subcommand === '--help') {
+    showHelp();
+    return;
+  }
+
+  const cfg = config.load();
+  const projectRoot = cfg._projectRoot;
+
+  // Handle auto-suggest flags first
+  if (parsedArgs['enable-auto']) {
+    toggleAutoSuggest(projectRoot, true);
+    return;
+  }
+
+  if (parsedArgs['disable-auto']) {
+    toggleAutoSuggest(projectRoot, false);
+    return;
+  }
+
+  if (parsedArgs.category) {
+    toggleCategory(projectRoot, parsedArgs.category);
+    return;
+  }
+
+  if (parsedArgs.suppress) {
+    suppressCommand(projectRoot, parsedArgs.suppress, true);
+    return;
+  }
+
+  if (parsedArgs.unsuppress) {
+    suppressCommand(projectRoot, parsedArgs.unsuppress, false);
+    return;
+  }
+
+  const limit = typeof parsedArgs.limit === 'number' ? parsedArgs.limit :
+    typeof parsedArgs.limit === 'string' ? parseInt(parsedArgs.limit, 10) : 5;
+
+  switch (subcommand) {
+    case 'prompts':
+    case 'prompt':
+    case 'ai': {
+      const promptResult = await generatePrompts(projectRoot, {
+        limit,
+        json: parsedArgs.json
+      });
+      if (parsedArgs.json && promptResult) {
+        console.log(JSON.stringify(promptResult, null, 2));
+      }
+      break;
+    }
+
+    case 'next':
+      await showNextAction(projectRoot);
+      break;
+
+    case 'learning':
+    case 'stats':
+      showLearningStats();
+      break;
+
+    case 'config':
+    case 'auto':
+    case 'settings':
+      showAutoSuggestConfig(projectRoot);
+      break;
+
+    case 'analyze':
+    case 'test': {
+      const text = parsedArgs._.slice(1).join(' ');
+      if (!text) {
+        console.log(`${utils.COLORS.yellow}Usage: bootspring suggest analyze "<text>"${utils.COLORS.reset}`);
+        return;
+      }
+      analyzeText(projectRoot, text);
+      break;
+    }
+
+    case 'workflows': {
+      const wfResult = await showRecommendations(projectRoot, {
+        limit,
+        json: parsedArgs.json
+      });
+      if (parsedArgs.json) {
+        console.log(JSON.stringify({ workflows: wfResult?.workflows || [] }, null, 2));
+      }
+      break;
+    }
+
+    case 'skills': {
+      const skResult = await showRecommendations(projectRoot, {
+        limit,
+        json: parsedArgs.json
+      });
+      if (parsedArgs.json) {
+        console.log(JSON.stringify({ skills: skResult?.skills || [] }, null, 2));
+      }
+      break;
+    }
+
+    default: {
+      const result = await showRecommendations(projectRoot, {
+        limit,
+        json: parsedArgs.json
+      });
+      if (parsedArgs.json) {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    }
+  }
+}
+
+export {
+  getProjectContext,
+  showRecommendations,
+  generatePrompts,
+  toggleAutoSuggest,
+  showAutoSuggestConfig,
+  analyzeText
+};