@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/core/onboard-workflow.ts

@@ -0,0 +1,1293 @@
+/**
+ * Bootspring Onboard Workflow Engine
+ *
+ * Layers Bootspring onto existing codebases through detection,
+ * pattern scanning, and configuration generation.
+ *
+ * @package bootspring
+ * @module core/onboard-workflow
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Import analyzers from JS modules
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { StructureAnalyzer } = require('../../analyzers/structure-analyzer') as {
+  StructureAnalyzer: new (projectRoot: string, options?: Record<string, unknown>) => {
+    analyze: () => Record<string, unknown>;
+  };
+};
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { ArchitectureAnalyzer } = require('../../analyzers/architecture-analyzer') as {
+  ArchitectureAnalyzer: new (projectRoot: string) => {
+    analyze: () => Record<string, unknown>;
+  };
+};
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { DependencyAnalyzer } = require('../../analyzers/dependency-analyzer') as {
+  DependencyAnalyzer: new (projectRoot: string) => {
+    analyze: () => Record<string, unknown>;
+  };
+};
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type OnboardPhaseStatus = 'pending' | 'in_progress' | 'completed' | 'skipped' | 'failed';
+
+export interface OnboardPhaseDefinition {
+  name: string;
+  description: string;
+  order: number;
+  required: boolean;
+  dependencies?: string[] | undefined;
+}
+
+export interface OnboardPhaseState {
+  status: OnboardPhaseStatus;
+  startedAt: string | null;
+  completedAt: string | null;
+  result: unknown | null;
+  error: string | null;
+}
+
+export interface DetectionPattern {
+  id: string;
+  name: string;
+  files?: string[] | undefined;
+  packages?: string[] | undefined;
+}
+
+export interface DetectedStack {
+  id: string;
+  name: string;
+}
+
+export interface StackDetection {
+  framework: DetectedStack | null;
+  language: DetectedStack | null;
+  database: DetectedStack | null;
+  hosting: DetectedStack | null;
+  testing: DetectedStack | null;
+  auth: DetectedStack | null;
+  payments: DetectedStack | null;
+  detected: Array<{ category: string } & DetectionPattern>;
+  packageJson?: {
+    name?: string;
+    version?: string;
+    description?: string;
+  } | null;
+}
+
+export interface DetectionData {
+  stack: StackDetection | null;
+  patterns: {
+    architecturePatterns?: unknown[];
+    moduleCount?: number;
+    circularDeps?: number;
+    quickMode?: boolean;
+  } | null;
+  docs: DocsDiscovery | null;
+}
+
+export interface GeneratedFiles {
+  config: string | null;
+  claudeMd: string | null;
+  timestamp?: string;
+}
+
+export interface BaselineMetrics {
+  files: number;
+  lines: number;
+  dependencies: number;
+}
+
+export interface Baseline {
+  timestamp: string;
+  metrics: BaselineMetrics;
+}
+
+export interface OnboardWorkflowState {
+  version: string;
+  startedAt: string | null;
+  lastUpdated: string | null;
+  currentPhase: string | null;
+  phases: Record<string, OnboardPhaseState>;
+  detection: DetectionData;
+  generated: GeneratedFiles;
+  baseline: Baseline | null;
+}
+
+export interface DetectionResult {
+  stack: StackDetection;
+  structure: Record<string, unknown>;
+  packageJson: {
+    name?: string;
+    version?: string;
+    description?: string;
+  } | null;
+  timestamp: string;
+}
+
+export interface PatternScanResult {
+  architecture: Record<string, unknown>;
+  dependencies: Record<string, unknown>;
+  features: FeatureDetection;
+  timestamp: string;
+  quickMode?: boolean;
+}
+
+export interface FeatureDetection {
+  auth: boolean;
+  payments: boolean;
+  api: boolean;
+  database: boolean;
+  email: boolean;
+  uploads: boolean;
+  search: boolean;
+  realtime: boolean;
+  analytics: boolean;
+  i18n: boolean;
+  [key: string]: boolean;
+}
+
+export interface DocInfo {
+  file: string;
+  type: string;
+  required: boolean;
+  path?: string;
+  size?: number;
+}
+
+export interface DocsDiscovery {
+  found: DocInfo[];
+  missing: DocInfo[];
+  recommended: DocInfo[];
+  hasDocsDir?: boolean;
+  docsCount?: number;
+}
+
+export interface ConfigGenerationResult {
+  configContent: string;
+  claudeMdContent: string;
+  configPath: string;
+  claudeMdPath: string;
+}
+
+export interface OnboardPhaseProgress {
+  id: string;
+  name: string;
+  description: string;
+  order: number;
+  required: boolean;
+  status: OnboardPhaseStatus;
+  dependenciesMet: boolean;
+}
+
+export interface OnboardWorkflowProgress {
+  currentPhase: string | null;
+  startedAt: string | null;
+  lastUpdated: string | null;
+  phases: OnboardPhaseProgress[];
+  overall: {
+    completed: number;
+    total: number;
+    percentage: number;
+  };
+  required: {
+    completed: number;
+    total: number;
+    percentage: number;
+  };
+  isComplete: boolean;
+  detection: DetectionData;
+}
+
+export interface OnboardResumePoint {
+  phase: string;
+  phaseName: string | undefined;
+  phaseStatus: OnboardPhaseStatus | undefined;
+  lastUpdated: string | null;
+}
+
+export interface OnboardWorkflowOptions {
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Workflow phase status
+ */
+export const PHASE_STATUS: Record<string, OnboardPhaseStatus> = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  SKIPPED: 'skipped',
+  FAILED: 'failed'
+};
+
+/**
+ * Onboarding phases
+ */
+export const ONBOARD_PHASES: Record<string, OnboardPhaseDefinition> = {
+  detection: {
+    name: 'Stack Detection',
+    description: 'Detect framework, language, database, and hosting',
+    order: 1,
+    required: true
+  },
+  patterns: {
+    name: 'Pattern Scan',
+    description: 'Find auth, payments, components, and code patterns',
+    order: 2,
+    required: true,
+    dependencies: ['detection']
+  },
+  docs: {
+    name: 'Documentation Discovery',
+    description: 'Inventory existing docs and find gaps',
+    order: 3,
+    required: false,
+    dependencies: ['detection']
+  },
+  config: {
+    name: 'Config Generation',
+    description: 'Generate bootspring.config.js and CLAUDE.md',
+    order: 4,
+    required: true,
+    dependencies: ['detection', 'patterns']
+  },
+  baseline: {
+    name: 'Baseline Capture',
+    description: 'Record metrics for future comparison',
+    order: 5,
+    required: false,
+    dependencies: ['detection', 'patterns']
+  },
+  reverse: {
+    name: 'Reverse Engineer',
+    description: 'Generate PRD from code structure (optional)',
+    order: 6,
+    required: false,
+    dependencies: ['detection', 'patterns', 'docs']
+  }
+};
+
+/**
+ * Stack detection patterns
+ */
+export const STACK_DETECTION: Record<string, DetectionPattern[]> = {
+  frameworks: [
+    { id: 'nextjs', name: 'Next.js', files: ['next.config.js', 'next.config.mjs', 'next.config.ts'], packages: ['next'] },
+    { id: 'remix', name: 'Remix', files: ['remix.config.js'], packages: ['@remix-run/react'] },
+    { id: 'nuxt', name: 'Nuxt', files: ['nuxt.config.js', 'nuxt.config.ts'], packages: ['nuxt'] },
+    { id: 'svelte', name: 'SvelteKit', files: ['svelte.config.js'], packages: ['@sveltejs/kit'] },
+    { id: 'astro', name: 'Astro', files: ['astro.config.mjs'], packages: ['astro'] },
+    { id: 'vite', name: 'Vite', files: ['vite.config.js', 'vite.config.ts'], packages: ['vite'] },
+    { id: 'express', name: 'Express', packages: ['express'] },
+    { id: 'fastify', name: 'Fastify', packages: ['fastify'] },
+    { id: 'nestjs', name: 'NestJS', packages: ['@nestjs/core'] },
+    { id: 'react', name: 'React', packages: ['react'] },
+    { id: 'vue', name: 'Vue', packages: ['vue'] },
+    { id: 'angular', name: 'Angular', files: ['angular.json'], packages: ['@angular/core'] }
+  ],
+  languages: [
+    { id: 'typescript', name: 'TypeScript', files: ['tsconfig.json'], packages: ['typescript'] },
+    { id: 'javascript', name: 'JavaScript', files: ['package.json'] }
+  ],
+  databases: [
+    { id: 'prisma', name: 'Prisma', files: ['prisma/schema.prisma'], packages: ['prisma', '@prisma/client'] },
+    { id: 'drizzle', name: 'Drizzle', packages: ['drizzle-orm'] },
+    { id: 'mongoose', name: 'MongoDB (Mongoose)', packages: ['mongoose'] },
+    { id: 'typeorm', name: 'TypeORM', packages: ['typeorm'] },
+    { id: 'sequelize', name: 'Sequelize', packages: ['sequelize'] },
+    { id: 'knex', name: 'Knex', packages: ['knex'] },
+    { id: 'supabase', name: 'Supabase', packages: ['@supabase/supabase-js'] },
+    { id: 'firebase', name: 'Firebase', packages: ['firebase', 'firebase-admin'] }
+  ],
+  hosting: [
+    { id: 'vercel', name: 'Vercel', files: ['vercel.json', '.vercel'] },
+    { id: 'netlify', name: 'Netlify', files: ['netlify.toml', '.netlify'] },
+    { id: 'railway', name: 'Railway', files: ['railway.json'] },
+    { id: 'docker', name: 'Docker', files: ['Dockerfile', 'docker-compose.yml'] },
+    { id: 'fly', name: 'Fly.io', files: ['fly.toml'] },
+    { id: 'render', name: 'Render', files: ['render.yaml'] },
+    { id: 'aws', name: 'AWS', files: ['serverless.yml', 'amplify.yml', 'samconfig.toml'] },
+    { id: 'gcp', name: 'Google Cloud', files: ['app.yaml', 'cloudbuild.yaml'] }
+  ],
+  testing: [
+    { id: 'vitest', name: 'Vitest', files: ['vitest.config.ts', 'vitest.config.js'], packages: ['vitest'] },
+    { id: 'jest', name: 'Jest', files: ['jest.config.js', 'jest.config.ts'], packages: ['jest'] },
+    { id: 'playwright', name: 'Playwright', files: ['playwright.config.ts'], packages: ['@playwright/test'] },
+    { id: 'cypress', name: 'Cypress', files: ['cypress.config.js', 'cypress.config.ts'], packages: ['cypress'] },
+    { id: 'mocha', name: 'Mocha', packages: ['mocha'] }
+  ],
+  auth: [
+    { id: 'nextauth', name: 'NextAuth.js', packages: ['next-auth'] },
+    { id: 'authjs', name: 'Auth.js', packages: ['@auth/core'] },
+    { id: 'clerk', name: 'Clerk', packages: ['@clerk/nextjs', '@clerk/clerk-react'] },
+    { id: 'auth0', name: 'Auth0', packages: ['@auth0/nextjs-auth0', 'auth0'] },
+    { id: 'supabase-auth', name: 'Supabase Auth', packages: ['@supabase/auth-helpers-nextjs'] },
+    { id: 'firebase-auth', name: 'Firebase Auth', packages: ['firebase/auth'] },
+    { id: 'passport', name: 'Passport.js', packages: ['passport'] }
+  ],
+  payments: [
+    { id: 'stripe', name: 'Stripe', packages: ['stripe', '@stripe/stripe-js'] },
+    { id: 'lemon-squeezy', name: 'Lemon Squeezy', packages: ['@lemonsqueezy/lemonsqueezy.js'] },
+    { id: 'paddle', name: 'Paddle', packages: ['@paddle/paddle-js'] },
+    { id: 'paypal', name: 'PayPal', packages: ['@paypal/react-paypal-js', 'paypal-rest-sdk'] }
+  ]
+};
+
+/**
+ * Default workflow state
+ */
+export const DEFAULT_STATE: OnboardWorkflowState = {
+  version: '1.0.0',
+  startedAt: null,
+  lastUpdated: null,
+  currentPhase: null,
+  phases: {},
+  detection: {
+    stack: null,
+    patterns: null,
+    docs: null
+  },
+  generated: {
+    config: null,
+    claudeMd: null
+  },
+  baseline: null
+};
+
+// ============================================================================
+// OnboardWorkflowEngine Class
+// ============================================================================
+
+/**
+ * OnboardWorkflowEngine - Manages onboarding workflow
+ */
+export class OnboardWorkflowEngine {
+  readonly projectRoot: string;
+  readonly workflowDir: string;
+  readonly stateFile: string;
+  readonly detectionDir: string;
+  readonly generatedDir: string;
+  readonly baselineDir: string;
+  readonly options: OnboardWorkflowOptions;
+  state: OnboardWorkflowState | null;
+
+  constructor(projectRoot: string, options: OnboardWorkflowOptions = {}) {
+    this.projectRoot = projectRoot;
+    this.workflowDir = path.join(projectRoot, '.bootspring', 'onboard');
+    this.stateFile = path.join(this.workflowDir, 'workflow-state.json');
+    this.detectionDir = path.join(this.workflowDir, 'detection');
+    this.generatedDir = path.join(this.workflowDir, 'generated');
+    this.baselineDir = path.join(this.workflowDir, 'baseline');
+    this.options = options;
+    this.state = null;
+  }
+
+  /**
+   * Setup directories
+   */
+  setupDirectories(): void {
+    const dirs = [
+      this.workflowDir,
+      this.detectionDir,
+      this.generatedDir,
+      this.baselineDir
+    ];
+
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    }
+  }
+
+  /**
+   * Load workflow state
+   */
+  loadState(): boolean {
+    if (fs.existsSync(this.stateFile)) {
+      try {
+        this.state = JSON.parse(fs.readFileSync(this.stateFile, 'utf-8')) as OnboardWorkflowState;
+        return true;
+      } catch {
+        this.state = { ...DEFAULT_STATE, phases: {}, detection: { stack: null, patterns: null, docs: null }, generated: { config: null, claudeMd: null } };
+        return false;
+      }
+    }
+    this.state = { ...DEFAULT_STATE, phases: {}, detection: { stack: null, patterns: null, docs: null }, generated: { config: null, claudeMd: null } };
+    return false;
+  }
+
+  /**
+   * Save workflow state
+   */
+  saveState(): void {
+    if (!this.state) return;
+    this.setupDirectories();
+    this.state.lastUpdated = new Date().toISOString();
+    fs.writeFileSync(this.stateFile, JSON.stringify(this.state, null, 2));
+  }
+
+  /**
+   * Initialize workflow
+   */
+  initializeWorkflow(): OnboardWorkflowState {
+    this.setupDirectories();
+    this.state = {
+      ...DEFAULT_STATE,
+      startedAt: new Date().toISOString(),
+      lastUpdated: new Date().toISOString(),
+      phases: {},
+      detection: { stack: null, patterns: null, docs: null },
+      generated: { config: null, claudeMd: null }
+    };
+
+    // Initialize phase states
+    for (const phaseId of Object.keys(ONBOARD_PHASES)) {
+      this.state.phases[phaseId] = {
+        status: 'pending',
+        startedAt: null,
+        completedAt: null,
+        result: null,
+        error: null
+      };
+    }
+
+    this.state.currentPhase = 'detection';
+    this.saveState();
+    return this.state;
+  }
+
+  /**
+   * Check if workflow exists
+   */
+  hasWorkflow(): boolean {
+    return fs.existsSync(this.stateFile);
+  }
+
+  /**
+   * Reset workflow
+   */
+  resetWorkflow(): boolean {
+    if (fs.existsSync(this.stateFile)) {
+      fs.unlinkSync(this.stateFile);
+    }
+    this.state = null;
+    return true;
+  }
+
+  /**
+   * Check if phase dependencies are met
+   */
+  arePhaseDependenciesMet(phaseId: string): boolean {
+    const phase = ONBOARD_PHASES[phaseId];
+    if (!phase || !phase.dependencies || phase.dependencies.length === 0) {
+      return true;
+    }
+
+    for (const depPhaseId of phase.dependencies) {
+      const depPhase = this.state?.phases[depPhaseId];
+      if (!depPhase || depPhase.status !== 'completed') {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get next phase
+   */
+  getNextPhase(): string | null {
+    if (!this.state) return null;
+
+    const phaseOrder = Object.keys(ONBOARD_PHASES).sort((a, b) => {
+      const phaseA = ONBOARD_PHASES[a];
+      const phaseB = ONBOARD_PHASES[b];
+      return (phaseA?.order ?? 0) - (phaseB?.order ?? 0);
+    });
+
+    for (const phaseId of phaseOrder) {
+      const phase = this.state.phases[phaseId];
+      if (phase?.status === 'pending' && this.arePhaseDependenciesMet(phaseId)) {
+        return phaseId;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Start a phase
+   */
+  startPhase(phaseId: string): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'in_progress';
+    phase.startedAt = new Date().toISOString();
+    this.state.currentPhase = phaseId;
+    this.saveState();
+  }
+
+  /**
+   * Complete a phase
+   */
+  completePhase(phaseId: string, result: unknown = null): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'completed';
+    phase.completedAt = new Date().toISOString();
+    phase.result = result;
+    this.saveState();
+  }
+
+  /**
+   * Fail a phase
+   */
+  failPhase(phaseId: string, error: string): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'failed';
+    phase.completedAt = new Date().toISOString();
+    phase.error = error;
+    this.saveState();
+  }
+
+  /**
+   * Skip a phase
+   */
+  skipPhase(phaseId: string): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'skipped';
+    phase.completedAt = new Date().toISOString();
+    this.saveState();
+  }
+
+  /**
+   * Run detection phase
+   */
+  async runDetection(): Promise<DetectionResult> {
+    const stack: StackDetection = {
+      framework: null,
+      language: null,
+      database: null,
+      hosting: null,
+      testing: null,
+      auth: null,
+      payments: null,
+      detected: []
+    };
+
+    // Read package.json if exists
+    const pkgPath = path.join(this.projectRoot, 'package.json');
+    let pkg: Record<string, unknown> | null = null;
+    if (fs.existsSync(pkgPath)) {
+      try {
+        pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as Record<string, unknown>;
+      } catch {
+        // Skip
+      }
+    }
+
+    const deps = (pkg?.dependencies ?? {}) as Record<string, string>;
+    const devDeps = (pkg?.devDependencies ?? {}) as Record<string, string>;
+    const allDeps: Record<string, string> = pkg ? { ...deps, ...devDeps } : {};
+
+    // Check for files and packages
+    const checkDetection = (_category: string, detections: DetectionPattern[]): DetectionPattern | null => {
+      for (const detection of detections) {
+        // Check files
+        if (detection.files) {
+          for (const file of detection.files) {
+            const filePath = path.join(this.projectRoot, file);
+            if (fs.existsSync(filePath)) {
+              return detection;
+            }
+          }
+        }
+
+        // Check packages
+        if (detection.packages) {
+          for (const pkgName of detection.packages) {
+            if (allDeps[pkgName]) {
+              return detection;
+            }
+          }
+        }
+      }
+      return null;
+    };
+
+    // Map plural category names to singular for stack object
+    const categoryToStackKey: Record<string, keyof StackDetection> = {
+      frameworks: 'framework',
+      languages: 'language',
+      databases: 'database',
+      hosting: 'hosting',
+      testing: 'testing',
+      auth: 'auth',
+      payments: 'payments'
+    };
+
+    // Detect each category
+    for (const [category, detections] of Object.entries(STACK_DETECTION)) {
+      const detected = checkDetection(category, detections);
+      if (detected) {
+        const stackKey = categoryToStackKey[category] ?? category;
+        if (stackKey in stack && stackKey !== 'detected' && stackKey !== 'packageJson') {
+          (stack as unknown as Record<string, unknown>)[stackKey] = {
+            id: detected.id,
+            name: detected.name
+          };
+        }
+        stack.detected.push({
+          category,
+          ...detected
+        });
+      }
+    }
+
+    // Run structure analysis
+    const structureAnalyzer = new StructureAnalyzer(this.projectRoot);
+    const structure = structureAnalyzer.analyze();
+
+    // Save detection results
+    const pkgName = pkg?.name as string | undefined;
+    const pkgVersion = pkg?.version as string | undefined;
+    const pkgDescription = pkg?.description as string | undefined;
+
+    const detectionResult: DetectionResult = {
+      stack,
+      structure,
+      packageJson: pkg ? {
+        ...(pkgName !== undefined && { name: pkgName }),
+        ...(pkgVersion !== undefined && { version: pkgVersion }),
+        ...(pkgDescription !== undefined && { description: pkgDescription })
+      } : null,
+      timestamp: new Date().toISOString()
+    };
+
+    // Write to detection directory
+    fs.writeFileSync(
+      path.join(this.detectionDir, 'stack.json'),
+      JSON.stringify(stack, null, 2)
+    );
+    fs.writeFileSync(
+      path.join(this.detectionDir, 'structure.json'),
+      JSON.stringify(structure, null, 2)
+    );
+
+    if (this.state) {
+      this.state.detection.stack = stack;
+    }
+    return detectionResult;
+  }
+
+  /**
+   * Run pattern scan phase
+   */
+  async runPatternScan(): Promise<PatternScanResult> {
+    // Auto-detect large codebase and use quick mode
+    const structurePath = path.join(this.detectionDir, 'structure.json');
+    let fileCount = 0;
+    if (fs.existsSync(structurePath)) {
+      try {
+        const structure = JSON.parse(fs.readFileSync(structurePath, 'utf-8')) as Record<string, unknown>;
+        const stats = structure.stats as Record<string, number> | undefined;
+        fileCount = stats?.totalFiles ?? 0;
+      } catch {
+        // Ignore
+      }
+    }
+
+    // For large codebases (500+ files), use quick mode automatically
+    const LARGE_CODEBASE_THRESHOLD = 500;
+    if (fileCount >= LARGE_CODEBASE_THRESHOLD) {
+      return this.runQuickPatternScan();
+    }
+
+    // Run architecture analysis
+    const architectureAnalyzer = new ArchitectureAnalyzer(this.projectRoot);
+    const architecture = architectureAnalyzer.analyze();
+
+    // Run dependency analysis
+    const dependencyAnalyzer = new DependencyAnalyzer(this.projectRoot);
+    const dependencies = dependencyAnalyzer.analyze();
+
+    const patterns: PatternScanResult = {
+      architecture,
+      dependencies,
+      features: this.detectFeatures(),
+      timestamp: new Date().toISOString()
+    };
+
+    // Save pattern results
+    fs.writeFileSync(
+      path.join(this.detectionDir, 'patterns.json'),
+      JSON.stringify(patterns, null, 2)
+    );
+
+    const archPatterns = architecture.patterns as unknown[] | undefined;
+    const modules = architecture.modules as unknown[] | undefined;
+    const circularDeps = dependencies.circularDependencies as unknown[] | undefined;
+
+    if (this.state) {
+      this.state.detection.patterns = {
+        architecturePatterns: (archPatterns ?? []).slice(0, 3),
+        moduleCount: modules?.length ?? 0,
+        circularDeps: circularDeps?.length ?? 0
+      };
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Run quick pattern scan (skips heavy dependency analysis)
+   */
+  async runQuickPatternScan(): Promise<PatternScanResult> {
+    // Run architecture analysis only (fast)
+    const architectureAnalyzer = new ArchitectureAnalyzer(this.projectRoot);
+    const architecture = architectureAnalyzer.analyze();
+
+    // Skip dependency analysis - it's too slow for large codebases
+    const patterns: PatternScanResult = {
+      architecture,
+      dependencies: {
+        fileCount: 0,
+        circularDependencies: [],
+        unusedDependencies: [],
+        summary: { totalFiles: 0, circularCount: 0, unusedCount: 0, skipped: true }
+      },
+      features: this.detectFeatures(),
+      timestamp: new Date().toISOString(),
+      quickMode: true
+    };
+
+    // Save pattern results
+    fs.writeFileSync(
+      path.join(this.detectionDir, 'patterns.json'),
+      JSON.stringify(patterns, null, 2)
+    );
+
+    const archPatterns = architecture.patterns as unknown[] | undefined;
+    const modules = architecture.modules as unknown[] | undefined;
+
+    if (this.state) {
+      this.state.detection.patterns = {
+        architecturePatterns: (archPatterns ?? []).slice(0, 3),
+        moduleCount: modules?.length ?? 0,
+        circularDeps: 0,
+        quickMode: true
+      };
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Detect features in the codebase
+   */
+  detectFeatures(): FeatureDetection {
+    const features: FeatureDetection = {
+      auth: false,
+      payments: false,
+      api: false,
+      database: false,
+      email: false,
+      uploads: false,
+      search: false,
+      realtime: false,
+      analytics: false,
+      i18n: false
+    };
+
+    // Check for feature directories
+    const featureDirs: Record<string, string[]> = {
+      auth: ['auth', 'authentication', 'login'],
+      payments: ['payments', 'billing', 'subscriptions', 'checkout'],
+      api: ['api', 'routes', 'endpoints'],
+      database: ['db', 'database', 'prisma', 'models'],
+      email: ['email', 'mail', 'notifications'],
+      uploads: ['uploads', 'files', 'storage'],
+      search: ['search'],
+      realtime: ['websocket', 'realtime', 'socket'],
+      analytics: ['analytics', 'tracking'],
+      i18n: ['i18n', 'locales', 'translations']
+    };
+
+    const searchPaths = [
+      this.projectRoot,
+      path.join(this.projectRoot, 'src'),
+      path.join(this.projectRoot, 'app'),
+      path.join(this.projectRoot, 'lib')
+    ];
+
+    for (const searchPath of searchPaths) {
+      if (!fs.existsSync(searchPath)) continue;
+
+      try {
+        const items = fs.readdirSync(searchPath);
+        for (const item of items) {
+          const lowerItem = item.toLowerCase();
+          for (const [feature, dirs] of Object.entries(featureDirs)) {
+            if (dirs.includes(lowerItem)) {
+              features[feature] = true;
+            }
+          }
+        }
+      } catch {
+        // Skip
+      }
+    }
+
+    return features;
+  }
+
+  /**
+   * Run documentation discovery phase
+   */
+  async runDocDiscovery(): Promise<DocsDiscovery> {
+    const docs: DocsDiscovery = {
+      found: [],
+      missing: [],
+      recommended: []
+    };
+
+    // Check for common documentation files
+    const commonDocs: DocInfo[] = [
+      { file: 'README.md', type: 'readme', required: true },
+      { file: 'CONTRIBUTING.md', type: 'contributing', required: false },
+      { file: 'CHANGELOG.md', type: 'changelog', required: false },
+      { file: 'LICENSE', type: 'license', required: true },
+      { file: 'CODE_OF_CONDUCT.md', type: 'code-of-conduct', required: false },
+      { file: 'SECURITY.md', type: 'security', required: false },
+      { file: 'docs/README.md', type: 'docs-readme', required: false },
+      { file: 'API.md', type: 'api-docs', required: false },
+      { file: '.env.example', type: 'env-example', required: true }
+    ];
+
+    for (const doc of commonDocs) {
+      const docPath = path.join(this.projectRoot, doc.file);
+      if (fs.existsSync(docPath)) {
+        docs.found.push({
+          ...doc,
+          path: doc.file,
+          size: fs.statSync(docPath).size
+        });
+      } else if (doc.required) {
+        docs.missing.push(doc);
+      } else {
+        docs.recommended.push(doc);
+      }
+    }
+
+    // Check for docs directory
+    const docsDir = path.join(this.projectRoot, 'docs');
+    if (fs.existsSync(docsDir)) {
+      docs.hasDocsDir = true;
+      try {
+        const docFiles = fs.readdirSync(docsDir);
+        docs.docsCount = docFiles.length;
+      } catch {
+        docs.docsCount = 0;
+      }
+    }
+
+    if (this.state) {
+      this.state.detection.docs = docs;
+    }
+    return docs;
+  }
+
+  /**
+   * Run config generation phase
+   */
+  async runConfigGeneration(): Promise<ConfigGenerationResult> {
+    const stack = this.state?.detection.stack ?? ({} as StackDetection);
+    const patterns = this.state?.detection.patterns ?? {};
+
+    // Generate bootspring.config.js
+    const configContent = this.generateConfigFile(stack, patterns);
+    const configPath = path.join(this.projectRoot, 'bootspring.config.js');
+
+    // Generate CLAUDE.md
+    const claudeMdContent = this.generateClaudeMd(stack, patterns);
+    const claudeMdPath = path.join(this.projectRoot, 'CLAUDE.md');
+
+    // Save to generated directory first
+    fs.writeFileSync(
+      path.join(this.generatedDir, 'bootspring.config.js'),
+      configContent
+    );
+    fs.writeFileSync(
+      path.join(this.generatedDir, 'CLAUDE.md'),
+      claudeMdContent
+    );
+
+    if (this.state) {
+      this.state.generated = {
+        config: configPath,
+        claudeMd: claudeMdPath,
+        timestamp: new Date().toISOString()
+      };
+    }
+
+    return {
+      configContent,
+      claudeMdContent,
+      configPath,
+      claudeMdPath
+    };
+  }
+
+  /**
+   * Apply generated config files
+   */
+  applyGeneratedFiles(): boolean {
+    const generatedConfig = path.join(this.generatedDir, 'bootspring.config.js');
+    const generatedClaudeMd = path.join(this.generatedDir, 'CLAUDE.md');
+
+    if (fs.existsSync(generatedConfig)) {
+      fs.copyFileSync(generatedConfig, path.join(this.projectRoot, 'bootspring.config.js'));
+    }
+
+    if (fs.existsSync(generatedClaudeMd)) {
+      fs.copyFileSync(generatedClaudeMd, path.join(this.projectRoot, 'CLAUDE.md'));
+    }
+
+    return true;
+  }
+
+  /**
+   * Generate bootspring.config.js content
+   */
+  generateConfigFile(stack: StackDetection, _patterns: Record<string, unknown>): string {
+    const framework = stack.framework?.id ?? 'unknown';
+    const language = stack.language?.id ?? 'javascript';
+    const database = stack.database?.id ?? null;
+    const hosting = stack.hosting?.id ?? null;
+
+    const plugins: string[] = [];
+    if (database) {
+      plugins.push(`    database: {\n      provider: '${database}',\n      features: ['default']\n    }`);
+    }
+    if (stack.testing) {
+      plugins.push(`    testing: {\n      provider: '${stack.testing.id}',\n      features: ['default']\n    }`);
+    }
+    plugins.push('    security: {\n      provider: \'default\',\n      features: [\'default\']\n    }');
+
+    const pkgName = stack.packageJson?.name ?? 'my-project';
+    const pkgVersion = stack.packageJson?.version ?? '1.0.0';
+    const pkgDescription = stack.packageJson?.description ?? 'A modern web application';
+
+    return `/**
+ * Bootspring Configuration
+ * Generated by: bootspring onboard
+ * Generated at: ${new Date().toISOString()}
+ */
+
+module.exports = {
+  // Project information
+  project: {
+    name: '${pkgName}',
+    version: '${pkgVersion}',
+    description: '${pkgDescription}'
+  },
+
+  // Technology stack
+  stack: {
+    framework: '${framework}',
+    language: '${language}',
+    database: ${database ? `'${database}'` : 'null'},
+    hosting: ${hosting ? `'${hosting}'` : 'null'}
+  },
+
+  // Enabled plugins
+  plugins: {
+${plugins.join(',\n')}
+  },
+
+  // AI context settings
+  context: {
+    // Files to include in AI context
+    include: [
+      'src/**/*.{ts,tsx,js,jsx}',
+      'app/**/*.{ts,tsx,js,jsx}',
+      'lib/**/*.{ts,tsx,js,jsx}',
+      'components/**/*.{ts,tsx,js,jsx}'
+    ],
+    // Files to exclude from AI context
+    exclude: [
+      'node_modules/**',
+      'dist/**',
+      'build/**',
+      '.next/**',
+      'coverage/**'
+    ]
+  },
+
+  // Development settings
+  dev: {
+    // Quality gates
+    quality: {
+      preCommit: ['typecheck', 'lint'],
+      prePush: ['typecheck', 'lint', 'test'],
+      preDeploy: ['typecheck', 'lint', 'test', 'build']
+    }
+  }
+};
+`;
+  }
+
+  /**
+   * Generate CLAUDE.md content
+   */
+  generateClaudeMd(stack: StackDetection, patterns: Record<string, unknown>): string {
+    const framework = stack.framework?.name ?? 'Unknown Framework';
+    const language = stack.language?.name ?? 'JavaScript';
+    const database = stack.database?.name ?? 'None';
+    const hosting = stack.hosting?.name ?? 'Unknown';
+
+    const features = (patterns.features ?? {}) as Record<string, boolean>;
+    const enabledFeatures = Object.entries(features)
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+
+    const archPatterns = patterns.architecturePatterns as Array<{ name: string; description?: string }> | undefined;
+
+    return `# Project - AI Context
+
+**Generated by**: Bootspring Onboard
+**Last Updated**: ${new Date().toISOString().split('T')[0]}
+**Status**: initialized
+**Health**: good
+
+---
+
+## Project Overview
+
+A modern web application built with ${framework}.
+
+---
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Framework | ${framework} |
+| Language | ${language} |
+| Database | ${database} |
+| Hosting | ${hosting} |
+
+---
+
+## Detected Features
+
+${enabledFeatures.length > 0 ? enabledFeatures.map(f => `- **${f}**: Detected`).join('\n') : '- No specific features detected'}
+
+---
+
+## Architecture
+
+${archPatterns && archPatterns.length > 0
+    ? archPatterns.map(p => `- **${p.name}**: ${p.description ?? 'Detected pattern'}`).join('\n')
+    : '- Standard project structure'}
+
+---
+
+## Development Guidelines
+
+### Code Style
+- Use ${language === 'TypeScript' ? 'TypeScript' : 'JavaScript'} for all new code
+- Follow existing naming conventions in the codebase
+- Keep files focused and under 300 lines when possible
+
+### Best Practices
+${framework.includes('Next') ? '- Use Server Components by default\n- Prefer Server Actions over API routes for mutations' : '- Follow framework best practices'}
+- Use Zod for all input validation
+- Never expose API keys to client-side code
+- Write tests for new features
+
+### Git Commits
+- Use conventional commit format: \`feat:\`, \`fix:\`, \`docs:\`, \`refactor:\`
+- Keep commits focused and atomic
+- Never commit sensitive data or API keys
+
+---
+
+## Current State
+
+- **Phase**: initialized
+- **Health**: good
+- **Open Todos**: 0
+- **Issues**: none
+
+---
+
+*Generated by [Bootspring](https://bootspring.com) - Development scaffolding with intelligence*
+`;
+  }
+
+  /**
+   * Run baseline capture phase
+   */
+  async runBaselineCapture(): Promise<Baseline> {
+    const baseline: Baseline = {
+      timestamp: new Date().toISOString(),
+      metrics: {
+        files: 0,
+        lines: 0,
+        dependencies: 0
+      }
+    };
+
+    // Count files
+    const structurePath = path.join(this.detectionDir, 'structure.json');
+    if (fs.existsSync(structurePath)) {
+      const structure = JSON.parse(fs.readFileSync(structurePath, 'utf-8')) as Record<string, unknown>;
+      const stats = structure.stats as Record<string, number> | undefined;
+      baseline.metrics.files = stats?.totalFiles ?? 0;
+    }
+
+    // Count dependencies
+    const pkgPath = path.join(this.projectRoot, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as Record<string, unknown>;
+        const deps = (pkg.dependencies ?? {}) as Record<string, unknown>;
+        const devDeps = (pkg.devDependencies ?? {}) as Record<string, unknown>;
+        baseline.metrics.dependencies = Object.keys(deps).length + Object.keys(devDeps).length;
+      } catch {
+        // Skip
+      }
+    }
+
+    // Save baseline
+    fs.writeFileSync(
+      path.join(this.baselineDir, 'metrics.json'),
+      JSON.stringify(baseline, null, 2)
+    );
+
+    if (this.state) {
+      this.state.baseline = baseline;
+    }
+    return baseline;
+  }
+
+  /**
+   * Get workflow progress
+   */
+  getProgress(): OnboardWorkflowProgress | null {
+    if (!this.state) return null;
+
+    const phases: OnboardPhaseProgress[] = Object.entries(ONBOARD_PHASES).map(([phaseId, phase]) => {
+      const phaseState = this.state?.phases[phaseId];
+      const status: OnboardPhaseStatus = phaseState?.status ?? 'pending';
+
+      return {
+        id: phaseId,
+        name: phase.name,
+        description: phase.description,
+        order: phase.order,
+        required: phase.required,
+        status,
+        dependenciesMet: this.arePhaseDependenciesMet(phaseId)
+      };
+    });
+
+    const completedCount = phases.filter(p => p.status === 'completed').length;
+    const requiredCount = phases.filter(p => p.required).length;
+    const requiredCompleted = phases.filter(p => p.required && p.status === 'completed').length;
+
+    return {
+      currentPhase: this.state.currentPhase,
+      startedAt: this.state.startedAt,
+      lastUpdated: this.state.lastUpdated,
+      phases,
+      overall: {
+        completed: completedCount,
+        total: phases.length,
+        percentage: phases.length > 0 ? Math.round((completedCount / phases.length) * 100) : 0
+      },
+      required: {
+        completed: requiredCompleted,
+        total: requiredCount,
+        percentage: requiredCount > 0 ? Math.round((requiredCompleted / requiredCount) * 100) : 0
+      },
+      isComplete: requiredCompleted === requiredCount,
+      detection: this.state.detection
+    };
+  }
+
+  /**
+   * Get resume point
+   */
+  getResumePoint(): OnboardResumePoint | null {
+    if (!this.state || !this.state.currentPhase) {
+      return null;
+    }
+
+    const phase = ONBOARD_PHASES[this.state.currentPhase];
+    const phaseState = this.state.phases[this.state.currentPhase];
+
+    return {
+      phase: this.state.currentPhase,
+      phaseName: phase?.name,
+      phaseStatus: phaseState?.status,
+      lastUpdated: this.state.lastUpdated
+    };
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export function createOnboardWorkflowEngine(
+  projectRoot: string,
+  options: OnboardWorkflowOptions = {}
+): OnboardWorkflowEngine {
+  return new OnboardWorkflowEngine(projectRoot, options);
+}