ai-spec-dev 0.1.0 → 0.14.1

package/cli/index.ts

@@ -0,0 +1,1961 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import * as dotenv from "dotenv";
+import { input, confirm, select, checkbox } from "@inquirer/prompts";
+
+dotenv.config();
+
+import {
+  SpecGenerator,
+  createProvider,
+  DEFAULT_MODELS,
+  ENV_KEY_MAP,
+  SUPPORTED_PROVIDERS,
+  PROVIDER_CATALOG,
+  AIProvider,
+} from "../core/spec-generator";
+import { ContextLoader, isFrontendDeps } from "../core/context-loader";
+import { SpecRefiner } from "../core/spec-refiner";
+import { CodeGenerator, CodeGenMode } from "../core/code-generator";
+import { CodeReviewer } from "../core/reviewer";
+import { GitWorktreeManager } from "../git/worktree";
+import { ConstitutionGenerator, CONSTITUTION_FILE, printConstitutionHint } from "../core/constitution-generator";
+import { ConstitutionConsolidator } from "../core/constitution-consolidator";
+import { TaskGenerator, printTasks } from "../core/task-generator";
+import { generateSpecWithTasks } from "../core/combined-generator";
+import {
+  slugify,
+  findLatestVersion,
+  nextVersionPath,
+  computeDiff,
+  printDiff,
+  printDiffSummary,
+} from "../core/spec-versioning";
+import { DslExtractor } from "../core/dsl-extractor";
+import { TestGenerator } from "../core/test-generator";
+import { runErrorFeedback } from "../core/error-feedback";
+import { assessSpec, printSpecAssessment } from "../core/spec-assessor";
+import { accumulateReviewKnowledge } from "../core/knowledge-memory";
+import {
+  WorkspaceLoader,
+  WorkspaceConfig,
+  RepoConfig,
+  WORKSPACE_CONFIG_FILE,
+  detectRepoType,
+} from "../core/workspace-loader";
+import {
+  loadGlobalConstitution,
+  saveGlobalConstitution,
+  GLOBAL_CONSTITUTION_FILE,
+} from "../core/global-constitution";
+import { getSavedKey, saveKey, clearAllKeys, clearKey, KEY_STORE_FILE } from "../core/key-store";
+import { printWelcome } from "./welcome";
+import {
+  globalConstitutionSystemPrompt,
+  buildGlobalConstitutionPrompt,
+} from "../prompts/global-constitution.prompt";
+import { RequirementDecomposer, DecompositionResult, RepoRequirement } from "../core/requirement-decomposer";
+import { buildFrontendApiContract, buildContractContextSection } from "../core/contract-bridge";
+import { loadFrontendContext, buildFrontendContextSection } from "../core/frontend-context-loader";
+import { buildFrontendSpecPrompt, frontendSpecSystemPrompt } from "../prompts/frontend-spec.prompt";
+import { SpecDSL } from "../core/dsl-types";
+import { generateMockAssets, findLatestDslFile } from "../core/mock-server-generator";
+import { SpecUpdater } from "../core/spec-updater";
+import { exportOpenApi } from "../core/openapi-exporter";
+
+// ─── Config File ──────────────────────────────────────────────────────────────
+
+interface AiSpecConfig {
+  provider?: string;
+  model?: string;
+  codegen?: CodeGenMode;
+  codegenProvider?: string;
+  codegenModel?: string;
+}
+
+const CONFIG_FILE = ".ai-spec.json";
+
+async function loadConfig(dir: string): Promise<AiSpecConfig> {
+  const p = path.join(dir, CONFIG_FILE);
+  if (await fs.pathExists(p)) {
+    return fs.readJson(p);
+  }
+  return {};
+}
+
+// ─── API Key Resolution ────────────────────────────────────────────────────────
+
+async function resolveApiKey(
+  providerName: string,
+  cliKey?: string
+): Promise<string> {
+  if (cliKey) return cliKey;
+
+  const envVar = ENV_KEY_MAP[providerName];
+  if (envVar && process.env[envVar]) return process.env[envVar]!;
+
+  // Check saved key and offer reuse
+  const savedKey = await getSavedKey(providerName);
+  if (savedKey) {
+    const masked = savedKey.slice(0, 6) + "..." + savedKey.slice(-4);
+    const choice = await select({
+      message: `${providerName} API key (saved: ${masked}):`,
+      choices: [
+        { name: "Use saved key", value: "reuse" },
+        { name: "Enter a new key", value: "new" },
+      ],
+    });
+    if (choice === "reuse") return savedKey;
+  }
+
+  // Fresh input — save for next time
+  const newKey = await input({
+    message: `Enter your ${providerName} API key${envVar ? ` (or set ${envVar} env var)` : ""}:`,
+    validate: (v) => v.trim().length > 0 || "API key cannot be empty",
+  });
+  await saveKey(providerName, newKey.trim());
+  console.log(chalk.gray(`  Key saved to ${KEY_STORE_FILE}`));
+  return newKey.trim();
+}
+
+// ─── Banner ───────────────────────────────────────────────────────────────────
+
+function printBanner(opts: {
+  specProvider: string;
+  specModel: string;
+  codegenMode: string;
+  codegenProvider: string;
+  codegenModel: string;
+}) {
+  console.log(chalk.blue("\n" + "─".repeat(52)));
+  console.log(chalk.bold("  ai-spec — AI-driven Development Orchestrator"));
+  console.log(chalk.blue("─".repeat(52)));
+  console.log(chalk.gray(`  Spec    : ${opts.specProvider} / ${opts.specModel}`));
+  console.log(
+    chalk.gray(
+      `  Codegen : ${opts.codegenMode} (${opts.codegenProvider} / ${opts.codegenModel})`
+    )
+  );
+  console.log(chalk.blue("─".repeat(52) + "\n"));
+}
+
+// ─── Program ──────────────────────────────────────────────────────────────────
+
+const program = new Command();
+
+program
+  .name("ai-spec")
+  .description("AI-driven Development Orchestrator — spec, generate, review")
+  .version("0.14.1");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: create
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("create")
+  .description("Generate a feature spec and kick off code generation")
+  .argument("[idea]", "Feature idea in natural language (prompted if omitted)")
+  .option(
+    "--provider <name>",
+    `AI provider for spec generation (${SUPPORTED_PROVIDERS.join("|")})`,
+    undefined
+  )
+  .option("--model <name>", "Model name for spec generation")
+  .option("-k, --key <apiKey>", "API key (overrides env var)")
+  .option(
+    "--codegen <mode>",
+    "Code generation mode: claude-code | api | plan",
+    undefined
+  )
+  .option(
+    "--codegen-provider <name>",
+    "AI provider for code generation (defaults to --provider)"
+  )
+  .option("--codegen-model <name>", "Model for code generation")
+  .option("--codegen-key <key>", "API key for code generation (if different)")
+  .option("--skip-worktree", "Skip git worktree creation (auto-set for frontend projects)")
+  .option("--worktree", "Force git worktree creation even for frontend projects")
+  .option("--skip-review", "Skip automated code review")
+  .option("--skip-tasks", "Skip task generation (just generate spec)")
+  .option("--auto", "Run claude non-interactively via -p flag (saves tokens)")
+  .option("--fast", "Skip interactive spec refinement, proceed immediately with initial spec")
+  .option("--resume", "Resume an interrupted run — skip tasks already marked as done")
+  .option("--skip-dsl", "Skip DSL extraction step")
+  .option("--skip-tests", "Skip test skeleton generation")
+  .option("--skip-error-feedback", "Skip error feedback loop (test/lint auto-fix)")
+  .option("--tdd", "TDD mode: generate failing tests first, then generate implementation to pass them")
+  .option("--skip-assessment", "Skip spec quality pre-assessment before the Approval Gate")
+  .action(async (idea: string | undefined, opts) => {
+    const currentDir = process.cwd();
+    const config = await loadConfig(currentDir);
+
+    // ── Resolve idea ──────────────────────────────────────────────────────────
+    if (!idea) {
+      idea = await input({
+        message: "What feature do you want to build?",
+        validate: (v) => v.trim().length > 0 || "Please describe your feature",
+      });
+    }
+
+    // ── Detect workspace mode ─────────────────────────────────────────────────
+    const workspaceLoader = new WorkspaceLoader(currentDir);
+    const workspaceConfig = await workspaceLoader.load();
+
+    if (workspaceConfig) {
+      console.log(chalk.cyan(`\n[Workspace] Detected workspace: ${workspaceConfig.name}`));
+      console.log(chalk.gray(`  Repos: ${workspaceConfig.repos.map((r) => r.name).join(", ")}`));
+      await runMultiRepoPipeline(idea!, workspaceConfig, opts, currentDir, config);
+      return;
+    }
+
+    // ── Resolve spec provider ─────────────────────────────────────────────────
+    const specProviderName = opts.provider || config.provider || "gemini";
+    const specModelName =
+      opts.model || config.model || DEFAULT_MODELS[specProviderName];
+    const specApiKey = await resolveApiKey(specProviderName, opts.key);
+
+    // ── Resolve codegen ───────────────────────────────────────────────────────
+    const codegenMode: CodeGenMode =
+      (opts.codegen as CodeGenMode) || config.codegen || "claude-code";
+    const codegenProviderName =
+      opts.codegenProvider || config.codegenProvider || specProviderName;
+    const codegenModelName =
+      opts.codegenModel ||
+      config.codegenModel ||
+      DEFAULT_MODELS[codegenProviderName];
+    const codegenApiKey =
+      codegenProviderName === specProviderName
+        ? specApiKey
+        : await resolveApiKey(codegenProviderName, opts.codegenKey);
+
+    printBanner({
+      specProvider: specProviderName,
+      specModel: specModelName,
+      codegenMode,
+      codegenProvider: codegenProviderName,
+      codegenModel: codegenModelName,
+    });
+
+    // ── Step 1: Context ───────────────────────────────────────────────────────
+    console.log(chalk.blue("[1/6] Loading project context..."));
+    const loader = new ContextLoader(currentDir);
+    const context = await loader.loadProjectContext();
+    const { type: detectedRepoType } = await detectRepoType(currentDir);
+    console.log(chalk.gray(`  Tech stack  : ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
+    console.log(chalk.gray(`  Dependencies: ${context.dependencies.length} packages`));
+    console.log(chalk.gray(`  API files   : ${context.apiStructure.length} files`));
+    if (context.schema) {
+      console.log(chalk.gray(`  Prisma schema: found`));
+    }
+    if (context.constitution) {
+      console.log(chalk.green(`  Constitution : found (.ai-spec-constitution.md)`));
+    } else {
+      // Auto-run init: generate constitution before proceeding
+      console.log(chalk.yellow("  Constitution : not found — auto-generating..."));
+      try {
+        const constitutionGen = new ConstitutionGenerator(
+          createProvider(specProviderName, specApiKey, specModelName)
+        );
+        const constitutionContent = await constitutionGen.generate(currentDir);
+        await constitutionGen.saveConstitution(currentDir, constitutionContent);
+        context.constitution = constitutionContent;
+        console.log(chalk.green(`  Constitution : ✔ generated and saved (.ai-spec-constitution.md)`));
+      } catch (err) {
+        console.log(chalk.yellow(`  Constitution : ⚠ auto-generation failed (${(err as Error).message}), continuing without it.`));
+      }
+    }
+
+    // ── Step 2: Spec + Tasks Generation (single AI call) ─────────────────────
+    console.log(chalk.blue(`\n[2/6] Generating spec with ${specProviderName}/${specModelName}...`));
+    const specProvider = createProvider(specProviderName, specApiKey, specModelName);
+
+    let initialSpec: string;
+    let initialTasks: import("../core/task-generator").SpecTask[] = [];
+
+    try {
+      if (opts.skipTasks) {
+        // Tasks skipped: use SpecGenerator alone
+        const generator = new SpecGenerator(specProvider);
+        initialSpec = await generator.generateSpec(idea, context);
+        console.log(chalk.green("  ✔ Spec generated."));
+      } else {
+        // Combined: spec + tasks in one call
+        const result = await generateSpecWithTasks(specProvider, idea, context);
+        initialSpec = result.spec;
+        initialTasks = result.tasks;
+        console.log(chalk.green(`  ✔ Spec generated.`));
+        if (initialTasks.length > 0) {
+          console.log(chalk.green(`  ✔ ${initialTasks.length} tasks generated (combined call).`));
+        } else {
+          console.log(chalk.yellow("  ⚠ Tasks not parsed from response — will retry separately after refinement."));
+        }
+      }
+    } catch (err) {
+      console.error(chalk.red("  ✘ Spec generation failed:"), err);
+      process.exit(1);
+    }
+
+    // ── Step 3: Interactive Refinement ────────────────────────────────────────
+    let finalSpec: string;
+    if (opts.fast) {
+      console.log(chalk.gray("\n[3/6] Skipping refinement (--fast)."));
+      finalSpec = initialSpec;
+    } else {
+      console.log(chalk.blue("\n[3/6] Interactive spec refinement..."));
+      const refiner = new SpecRefiner(specProvider);
+      finalSpec = await refiner.refineLoop(initialSpec);
+    }
+
+    // Compute slug once — used in Approval Gate diff preview and versioned file save
+    const featureSlug = slugify(idea!);
+
+    // ── Step 3.4: Spec Quality Pre-Assessment ────────────────────────────────
+    // Advisory only — never blocks the flow. Skipped in --auto mode and with --skip-assessment.
+    if (!opts.auto && !opts.skipAssessment) {
+      console.log(chalk.blue("\n[3.4/6] Spec quality assessment..."));
+      const assessment = await assessSpec(specProvider, finalSpec, context.constitution ?? undefined);
+      if (assessment) {
+        printSpecAssessment(assessment);
+      } else {
+        console.log(chalk.gray("  (Assessment skipped — AI call failed or timed out)"));
+      }
+    }
+
+    // ── Step 3.5: Approval Gate ───────────────────────────────────────────────
+    if (!opts.auto) {
+      console.log(chalk.blue("\n[3.5/6] Approval Gate — review before code generation"));
+
+      // Show spec stats
+      const specLines = finalSpec.split("\n").length;
+      const specWords = finalSpec.split(/\s+/).length;
+      const taskCountHint = initialTasks.length > 0 ? `  Tasks generated : ${initialTasks.length}` : "";
+      console.log(chalk.gray(`  Spec length     : ${specLines} lines / ${specWords} words`));
+      if (taskCountHint) console.log(chalk.gray(taskCountHint));
+
+      // Show diff vs previous version if one exists
+      const previewSpecsDir = path.join(currentDir, "specs");
+      const slug = featureSlug;
+      const prevVersion = await findLatestVersion(previewSpecsDir, slug);
+      if (prevVersion) {
+        console.log(chalk.gray(`  Previous version: v${prevVersion.version} (${prevVersion.filePath})`));
+        const diff = computeDiff(prevVersion.content, finalSpec);
+        console.log(chalk.cyan("\n  ── Changes vs previous version ──────────────"));
+        printDiffSummary(diff, `v${prevVersion.version} → v${prevVersion.version + 1}`);
+        printDiff(diff);
+        console.log(chalk.cyan("  ────────────────────────────────────────────"));
+      }
+
+      const gate = await select({
+        message: "Ready to proceed to code generation?",
+        choices: [
+          { name: "✅  Proceed — start code generation", value: "proceed" },
+          { name: "📋  View full spec", value: "view" },
+          { name: "❌  Abort", value: "abort" },
+        ],
+      });
+
+      if (gate === "view") {
+        console.log(chalk.cyan("\n" + "─".repeat(52)));
+        console.log(finalSpec);
+        console.log(chalk.cyan("─".repeat(52) + "\n"));
+
+        const confirm2 = await select({
+          message: "Proceed to code generation?",
+          choices: [
+            { name: "✅  Proceed", value: "proceed" },
+            { name: "❌  Abort", value: "abort" },
+          ],
+        });
+        if (confirm2 === "abort") {
+          console.log(chalk.yellow("  Aborted. Spec was NOT saved."));
+          process.exit(0);
+        }
+      } else if (gate === "abort") {
+        console.log(chalk.yellow("  Aborted. Spec was NOT saved."));
+        process.exit(0);
+      }
+
+      console.log(chalk.green("  ✔ Approved — continuing to code generation."));
+    } else {
+      console.log(chalk.gray("[3.5/6] Approval Gate: skipped (--auto)."));
+    }
+
+    // ── Step 3.8: DSL Extraction + Validation ─────────────────────────────────
+    // Runs after approval, before worktree, so the DSL is saved alongside the spec.
+    // We extract from finalSpec (already approved). The DSL file is saved in Step 5.
+    let extractedDsl: import("../core/dsl-types").SpecDSL | null = null;
+
+    if (opts.skipDsl) {
+      console.log(chalk.gray("\n[DSL] Skipped (--skip-dsl)."));
+    } else {
+      console.log(chalk.blue("\n[DSL] Extracting structured DSL from spec..."));
+      console.log(chalk.gray(`  Provider: ${specProviderName}/${specModelName}`));
+      try {
+        const isFrontend = isFrontendDeps(context.dependencies);
+        if (isFrontend) console.log(chalk.gray("  Frontend project detected — using ComponentSpec extractor"));
+        const dslExtractor = new DslExtractor(specProvider);
+        extractedDsl = await dslExtractor.extract(finalSpec, { auto: opts.auto, isFrontend });
+        if (extractedDsl) {
+          console.log(chalk.green("  ✔ DSL extracted and validated."));
+        } else {
+          console.log(chalk.yellow("  ⚠ DSL skipped — codegen will use Spec + Tasks only."));
+        }
+      } catch (err) {
+        // Unexpected error (not user abort — that would have called process.exit)
+        console.log(chalk.yellow(`  ⚠ DSL extraction error: ${(err as Error).message} — continuing without DSL.`));
+      }
+    }
+
+    // ── Step 4: Git Worktree ──────────────────────────────────────────────────
+    // Frontend projects (React / Vue / Next / React-Native) work directly on a
+    // feature branch — no worktree needed. node_modules is not copied into
+    // worktrees by default, so running the dev server would break.
+    // Auto-skip unless the user explicitly passes --worktree.
+    const isFrontendProject = isFrontendDeps(context.dependencies ?? []);
+    const skipWorktree = opts.worktree
+      ? false
+      : opts.skipWorktree || isFrontendProject;
+
+    let workingDir = currentDir;
+    if (!skipWorktree) {
+      console.log(chalk.blue("\n[4/6] Setting up git worktree..."));
+      const worktreeManager = new GitWorktreeManager(currentDir);
+      const worktreePath = await worktreeManager.createWorktree(idea);
+      if (worktreePath) workingDir = worktreePath;
+    } else {
+      const reason = opts.worktree
+        ? ""
+        : isFrontendProject
+        ? " (frontend project — use --worktree to override)"
+        : " (--skip-worktree)";
+      console.log(chalk.gray(`[4/6] Skipping worktree${reason}.`));
+    }
+
+    // ── Step 5: Save Spec (versioned) + Generate Tasks ────────────────────────
+    const specsDir = path.join(workingDir, "specs");
+    await fs.ensureDir(specsDir);
+
+    const { filePath: specFile, version: specVersion } = await nextVersionPath(specsDir, featureSlug);
+    await fs.writeFile(specFile, finalSpec, "utf-8");
+    console.log(chalk.green(`\n[5/6] ✔ Spec saved: ${specFile}`) + chalk.gray(` (v${specVersion})`));
+
+    // Save DSL alongside the spec if extraction succeeded
+    let savedDslFile: string | null = null;
+    if (extractedDsl) {
+      const dslExtractor = new DslExtractor(specProvider);
+      savedDslFile = await dslExtractor.saveDsl(extractedDsl, specFile);
+      console.log(chalk.green(`  ✔ DSL saved : ${savedDslFile}`));
+    }
+
+    if (!opts.skipTasks) {
+      const taskGen = new TaskGenerator(specProvider);
+      let tasksToSave = initialTasks;
+
+      // If combined call didn't produce tasks (parse failed), retry as a separate call
+      if (tasksToSave.length === 0) {
+        console.log(chalk.blue(`\n  Generating tasks (separate call)...`));
+        try {
+          tasksToSave = await taskGen.generateTasks(finalSpec, context);
+        } catch (err) {
+          console.log(chalk.yellow(`  ⚠ Task generation failed: ${(err as Error).message}`));
+        }
+      }
+
+      if (tasksToSave.length > 0) {
+        const sorted = taskGen.sortByLayer(tasksToSave);
+        const tasksFile = await taskGen.saveTasks(sorted, specFile);
+        printTasks(sorted);
+        console.log(chalk.green(`  ✔ Tasks saved: ${tasksFile}`));
+      } else {
+        console.log(chalk.yellow("  ⚠ No tasks generated — code generation will use fallback file planning."));
+      }
+    }
+
+    // ── Step 6: Code Generation ───────────────────────────────────────────────
+    console.log(chalk.blue(`\n[6/6] Code generation (mode: ${codegenMode})...`));
+    const codegenProvider =
+      codegenProviderName === specProviderName && codegenApiKey === specApiKey
+        ? specProvider
+        : createProvider(codegenProviderName, codegenApiKey, codegenModelName);
+
+    // ── TDD: generate failing tests BEFORE implementation ────────────────────
+    let generatedTestFiles: string[] = [];
+    if (opts.tdd && extractedDsl) {
+      console.log(chalk.cyan("\n[TDD] Generating pre-implementation tests (will fail until code is written)..."));
+      const testGen = new TestGenerator(codegenProvider);
+      generatedTestFiles = await testGen.generateTdd(extractedDsl, workingDir);
+    }
+
+    const codegen = new CodeGenerator(codegenProvider, codegenMode);
+    const generatedFiles = await codegen.generateCode(specFile, workingDir, context, {
+      auto: opts.auto,
+      resume: opts.resume,
+      dslFilePath: savedDslFile ?? undefined,
+      repoType: detectedRepoType,
+    });
+
+    // ── Step 7: Test Skeleton Generation (skipped in TDD mode — tests already written) ──
+    if (opts.tdd) {
+      console.log(chalk.gray("\n[7/9] TDD mode — test files already written pre-implementation."));
+    } else if (opts.skipTests) {
+      console.log(chalk.gray("\n[7/9] Skipping test generation (--skip-tests)."));
+    } else if (!extractedDsl) {
+      console.log(chalk.gray("\n[7/9] Skipping test generation (no DSL available)."));
+    } else {
+      console.log(chalk.blue(`\n[7/9] Test skeleton generation...`));
+      const testGen = new TestGenerator(codegenProvider);
+      generatedTestFiles = await testGen.generate(extractedDsl, workingDir);
+    }
+
+    // ── Step 8: Error Feedback Loop ───────────────────────────────────────────
+    // In TDD mode, the error feedback loop is the primary driver:
+    // it runs tests, collects failures, and fixes implementation until tests pass.
+    if (opts.skipErrorFeedback) {
+      console.log(chalk.gray("[8/9] Skipping error feedback (--skip-error-feedback)."));
+    } else {
+      if (opts.tdd) {
+        console.log(chalk.cyan("[8/9] TDD mode — error feedback loop driving implementation to pass tests..."));
+      }
+      await runErrorFeedback(codegenProvider, workingDir, extractedDsl, {
+        maxCycles: opts.tdd ? 3 : 2,  // TDD gets one extra cycle
+      });
+    }
+
+    // ── Step 9: Code Review ───────────────────────────────────────────────────
+    let reviewResult = "";
+    if (!opts.skipReview) {
+      console.log(chalk.blue("\n[9/9] Automated code review (2-pass: architecture + implementation)..."));
+      const reviewer = new CodeReviewer(specProvider, currentDir);
+      const savedSpec = await fs.readFile(specFile, "utf-8");
+
+      if (codegenMode === "api" && generatedFiles.length > 0) {
+        // api mode: review the generated files directly (no git diff available)
+        reviewResult = await reviewer.reviewFiles(savedSpec, generatedFiles, workingDir, specFile);
+      } else {
+        // claude-code / plan mode: review via git diff
+        const originalDir = process.cwd();
+        try {
+          process.chdir(workingDir);
+          reviewResult = await reviewer.reviewCode(savedSpec, specFile);
+        } finally {
+          process.chdir(originalDir);
+        }
+      }
+
+      // Knowledge Memory: extract lessons from review and append to constitution §9
+      await accumulateReviewKnowledge(specProvider, currentDir, reviewResult);
+    }
+
+    // ── Done ──────────────────────────────────────────────────────────────────
+    console.log(chalk.bold.green("\n✔ All done!"));
+    console.log(chalk.gray(`  Spec        : ${specFile}`));
+    if (savedDslFile) console.log(chalk.gray(`  DSL         : ${savedDslFile}`));
+    if (generatedTestFiles.length > 0) {
+      console.log(chalk.gray(`  Tests       : ${generatedTestFiles.length} skeleton file(s) generated`));
+    }
+    console.log(chalk.gray(`  Working dir : ${workingDir}`));
+    if (workingDir !== currentDir) {
+      console.log(chalk.gray(`  Run \`cd ${workingDir}\` to enter the worktree.`));
+    }
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: review
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("review")
+  .description("Run AI code review on current git diff against a spec")
+  .argument("[specFile]", "Path to spec file (auto-detects latest in specs/ if omitted)")
+  .option(
+    "--provider <name>",
+    `AI provider (${SUPPORTED_PROVIDERS.join("|")})`,
+    undefined
+  )
+  .option("--model <name>", "Model name")
+  .option("-k, --key <apiKey>", "API key")
+  .action(async (specFile: string | undefined, opts) => {
+    const currentDir = process.cwd();
+    const config = await loadConfig(currentDir);
+
+    const providerName = opts.provider || config.provider || "gemini";
+    const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
+    const apiKey = await resolveApiKey(providerName, opts.key);
+
+    const provider = createProvider(providerName, apiKey, modelName);
+    const reviewer = new CodeReviewer(provider, currentDir);
+
+    let specContent = "";
+    let resolvedSpecFile: string | undefined;
+
+    if (specFile && (await fs.pathExists(specFile))) {
+      specContent = await fs.readFile(specFile, "utf-8");
+      resolvedSpecFile = specFile;
+      console.log(chalk.gray(`Using spec: ${specFile}`));
+    } else {
+      // Auto-detect the latest spec in specs/
+      const specsDir = path.join(currentDir, "specs");
+      if (await fs.pathExists(specsDir)) {
+        const files = (await fs.readdir(specsDir))
+          .filter((f) => f.endsWith(".md"))
+          .sort()
+          .reverse();
+        if (files.length > 0) {
+          const latest = path.join(specsDir, files[0]);
+          specContent = await fs.readFile(latest, "utf-8");
+          resolvedSpecFile = latest;
+          console.log(chalk.gray(`Auto-detected spec: specs/${files[0]}`));
+        }
+      }
+    }
+
+    if (!specContent) {
+      console.log(chalk.yellow("No spec file found. Running review without spec context."));
+    }
+
+    await reviewer.reviewCode(specContent, resolvedSpecFile);
+    await reviewer.printScoreTrend();
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: init  —  generate Project Constitution
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("init")
+  .description(`Analyze codebase and generate Project Constitution (${CONSTITUTION_FILE})`)
+  .option(
+    "--provider <name>",
+    `AI provider (${SUPPORTED_PROVIDERS.join("|")})`,
+    undefined
+  )
+  .option("--model <name>", "Model name")
+  .option("-k, --key <apiKey>", "API key")
+  .option("--force", "Overwrite existing constitution")
+  .option(
+    "--global",
+    `Generate a Global Constitution (~/${GLOBAL_CONSTITUTION_FILE}) instead of a project-level one`
+  )
+  .option("--consolidate", "Consolidate §9 accumulated lessons into §1–§8 core rules (prune & rebase)")
+  .option("--dry-run", "Preview consolidation result without writing (use with --consolidate)")
+  .action(async (opts) => {
+    const currentDir = process.cwd();
+    const config = await loadConfig(currentDir);
+
+    const providerName = opts.provider || config.provider || "gemini";
+    const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
+    const apiKey = await resolveApiKey(providerName, opts.key);
+    const provider = createProvider(providerName, apiKey, modelName);
+
+    // ── Consolidate mode ─────────────────────────────────────────────────
+    if (opts.consolidate) {
+      const consolidator = new ConstitutionConsolidator(provider);
+      try {
+        const result = await consolidator.consolidate(currentDir, {
+          dryRun: opts.dryRun,
+          auto: opts.auto,
+        });
+        if (result.written) {
+          console.log(chalk.blue("\n  Summary:"));
+          console.log(chalk.gray(`  Lines : ${result.before.totalLines} → ${result.after.totalLines} (${result.before.totalLines - result.after.totalLines > 0 ? "-" : "+"}${Math.abs(result.before.totalLines - result.after.totalLines)})`));
+          console.log(chalk.gray(`  §9    : ${result.before.lessonCount} → ${result.after.lessonCount} lessons remaining`));
+          if (result.backupPath) {
+            console.log(chalk.gray(`  Backup: ${path.basename(result.backupPath)}`));
+          }
+        }
+      } catch (err) {
+        console.error(chalk.red(`  ✘ Consolidation failed: ${(err as Error).message}`));
+        process.exit(1);
+      }
+      return;
+    }
+
+    // ── Global constitution mode ──────────────────────────────────────────
+    if (opts.global) {
+      const existing = await loadGlobalConstitution([currentDir]);
+      if (existing && !opts.force) {
+        console.log(chalk.yellow(`\n  Global constitution already exists at: ${existing.source}`));
+        console.log(chalk.gray("  Use --force to overwrite it."));
+        return;
+      }
+
+      console.log(chalk.blue("\n─── Generating Global Constitution ──────────────"));
+      console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
+      console.log(chalk.gray("  Scanning repos in workspace..."));
+
+      // Build per-repo summaries from sibling directories
+      const loader = new ContextLoader(currentDir);
+      const ctx = await loader.loadProjectContext();
+      const summary = [
+        `Tech stack: ${ctx.techStack.join(", ") || "unknown"}`,
+        `Dependencies: ${ctx.dependencies.slice(0, 20).join(", ")}`,
+      ].join("\n");
+
+      const prompt = buildGlobalConstitutionPrompt([{ name: path.basename(currentDir), summary }]);
+      let globalConstitution: string;
+      try {
+        globalConstitution = await provider.generate(prompt, globalConstitutionSystemPrompt);
+      } catch (err) {
+        console.error(chalk.red("  ✘ Failed to generate global constitution:"), err);
+        process.exit(1);
+      }
+
+      const saved = await saveGlobalConstitution(globalConstitution, currentDir);
+      console.log(chalk.green(`\n  ✔ Global constitution saved: ${saved}`));
+      console.log(chalk.gray("  This will be automatically merged into all project constitutions in this workspace."));
+      console.log(chalk.gray("  Project-level rules always override global rules.\n"));
+      console.log(chalk.bold("  Preview:"));
+      console.log(chalk.gray(globalConstitution.split("\n").slice(0, 12).join("\n")));
+      if (globalConstitution.split("\n").length > 12) {
+        console.log(chalk.gray(`  ... (${globalConstitution.split("\n").length} lines total)`));
+      }
+      return;
+    }
+
+    // ── Project constitution mode (default) ───────────────────────────────
+    const constitutionPath = path.join(currentDir, CONSTITUTION_FILE);
+
+    if (!opts.force && (await fs.pathExists(constitutionPath))) {
+      console.log(chalk.yellow(`\n  ${CONSTITUTION_FILE} already exists.`));
+      console.log(chalk.gray("  Use --force to overwrite it."));
+      console.log(chalk.gray(`  Or edit it directly: ${constitutionPath}`));
+      return;
+    }
+
+    console.log(chalk.blue("\n─── Generating Project Constitution ─────────────"));
+    console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
+    console.log(chalk.gray("  Analyzing codebase..."));
+
+    const generator = new ConstitutionGenerator(provider);
+
+    let constitution: string;
+    try {
+      constitution = await generator.generate(currentDir);
+    } catch (err) {
+      console.error(chalk.red("  ✘ Failed to generate constitution:"), err);
+      process.exit(1);
+    }
+
+    const saved = await generator.saveConstitution(currentDir, constitution);
+
+    // Note if a global constitution will also be applied
+    const globalResult = await loadGlobalConstitution([path.dirname(currentDir)]);
+    if (globalResult) {
+      console.log(chalk.cyan(`\n  ℹ Global constitution detected: ${globalResult.source}`));
+      console.log(chalk.gray("    It will be merged with this project constitution at runtime."));
+      console.log(chalk.gray("    Project rules take priority over global rules."));
+    }
+
+    console.log(chalk.green(`\n  ✔ Constitution saved: ${saved}`));
+    console.log(chalk.gray("  This file will be automatically used in all future `ai-spec create` runs."));
+    console.log(chalk.gray("  Edit it to add custom rules or red lines for your project.\n"));
+    console.log(chalk.bold("  Preview:"));
+    console.log(chalk.gray(constitution.split("\n").slice(0, 15).join("\n")));
+    if (constitution.split("\n").length > 15) {
+      console.log(chalk.gray(`  ... (${constitution.split("\n").length} lines total)`));
+    }
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: config
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("config")
+  .description(`Set default configuration for this project (saved to ${CONFIG_FILE})`)
+  .option("--provider <name>", "Default AI provider for spec generation")
+  .option("--model <name>", "Default model for spec generation")
+  .option(
+    "--codegen <mode>",
+    "Default code generation mode (claude-code|api|plan)"
+  )
+  .option("--codegen-provider <name>", "Default provider for code generation")
+  .option("--codegen-model <name>", "Default model for code generation")
+  .option("--show", "Print current configuration")
+  .option("--reset", "Reset configuration to empty")
+  .option("--clear-keys", "Delete all saved API keys from ~/.ai-spec-keys.json")
+  .option("--clear-key <provider>", "Delete saved API key for a specific provider")
+  .option("--list-keys", "Show which providers have a saved key")
+  .action(async (opts) => {
+    const currentDir = process.cwd();
+    const configPath = path.join(currentDir, CONFIG_FILE);
+
+    if (opts.clearKeys) {
+      await clearAllKeys();
+      console.log(chalk.green(`✔ All saved API keys cleared.`));
+      return;
+    }
+
+    if (opts.clearKey) {
+      await clearKey(opts.clearKey);
+      console.log(chalk.green(`✔ Saved key for "${opts.clearKey}" removed.`));
+      return;
+    }
+
+    if (opts.listKeys) {
+      const store: Record<string, string> = await fs.readJson(KEY_STORE_FILE).catch(() => ({}));
+      const providers = Object.keys(store);
+      if (providers.length === 0) {
+        console.log(chalk.gray("No saved API keys."));
+      } else {
+        console.log(chalk.bold("Saved API keys:"));
+        for (const p of providers) {
+          const k = store[p];
+          console.log(chalk.gray(`  ${p}: ${k.slice(0, 6)}...${k.slice(-4)}`));
+        }
+        console.log(chalk.gray(`\nFile: ${KEY_STORE_FILE}`));
+      }
+      return;
+    }
+
+    if (opts.reset) {
+      await fs.writeJson(configPath, {}, { spaces: 2 });
+      console.log(chalk.green(`✔ Config reset: ${configPath}`));
+      return;
+    }
+
+    const existing: AiSpecConfig = await loadConfig(currentDir);
+
+    if (opts.show) {
+      if (Object.keys(existing).length === 0) {
+        console.log(chalk.gray("No config file found. Using built-in defaults."));
+      } else {
+        console.log(chalk.bold(`${configPath}:`));
+        console.log(JSON.stringify(existing, null, 2));
+      }
+      return;
+    }
+
+    const updated: AiSpecConfig = { ...existing };
+    if (opts.provider) updated.provider = opts.provider;
+    if (opts.model) updated.model = opts.model;
+    if (opts.codegen) updated.codegen = opts.codegen as CodeGenMode;
+    if (opts.codegenProvider) updated.codegenProvider = opts.codegenProvider;
+    if (opts.codegenModel) updated.codegenModel = opts.codegenModel;
+
+    await fs.writeJson(configPath, updated, { spaces: 2 });
+    console.log(chalk.green(`✔ Config saved to ${configPath}`));
+    console.log(JSON.stringify(updated, null, 2));
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: model  —  interactive model switcher
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("model")
+  .description("Interactively switch the active AI provider/model and save to .ai-spec.json")
+  .option("--list", "List all available providers and models")
+  .action(async (opts) => {
+    const currentDir = process.cwd();
+    const configPath = path.join(currentDir, CONFIG_FILE);
+
+    // ── --list: just print the catalog ────────────────────────────────────────
+    if (opts.list) {
+      console.log(chalk.bold("\nAvailable providers & models:\n"));
+      for (const [key, meta] of Object.entries(PROVIDER_CATALOG)) {
+        console.log(
+          `  ${chalk.bold.cyan(key.padEnd(10))} ${chalk.white(meta.displayName)}`
+        );
+        console.log(chalk.gray(`             ${meta.description}`));
+        console.log(
+          chalk.gray(
+            `             env: ${meta.envKey}  |  models: ${meta.models.join(", ")}`
+          )
+        );
+        console.log();
+      }
+      return;
+    }
+
+    const existing: AiSpecConfig = await loadConfig(currentDir);
+
+    console.log(chalk.blue("\n─── Model Switcher ─────────────────────────────"));
+    if (Object.keys(existing).length > 0) {
+      console.log(
+        chalk.gray(
+          `  Current: spec=${existing.provider ?? "gemini"}/${existing.model ?? DEFAULT_MODELS[existing.provider ?? "gemini"]}` +
+            (existing.codegenProvider
+              ? `  codegen=${existing.codegenProvider}/${existing.codegenModel ?? ""}`
+              : "")
+        )
+      );
+    }
+    console.log();
+
+    // ── What to configure ─────────────────────────────────────────────────────
+    const target = await select({
+      message: "Configure model for:",
+      choices: [
+        { name: "Spec generation  (used for spec writing & refinement)", value: "spec" },
+        { name: "Code generation  (used when --codegen api is active)", value: "codegen" },
+        { name: "Both             (same provider/model for all tasks)", value: "both" },
+      ],
+    });
+
+    // ── Helper: pick provider + model ─────────────────────────────────────────
+    async function pickProviderAndModel(label: string): Promise<{ provider: string; model: string }> {
+      const providerKey = await select({
+        message: `${label} — select provider:`,
+        choices: Object.entries(PROVIDER_CATALOG).map(([key, meta]) => ({
+          name: `${meta.displayName.padEnd(22)} ${chalk.gray(meta.description)}`,
+          value: key,
+          short: meta.displayName,
+        })),
+      });
+
+      const meta = PROVIDER_CATALOG[providerKey];
+      const modelChoices = [
+        ...meta.models.map((m) => ({ name: m, value: m })),
+        { name: chalk.italic("✎  Enter custom model name..."), value: "__custom__" },
+      ];
+
+      let chosenModel = await select({
+        message: `${label} — select model (${meta.displayName}):`,
+        choices: modelChoices,
+      });
+
+      if (chosenModel === "__custom__") {
+        chosenModel = await input({
+          message: "Enter model name:",
+          validate: (v) => v.trim().length > 0 || "Model name cannot be empty",
+        });
+      }
+
+      return { provider: providerKey, model: chosenModel };
+    }
+
+    // ── Run picker(s) ─────────────────────────────────────────────────────────
+    const updated: AiSpecConfig = { ...existing };
+
+    if (target === "spec" || target === "both") {
+      const { provider, model } = await pickProviderAndModel("Spec");
+      updated.provider = provider;
+      updated.model = model;
+    }
+
+    if (target === "codegen" || target === "both") {
+      if (target === "both") {
+        updated.codegenProvider = updated.provider;
+        updated.codegenModel = updated.model;
+      } else {
+        const { provider, model } = await pickProviderAndModel("Codegen");
+        updated.codegenProvider = provider;
+        updated.codegenModel = model;
+      }
+
+      // claude-code 模式只支持 Claude provider。
+      // 如果选了非 claude provider，自动把 codegen 模式改为 api。
+      const effectiveCodegenProvider = updated.codegenProvider ?? updated.provider ?? "gemini";
+      if (effectiveCodegenProvider !== "claude") {
+        if (!updated.codegen || updated.codegen === "claude-code") {
+          updated.codegen = "api";
+          console.log(
+            chalk.yellow(
+              `\n  ⚠  provider "${effectiveCodegenProvider}" 不支持 "claude-code" 模式。`
+            )
+          );
+          console.log(chalk.gray(`  已自动将 codegen 模式设为 "api"。`));
+        }
+      }
+    }
+
+    // ── Confirm & save ────────────────────────────────────────────────────────
+    console.log(chalk.blue("\n  Preview:"));
+    console.log(chalk.gray(`    spec    → ${updated.provider}/${updated.model}`));
+    if (updated.codegenProvider) {
+      console.log(
+        chalk.gray(
+          `    codegen → ${updated.codegenProvider}/${updated.codegenModel}  (mode: ${updated.codegen ?? "claude-code"})`
+        )
+      );
+    }
+
+    const ok = await confirm({ message: "Save to .ai-spec.json?", default: true });
+    if (!ok) {
+      console.log(chalk.gray("  Cancelled."));
+      return;
+    }
+
+    await fs.writeJson(configPath, updated, { spaces: 2 });
+    console.log(chalk.green(`\n  ✔ Saved to ${configPath}`));
+
+    // Remind about env var if not set
+    const providerToCheck = updated.provider ?? "gemini";
+    const envKey = ENV_KEY_MAP[providerToCheck];
+    if (envKey && !process.env[envKey]) {
+      console.log(
+        chalk.yellow(
+          `  ⚠  Remember to set ${envKey} in your environment or .env file.`
+        )
+      );
+    }
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Multi-Repo Pipeline
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Run a single repo through the full spec→dsl→worktree→codegen→tests→review pipeline.
+ * Returns the extracted DSL (or null) for contract bridging.
+ */
+async function runSingleRepoPipelineInWorkspace(opts: {
+  idea: string;
+  specProvider: ReturnType<typeof createProvider>;
+  specProviderName: string;
+  specModelName: string;
+  codegenProvider: ReturnType<typeof createProvider>;
+  codegenMode: CodeGenMode;
+  repoAbsPath: string;
+  repoName: string;
+  cliOpts: Record<string, unknown>;
+  contractContextSection?: string;
+}): Promise<{ dsl: SpecDSL | null; specFile: string | null }> {
+  const {
+    idea,
+    specProvider,
+    specProviderName,
+    specModelName,
+    codegenProvider,
+    codegenMode,
+    repoAbsPath,
+    repoName,
+    cliOpts,
+    contractContextSection,
+  } = opts;
+
+  console.log(chalk.blue(`\n  [${repoName}] Loading project context...`));
+  const loader = new ContextLoader(repoAbsPath);
+  let context = await loader.loadProjectContext();
+
+  // Detect repo language so the correct codegen system prompt is used
+  const { type: detectedRepoType } = await detectRepoType(repoAbsPath);
+
+  console.log(chalk.gray(`    Tech stack: ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
+  console.log(chalk.gray(`    Dependencies: ${context.dependencies.length} packages`));
+
+  if (!context.constitution) {
+    console.log(chalk.yellow(`    Constitution: not found — auto-generating...`));
+    try {
+      const constitutionGen = new ConstitutionGenerator(specProvider);
+      const constitutionContent = await constitutionGen.generate(repoAbsPath);
+      await constitutionGen.saveConstitution(repoAbsPath, constitutionContent);
+      context.constitution = constitutionContent;
+      console.log(chalk.green(`    Constitution: generated`));
+    } catch (err) {
+      console.log(chalk.yellow(`    Constitution: auto-generation failed (${(err as Error).message}), continuing.`));
+    }
+  } else {
+    console.log(chalk.green(`    Constitution: found`));
+  }
+
+  // Build the spec idea: inject contract context if available
+  let fullIdea = idea;
+  if (contractContextSection) {
+    fullIdea = `${idea}\n\n${contractContextSection}`;
+  }
+
+  console.log(chalk.blue(`  [${repoName}] Generating spec...`));
+  let finalSpec: string;
+  try {
+    const result = await generateSpecWithTasks(specProvider, fullIdea, context);
+    finalSpec = result.spec;
+    console.log(chalk.green(`    Spec generated.`));
+  } catch (err) {
+    console.error(chalk.red(`    Spec generation failed: ${(err as Error).message}`));
+    return { dsl: null, specFile: null };
+  }
+
+  // DSL Extraction
+  let extractedDsl: SpecDSL | null = null;
+  if (!cliOpts.skipDsl) {
+    console.log(chalk.blue(`  [${repoName}] Extracting DSL...`));
+    try {
+      const dslExtractor = new DslExtractor(specProvider);
+      const repoIsFrontend = isFrontendDeps(context.dependencies);
+      extractedDsl = await dslExtractor.extract(finalSpec, { auto: true, isFrontend: repoIsFrontend });
+      if (extractedDsl) {
+        console.log(chalk.green(`    DSL extracted.`));
+      }
+    } catch (err) {
+      console.log(chalk.yellow(`    DSL extraction failed: ${(err as Error).message}`));
+    }
+  }
+
+  // Git Worktree — auto-skip for frontend repos
+  const isFrontendRepo = isFrontendDeps(context.dependencies ?? []);
+  const skipWorktreeForRepo = cliOpts.worktree
+    ? false
+    : cliOpts.skipWorktree || isFrontendRepo;
+
+  let workingDir = repoAbsPath;
+  if (!skipWorktreeForRepo) {
+    console.log(chalk.blue(`  [${repoName}] Setting up git worktree...`));
+    try {
+      const worktreeManager = new GitWorktreeManager(repoAbsPath);
+      const worktreePath = await worktreeManager.createWorktree(idea);
+      if (worktreePath) workingDir = worktreePath;
+    } catch (err) {
+      console.log(chalk.yellow(`    Worktree setup failed: ${(err as Error).message}. Using main branch.`));
+    }
+  } else {
+    console.log(chalk.gray(`  [${repoName}] Skipping worktree${isFrontendRepo ? " (frontend repo)" : ""}.`));
+  }
+
+  // Save Spec
+  const specsDir = path.join(workingDir, "specs");
+  await fs.ensureDir(specsDir);
+  const featureSlug = slugify(idea);
+  const { filePath: specFile } = await nextVersionPath(specsDir, featureSlug);
+  await fs.writeFile(specFile, finalSpec, "utf-8");
+  console.log(chalk.green(`    Spec saved: ${path.relative(repoAbsPath, specFile)}`));
+
+  let savedDslFile: string | null = null;
+  if (extractedDsl) {
+    const dslExtractorForSave = new DslExtractor(specProvider);
+    savedDslFile = await dslExtractorForSave.saveDsl(extractedDsl, specFile);
+    console.log(chalk.green(`    DSL saved: ${path.relative(repoAbsPath, savedDslFile)}`));
+  }
+
+  // Code Generation
+  console.log(chalk.blue(`  [${repoName}] Running code generation (mode: ${codegenMode})...`));
+  try {
+    const codegen = new CodeGenerator(codegenProvider, codegenMode);
+    await codegen.generateCode(specFile, workingDir, context, {
+      auto: true,
+      dslFilePath: savedDslFile ?? undefined,
+      repoType: detectedRepoType,
+    });
+    console.log(chalk.green(`    Code generation complete.`));
+  } catch (err) {
+    console.log(chalk.yellow(`    Code generation failed: ${(err as Error).message}`));
+  }
+
+  // Test Generation
+  if (!cliOpts.skipTests && extractedDsl) {
+    console.log(chalk.blue(`  [${repoName}] Generating test skeletons...`));
+    try {
+      const testGen = new TestGenerator(codegenProvider);
+      const testFiles = await testGen.generate(extractedDsl, workingDir);
+      console.log(chalk.green(`    ${testFiles.length} test file(s) generated.`));
+    } catch (err) {
+      console.log(chalk.yellow(`    Test generation failed: ${(err as Error).message}`));
+    }
+  }
+
+  // Error Feedback
+  if (!cliOpts.skipErrorFeedback) {
+    try {
+      await runErrorFeedback(codegenProvider, workingDir, extractedDsl, { maxCycles: 1 });
+    } catch (err) {
+      console.log(chalk.yellow(`    Error feedback failed: ${(err as Error).message}`));
+    }
+  }
+
+  // Code Review
+  if (!cliOpts.skipReview) {
+    console.log(chalk.blue(`  [${repoName}] Running code review...`));
+    try {
+      const reviewer = new CodeReviewer(specProvider);
+      const reviewResult = await reviewer.reviewCode(finalSpec);
+      await accumulateReviewKnowledge(specProvider, repoAbsPath, reviewResult);
+      console.log(chalk.green(`    Code review complete.`));
+    } catch (err) {
+      console.log(chalk.yellow(`    Code review failed: ${(err as Error).message}`));
+    }
+  }
+
+  return { dsl: extractedDsl, specFile };
+}
+
+/**
+ * Multi-repo pipeline: decompose → order repos → run each repo in order → bridge contracts.
+ */
+async function runMultiRepoPipeline(
+  idea: string,
+  workspace: WorkspaceConfig,
+  opts: Record<string, unknown>,
+  currentDir: string,
+  config: AiSpecConfig
+): Promise<void> {
+  // ── Resolve providers ──────────────────────────────────────────────────────
+  const specProviderName = (opts.provider as string) || config.provider || "gemini";
+  const specModelName = (opts.model as string) || config.model || DEFAULT_MODELS[specProviderName];
+  const specApiKey = await resolveApiKey(specProviderName, opts.key as string | undefined);
+  const specProvider = createProvider(specProviderName, specApiKey, specModelName);
+
+  const codegenMode: CodeGenMode = ((opts.codegen as string) as CodeGenMode) || config.codegen || "claude-code";
+  const codegenProviderName = (opts.codegenProvider as string) || config.codegenProvider || specProviderName;
+  const codegenModelName = (opts.codegenModel as string) || config.codegenModel || DEFAULT_MODELS[codegenProviderName];
+  const codegenApiKey =
+    codegenProviderName === specProviderName
+      ? specApiKey
+      : await resolveApiKey(codegenProviderName, opts.codegenKey as string | undefined);
+  const codegenProvider =
+    codegenProviderName === specProviderName && codegenApiKey === specApiKey
+      ? specProvider
+      : createProvider(codegenProviderName, codegenApiKey, codegenModelName);
+
+  printBanner({
+    specProvider: specProviderName,
+    specModel: specModelName,
+    codegenMode,
+    codegenProvider: codegenProviderName,
+    codegenModel: codegenModelName,
+  });
+
+  const workspaceLoader = new WorkspaceLoader(currentDir);
+
+  // ── Step 1: Load per-repo contexts ─────────────────────────────────────────
+  console.log(chalk.blue("\n[W1] Loading per-repo contexts..."));
+  const contexts = new Map<string, import("../core/context-loader").ProjectContext>();
+  const frontendContexts = new Map<string, import("../core/frontend-context-loader").FrontendContext>();
+
+  for (const repo of workspace.repos) {
+    const repoAbsPath = workspaceLoader.resolveAbsPath(repo);
+    try {
+      const loader = new ContextLoader(repoAbsPath);
+      const ctx = await loader.loadProjectContext();
+      contexts.set(repo.name, ctx);
+
+      // Load frontend context for frontend/mobile repos
+      if (repo.role === "frontend" || repo.role === "mobile") {
+        const fctx = await loadFrontendContext(repoAbsPath);
+        frontendContexts.set(repo.name, fctx);
+        console.log(chalk.gray(`  ${repo.name}: ${fctx.framework} / ${fctx.httpClient} / hooks:${fctx.hookFiles.length} stores:${fctx.storeFiles.length}`));
+      } else {
+        console.log(chalk.gray(`  ${repo.name}: ${ctx.techStack.join(", ") || "unknown"} (${ctx.dependencies.length} deps)`));
+      }
+    } catch (err) {
+      console.log(chalk.yellow(`  ${repo.name}: context load failed — ${(err as Error).message}`));
+    }
+  }
+
+  // ── Step 2: Decompose requirement ─────────────────────────────────────────
+  console.log(chalk.blue("\n[W2] Decomposing requirement across repos..."));
+  const decomposer = new RequirementDecomposer(specProvider);
+  let decomposition: DecompositionResult;
+
+  try {
+    decomposition = await decomposer.decompose(idea, workspace, contexts, frontendContexts);
+    console.log(chalk.green(`  Summary: ${decomposition.summary}`));
+    console.log(chalk.gray(`  Repos affected: ${decomposition.repos.map((r) => r.repoName).join(", ")}`));
+    if (decomposition.coordinationNotes) {
+      console.log(chalk.gray(`  Coordination: ${decomposition.coordinationNotes}`));
+    }
+  } catch (err) {
+    console.error(chalk.red(`  Decomposition failed: ${(err as Error).message}`));
+    console.log(chalk.yellow("  Falling back to running all repos independently."));
+    // Fallback: create basic requirements for all repos
+    decomposition = {
+      originalRequirement: idea,
+      summary: idea,
+      coordinationNotes: "",
+      repos: workspace.repos.map((repo) => ({
+        repoName: repo.name,
+        role: repo.role,
+        specIdea: idea,
+        isContractProvider: repo.role === "backend",
+        dependsOnRepos: repo.role !== "backend" ? workspace.repos.filter((r) => r.role === "backend").map((r) => r.name) : [],
+        uxDecisions: null,
+      })),
+    };
+  }
+
+  // ── Step 3: Show decomposition preview + confirmation ─────────────────────
+  if (!opts.auto) {
+    console.log(chalk.cyan("\n[W3] Decomposition Preview:"));
+    console.log(chalk.cyan("─".repeat(52)));
+    for (const r of decomposition.repos) {
+      console.log(chalk.bold(`  ${r.repoName} (${r.role})`));
+      console.log(chalk.gray(`    ${r.specIdea.slice(0, 150)}${r.specIdea.length > 150 ? "..." : ""}`));
+      if (r.uxDecisions) {
+        const ux = r.uxDecisions;
+        const uxSummary = [
+          ux.throttleMs ? `throttle ${ux.throttleMs}ms` : "",
+          ux.debounceMs ? `debounce ${ux.debounceMs}ms` : "",
+          ux.optimisticUpdate ? "optimistic-update" : "",
+          ux.errorRollback ? "rollback" : "",
+        ]
+          .filter(Boolean)
+          .join(", ");
+        if (uxSummary) console.log(chalk.cyan(`    UX: ${uxSummary}`));
+      }
+      if (r.dependsOnRepos.length > 0) {
+        console.log(chalk.gray(`    Depends on: ${r.dependsOnRepos.join(", ")}`));
+      }
+    }
+    console.log(chalk.cyan("─".repeat(52)));
+
+    const gate = await select({
+      message: "Proceed with multi-repo pipeline?",
+      choices: [
+        { name: "Proceed — run all repos", value: "proceed" },
+        { name: "Abort", value: "abort" },
+      ],
+    });
+
+    if (gate === "abort") {
+      console.log(chalk.yellow("  Aborted."));
+      process.exit(0);
+    }
+  }
+
+  // ── Step 4: Sort repos by dependency order ─────────────────────────────────
+  const sortedRepoRequirements = RequirementDecomposer.sortByDependency(decomposition.repos);
+
+  // Contract accumulator: repoName → extracted DSL
+  const contractDsls = new Map<string, SpecDSL>();
+
+  // ── Step 5: Run each repo's pipeline ──────────────────────────────────────
+  console.log(chalk.blue(`\n[W4] Running pipeline for ${sortedRepoRequirements.length} repo(s)...`));
+
+  const results: Array<{
+    repoName: string;
+    status: "success" | "failed" | "skipped";
+    specFile: string | null;
+    dsl: SpecDSL | null;
+  }> = [];
+
+  for (const repoReq of sortedRepoRequirements) {
+    // Find repo config in workspace
+    const repoConfig = workspace.repos.find((r) => r.name === repoReq.repoName);
+    if (!repoConfig) {
+      console.log(chalk.yellow(`  Skipping ${repoReq.repoName} — not found in workspace config.`));
+      results.push({ repoName: repoReq.repoName, status: "skipped", specFile: null, dsl: null });
+      continue;
+    }
+
+    const repoAbsPath = workspaceLoader.resolveAbsPath(repoConfig);
+
+    console.log(chalk.bold.blue(`\n  ── ${repoReq.repoName} (${repoReq.role}) ──────────────────────`));
+
+    // Build contract context from upstream repos
+    let contractContextSection: string | undefined;
+    if (repoReq.dependsOnRepos.length > 0) {
+      const contractParts: string[] = [];
+      for (const depName of repoReq.dependsOnRepos) {
+        const depDsl = contractDsls.get(depName);
+        if (depDsl) {
+          console.log(chalk.gray(`    Using API contract from: ${depName}`));
+          const contract = buildFrontendApiContract(depDsl);
+          contractParts.push(buildContractContextSection(contract));
+        }
+      }
+      if (contractParts.length > 0) {
+        contractContextSection = contractParts.join("\n\n");
+      }
+    }
+
+    // For frontend repos, also load frontend context and inject UX decisions
+    let specIdea = repoReq.specIdea;
+    if (
+      (repoReq.role === "frontend" || repoReq.role === "mobile") &&
+      repoReq.uxDecisions
+    ) {
+      const frontendCtx = await loadFrontendContext(repoAbsPath);
+      const frontendCtxSection = buildFrontendContextSection(frontendCtx);
+
+      specIdea = buildFrontendSpecPrompt({
+        specIdea: repoReq.specIdea,
+        apiContractSection: contractContextSection,
+        uxDecisions: repoReq.uxDecisions,
+        frontendContext: frontendCtx,
+      });
+
+      // contractContextSection is already injected via buildFrontendSpecPrompt
+      contractContextSection = undefined;
+
+      console.log(chalk.gray(`    Frontend context: ${frontendCtx.framework} / ${frontendCtx.httpClient} / ${frontendCtx.uiLibrary}`));
+    }
+
+    try {
+      const { dsl, specFile } = await runSingleRepoPipelineInWorkspace({
+        idea: specIdea,
+        specProvider,
+        specProviderName,
+        specModelName,
+        codegenProvider,
+        codegenMode,
+        repoAbsPath,
+        repoName: repoReq.repoName,
+        cliOpts: opts,
+        contractContextSection,
+      });
+
+      // Store DSL for downstream repos if this is a contract provider
+      if (repoReq.isContractProvider && dsl) {
+        contractDsls.set(repoReq.repoName, dsl);
+        console.log(chalk.green(`    Contract stored for downstream repos.`));
+      }
+
+      results.push({ repoName: repoReq.repoName, status: "success", specFile, dsl });
+      console.log(chalk.green(`  ✔ ${repoReq.repoName} complete`));
+    } catch (err) {
+      console.error(chalk.red(`  ✘ ${repoReq.repoName} failed: ${(err as Error).message}`));
+      results.push({ repoName: repoReq.repoName, status: "failed", specFile: null, dsl: null });
+      // Continue — don't abort other repos
+    }
+  }
+
+  // ── Done ──────────────────────────────────────────────────────────────────
+  console.log(chalk.bold.green("\n✔ Multi-repo pipeline complete!"));
+  console.log(chalk.gray(`  Workspace: ${workspace.name}`));
+  console.log(chalk.gray(`  Requirement: ${idea}`));
+  console.log();
+  for (const r of results) {
+    const icon = r.status === "success" ? chalk.green("✔") : r.status === "failed" ? chalk.red("✘") : chalk.gray("−");
+    const specInfo = r.specFile ? chalk.gray(` → ${r.specFile}`) : "";
+    console.log(`  ${icon} ${r.repoName} (${r.status})${specInfo}`);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: workspace
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const workspaceCmd = program
+  .command("workspace")
+  .description("Manage multi-repo workspace configuration");
+
+// workspace init
+workspaceCmd
+  .command("init")
+  .description(`Interactive workspace setup — creates ${WORKSPACE_CONFIG_FILE}`)
+  .action(async () => {
+    const currentDir = process.cwd();
+    const configPath = path.join(currentDir, WORKSPACE_CONFIG_FILE);
+
+    if (await fs.pathExists(configPath)) {
+      const overwrite = await confirm({
+        message: `${WORKSPACE_CONFIG_FILE} already exists. Overwrite?`,
+        default: false,
+      });
+      if (!overwrite) {
+        console.log(chalk.gray("  Cancelled."));
+        return;
+      }
+    }
+
+    console.log(chalk.blue("\n─── Workspace Setup ────────────────────────────"));
+
+    const workspaceName = await input({
+      message: "Workspace name:",
+      validate: (v) => v.trim().length > 0 || "Name cannot be empty",
+    });
+
+    const repos: RepoConfig[] = [];
+
+    // ── Auto-scan option ──────────────────────────────────────────────────────
+    const useAutoScan = await confirm({
+      message: "Auto-scan sibling directories for repos?",
+      default: true,
+    });
+
+    if (useAutoScan) {
+      const workspaceLoader = new WorkspaceLoader(currentDir);
+      const detected = await workspaceLoader.autoDetect();
+
+      if (detected.length === 0) {
+        console.log(chalk.yellow("  No recognizable repos found in sibling directories."));
+      } else {
+        console.log(chalk.cyan("\n  Detected repos:"));
+        for (const r of detected) {
+          console.log(chalk.gray(`    - ${r.name}: ${r.role} (${r.type}) at ${r.path}`));
+        }
+
+        const keepAll = await confirm({
+          message: `Include all ${detected.length} detected repo(s)?`,
+          default: true,
+        });
+
+        if (keepAll) {
+          repos.push(...detected);
+        } else {
+          // Let user cherry-pick
+          for (const r of detected) {
+            const keep = await confirm({
+              message: `Include "${r.name}" (${r.role}, ${r.type})?`,
+              default: true,
+            });
+            if (keep) repos.push(r);
+          }
+        }
+        console.log(chalk.green(`  ✔ ${repos.length} repo(s) added from auto-scan.`));
+      }
+    }
+
+    // ── Manual add (always offered after auto-scan) ───────────────────────────
+    const repoTypeChoices = [
+      { name: "node-express (Node.js/Express backend)", value: "node-express" },
+      { name: "node-koa (Node.js/Koa backend)", value: "node-koa" },
+      { name: "go (Go backend)", value: "go" },
+      { name: "python (Python backend)", value: "python" },
+      { name: "java (Java/Spring backend)", value: "java" },
+      { name: "rust (Rust backend)", value: "rust" },
+      { name: "php (PHP/Lumen/Laravel backend)", value: "php" },
+      { name: "react (React frontend)", value: "react" },
+      { name: "next (Next.js)", value: "next" },
+      { name: "vue (Vue frontend)", value: "vue" },
+      { name: "react-native (React Native mobile)", value: "react-native" },
+      { name: "unknown", value: "unknown" },
+    ];
+
+    let addMore = await confirm({
+      message: repos.length > 0 ? "Manually add more repos?" : "Add repos manually?",
+      default: repos.length === 0,
+    });
+
+    while (addMore) {
+      console.log(chalk.cyan(`\n  Adding repo #${repos.length + 1}`));
+
+      const repoName = await input({
+        message: "Repo name (e.g. api, web, app):",
+        validate: (v) => {
+          if (!v.trim()) return "Name cannot be empty";
+          if (repos.some((r) => r.name === v.trim())) return "Name already used";
+          return true;
+        },
+      });
+
+      const repoPath = await input({
+        message: `Relative path to "${repoName}" from here (default: ./${repoName}):`,
+        default: `./${repoName}`,
+      });
+
+      // Try to auto-detect type
+      const absPath = path.resolve(currentDir, repoPath);
+      let detectedType = "unknown";
+      let detectedRole = "shared";
+
+      if (await fs.pathExists(absPath)) {
+        const { type, role } = await detectRepoType(absPath);
+        detectedType = type;
+        detectedRole = role;
+        console.log(chalk.gray(`    Auto-detected: type=${type}, role=${role}`));
+      } else {
+        console.log(chalk.yellow(`    Path "${absPath}" not found — type/role will be manual.`));
+      }
+
+      const repoType = await select({
+        message: `Repo type for "${repoName}":`,
+        choices: repoTypeChoices,
+        default: detectedType,
+      });
+
+      const repoRole = await select({
+        message: `Repo role for "${repoName}":`,
+        choices: [
+          { name: "backend", value: "backend" },
+          { name: "frontend", value: "frontend" },
+          { name: "mobile", value: "mobile" },
+          { name: "shared", value: "shared" },
+        ],
+        default: detectedRole,
+      });
+
+      repos.push({
+        name: repoName,
+        path: repoPath,
+        type: repoType as RepoConfig["type"],
+        role: repoRole as RepoConfig["role"],
+      });
+
+      console.log(chalk.green(`  ✔ Added: ${repoName} (${repoRole}, ${repoType})`));
+
+      addMore = await confirm({
+        message: "Add another repo?",
+        default: false,
+      });
+    }
+
+    const workspaceConfig: WorkspaceConfig = { name: workspaceName, repos };
+
+    // Show summary
+    console.log(chalk.cyan("\n  Workspace summary:"));
+    console.log(chalk.gray(`  Name: ${workspaceName}`));
+    for (const r of repos) {
+      console.log(chalk.gray(`  - ${r.name}: ${r.role} (${r.type}) at ${r.path}`));
+    }
+
+    const ok = await confirm({ message: `Save to ${WORKSPACE_CONFIG_FILE}?`, default: true });
+    if (!ok) {
+      console.log(chalk.gray("  Cancelled."));
+      return;
+    }
+
+    const loader = new WorkspaceLoader(currentDir);
+    const saved = await loader.save(workspaceConfig);
+    console.log(chalk.green(`\n  ✔ Workspace saved: ${saved}`));
+    console.log(chalk.gray(`  Run \`ai-spec create "your feature"\` — workspace mode will activate automatically.`));
+  });
+
+// workspace status
+workspaceCmd
+  .command("status")
+  .description("Show current workspace configuration")
+  .action(async () => {
+    const currentDir = process.cwd();
+    const loader = new WorkspaceLoader(currentDir);
+    const config = await loader.load();
+
+    if (!config) {
+      console.log(chalk.yellow(`No ${WORKSPACE_CONFIG_FILE} found in ${currentDir}`));
+      console.log(chalk.gray("  Run `ai-spec workspace init` to create one."));
+      return;
+    }
+
+    console.log(chalk.bold(`\nWorkspace: ${config.name}`));
+    console.log(chalk.gray(`  Config: ${path.join(currentDir, WORKSPACE_CONFIG_FILE)}`));
+    console.log(chalk.gray(`  Repos (${config.repos.length}):\n`));
+
+    for (const repo of config.repos) {
+      const absPath = loader.resolveAbsPath(repo);
+      const exists = await fs.pathExists(absPath);
+      const status = exists ? chalk.green("found") : chalk.red("not found");
+
+      console.log(
+        `  ${chalk.bold(repo.name.padEnd(12))} ${repo.role.padEnd(10)} ${repo.type.padEnd(16)} ${status}`
+      );
+      console.log(chalk.gray(`    path: ${absPath}`));
+      if (repo.constitution) {
+        console.log(chalk.green(`    constitution: found`));
+      }
+    }
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: update  —  Incremental spec + code update pipeline
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("update")
+  .description("Update an existing spec with a change request, re-extract DSL, and identify affected files")
+  .argument("[change]", "Change description (prompted if omitted)")
+  .option("--provider <name>", `AI provider (${SUPPORTED_PROVIDERS.join("|")})`, undefined)
+  .option("--model <name>", "Model name")
+  .option("-k, --key <apiKey>", "API key")
+  .option("--spec <path>", "Path to the existing spec file (auto-detected if omitted)")
+  .option("--codegen", "Regenerate affected files automatically after updating spec")
+  .option("--codegen-provider <name>", "Provider for code generation")
+  .option("--codegen-model <name>", "Model for code generation")
+  .option("--codegen-key <key>", "API key for code generation")
+  .option("--skip-affected", "Skip identifying affected files")
+  .action(async (change: string | undefined, opts) => {
+    const currentDir = process.cwd();
+    const config = await loadConfig(currentDir);
+
+    // ── Resolve change ────────────────────────────────────────────────────────
+    if (!change) {
+      change = await input({
+        message: "Describe the change you want to make:",
+        validate: (v) => v.trim().length > 0 || "Change description cannot be empty",
+      });
+    }
+
+    // ── Resolve provider ──────────────────────────────────────────────────────
+    const providerName = opts.provider || config.provider || "gemini";
+    const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
+    const apiKey = await resolveApiKey(providerName, opts.key);
+    const provider = createProvider(providerName, apiKey, modelName);
+
+    console.log(chalk.blue("\n─── ai-spec update ─────────────────────────────"));
+    console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
+
+    // ── Find existing spec ────────────────────────────────────────────────────
+    let specPath: string | null = opts.spec ?? null;
+    if (!specPath) {
+      const specsDir = path.join(currentDir, "specs");
+      const latest = await SpecUpdater.findLatestSpec(specsDir);
+      if (!latest) {
+        console.error(chalk.red("  No spec files found in specs/. Run `ai-spec create` first or use --spec <path>."));
+        process.exit(1);
+      }
+      specPath = latest.filePath;
+      console.log(chalk.gray(`  Using spec: ${path.relative(currentDir, specPath)} (v${latest.version})`));
+    }
+
+    // ── Load context ──────────────────────────────────────────────────────────
+    console.log(chalk.gray("  Loading project context..."));
+    const loader = new ContextLoader(currentDir);
+    const context = await loader.loadProjectContext();
+
+    // ── Detect repo type ──────────────────────────────────────────────────────
+    const { detectRepoType: _detectRepoType } = await import("../core/workspace-loader");
+    const { type: repoType } = await _detectRepoType(currentDir);
+
+    // ── Run update ────────────────────────────────────────────────────────────
+    const updater = new SpecUpdater(provider);
+    let result;
+    try {
+      result = await updater.update(change!, specPath, currentDir, context, {
+        skipAffectedFiles: opts.skipAffected,
+        repoType,
+      });
+    } catch (err) {
+      console.error(chalk.red(`  Update failed: ${(err as Error).message}`));
+      process.exit(1);
+    }
+
+    console.log(chalk.green(`\n  ✔ Spec updated → v${result.newVersion}: ${path.relative(currentDir, result.newSpecPath)}`));
+    if (result.newDslPath) {
+      console.log(chalk.green(`  ✔ DSL updated: ${path.relative(currentDir, result.newDslPath)}`));
+    }
+
+    // ── Show affected files ───────────────────────────────────────────────────
+    if (result.affectedFiles.length > 0) {
+      console.log(chalk.cyan("\n  Affected files:"));
+      for (const f of result.affectedFiles) {
+        const icon = f.action === "create" ? chalk.green("+") : chalk.yellow("~");
+        console.log(`    ${icon} ${f.file}: ${chalk.gray(f.description)}`);
+      }
+    }
+
+    // ── Optional: regenerate affected files ───────────────────────────────────
+    if (opts.codegen && result.affectedFiles.length > 0) {
+      const codegenProviderName = opts.codegenProvider || config.codegenProvider || providerName;
+      const codegenModelName = opts.codegenModel || config.codegenModel || DEFAULT_MODELS[codegenProviderName];
+      const codegenApiKey = opts.codegenKey ?? (codegenProviderName === providerName ? apiKey : await resolveApiKey(codegenProviderName, opts.codegenKey));
+      const codegenProvider = createProvider(codegenProviderName, codegenApiKey, codegenModelName);
+
+      console.log(chalk.blue("\n  Regenerating affected files..."));
+      const codeGenerator = new CodeGenerator(codegenProvider, "api");
+
+      const specContent = await fs.readFile(result.newSpecPath, "utf-8");
+      const constitutionSection = context.constitution
+        ? `\n=== Project Constitution (MUST follow) ===\n${context.constitution.slice(0, 2000)}\n`
+        : "";
+      const dslSection = result.updatedDsl
+        ? `\n=== DSL Context ===\n${JSON.stringify(result.updatedDsl, null, 2).slice(0, 3000)}\n`
+        : "";
+
+      for (const affected of result.affectedFiles) {
+        const fullPath = path.join(currentDir, affected.file);
+        let existing = "";
+        try { existing = await fs.readFile(fullPath, "utf-8"); } catch { /* new file */ }
+
+        const codePrompt = `Apply this change to the file.
+
+Change: ${change}
+File: ${affected.file}
+Purpose: ${affected.description}
+
+=== Feature Spec (updated) ===
+${specContent}
+${constitutionSection}${dslSection}
+=== ${existing ? "Current File (return the FULL updated content)" : "New File"} ===
+${existing || "Create from scratch."}`;
+
+        process.stdout.write(`  ${existing ? chalk.yellow("~") : chalk.green("+")} ${affected.file}... `);
+        try {
+          const { getCodeGenSystemPrompt: _getPrompt } = await import("../prompts/codegen.prompt");
+          const raw = await codegenProvider.generate(codePrompt, _getPrompt(repoType));
+          const content = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
+          await fs.ensureDir(path.dirname(fullPath));
+          await fs.writeFile(fullPath, content, "utf-8");
+          console.log(chalk.green("✔"));
+        } catch (err) {
+          console.log(chalk.red(`✘ ${(err as Error).message}`));
+        }
+      }
+    }
+
+    // ── Hints ─────────────────────────────────────────────────────────────────
+    if (!opts.codegen && result.affectedFiles.length > 0) {
+      console.log(chalk.blue("\n  Next steps:"));
+      console.log(chalk.gray(`  • Re-run with --codegen to regenerate affected files automatically`));
+      console.log(chalk.gray(`  • Or update files manually based on the affected files list above`));
+      console.log(chalk.gray(`  • Run \`ai-spec mock\` to refresh the mock server with the new DSL`));
+    }
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: export  —  Export DSL to OpenAPI / other formats
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("export")
+  .description("Export the latest DSL to OpenAPI 3.1.0 (YAML or JSON)")
+  .option("--openapi", "Export as OpenAPI 3.1.0 (default behaviour)")
+  .option("--format <fmt>", "Output format: yaml | json (default: yaml)", "yaml")
+  .option("--output <path>", "Output file path (default: openapi.yaml)")
+  .option("--server <url>", "API server URL in the OpenAPI document (default: http://localhost:3000)")
+  .option("--dsl <path>", "Path to a specific .dsl.json file (auto-detected if omitted)")
+  .action(async (opts) => {
+    const currentDir = process.cwd();
+
+    // ── Find DSL ──────────────────────────────────────────────────────────────
+    let dslPath: string | null = opts.dsl ?? null;
+    if (!dslPath) {
+      dslPath = await findLatestDslFile(currentDir);
+      if (!dslPath) {
+        console.error(chalk.red("  No .dsl.json file found. Run `ai-spec create` first or use --dsl <path>."));
+        process.exit(1);
+      }
+      console.log(chalk.gray(`  Using DSL: ${path.relative(currentDir, dslPath)}`));
+    }
+
+    let dsl: SpecDSL;
+    try {
+      dsl = await fs.readJson(dslPath);
+    } catch (err) {
+      console.error(chalk.red(`  Failed to read DSL: ${(err as Error).message}`));
+      process.exit(1);
+    }
+
+    // ── Export ────────────────────────────────────────────────────────────────
+    console.log(chalk.blue("\n─── ai-spec export ─────────────────────────────"));
+
+    const format = (opts.format === "json" ? "json" : "yaml") as "yaml" | "json";
+    const serverUrl = opts.server || "http://localhost:3000";
+
+    try {
+      const outputPath = await exportOpenApi(dsl, currentDir, {
+        format,
+        serverUrl,
+        outputPath: opts.output,
+      });
+      const rel = path.relative(currentDir, outputPath);
+      console.log(chalk.green(`  ✔ OpenAPI ${format.toUpperCase()} exported: ${rel}`));
+      console.log(chalk.gray(`  Feature  : ${dsl.feature.title}`));
+      console.log(chalk.gray(`  Endpoints: ${dsl.endpoints.length}`));
+      console.log(chalk.gray(`  Models   : ${dsl.models.length}`));
+      console.log(chalk.gray(`  Server   : ${serverUrl}`));
+      console.log(chalk.blue("\n  Next steps:"));
+      console.log(chalk.gray(`  • Import ${rel} into Postman / Insomnia / Swagger UI`));
+      console.log(chalk.gray(`  • Use openapi-generator to generate client SDKs`));
+    } catch (err) {
+      console.error(chalk.red(`  Export failed: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: mock  —  Generate mock server, proxy config, and MSW handlers from DSL
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("mock")
+  .description("Generate a standalone mock server + proxy config from the latest DSL")
+  .option("--port <n>", "Mock server port (default: 3001)", "3001")
+  .option("--msw", "Also generate MSW (Mock Service Worker) handlers at src/mocks/")
+  .option("--proxy", "Also generate frontend proxy config snippet")
+  .option("--dsl <path>", "Path to a specific .dsl.json file (auto-detected if omitted)")
+  .option(
+    "--workspace",
+    "Generate mock assets for all backend repos in the workspace"
+  )
+  .action(async (opts) => {
+    const currentDir = process.cwd();
+    const port = parseInt(opts.port, 10) || 3001;
+
+    console.log(chalk.blue("\n─── ai-spec mock ───────────────────────────────"));
+
+    // ── Workspace mode ────────────────────────────────────────────────────────
+    if (opts.workspace) {
+      const workspaceLoader = new WorkspaceLoader(currentDir);
+      const workspaceConfig = await workspaceLoader.load();
+      if (!workspaceConfig) {
+        console.error(chalk.red(`  No ${WORKSPACE_CONFIG_FILE} found. Run \`ai-spec workspace init\` first.`));
+        process.exit(1);
+      }
+
+      const backendRepos = workspaceConfig.repos.filter((r) => r.role === "backend");
+      if (backendRepos.length === 0) {
+        console.log(chalk.yellow("  No backend repos found in workspace."));
+        return;
+      }
+
+      for (const repo of backendRepos) {
+        const repoAbsPath = workspaceLoader.resolveAbsPath(repo);
+        console.log(chalk.cyan(`\n  Repo: ${repo.name} (${repoAbsPath})`));
+
+        const dslFile = await findLatestDslFile(repoAbsPath);
+        if (!dslFile) {
+          console.log(chalk.yellow(`    No DSL file found — skipping.`));
+          continue;
+        }
+
+        const dsl: SpecDSL = await fs.readJson(dslFile);
+        const result = await generateMockAssets(dsl, repoAbsPath, {
+          port,
+          msw: opts.msw,
+          proxy: opts.proxy,
+        });
+
+        for (const f of result.files) {
+          console.log(chalk.green(`    ✔ ${f.path}`));
+          console.log(chalk.gray(`      ${f.description}`));
+        }
+      }
+      return;
+    }
+
+    // ── Single-repo mode ──────────────────────────────────────────────────────
+    let dslPath: string | null = opts.dsl ?? null;
+
+    if (!dslPath) {
+      dslPath = await findLatestDslFile(currentDir);
+      if (!dslPath) {
+        console.error(
+          chalk.red(
+            "  No .dsl.json file found in .ai-spec/. Run `ai-spec create` first or use --dsl <path>."
+          )
+        );
+        process.exit(1);
+      }
+      console.log(chalk.gray(`  Using DSL: ${path.relative(currentDir, dslPath)}`));
+    }
+
+    let dsl: SpecDSL;
+    try {
+      dsl = await fs.readJson(dslPath);
+    } catch (err) {
+      console.error(chalk.red(`  Failed to read DSL file: ${(err as Error).message}`));
+      process.exit(1);
+    }
+
+    const result = await generateMockAssets(dsl, currentDir, {
+      port,
+      msw: opts.msw,
+      proxy: opts.proxy,
+    });
+
+    console.log(chalk.green(`\n  ✔ Mock assets generated (${result.files.length} file(s)):`));
+    for (const f of result.files) {
+      console.log(chalk.green(`    ${f.path}`));
+      console.log(chalk.gray(`      ${f.description}`));
+    }
+
+    console.log(chalk.blue("\n─── Quick start ────────────────────────────────"));
+    console.log(chalk.white(`  1. Install express (if not already):`));
+    console.log(chalk.gray(`       npm install --save-dev express`));
+    console.log(chalk.white(`  2. Start mock server:`));
+    console.log(chalk.gray(`       node mock/server.js`));
+    console.log(chalk.white(`  3. Configure your frontend to proxy API calls to:`));
+    console.log(chalk.gray(`       http://localhost:${port}`));
+    if (opts.proxy) {
+      console.log(chalk.gray(`     (See the generated proxy config file for framework-specific instructions)`));
+    }
+    if (opts.msw) {
+      console.log(chalk.white(`  4. MSW: import and start the worker in your app entry:`));
+      console.log(chalk.gray(`       import { worker } from './mocks/browser';`));
+      console.log(chalk.gray(`       if (process.env.NODE_ENV === 'development') worker.start();`));
+    }
+  });
+
+// Show welcome screen when invoked with no arguments
+if (process.argv.length <= 2) {
+  (async () => {
+    const currentDir = process.cwd();
+    const config = await loadConfig(currentDir);
+    await printWelcome(currentDir, config);
+  })();
+} else {
+  program.parse();
+}