@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/build.ts

@@ -0,0 +1,1089 @@
+/**
+ * Bootspring Build Command
+ *
+ * Dedicated build management commands:
+ * - status: Check build progress
+ * - pause: Pause the build loop
+ * - resume: Resume the build loop
+ * - task: Show current task
+ * - skip: Skip current task
+ * - plan: View full plan
+ * - reset: Reset build state
+ *
+ * @package bootspring
+ * @command build
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+
+// Type interfaces for JS modules
+interface Config {
+  _projectRoot: string;
+  apiBase?: string | undefined;
+}
+
+interface ConfigModule {
+  load(): Config;
+}
+
+interface UtilsModule {
+  parseArgs(args: string[]): ParsedArgs;
+  createSpinner(text: string): Spinner;
+}
+
+interface ParsedArgs {
+  _: string[];
+  [key: string]: string | boolean | string[] | undefined;
+}
+
+interface Spinner {
+  start(): Spinner;
+  stop(): void;
+  succeed(text: string): void;
+  fail(text: string): void;
+  info(text: string): void;
+}
+
+interface BuildTask {
+  id: string;
+  title: string;
+  description?: string | undefined;
+  phase?: string | undefined;
+  source?: string | undefined;
+  sourceSection?: string | undefined;
+  status: string;
+  estimatedComplexity?: string | undefined;
+  acceptanceCriteria?: string[] | undefined;
+  dependencies?: string[] | undefined;
+  error?: string | undefined;
+}
+
+interface BuildStateData {
+  projectName: string;
+  status: string;
+  currentPhase: string;
+  implementationQueue: BuildTask[];
+  loopSession?: {
+    sessionId?: string | undefined;
+  } | undefined;
+}
+
+interface BuildStats {
+  progress: number;
+  completed: number;
+  pending: number;
+  inProgress: number;
+  blocked: number;
+  skipped: number;
+  total: number;
+  completedPercent: number;
+  mvpProgress: number;
+  mvpComplete: boolean;
+  iteration: number;
+  maxIterations: number;
+}
+
+interface BuildStateModule {
+  load(projectRoot: string): BuildStateData | null;
+  getStats(projectRoot: string): BuildStats;
+  getNextTask(projectRoot: string): BuildTask | null;
+  updateProgress(projectRoot: string, taskId: string, status: string, options?: { error?: string }): void;
+  pause(projectRoot: string): void;
+  resume(projectRoot: string): void;
+  reset(projectRoot: string): void;
+}
+
+interface BuildOrchestratorInstance {
+  initialize(): Promise<{ success: boolean; error?: string; taskCount?: number }>;
+  generateTaskPrompt(task: BuildTask): string;
+}
+
+interface BuildOrchestratorClass {
+  new (projectRoot: string): BuildOrchestratorInstance;
+}
+
+interface LoopModule {
+  setStopSignal(projectRoot: string): void;
+}
+
+interface LoopState {
+  active: boolean;
+  noCommit?: boolean | undefined;
+  noPush?: boolean | undefined;
+  currentTaskId?: string | undefined;
+  lastTaskCompletedAt?: string | undefined;
+  startedAt?: string | undefined;
+  pausedAt?: string | undefined;
+  resumedAt?: string | undefined;
+  completedAt?: string | undefined;
+}
+
+interface CommitResult {
+  committed: boolean;
+  pushed: boolean;
+}
+
+const config = require('../core/config') as ConfigModule;
+const utils = require('../core/utils') as UtilsModule;
+const buildState = require('../core/build-state') as BuildStateModule;
+const { BuildOrchestrator } = require('../core/build-orchestrator') as { BuildOrchestrator: BuildOrchestratorClass };
+
+// 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'
+};
+
+/**
+ * Main run function - Interactive by default
+ */
+export async function run(args: string[]): Promise<void> {
+  const parsedArgs = utils.parseArgs(args);
+  const subcommand = parsedArgs._[0];
+
+  const cfg = config.load();
+  const projectRoot = cfg._projectRoot;
+
+  // If no subcommand, run interactive mode
+  if (!subcommand) {
+    return interactiveBuild(projectRoot, parsedArgs);
+  }
+
+  // Advanced users can use subcommands directly
+  switch (subcommand) {
+    case 'status':
+      return showBuildStatus(projectRoot, parsedArgs);
+
+    case 'pause':
+      return pauseBuildLoop(projectRoot);
+
+    case 'stop':
+      return gracefulStop(projectRoot);
+
+    case 'resume':
+    case 'continue':
+      return resumeBuildLoop(projectRoot);
+
+    case 'task':
+      return showCurrentTask(projectRoot, parsedArgs);
+
+    case 'skip':
+      return skipCurrentTask(projectRoot, parsedArgs);
+
+    case 'plan':
+      return showPlan(projectRoot);
+
+    case 'reset':
+      return resetBuild(projectRoot, parsedArgs);
+
+    case 'next':
+      return buildNextTask(projectRoot, parsedArgs);
+
+    case 'done':
+    case 'complete':
+      return markTaskDone(projectRoot, parsedArgs);
+
+    case 'loop':
+    case 'all':
+      return buildLoop(projectRoot, parsedArgs);
+
+    case 'help':
+    case '-h':
+    case '--help':
+      return showHelp();
+
+    default:
+      console.log(`${c.red}Unknown subcommand: ${subcommand}${c.reset}`);
+      showHelp();
+  }
+}
+
+/**
+ * Interactive build mode - guides user through options
+ */
+async function interactiveBuild(projectRoot: string, args: ParsedArgs = { _: [] }): Promise<void> {
+  const state = buildState.load(projectRoot);
+
+  console.log(`
+${c.cyan}${c.bold}Bootspring Build${c.reset}
+`);
+
+  // No build state - offer to initialize
+  if (!state) {
+    console.log(`${c.yellow}No build found.${c.reset}
+
+This will:
+  1. Extract tasks from your seed documents
+  2. Create a build plan in /planning
+  3. Guide you through building your MVP
+
+`);
+
+    const answer = await askQuestion('Initialize build from seed docs? [Y/n] ');
+
+    if (answer.toLowerCase() === 'n') {
+      console.log(`\n${c.dim}Run 'bootspring preseed start' first if you haven't set up seed docs.${c.reset}\n`);
+      return;
+    }
+
+    // Initialize build
+    const orchestrator = new BuildOrchestrator(projectRoot);
+    const spinner = utils.createSpinner('Analyzing seed documents...').start();
+
+    const result = await orchestrator.initialize();
+
+    if (!result.success) {
+      spinner.fail(result.error || 'Unknown error');
+      return;
+    }
+
+    spinner.succeed(`Found ${result.taskCount} tasks to build`);
+    console.log('');
+
+    // Continue to show options
+    return interactiveBuild(projectRoot, args);
+  }
+
+  // Show current progress
+  const stats = buildState.getStats(projectRoot);
+  const nextTask = buildState.getNextTask(projectRoot);
+
+  // Progress bar
+  const barWidth = 30;
+  const filled = Math.round((stats.progress / 100) * barWidth);
+  const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+  const progressColor = stats.progress === 100 ? c.green : stats.progress > 50 ? c.cyan : c.yellow;
+
+  console.log(`${c.bold}${state.projectName}${c.reset}
+
+  Progress: [${progressColor}${bar}${c.reset}] ${stats.progress}%
+  Tasks: ${c.green}${stats.completed}${c.reset} done, ${stats.pending} remaining
+  Phase: ${formatPhaseName(state.currentPhase)}
+`);
+
+  // All done!
+  if (!nextTask) {
+    if (stats.completed === stats.total) {
+      console.log(`${c.green}${c.bold}All tasks complete! Your MVP is ready.${c.reset}
+
+Next steps:
+  ${c.cyan}npm run dev${c.reset}     Start development server
+  ${c.cyan}npm run build${c.reset}   Build for production
+  ${c.cyan}bootspring deploy${c.reset}  Deploy to production
+`);
+    } else {
+      console.log(`${c.yellow}No pending tasks available.${c.reset}
+Some tasks may be blocked. Run ${c.cyan}bootspring build status${c.reset} for details.
+`);
+    }
+    return;
+  }
+
+  // Show next task
+  console.log(`${c.bold}Next Task:${c.reset}
+  ${nextTask.title}
+  ${c.dim}${nextTask.source || ''}${c.reset}
+`);
+
+  // Show options
+  console.log(`${c.bold}What would you like to do?${c.reset}
+
+  ${c.cyan}1${c.reset}  Start this task (shows prompt for Claude Code)
+  ${c.cyan}2${c.reset}  Loop all tasks (autonomous - runs Claude until complete)
+  ${c.cyan}3${c.reset}  View task details
+  ${c.cyan}4${c.reset}  Skip this task
+  ${c.cyan}5${c.reset}  View full plan
+  ${c.cyan}q${c.reset}  Quit
+`);
+
+  const choice = await askQuestion('Choose [1-5, q]: ');
+
+  switch (choice.trim()) {
+    case '1':
+    case '':
+      return buildNextTask(projectRoot, args);
+
+    case '2':
+      return buildLoop(projectRoot, args);
+
+    case '3':
+      showCurrentTask(projectRoot, { _: [], prompt: true });
+      console.log('');
+      return interactiveBuild(projectRoot, args);
+
+    case '4': {
+      const reason = await askQuestion('Skip reason (optional): ');
+      skipCurrentTask(projectRoot, { _: [], reason: reason || 'Skipped by user' });
+      return interactiveBuild(projectRoot, args);
+    }
+
+    case '5':
+      showPlan(projectRoot);
+      return interactiveBuild(projectRoot, args);
+
+    case 'q':
+    case 'Q':
+      console.log(`\n${c.dim}Run 'bootspring build' anytime to continue.${c.reset}\n`);
+      return;
+
+    default:
+      console.log(`${c.yellow}Invalid choice. Please try again.${c.reset}\n`);
+      return interactiveBuild(projectRoot, args);
+  }
+}
+
+/**
+ * Build the next task - writes to CURRENT_TASK.md for Claude Code
+ */
+async function buildNextTask(projectRoot: string, _args: ParsedArgs = { _: [] }): Promise<void> {
+  const state = buildState.load(projectRoot);
+
+  if (!state) {
+    console.log(`${c.yellow}No build state found. Run 'bootspring build' to start.${c.reset}`);
+    return;
+  }
+
+  const nextTask = buildState.getNextTask(projectRoot);
+
+  if (!nextTask) {
+    console.log(`${c.green}All tasks complete!${c.reset}`);
+    return;
+  }
+
+  // Mark task as in progress
+  buildState.updateProgress(projectRoot, nextTask.id, 'in_progress');
+
+  console.log(`
+${c.green}${c.bold}✓ Task ${nextTask.id} now in progress${c.reset}
+
+${c.bold}Task:${c.reset} ${nextTask.title}
+${c.bold}Phase:${c.reset} ${nextTask.phase || 'MVP'}
+${c.bold}Source:${c.reset} ${nextTask.source || 'PRD.md'}
+
+${c.cyan}${c.bold}Tell Claude Code:${c.reset}
+  "Read planning/TASK_QUEUE.md, find ${nextTask.id}, and implement it"
+
+${c.dim}When done, run: bootspring build done${c.reset}
+`);
+}
+
+
+/**
+ * Generate a prompt for Claude Code to execute
+ */
+function _generateTaskPrompt(task: BuildTask, _projectRoot: string): string {
+  const lines: string[] = [];
+
+  lines.push(`**Objective:** ${task.title}`);
+  lines.push('');
+
+  if (task.description) {
+    lines.push('**Description:**');
+    lines.push(task.description);
+    lines.push('');
+  }
+
+  if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+    lines.push('**Acceptance Criteria:**');
+    task.acceptanceCriteria.forEach(ac => {
+      lines.push(`- [ ] ${ac}`);
+    });
+    lines.push('');
+  }
+
+  if (task.sourceSection) {
+    lines.push(`**Source:** ${task.source} - ${task.sourceSection}`);
+    lines.push('');
+  }
+
+  lines.push('**Instructions:**');
+  lines.push('1. Implement the task as described above');
+  lines.push('2. Ensure all acceptance criteria are met');
+  lines.push('3. Test your implementation');
+  lines.push('4. When done, run: bootspring build done');
+
+  return lines.join('\n');
+}
+
+/**
+ * Mark current task as done and auto-queue next
+ */
+async function markTaskDone(projectRoot: string, _args: ParsedArgs = { _: [] }): Promise<void> {
+  const state = buildState.load(projectRoot);
+
+  if (!state) {
+    console.log(`${c.yellow}No build state found.${c.reset}`);
+    return;
+  }
+
+  // Find in-progress task
+  const inProgressTask = state.implementationQueue.find(t => t.status === 'in_progress');
+
+  if (!inProgressTask) {
+    console.log(`${c.yellow}No task currently in progress.${c.reset}`);
+    return;
+  }
+
+  // Mark as complete
+  buildState.updateProgress(projectRoot, inProgressTask.id, 'completed');
+
+  console.log(`${c.green}✓${c.reset} Completed: ${c.bold}${inProgressTask.title}${c.reset}`);
+
+  // Check if loop mode is active - if so, commit and push
+  const loopState = loadLoopState(projectRoot);
+  if (loopState && loopState.active) {
+    await commitAndPush(projectRoot, inProgressTask, {
+      noCommit: loopState.noCommit,
+      noPush: loopState.noPush
+    });
+  }
+
+  // Get stats
+  const stats = buildState.getStats(projectRoot);
+  console.log(`${c.dim}Progress: ${stats.completed}/${stats.total} tasks (${Math.round(stats.completedPercent)}%)${c.reset}`);
+
+  // Auto-queue next task
+  const nextTask = buildState.getNextTask(projectRoot);
+
+  if (nextTask) {
+    // Mark as in progress
+    buildState.updateProgress(projectRoot, nextTask.id, 'in_progress');
+
+    // Update loop state with new task
+    if (loopState && loopState.active) {
+      saveLoopState(projectRoot, {
+        ...loopState,
+        currentTaskId: nextTask.id,
+        lastTaskCompletedAt: new Date().toISOString()
+      });
+    }
+
+    console.log(`
+${c.cyan}${c.bold}▶ Next: ${nextTask.title}${c.reset} (${nextTask.id})
+
+${c.bold}Continue building:${c.reset} Read planning/TASK_QUEUE.md, implement ${nextTask.id}
+${c.dim}Then run: bootspring build done${c.reset}
+`);
+  } else {
+    // Clear loop state - build complete
+    if (loopState && loopState.active) {
+      saveLoopState(projectRoot, {
+        ...loopState,
+        active: false,
+        completedAt: new Date().toISOString()
+      });
+    }
+
+    console.log(`
+${c.green}${c.bold}🎉 MVP BUILD COMPLETE!${c.reset}
+
+All ${stats.total} tasks finished. Your MVP is ready.
+
+${c.bold}Next steps:${c.reset}
+  1. Review the generated code
+  2. Run tests: ${c.cyan}npm test${c.reset}
+  3. Deploy: ${c.cyan}bootspring deploy${c.reset}
+`);
+  }
+}
+
+/**
+ * Build loop - autonomous task execution with commit/push after each task
+ *
+ * Usage:
+ *   bootspring build loop              # Start/resume the loop
+ *   bootspring build loop --no-push    # Commit but don't push
+ *   bootspring build loop --no-commit  # No git operations
+ */
+async function buildLoop(projectRoot: string, args: ParsedArgs = { _: [] }): Promise<void> {
+  const state = buildState.load(projectRoot);
+
+  if (!state) {
+    console.log(`${c.yellow}No build state found. Run 'bootspring seed synthesize' first.${c.reset}`);
+    return;
+  }
+
+  const stats = buildState.getStats(projectRoot);
+  const noCommit = args['no-commit'] || args.noCommit;
+  const noPush = args['no-push'] || args.noPush || noCommit;
+
+  // Check for in-progress task (crash recovery)
+  const inProgress = state.implementationQueue.find(t => t.status === 'in_progress');
+
+  if (inProgress) {
+    console.log(`
+${c.yellow}${c.bold}⚠ Resuming from crash${c.reset}
+
+Found in-progress task: ${c.cyan}${inProgress.title}${c.reset} (${inProgress.id})
+
+${c.dim}This task was in progress when the loop stopped.
+Continue implementing it, then run 'bootspring build done'.${c.reset}
+`);
+  } else {
+    // Queue next task
+    const nextTask = buildState.getNextTask(projectRoot);
+    if (!nextTask) {
+      console.log(`${c.green}${c.bold}🎉 All tasks complete!${c.reset}`);
+      return;
+    }
+    buildState.updateProgress(projectRoot, nextTask.id, 'in_progress');
+  }
+
+  const currentTask = state.implementationQueue.find(t => t.status === 'in_progress')
+    || buildState.getNextTask(projectRoot);
+
+  console.log(`
+${c.cyan}${c.bold}⚡ Bootspring Build Loop${c.reset}
+
+${c.bold}Current Task:${c.reset} ${currentTask?.title || 'None'} (${currentTask?.id || '-'})
+${c.bold}Progress:${c.reset} ${stats.completed}/${stats.total} tasks (${Math.round(stats.completedPercent)}%)
+${c.bold}Git Mode:${c.reset} ${noCommit ? 'Disabled' : noPush ? 'Commit only' : 'Commit + Push'}
+
+${c.bold}Workflow:${c.reset}
+  1. Read planning/TASK_QUEUE.md, find ${currentTask?.id || 'current task'}
+  2. Implement the task
+  3. Run: ${c.cyan}bootspring build done${c.reset}${!noCommit ? `
+     (Auto-commits: "feat(${currentTask?.id}): ${currentTask?.title?.slice(0, 40) || 'task'}...")${!noPush ? `
+     (Auto-pushes to origin)` : ''}` : ''}
+  4. Continue to next task...
+
+${c.dim}Press Ctrl+C to stop. Run 'bootspring build loop' to resume.${c.reset}
+`);
+
+  // Save loop state for crash recovery
+  saveLoopState(projectRoot, {
+    active: true,
+    startedAt: new Date().toISOString(),
+    noCommit: noCommit as boolean | undefined,
+    noPush: noPush as boolean | undefined
+  });
+}
+
+/**
+ * Save loop state for crash recovery
+ */
+function saveLoopState(projectRoot: string, state: LoopState): void {
+  const loopFile = path.join(projectRoot, '.bootspring', 'loop-state.json');
+  const dir = path.dirname(loopFile);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(loopFile, JSON.stringify(state, null, 2));
+}
+
+/**
+ * Load loop state
+ */
+function loadLoopState(projectRoot: string): LoopState | null {
+  const loopFile = path.join(projectRoot, '.bootspring', 'loop-state.json');
+  if (fs.existsSync(loopFile)) {
+    try {
+      return JSON.parse(fs.readFileSync(loopFile, 'utf-8')) as LoopState;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Clear loop state (used when stopping or completing)
+ */
+function _clearLoopState(projectRoot: string): void {
+  const loopFile = path.join(projectRoot, '.bootspring', 'loop-state.json');
+  if (fs.existsSync(loopFile)) {
+    fs.unlinkSync(loopFile);
+  }
+}
+
+/**
+ * Commit and push changes for a completed task
+ */
+async function commitAndPush(projectRoot: string, task: BuildTask, options: { noCommit?: boolean | undefined; noPush?: boolean | undefined } = {}): Promise<CommitResult> {
+  const { noCommit, noPush } = options;
+
+  if (noCommit) return { committed: false, pushed: false };
+
+  const { execSync } = require('child_process');
+
+  try {
+    // Check if there are changes to commit
+    const status = execSync('git status --porcelain', { cwd: projectRoot, encoding: 'utf-8' }) as string;
+    if (!status.trim()) {
+      console.log(`${c.dim}No changes to commit${c.reset}`);
+      return { committed: false, pushed: false };
+    }
+
+    // Stage all changes
+    execSync('git add -A', { cwd: projectRoot });
+
+    // Create commit message
+    const shortTitle = task.title.length > 50 ? task.title.slice(0, 47) + '...' : task.title;
+    const commitMsg = `feat(${task.id}): ${shortTitle}
+
+Task: ${task.title}
+Phase: ${task.phase || 'MVP'}
+Source: ${task.source || 'planning'}
+
+Acceptance Criteria:
+${(task.acceptanceCriteria || []).map(ac => `- [x] ${ac}`).join('\n')}
+
+Built with Bootspring autonomous loop.`;
+
+    // Commit
+    execSync(`git commit -m "${commitMsg.replace(/"/g, '\\"')}"`, { cwd: projectRoot });
+    console.log(`${c.green}✓${c.reset} Committed: ${c.bold}${task.id}${c.reset}`);
+
+    if (noPush) {
+      return { committed: true, pushed: false };
+    }
+
+    // Push
+    try {
+      execSync('git push', { cwd: projectRoot, stdio: 'pipe' });
+      console.log(`${c.green}✓${c.reset} Pushed to origin`);
+      return { committed: true, pushed: true };
+    } catch (pushError) {
+      console.log(`${c.yellow}⚠${c.reset} Push failed (commit saved locally): ${(pushError as Error).message}`);
+      return { committed: true, pushed: false };
+    }
+  } catch (error) {
+    console.log(`${c.yellow}⚠${c.reset} Git operation failed: ${(error as Error).message}`);
+    return { committed: false, pushed: false };
+  }
+}
+
+/**
+ * Ask a question and get user input
+ */
+function askQuestion(question: string): Promise<string> {
+  const readline = require('readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise(resolve => {
+    rl.question(question, (answer: string) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+/**
+ * Show build status
+ */
+function showBuildStatus(projectRoot: string, _args: ParsedArgs = { _: [] }): void {
+  const state = buildState.load(projectRoot);
+
+  if (!state) {
+    console.log(`
+${c.cyan}${c.bold}Build Status${c.reset}
+
+${c.yellow}No build state found.${c.reset}
+Run ${c.cyan}bootspring seed build${c.reset} to initialize the build system.
+`);
+    return;
+  }
+
+  const stats = buildState.getStats(projectRoot);
+
+  // Status icon
+  const statusIcon: Record<string, string> = {
+    pending: `${c.dim}○${c.reset}`,
+    in_progress: `${c.green}●${c.reset}`,
+    paused: `${c.yellow}◐${c.reset}`,
+    completed: `${c.green}✓${c.reset}`,
+    failed: `${c.red}✗${c.reset}`
+  };
+  const icon = statusIcon[state.status] || '?';
+
+  // Progress bar
+  const barWidth = 40;
+  const filled = Math.round((stats.progress / 100) * barWidth);
+  const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+  const progressColor = stats.progress === 100 ? c.green :
+    stats.progress > 50 ? c.cyan : c.yellow;
+
+  console.log(`
+${c.cyan}${c.bold}Build Status${c.reset}
+
+${c.bold}Project:${c.reset} ${state.projectName}
+${c.bold}Status:${c.reset} ${icon} ${state.status}
+${c.bold}Phase:${c.reset} ${formatPhaseName(state.currentPhase)}
+
+${c.bold}Progress${c.reset}
+  [${progressColor}${bar}${c.reset}] ${stats.progress}%
+
+${c.bold}Tasks${c.reset}
+  Total:       ${stats.total}
+  Completed:   ${c.green}${stats.completed}${c.reset}
+  In Progress: ${c.cyan}${stats.inProgress}${c.reset}
+  Pending:     ${stats.pending}
+  Blocked:     ${c.red}${stats.blocked}${c.reset}
+  Skipped:     ${c.dim}${stats.skipped}${c.reset}
+
+${c.bold}MVP Progress${c.reset}
+  ${stats.mvpProgress}% complete ${stats.mvpComplete ? `${c.green}✓ MVP Complete${c.reset}` : ''}
+
+${c.bold}Loop Session${c.reset}
+  Iteration: ${stats.iteration}/${stats.maxIterations}
+  Session ID: ${c.dim}${state.loopSession?.sessionId || 'N/A'}${c.reset}
+`);
+
+  // Show next actions
+  showNextActions(state, stats);
+}
+
+/**
+ * Show suggested next actions
+ */
+function showNextActions(state: BuildStateData, _stats: BuildStats): void {
+  console.log(`${c.bold}Next Actions:${c.reset}`);
+
+  if (state.status === 'paused') {
+    console.log(`  ${c.cyan}1.${c.reset} Resume building     → ${c.dim}bootspring build resume${c.reset}`);
+    console.log(`  ${c.cyan}2.${c.reset} View current task   → ${c.dim}bootspring build task${c.reset}`);
+    console.log(`  ${c.cyan}3.${c.reset} View full plan      → ${c.dim}bootspring build plan${c.reset}`);
+  } else if (state.status === 'completed') {
+    console.log(`  ${c.green}Build complete!${c.reset} All tasks have been finished.`);
+    console.log(`  ${c.cyan}1.${c.reset} View summary        → ${c.dim}bootspring build plan${c.reset}`);
+    console.log(`  ${c.cyan}2.${c.reset} Deploy              → ${c.dim}bootspring deploy${c.reset}`);
+  } else if (state.status === 'failed') {
+    console.log(`  ${c.red}Build failed.${c.reset} Review errors and resume.`);
+    console.log(`  ${c.cyan}1.${c.reset} View current task   → ${c.dim}bootspring build task${c.reset}`);
+    console.log(`  ${c.cyan}2.${c.reset} Skip blocked task   → ${c.dim}bootspring build skip${c.reset}`);
+    console.log(`  ${c.cyan}3.${c.reset} Reset build         → ${c.dim}bootspring build reset${c.reset}`);
+  } else if (state.status === 'in_progress') {
+    console.log(`  ${c.cyan}Build in progress...${c.reset}`);
+    console.log(`  ${c.cyan}1.${c.reset} Pause building      → ${c.dim}bootspring build pause${c.reset}`);
+    console.log(`  ${c.cyan}2.${c.reset} View current task   → ${c.dim}bootspring build task${c.reset}`);
+  } else {
+    console.log(`  ${c.cyan}1.${c.reset} Start building      → ${c.dim}bootspring seed build --loop${c.reset}`);
+    console.log(`  ${c.cyan}2.${c.reset} View current task   → ${c.dim}bootspring build task${c.reset}`);
+    console.log(`  ${c.cyan}3.${c.reset} View full plan      → ${c.dim}bootspring build plan${c.reset}`);
+  }
+
+  console.log('');
+}
+
+/**
+ * Pause the build loop
+ */
+function pauseBuildLoop(projectRoot: string): void {
+  const state = buildState.load(projectRoot);
+
+  if (!state) {
+    console.log(`${c.yellow}No build state found.${c.reset}`);
+    return;
+  }
+
+  if (state.status !== 'in_progress') {
+    console.log(`${c.yellow}Build is not running (status: ${state.status})${c.reset}`);
+    return;
+  }
+
+  buildState.pause(projectRoot);
+
+  // Update loop state to inactive
+  const loopState = loadLoopState(projectRoot);
+  if (loopState) {
+    saveLoopState(projectRoot, {
+      ...loopState,
+      active: false,
+      pausedAt: new Date().toISOString()
+    });
+  }
+
+  console.log(`
+${c.green}Build paused.${c.reset}
+
+Resume with: ${c.cyan}bootspring build resume${c.reset}
+`);
+}
+
+/**
+ * Resume the build loop
+ */
+function resumeBuildLoop(projectRoot: string): void {
+  const state = buildState.load(projectRoot);
+
+  if (!state) {
+    console.log(`${c.yellow}No build state found.${c.reset}`);
+    console.log(`Initialize with: ${c.cyan}bootspring seed build${c.reset}`);
+    return;
+  }
+
+  if (state.status === 'completed') {
+    console.log(`${c.green}Build is already complete!${c.reset}`);
+    return;
+  }
+
+  if (state.status !== 'paused' && state.status !== 'pending') {
+    console.log(`${c.yellow}Build status: ${state.status}${c.reset}`);
+    console.log('Cannot resume from this state.');
+    return;
+  }
+
+  buildState.resume(projectRoot);
+
+  // Restore loop state if it exists
+  const loopState = loadLoopState(projectRoot);
+  if (loopState) {
+    saveLoopState(projectRoot, {
+      ...loopState,
+      active: true,
+      resumedAt: new Date().toISOString()
+    });
+  }
+
+  console.log(`
+${c.green}Build resumed.${c.reset}
+
+Continue with: ${c.cyan}bootspring build next${c.reset}
+Or run loop: ${c.cyan}bootspring build loop${c.reset}
+`);
+}
+
+/**
+ * Graceful stop - finish current task then pause
+ */
+function gracefulStop(projectRoot: string): void {
+  const loop = require('./loop') as LoopModule;
+
+  console.log(`
+${c.yellow}${c.bold}Graceful stop requested${c.reset}
+
+The loop will pause after the current task completes.
+This ensures no work is interrupted mid-task.
+
+${c.dim}Waiting for current task to finish...${c.reset}
+`);
+
+  loop.setStopSignal(projectRoot);
+}
+
+/**
+ * Show current task
+ */
+function showCurrentTask(projectRoot: string, args: ParsedArgs = { _: [] }): void {
+  const state = buildState.load(projectRoot);
+
+  if (!state) {
+    console.log(`${c.yellow}No build state found.${c.reset}`);
+    return;
+  }
+
+  const nextTask = buildState.getNextTask(projectRoot);
+
+  if (!nextTask) {
+    const stats = buildState.getStats(projectRoot);
+
+    if (stats.completed === stats.total) {
+      console.log(`
+${c.green}${c.bold}All tasks complete!${c.reset}
+
+${stats.completed} tasks have been completed.
+`);
+    } else {
+      console.log(`
+${c.yellow}No pending tasks available.${c.reset}
+
+${c.bold}Summary:${c.reset}
+  Completed: ${stats.completed}
+  Blocked: ${stats.blocked}
+  Skipped: ${stats.skipped}
+`);
+    }
+    return;
+  }
+
+  console.log(`
+${c.cyan}${c.bold}Current Task${c.reset}
+
+${c.bold}ID:${c.reset} ${nextTask.id}
+${c.bold}Title:${c.reset} ${nextTask.title}
+${c.bold}Phase:${c.reset} ${formatPhaseName(nextTask.phase)}
+${c.bold}Complexity:${c.reset} ${nextTask.estimatedComplexity || 'medium'}
+${c.bold}Source:${c.reset} ${nextTask.source || 'Manual'} ${nextTask.sourceSection ? `(${nextTask.sourceSection})` : ''}
+${c.bold}Status:${c.reset} ${nextTask.status}
+`);
+
+  if (nextTask.description) {
+    console.log(`${c.bold}Description:${c.reset}
+${nextTask.description}
+`);
+  }
+
+  if (nextTask.acceptanceCriteria && nextTask.acceptanceCriteria.length > 0) {
+    console.log(`${c.bold}Acceptance Criteria:${c.reset}`);
+    nextTask.acceptanceCriteria.forEach((criteria, i) => {
+      console.log(`  ${c.dim}${i + 1}.${c.reset} ${criteria}`);
+    });
+    console.log('');
+  }
+
+  if (nextTask.dependencies && nextTask.dependencies.length > 0) {
+    console.log(`${c.bold}Dependencies:${c.reset} ${nextTask.dependencies.join(', ')}`);
+    console.log('');
+  }
+
+  // Show prompt generation option
+  if (args.prompt) {
+    const orchestrator = new BuildOrchestrator(projectRoot);
+    const prompt = orchestrator.generateTaskPrompt(nextTask);
+    console.log(`${c.bold}Generated Prompt:${c.reset}`);
+    console.log(c.dim + '─'.repeat(60) + c.reset);
+    console.log(prompt);
+    console.log(c.dim + '─'.repeat(60) + c.reset);
+  } else {
+    console.log(`${c.dim}Use --prompt to generate AI prompt for this task${c.reset}`);
+  }
+}
+
+/**
+ * Skip current task
+ */
+function skipCurrentTask(projectRoot: string, args: ParsedArgs = { _: [] }): void {
+  const state = buildState.load(projectRoot);
+
+  if (!state) {
+    console.log(`${c.yellow}No build state found.${c.reset}`);
+    return;
+  }
+
+  const nextTask = buildState.getNextTask(projectRoot);
+
+  if (!nextTask) {
+    console.log(`${c.yellow}No pending tasks to skip.${c.reset}`);
+    return;
+  }
+
+  const reason = (args.reason as string | undefined) || args._[1] || 'Manually skipped';
+
+  buildState.updateProgress(projectRoot, nextTask.id, 'skipped', {
+    error: reason
+  });
+
+  console.log(`
+${c.yellow}Skipped task: ${nextTask.title}${c.reset}
+Reason: ${reason}
+
+Next task: ${buildState.getNextTask(projectRoot)?.title || 'None remaining'}
+`);
+}
+
+/**
+ * Show full plan
+ */
+function showPlan(projectRoot: string): void {
+  const planPath = path.join(projectRoot, 'planning', 'MASTER_PLAN.md');
+
+  if (!fs.existsSync(planPath)) {
+    console.log(`${c.yellow}No plan found.${c.reset}`);
+    console.log(`Initialize with: ${c.cyan}bootspring seed build${c.reset}`);
+    return;
+  }
+
+  const content = fs.readFileSync(planPath, 'utf-8');
+
+  // Print with formatting
+  console.log(`
+${c.cyan}${c.bold}Master Plan${c.reset}
+${c.dim}${planPath}${c.reset}
+
+${content}
+`);
+}
+
+/**
+ * Reset build state
+ */
+function resetBuild(projectRoot: string, args: ParsedArgs = { _: [] }): void {
+  const force = args.force || args.f;
+
+  const state = buildState.load(projectRoot);
+
+  if (!state) {
+    console.log(`${c.yellow}No build state found.${c.reset}`);
+    return;
+  }
+
+  if (!force && state.status === 'in_progress') {
+    console.log(`${c.yellow}Build is in progress. Use --force to reset.${c.reset}`);
+    return;
+  }
+
+  buildState.reset(projectRoot);
+
+  console.log(`
+${c.green}Build state reset.${c.reset}
+
+Re-initialize with: ${c.cyan}bootspring seed build${c.reset}
+`);
+}
+
+/**
+ * Format phase name for display
+ */
+function formatPhaseName(phase: string | undefined): string {
+  if (!phase) return 'Unknown';
+
+  const names: Record<string, string> = {
+    foundation: 'Foundation',
+    mvp: 'MVP',
+    launch: 'Launch',
+    other: 'Other'
+  };
+
+  return names[phase] || phase.charAt(0).toUpperCase() + phase.slice(1);
+}
+
+/**
+ * Show help
+ */
+function showHelp(): void {
+  console.log(`
+${c.cyan}${c.bold}Bootspring Build${c.reset}
+${c.dim}Task-driven build system for Claude Code${c.reset}
+
+${c.bold}Quick Start:${c.reset}
+  ${c.cyan}bootspring build next${c.reset}  Get next task and start building
+
+${c.bold}Workflow:${c.reset}
+  1. Run ${c.cyan}bootspring build next${c.reset} to get the next task
+  2. Implement the task in your codebase
+  3. Run ${c.cyan}bootspring build done${c.reset} when complete
+  4. Repeat until MVP is complete
+
+${c.bold}Commands:${c.reset}
+  ${c.cyan}bootspring build${c.reset}           Start interactive build
+  ${c.cyan}bootspring build next${c.reset}      Get next task (start here!)
+  ${c.cyan}bootspring build done${c.reset}      Mark current task complete
+  ${c.cyan}bootspring build loop${c.reset}      Start autonomous loop (commit+push each task)
+  ${c.cyan}bootspring build skip${c.reset}      Skip current task
+  ${c.cyan}bootspring build stop${c.reset}      Graceful stop (finish current task, then pause)
+  ${c.cyan}bootspring build status${c.reset}    View detailed progress
+  ${c.cyan}bootspring build task${c.reset}      View current task details
+  ${c.cyan}bootspring build plan${c.reset}      View the full master plan
+  ${c.cyan}bootspring build reset${c.reset}     Start over
+
+${c.bold}Loop Options:${c.reset}
+  ${c.cyan}bootspring build loop${c.reset}              Commit + push after each task
+  ${c.cyan}bootspring build loop --no-push${c.reset}    Commit only (no push)
+  ${c.cyan}bootspring build loop --no-commit${c.reset}  No git operations
+
+${c.bold}Other Options:${c.reset}
+  --prompt          Show AI prompt for current task
+  --force           Force reset even if in progress
+`);
+}