@specmarket/cli 0.0.4 → 0.0.6

package/dist/index.js

@@ -2,16 +2,22 @@
 import {
   CONFIG_PATHS,
   DEFAULT_CONVEX_URL,
+  DEFAULT_HARNESS,
+  DEFAULT_WEB_URL,
   EXIT_CODES,
+  KNOWN_HARNESSES,
+  MODEL_COST_PER_TOKEN,
   REQUIRED_SPEC_FILES,
   REQUIRED_STDLIB_FILES,
   RUN_DEFAULTS,
+  SIDECAR_FILENAME,
   TOKEN_EXPIRY_MS,
   loadConfig,
   saveConfig,
   specYamlSchema,
+  specmarketSidecarSchema,
   transformInfrastructure
-} from "./chunk-MS2DYACY.js";
+} from "./chunk-OTXWWFAO.js";
 import {
   api
 } from "./chunk-JEUDDJP7.js";
@@ -97,6 +103,11 @@ var debug2 = createDebug2("specmarket:convex");
 async function getConvexClient(token) {
   const config = await loadConfig();
   const url = process.env["CONVEX_URL"] ?? config.convexUrl ?? DEFAULT_CONVEX_URL;
+  if (url.includes("placeholder.convex.cloud")) {
+    throw new Error(
+      "CONVEX_URL is not configured. Set the CONVEX_URL environment variable or run `specmarket config set convexUrl <url>`."
+    );
+  }
   debug2("Creating Convex client for URL: %s", url);
   const client = new ConvexHttpClient(url);
   if (token) {
@@ -162,9 +173,7 @@ async function handleTokenLogin(token) {
   }
 }
 async function handleDeviceCodeLogin() {
-  const config = await import("./config-R5KWZSJP.js").then((m) => m.loadConfig());
-  const baseUrl = config.convexUrl ?? process.env["CONVEX_URL"] ?? "https://your-deployment.convex.cloud";
-  const webUrl = baseUrl.replace("convex.cloud", "specmarket.dev");
+  const webUrl = DEFAULT_WEB_URL;
   const client = await getConvexClient();
   let api2;
   try {
@@ -339,10 +348,177 @@ function createWhoamiCommand() {
 import { Command as Command4 } from "commander";
 import chalk4 from "chalk";
 import ora2 from "ora";
-import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
-import { join as join2, resolve } from "path";
+import { mkdir as mkdir2, writeFile as writeFile2, readdir as readdir2 } from "fs/promises";
+import { join as join3, resolve, basename } from "path";
 import createDebug4 from "debug";
+
+// src/lib/format-detection.ts
+import { readFile as readFile2, readdir, access } from "fs/promises";
+import { join as join2 } from "path";
+import { parse as parseYaml } from "yaml";
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function directoryExists(dirPath) {
+  try {
+    await access(dirPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function hasStoryFiles(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.some(
+      (e) => e.isFile() && e.name.startsWith("story-") && e.name.endsWith(".md")
+    );
+  } catch {
+    return false;
+  }
+}
+async function hasMarkdownFiles(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".md")) return true;
+      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+        const found = await hasMarkdownFiles(join2(dir, entry.name));
+        if (found) return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+async function tryReadSidecar(dir) {
+  const path = join2(dir, SIDECAR_FILENAME);
+  if (!await fileExists(path)) return null;
+  try {
+    const raw = await readFile2(path, "utf-8");
+    const parsed = parseYaml(raw);
+    if (parsed && typeof parsed === "object" && "spec_format" in parsed) {
+      const fmt = parsed.spec_format;
+      if (typeof fmt === "string" && fmt.length > 0) return { spec_format: fmt };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function detectSpecFormat(dir) {
+  const sidecar = await tryReadSidecar(dir);
+  if (sidecar) {
+    return {
+      format: sidecar.spec_format,
+      detectedBy: "sidecar",
+      confidence: "high"
+    };
+  }
+  const hasSpecYaml = await fileExists(join2(dir, "spec.yaml"));
+  const hasPromptMd = await fileExists(join2(dir, "PROMPT.md"));
+  const hasSuccessCriteria = await fileExists(join2(dir, "SUCCESS_CRITERIA.md"));
+  if (hasSpecYaml && hasPromptMd && hasSuccessCriteria) {
+    return {
+      format: "specmarket",
+      detectedBy: "heuristic",
+      confidence: "high"
+    };
+  }
+  if (hasPromptMd && hasSuccessCriteria) {
+    return {
+      format: "specmarket",
+      detectedBy: "heuristic",
+      confidence: "high"
+    };
+  }
+  const hasSpecMd = await fileExists(join2(dir, "spec.md"));
+  const hasPlanMd = await fileExists(join2(dir, "plan.md"));
+  const hasTasksMd = await fileExists(join2(dir, "tasks.md"));
+  if (hasSpecMd && (hasPlanMd || hasTasksMd)) {
+    return {
+      format: "speckit",
+      detectedBy: "heuristic",
+      confidence: "high"
+    };
+  }
+  if (hasSpecMd) {
+    return {
+      format: "speckit",
+      detectedBy: "heuristic",
+      confidence: "high"
+    };
+  }
+  const hasPrdMd = await fileExists(join2(dir, "prd.md"));
+  const hasArchitectureMd = await fileExists(join2(dir, "architecture.md"));
+  const storyFiles = await hasStoryFiles(dir);
+  if (hasPrdMd && (hasArchitectureMd || storyFiles)) {
+    return {
+      format: "bmad",
+      detectedBy: "heuristic",
+      confidence: "high"
+    };
+  }
+  const prdJsonPath = join2(dir, "prd.json");
+  if (await fileExists(prdJsonPath)) {
+    try {
+      const raw = await readFile2(prdJsonPath, "utf-8");
+      const data = JSON.parse(raw);
+      if (data && typeof data === "object") {
+        return {
+          format: "ralph",
+          detectedBy: "heuristic",
+          confidence: "high"
+        };
+      }
+    } catch {
+    }
+  }
+  if (await hasMarkdownFiles(dir)) {
+    return {
+      format: "custom",
+      detectedBy: "heuristic",
+      confidence: "low"
+    };
+  }
+  return {
+    format: "custom",
+    detectedBy: "heuristic",
+    confidence: "low"
+  };
+}
+
+// src/commands/init.ts
 var debug4 = createDebug4("specmarket:cli");
+function buildSpecmarketYaml(data) {
+  return `# SpecMarket metadata (required for validate/publish)
+# Single source of truth for format and marketplace fields.
+# Your existing spec files (Spec Kit, BMAD, Ralph, etc.) are not modified.
+
+spec_format: ${data.specFormat}
+display_name: "${data.displayName.replace(/"/g, '\\"')}"
+description: "${data.description.replace(/"/g, '\\"')}"
+output_type: ${data.outputType}
+primary_stack: ${data.primaryStack}
+${data.replacesSaas ? `replaces_saas: "${data.replacesSaas.replace(/"/g, '\\"')}"` : '# replaces_saas: "ProductName"'}
+# replaces_pricing: "$0-16/mo"
+tags: []
+estimated_tokens: 50000
+estimated_cost_usd: 2.50
+estimated_time_minutes: 30
+`;
+}
+var SPECMARKET_YAML_TEMPLATE = (data) => buildSpecmarketYaml({
+  ...data,
+  specFormat: "specmarket",
+  description: `A ${data.outputType} spec${data.replacesSaas ? ` that replaces ${data.replacesSaas}` : ""}.`
+});
 var SPEC_YAML_TEMPLATE = (data) => `# SpecMarket Spec Configuration
 # See: https://specmarket.dev/docs/spec-yaml
 
@@ -355,7 +531,7 @@ ${data.replacesSaas ? `replaces_saas: "${data.replacesSaas}"` : '# replaces_saas
 output_type: ${data.outputType}
 primary_stack: ${data.primaryStack}
 version: "1.0.0"
-runner: claude-code
+runner: claude
 min_model: "claude-opus-4-5"
 
 estimated_tokens: 50000
@@ -399,9 +575,9 @@ Read the requirements in SPEC.md and implement the application step by step.
 ## Process
 
 1. Read SPEC.md completely before writing any code
-2. Check fix_plan.md for outstanding items
+2. Check TASKS.md for outstanding items
 3. Implement features, run tests, iterate
-4. Update fix_plan.md as you complete items
+4. Update TASKS.md as you complete items
 5. Verify SUCCESS_CRITERIA.md criteria are met
 
 ## Rules
@@ -409,7 +585,7 @@ Read the requirements in SPEC.md and implement the application step by step.
 - Follow stdlib/STACK.md for technology choices
 - Write tests for all business logic
 - Do not skip steps or take shortcuts
-- Update fix_plan.md after each significant change
+- Update TASKS.md after each significant change
 `;
 var SPEC_MD_TEMPLATE = (data) => `# ${data.displayName} \u2014 Specification
 
@@ -468,12 +644,12 @@ ${primaryStack}
 - Vitest for unit tests
 - Playwright for E2E (optional)
 `;
-var FIX_PLAN_TEMPLATE = (displayName) => `# Fix Plan
+var TASKS_MD_TEMPLATE = (displayName) => `# Tasks
 
 > This file tracks outstanding work. Update it after each change.
-> Empty = implementation complete.
+> All items checked = implementation complete.
 
-## ${displayName} \u2014 Initial Implementation
+## Phase 1: ${displayName} \u2014 Initial Implementation
 
 - [ ] Set up project structure and dependencies
 - [ ] Implement core data model
@@ -482,9 +658,217 @@ var FIX_PLAN_TEMPLATE = (displayName) => `# Fix Plan
 - [ ] Implement UI/interface
 - [ ] Write integration tests
 - [ ] Update README.md
+
+## Discovered Issues
 `;
+async function promptMetadataOnly(defaultDisplayName) {
+  const { default: inquirer } = await import("inquirer");
+  const answers = await inquirer.prompt([
+    {
+      type: "input",
+      name: "displayName",
+      message: "Display name for the marketplace:",
+      default: defaultDisplayName ?? "My Spec"
+    },
+    {
+      type: "input",
+      name: "description",
+      message: "Short description (min 10 characters):",
+      default: "A spec ready to validate and publish on SpecMarket.",
+      validate: (v) => v.length >= 10 ? true : "Description must be at least 10 characters"
+    },
+    {
+      type: "input",
+      name: "replacesSaas",
+      message: "What SaaS product does this replace? (optional, Enter to skip):",
+      default: ""
+    },
+    {
+      type: "list",
+      name: "outputType",
+      message: "Output type:",
+      choices: [
+        { name: "Web Application", value: "web-app" },
+        { name: "CLI Tool", value: "cli-tool" },
+        { name: "API Service", value: "api-service" },
+        { name: "Library/Package", value: "library" },
+        { name: "Mobile App", value: "mobile-app" }
+      ]
+    },
+    {
+      type: "list",
+      name: "primaryStack",
+      message: "Primary stack:",
+      choices: [
+        { name: "Next.js + TypeScript", value: "nextjs-typescript" },
+        { name: "Astro + TypeScript", value: "astro-typescript" },
+        { name: "Python + FastAPI", value: "python-fastapi" },
+        { name: "Go", value: "go" },
+        { name: "Rust", value: "rust" },
+        { name: "Other", value: "other" }
+      ]
+    }
+  ]);
+  return {
+    displayName: answers.displayName,
+    description: answers.description,
+    replacesSaas: answers.replacesSaas || void 0,
+    outputType: answers.outputType,
+    primaryStack: answers.primaryStack
+  };
+}
+async function dirHasFiles(dir) {
+  try {
+    const entries = await readdir2(dir, { withFileTypes: true });
+    return entries.some((e) => e.isFile());
+  } catch {
+    return false;
+  }
+}
 async function handleInit(opts) {
   const { default: inquirer } = await import("inquirer");
+  if (opts.from !== void 0 && opts.from !== "") {
+    const targetDir2 = resolve(opts.from);
+    const dirExists = await directoryExists(targetDir2);
+    if (!dirExists) {
+      console.error(chalk4.red(`Directory not found: ${targetDir2}`));
+      console.error(chalk4.gray("--from requires an existing spec directory. Run specmarket init (no flags) to create a new spec from scratch."));
+      process.exit(EXIT_CODES.INVALID_SPEC);
+    }
+    const hasAnyFiles = await dirHasFiles(targetDir2);
+    if (!hasAnyFiles) {
+      console.error(chalk4.red(`Directory is empty: ${targetDir2}`));
+      console.error(chalk4.gray("--from requires a directory with spec files (Spec Kit, BMAD, Ralph, or custom markdown). Run specmarket init to create a new spec."));
+      process.exit(EXIT_CODES.INVALID_SPEC);
+    }
+    const sidecarPath = join3(targetDir2, SIDECAR_FILENAME);
+    if (await fileExists(sidecarPath)) {
+      console.log(chalk4.yellow(`${SIDECAR_FILENAME} already exists in this directory.`));
+      console.log(chalk4.gray("Run specmarket validate to check your spec, then specmarket publish to publish."));
+      return;
+    }
+    const detection = await detectSpecFormat(targetDir2);
+    const formatLabel = detection.format === "specmarket" ? "SpecMarket (spec.yaml + PROMPT.md + \u2026)" : detection.format === "speckit" ? "Spec Kit" : detection.format === "bmad" ? "BMAD" : detection.format === "ralph" ? "Ralph" : "custom markdown";
+    console.log(chalk4.gray(`Detected ${formatLabel} spec. Adding SpecMarket metadata only; your files will not be modified.`));
+    console.log("");
+    const metadata = await promptMetadataOnly(basename(targetDir2));
+    const yaml = buildSpecmarketYaml({ ...metadata, specFormat: detection.format });
+    await writeFile2(sidecarPath, yaml);
+    console.log("");
+    console.log(chalk4.green(`Added ${SIDECAR_FILENAME} to ${targetDir2}`));
+    console.log("");
+    console.log(chalk4.bold("Next steps:"));
+    console.log(`  1. Run ${chalk4.cyan("specmarket validate")} to check your spec`);
+    console.log(`  2. Run ${chalk4.cyan("specmarket publish")} to publish to the marketplace`);
+    console.log(`  3. Run ${chalk4.cyan("specmarket run")} to execute the spec locally`);
+    return;
+  }
+  if (opts.path !== void 0 && opts.path !== "") {
+    const targetDir2 = resolve(opts.path);
+    await mkdir2(targetDir2, { recursive: true });
+    const sidecarPath = join3(targetDir2, SIDECAR_FILENAME);
+    if (await fileExists(sidecarPath)) {
+      console.log(chalk4.yellow(`${SIDECAR_FILENAME} already exists in this directory.`));
+      console.log(chalk4.gray("Run specmarket validate to check your spec, then specmarket publish to publish."));
+      return;
+    }
+    const detection = await detectSpecFormat(targetDir2);
+    const hasAnyFiles = await dirHasFiles(targetDir2);
+    if (hasAnyFiles && detection.format !== "custom") {
+      const formatLabel = detection.format === "specmarket" ? "SpecMarket (spec.yaml + PROMPT.md + \u2026)" : detection.format === "speckit" ? "Spec Kit" : detection.format === "bmad" ? "BMAD" : detection.format === "ralph" ? "Ralph" : detection.format;
+      console.log(chalk4.gray(`Detected ${formatLabel} spec. Adding SpecMarket metadata only; your files will not be modified.`));
+      console.log("");
+      const metadata = await promptMetadataOnly(basename(targetDir2));
+      const yaml = buildSpecmarketYaml({
+        ...metadata,
+        specFormat: detection.format
+      });
+      await writeFile2(sidecarPath, yaml);
+      console.log("");
+      console.log(chalk4.green(`Added ${SIDECAR_FILENAME} to ${targetDir2}`));
+      console.log("");
+      console.log(chalk4.bold("Next steps:"));
+      console.log(`  1. Run ${chalk4.cyan("specmarket validate")} to check your spec`);
+      console.log(`  2. Run ${chalk4.cyan("specmarket publish")} to publish to the marketplace`);
+      console.log(`  3. Run ${chalk4.cyan("specmarket run")} to execute the spec locally`);
+      return;
+    }
+    if (hasAnyFiles && detection.format === "custom") {
+      console.log(chalk4.gray("Detected markdown spec. Adding SpecMarket metadata only; your files will not be modified."));
+      console.log("");
+      const metadata = await promptMetadataOnly(basename(targetDir2));
+      const yaml = buildSpecmarketYaml({
+        ...metadata,
+        specFormat: "custom"
+      });
+      await writeFile2(sidecarPath, yaml);
+      console.log("");
+      console.log(chalk4.green(`Added ${SIDECAR_FILENAME} to ${targetDir2}`));
+      console.log("");
+      console.log(chalk4.bold("Next steps:"));
+      console.log(`  1. Run ${chalk4.cyan("specmarket validate")} to check your spec`);
+      console.log(`  2. Run ${chalk4.cyan("specmarket publish")} to publish to the marketplace`);
+      return;
+    }
+    console.log(chalk4.gray("Directory is empty or has no recognized spec format."));
+    const { createNew } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "createNew",
+        message: "Create a new SpecMarket spec from scratch here?",
+        default: true
+      }
+    ]);
+    if (!createNew) {
+      console.log(chalk4.gray("Exiting. Add spec files (e.g. Spec Kit, BMAD) and run specmarket init -p . again."));
+      return;
+    }
+    const spinner2 = ora2(`Creating spec at ${targetDir2}...`).start();
+    const fullAnswers = await inquirer.prompt([
+      { type: "input", name: "name", message: "Spec name (lowercase, hyphens only):", default: opts.name ?? (basename(targetDir2) || "my-spec"), validate: (v) => /^[a-z0-9-]+$/.test(v) || "Must be lowercase alphanumeric with hyphens" },
+      { type: "input", name: "displayName", message: "Display name:", default: (a) => a.name.split("-").map((w) => w[0]?.toUpperCase() + w.slice(1)).join(" ") },
+      { type: "input", name: "replacesSaas", message: "What SaaS product does this replace? (optional):", default: "" },
+      { type: "list", name: "outputType", message: "Output type:", choices: [
+        { name: "Web Application", value: "web-app" },
+        { name: "CLI Tool", value: "cli-tool" },
+        { name: "API Service", value: "api-service" },
+        { name: "Library/Package", value: "library" },
+        { name: "Mobile App", value: "mobile-app" }
+      ] },
+      { type: "list", name: "primaryStack", message: "Primary stack:", choices: [
+        { name: "Next.js + TypeScript", value: "nextjs-typescript" },
+        { name: "Astro + TypeScript", value: "astro-typescript" },
+        { name: "Python + FastAPI", value: "python-fastapi" },
+        { name: "Go", value: "go" },
+        { name: "Rust", value: "rust" },
+        { name: "Other", value: "other" }
+      ] }
+    ]);
+    const data = {
+      name: fullAnswers.name,
+      displayName: fullAnswers.displayName,
+      replacesSaas: fullAnswers.replacesSaas || void 0,
+      outputType: fullAnswers.outputType,
+      primaryStack: fullAnswers.primaryStack
+    };
+    await mkdir2(join3(targetDir2, "stdlib"), { recursive: true });
+    await Promise.all([
+      writeFile2(sidecarPath, SPECMARKET_YAML_TEMPLATE(data)),
+      writeFile2(join3(targetDir2, "spec.yaml"), SPEC_YAML_TEMPLATE(data)),
+      writeFile2(join3(targetDir2, "PROMPT.md"), PROMPT_MD_TEMPLATE(data)),
+      writeFile2(join3(targetDir2, "SPEC.md"), SPEC_MD_TEMPLATE(data)),
+      writeFile2(join3(targetDir2, "SUCCESS_CRITERIA.md"), SUCCESS_CRITERIA_TEMPLATE),
+      writeFile2(join3(targetDir2, "stdlib", "STACK.md"), STACK_MD_TEMPLATE(fullAnswers.primaryStack)),
+      writeFile2(join3(targetDir2, "TASKS.md"), TASKS_MD_TEMPLATE(fullAnswers.displayName))
+    ]);
+    spinner2.succeed(chalk4.green(`Spec created at ${targetDir2}`));
+    console.log("");
+    console.log(chalk4.bold("Next steps:"));
+    console.log(`  1. Edit ${chalk4.cyan("SPEC.md")} with your application requirements`);
+    console.log(`  2. Edit ${chalk4.cyan("SUCCESS_CRITERIA.md")} with pass/fail criteria`);
+    console.log(`  3. Run ${chalk4.cyan("specmarket validate")} then ${chalk4.cyan("specmarket run")}`);
+    return;
+  }
   const answers = await inquirer.prompt([
     {
       type: "input",
@@ -497,7 +881,7 @@ async function handleInit(opts) {
       type: "input",
       name: "displayName",
       message: "Display name:",
-      default: (answers2) => answers2.name.split("-").map((w) => w[0]?.toUpperCase() + w.slice(1)).join(" ")
+      default: (ans) => ans.name.split("-").map((w) => w[0]?.toUpperCase() + w.slice(1)).join(" ")
     },
     {
       type: "input",
@@ -531,11 +915,40 @@ async function handleInit(opts) {
       ]
     }
   ]);
-  const targetDir = resolve(opts.path ?? answers.name);
+  const targetDir = resolve(answers.name);
   const spinner = ora2(`Creating spec directory at ${targetDir}...`).start();
   try {
     await mkdir2(targetDir, { recursive: true });
-    await mkdir2(join2(targetDir, "stdlib"), { recursive: true });
+    const sidecarPath = join3(targetDir, SIDECAR_FILENAME);
+    if (await fileExists(sidecarPath)) {
+      spinner.stop();
+      console.log(chalk4.yellow(`${SIDECAR_FILENAME} already exists in ${targetDir}.`));
+      console.log(chalk4.gray("Run specmarket validate to check your spec, then specmarket publish to publish."));
+      return;
+    }
+    const hasFiles = await dirHasFiles(targetDir);
+    if (hasFiles) {
+      const detection = await detectSpecFormat(targetDir);
+      spinner.stop();
+      console.log(chalk4.gray(`Directory already has files (detected: ${detection.format}). Adding ${SIDECAR_FILENAME} only; no files overwritten.`));
+      const metadata = {
+        displayName: answers.displayName,
+        description: `A ${answers.outputType} spec${answers.replacesSaas ? ` that replaces ${answers.replacesSaas}` : ""}.`,
+        replacesSaas: answers.replacesSaas || void 0,
+        outputType: answers.outputType,
+        primaryStack: answers.primaryStack
+      };
+      const yaml = buildSpecmarketYaml({ ...metadata, specFormat: detection.format });
+      await writeFile2(sidecarPath, yaml);
+      console.log("");
+      console.log(chalk4.green(`Added ${SIDECAR_FILENAME} to ${targetDir}`));
+      console.log("");
+      console.log(chalk4.bold("Next steps:"));
+      console.log(`  1. Run ${chalk4.cyan("specmarket validate")} to check your spec`);
+      console.log(`  2. Run ${chalk4.cyan("specmarket publish")} to publish to the marketplace`);
+      return;
+    }
+    await mkdir2(join3(targetDir, "stdlib"), { recursive: true });
     const data = {
       name: answers.name,
       displayName: answers.displayName,
@@ -544,12 +957,13 @@ async function handleInit(opts) {
       primaryStack: answers.primaryStack
     };
     await Promise.all([
-      writeFile2(join2(targetDir, "spec.yaml"), SPEC_YAML_TEMPLATE(data)),
-      writeFile2(join2(targetDir, "PROMPT.md"), PROMPT_MD_TEMPLATE(data)),
-      writeFile2(join2(targetDir, "SPEC.md"), SPEC_MD_TEMPLATE(data)),
-      writeFile2(join2(targetDir, "SUCCESS_CRITERIA.md"), SUCCESS_CRITERIA_TEMPLATE),
-      writeFile2(join2(targetDir, "stdlib", "STACK.md"), STACK_MD_TEMPLATE(answers.primaryStack)),
-      writeFile2(join2(targetDir, "fix_plan.md"), FIX_PLAN_TEMPLATE(answers.displayName))
+      writeFile2(sidecarPath, SPECMARKET_YAML_TEMPLATE(data)),
+      writeFile2(join3(targetDir, "spec.yaml"), SPEC_YAML_TEMPLATE(data)),
+      writeFile2(join3(targetDir, "PROMPT.md"), PROMPT_MD_TEMPLATE(data)),
+      writeFile2(join3(targetDir, "SPEC.md"), SPEC_MD_TEMPLATE(data)),
+      writeFile2(join3(targetDir, "SUCCESS_CRITERIA.md"), SUCCESS_CRITERIA_TEMPLATE),
+      writeFile2(join3(targetDir, "stdlib", "STACK.md"), STACK_MD_TEMPLATE(answers.primaryStack)),
+      writeFile2(join3(targetDir, "TASKS.md"), TASKS_MD_TEMPLATE(answers.displayName))
     ]);
     spinner.succeed(chalk4.green(`Spec created at ${targetDir}`));
     console.log("");
@@ -557,15 +971,17 @@ async function handleInit(opts) {
     console.log(`  1. ${chalk4.cyan(`cd ${answers.name}`)}`);
     console.log(`  2. Edit ${chalk4.cyan("SPEC.md")} with your application requirements`);
     console.log(`  3. Edit ${chalk4.cyan("SUCCESS_CRITERIA.md")} with specific pass/fail criteria`);
-    console.log(`  4. Run ${chalk4.cyan(`specmarket validate ${answers.name}`)} to check your spec`);
-    console.log(`  5. Run ${chalk4.cyan(`specmarket run ${answers.name}`)} to execute the spec`);
+    console.log(`  4. Run ${chalk4.cyan("specmarket validate")} to check your spec`);
+    console.log(`  5. Run ${chalk4.cyan("specmarket run")} to execute the spec`);
   } catch (err) {
     spinner.fail(chalk4.red(`Failed to create spec: ${err.message}`));
     throw err;
   }
 }
 function createInitCommand() {
-  return new Command4("init").description("Create a new spec directory with template files").option("-n, --name <name>", "Spec name (skip prompt)").option("-p, --path <path>", "Target directory path (defaults to spec name)").action(async (opts) => {
+  return new Command4("init").description(
+    "Create a new SpecMarket spec or add specmarket.yaml to an existing spec (Spec Kit, BMAD, Ralph). Use -p . to init in current directory without overwriting existing files."
+  ).option("-n, --name <name>", "Spec name (skip prompt)").option("-p, --path <path>", "Target directory (e.g. . or ./my-spec). When set, detects existing format and adds only specmarket.yaml if present; no files overwritten.").option("--from <path>", "Import an existing spec directory (Spec Kit, BMAD, Ralph, or custom markdown). Detects format and adds specmarket.yaml metadata sidecar without modifying original files. Errors if the directory is missing or empty.").action(async (opts) => {
     try {
       await handleInit(opts);
     } catch (err) {
@@ -578,123 +994,29 @@ function createInitCommand() {
 // src/commands/validate.ts
 import { Command as Command5 } from "commander";
 import chalk5 from "chalk";
-import { readFile as readFile2, readdir, access } from "fs/promises";
-import { join as join3, resolve as resolve2, relative, normalize } from "path";
-import { parse as parseYaml } from "yaml";
-async function validateSpec(specPath) {
-  const dir = resolve2(specPath);
-  const errors = [];
-  const warnings = [];
-  for (const file of REQUIRED_SPEC_FILES) {
-    const filePath = join3(dir, file);
-    try {
-      await access(filePath);
-      const content = await readFile2(filePath, "utf-8");
-      if (content.trim().length === 0) {
-        errors.push(`${file} exists but is empty`);
-      }
-    } catch {
-      errors.push(`Required file missing: ${file}`);
-    }
-  }
-  const stdlibDir = join3(dir, "stdlib");
-  for (const file of REQUIRED_STDLIB_FILES) {
-    const filePath = join3(stdlibDir, file);
-    try {
-      await access(filePath);
-      const content = await readFile2(filePath, "utf-8");
-      if (content.trim().length === 0) {
-        errors.push(`stdlib/${file} exists but is empty`);
-      }
-    } catch {
-      errors.push(`Required file missing: stdlib/${file}`);
-    }
-  }
-  let specYaml = null;
-  const specYamlPath = join3(dir, "spec.yaml");
+import { readFile as readFile3, readdir as readdir3, access as access2 } from "fs/promises";
+import { join as join4, resolve as resolve2, relative, normalize } from "path";
+import { parse as parseYaml2 } from "yaml";
+async function collectFiles(currentDir, baseDir, extensions) {
+  const results = [];
   try {
-    const raw = await readFile2(specYamlPath, "utf-8");
-    specYaml = parseYaml(raw);
-  } catch (err) {
-    errors.push(`spec.yaml: Failed to parse YAML: ${err.message}`);
-    return { valid: false, errors, warnings };
-  }
-  const parseResult = specYamlSchema.safeParse(specYaml);
-  if (!parseResult.success) {
-    for (const issue of parseResult.error.issues) {
-      errors.push(
-        `spec.yaml: ${issue.path.join(".")} \u2014 ${issue.message}`
-      );
-    }
-  } else {
-    const parsed = parseResult.data;
-    try {
-      const criteriaContent = await readFile2(join3(dir, "SUCCESS_CRITERIA.md"), "utf-8");
-      const hasCriterion = /^- \[[ x]\]/m.test(criteriaContent);
-      if (!hasCriterion) {
-        errors.push(
-          "SUCCESS_CRITERIA.md: Must contain at least one criterion in format: - [ ] criterion text"
-        );
-      }
-    } catch {
-    }
-    const cycles = await detectCircularReferences(dir);
-    for (const cycle of cycles) {
-      errors.push(`Circular reference detected: ${cycle}`);
-    }
-    if (parsed.infrastructure) {
-      const infra = parsed.infrastructure;
-      if (["web-app", "api-service", "mobile-app"].includes(parsed.output_type) && infra.services.length === 0) {
-        warnings.push(
-          `${parsed.output_type} should typically define infrastructure services (database, auth, etc.)`
-        );
-      }
-      if (!infra.setup_time_minutes) {
-        warnings.push("infrastructure.setup_time_minutes is not set");
-      }
-      for (const service of infra.services) {
-        if (service.default_provider) {
-          const providerNames = service.providers.map((p) => p.name);
-          if (!providerNames.includes(service.default_provider)) {
-            errors.push(
-              `infrastructure.services[${service.name}].default_provider "${service.default_provider}" does not match any defined provider (${providerNames.join(", ")})`
-            );
-          }
+    const entries = await readdir3(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join4(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+        const subFiles = await collectFiles(fullPath, baseDir, extensions);
+        results.push(...subFiles);
+      } else if (entry.isFile()) {
+        const ext = entry.name.includes(".") ? "." + entry.name.split(".").pop() : "";
+        if (extensions.has(ext)) {
+          results.push(relative(baseDir, fullPath));
         }
       }
-    } else {
-      if (["web-app", "api-service", "mobile-app"].includes(parsed.output_type)) {
-        warnings.push(
-          "No infrastructure block defined. Consider adding infrastructure.services for database, auth, etc."
-        );
-      }
-    }
-    if (parsed.estimated_tokens < 1e3) {
-      warnings.push(
-        `estimated_tokens (${parsed.estimated_tokens}) seems very low. Most specs use 10,000+.`
-      );
-    }
-    if (parsed.estimated_tokens > 1e7) {
-      warnings.push(
-        `estimated_tokens (${parsed.estimated_tokens}) seems very high.`
-      );
-    }
-    if (parsed.estimated_cost_usd < 0.01) {
-      warnings.push(
-        `estimated_cost_usd ($${parsed.estimated_cost_usd}) seems very low.`
-      );
-    }
-    if (parsed.estimated_time_minutes < 1) {
-      warnings.push(
-        `estimated_time_minutes (${parsed.estimated_time_minutes}) seems unrealistically low.`
-      );
     }
+  } catch {
   }
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings
-  };
+  return results;
 }
 async function detectCircularReferences(dir) {
   const textExtensions = /* @__PURE__ */ new Set([".md", ".yaml", ".yml"]);
@@ -704,7 +1026,7 @@ async function detectCircularReferences(dir) {
   for (const file of files) {
     const refs = /* @__PURE__ */ new Set();
     try {
-      const content = await readFile2(join3(dir, file), "utf-8");
+      const content = await readFile3(join4(dir, file), "utf-8");
       let match;
       while ((match = linkPattern.exec(content)) !== null) {
         const target = match[1];
@@ -713,7 +1035,7 @@ async function detectCircularReferences(dir) {
         }
         const targetPath = target.split("#")[0];
         if (!targetPath) continue;
-        const fileDir = join3(dir, file, "..");
+        const fileDir = join4(dir, file, "..");
         const resolvedTarget = normalize(relative(dir, resolve2(fileDir, targetPath)));
         if (!resolvedTarget.startsWith("..") && files.includes(resolvedTarget)) {
           refs.add(resolvedTarget);
@@ -760,31 +1082,249 @@ async function detectCircularReferences(dir) {
   }
   return cycles;
 }
-async function collectFiles(currentDir, baseDir, extensions) {
-  const results = [];
+async function validateSpecmarketContent(dir, errors, warnings) {
+  for (const file of REQUIRED_SPEC_FILES) {
+    const filePath = join4(dir, file);
+    try {
+      await access2(filePath);
+      const content = await readFile3(filePath, "utf-8");
+      if (content.trim().length === 0) {
+        errors.push(`${file} exists but is empty`);
+      }
+    } catch {
+      errors.push(`Required file missing: ${file}`);
+    }
+  }
+  const stdlibDir = join4(dir, "stdlib");
+  for (const file of REQUIRED_STDLIB_FILES) {
+    const filePath = join4(stdlibDir, file);
+    try {
+      await access2(filePath);
+      const content = await readFile3(filePath, "utf-8");
+      if (content.trim().length === 0) {
+        errors.push(`stdlib/${file} exists but is empty`);
+      }
+    } catch {
+      errors.push(`Required file missing: stdlib/${file}`);
+    }
+  }
+  let specYaml = null;
+  const specYamlPath = join4(dir, "spec.yaml");
   try {
-    const entries = await readdir(currentDir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = join3(currentDir, entry.name);
-      if (entry.isDirectory()) {
-        if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-        const subFiles = await collectFiles(fullPath, baseDir, extensions);
-        results.push(...subFiles);
-      } else if (entry.isFile()) {
-        const ext = entry.name.includes(".") ? "." + entry.name.split(".").pop() : "";
-        if (extensions.has(ext)) {
-          results.push(relative(baseDir, fullPath));
+    const raw = await readFile3(specYamlPath, "utf-8");
+    specYaml = parseYaml2(raw);
+  } catch (err) {
+    errors.push(`spec.yaml: Failed to parse YAML: ${err.message}`);
+    return;
+  }
+  const parseResult = specYamlSchema.safeParse(specYaml);
+  if (!parseResult.success) {
+    for (const issue of parseResult.error.issues) {
+      errors.push(`spec.yaml: ${issue.path.join(".")} \u2014 ${issue.message}`);
+    }
+    return;
+  }
+  const parsed = parseResult.data;
+  try {
+    const criteriaContent = await readFile3(join4(dir, "SUCCESS_CRITERIA.md"), "utf-8");
+    const hasCriterion = /^- \[[ x]\]/m.test(criteriaContent);
+    if (!hasCriterion) {
+      errors.push(
+        "SUCCESS_CRITERIA.md: Must contain at least one criterion in format: - [ ] criterion text"
+      );
+    }
+  } catch {
+  }
+  const cycles = await detectCircularReferences(dir);
+  for (const cycle of cycles) {
+    errors.push(`Circular reference detected: ${cycle}`);
+  }
+  if (parsed.infrastructure) {
+    const infra = parsed.infrastructure;
+    if (["web-app", "api-service", "mobile-app"].includes(parsed.output_type) && infra.services.length === 0) {
+      warnings.push(
+        `${parsed.output_type} should typically define infrastructure services (database, auth, etc.)`
+      );
+    }
+    if (!infra.setup_time_minutes) {
+      warnings.push("infrastructure.setup_time_minutes is not set");
+    }
+    for (const service of infra.services) {
+      if (service.default_provider) {
+        const providerNames = service.providers.map((p) => p.name);
+        if (!providerNames.includes(service.default_provider)) {
+          errors.push(
+            `infrastructure.services[${service.name}].default_provider "${service.default_provider}" does not match any defined provider (${providerNames.join(", ")})`
+          );
         }
       }
     }
+  } else {
+    if (["web-app", "api-service", "mobile-app"].includes(parsed.output_type)) {
+      warnings.push(
+        "No infrastructure block defined. Consider adding infrastructure.services for database, auth, etc."
+      );
+    }
+  }
+  if (parsed.estimated_tokens < 1e3) {
+    warnings.push(
+      `estimated_tokens (${parsed.estimated_tokens}) seems very low. Most specs use 10,000+.`
+    );
+  }
+  if (parsed.estimated_tokens > 1e7) {
+    warnings.push(`estimated_tokens (${parsed.estimated_tokens}) seems very high.`);
+  }
+  if (parsed.estimated_cost_usd < 0.01) {
+    warnings.push(
+      `estimated_cost_usd ($${parsed.estimated_cost_usd}) seems very low.`
+    );
+  }
+  if (parsed.estimated_time_minutes < 1) {
+    warnings.push(
+      `estimated_time_minutes (${parsed.estimated_time_minutes}) seems unrealistically low.`
+    );
+  }
+}
+async function validateSpec(specPath) {
+  const dir = resolve2(specPath);
+  const errors = [];
+  const warnings = [];
+  let format;
+  let formatDetectedBy = "sidecar";
+  try {
+    const entries = await readdir3(dir, { withFileTypes: true });
+    const hasAnyFile = entries.some((e) => e.isFile());
+    if (!hasAnyFile) {
+      errors.push("Directory is empty or has no readable files");
+    }
   } catch {
+    errors.push("Directory is empty or unreadable");
   }
-  return results;
+  const sidecarPath = join4(dir, SIDECAR_FILENAME);
+  const sidecarExists = await fileExists(sidecarPath);
+  if (!sidecarExists) {
+    errors.push(`${SIDECAR_FILENAME} is required for all specs (single source of truth for format and metadata)`);
+  } else {
+    try {
+      const raw = await readFile3(sidecarPath, "utf-8");
+      const parsed = parseYaml2(raw);
+      const sidecarResult = specmarketSidecarSchema.safeParse(parsed);
+      if (!sidecarResult.success) {
+        for (const issue of sidecarResult.error.issues) {
+          errors.push(
+            `${SIDECAR_FILENAME}: ${issue.path.join(".")} \u2014 ${issue.message}`
+          );
+        }
+      } else {
+        const sidecar = sidecarResult.data;
+        format = sidecar.spec_format;
+        if (sidecar.estimated_tokens !== void 0) {
+          if (sidecar.estimated_tokens < 1e3) {
+            warnings.push(
+              `estimated_tokens (${sidecar.estimated_tokens}) seems very low.`
+            );
+          }
+          if (sidecar.estimated_tokens > 1e7) {
+            warnings.push(`estimated_tokens (${sidecar.estimated_tokens}) seems very high.`);
+          }
+        }
+        if (sidecar.estimated_cost_usd !== void 0 && sidecar.estimated_cost_usd < 0.01) {
+          warnings.push(
+            `estimated_cost_usd ($${sidecar.estimated_cost_usd}) seems very low.`
+          );
+        }
+        if (sidecar.estimated_time_minutes !== void 0 && sidecar.estimated_time_minutes < 1) {
+          warnings.push(
+            `estimated_time_minutes (${sidecar.estimated_time_minutes}) seems unrealistically low.`
+          );
+        }
+        switch (format) {
+          case "specmarket":
+            await validateSpecmarketContent(dir, errors, warnings);
+            break;
+          case "speckit": {
+            const hasSpecMd = await fileExists(join4(dir, "spec.md"));
+            const hasTasksMd = await fileExists(join4(dir, "tasks.md"));
+            const hasPlanMd = await fileExists(join4(dir, "plan.md"));
+            const hasSpecifyDir = await directoryExists(join4(dir, ".specify"));
+            if (!hasSpecMd) errors.push("speckit format requires spec.md");
+            if (!hasTasksMd && !hasPlanMd) errors.push("speckit format requires tasks.md or plan.md");
+            if (!hasSpecifyDir) warnings.push("speckit format: .specify/ directory is recommended");
+            break;
+          }
+          case "bmad": {
+            const hasPrdMd = await fileExists(join4(dir, "prd.md"));
+            const hasStory = await hasStoryFiles(dir);
+            if (!hasPrdMd && !hasStory) errors.push("bmad format requires prd.md or story-*.md files");
+            const hasArch = await fileExists(join4(dir, "architecture.md"));
+            if (!hasArch) warnings.push("bmad format: architecture.md is recommended");
+            break;
+          }
+          case "ralph": {
+            const prdPath = join4(dir, "prd.json");
+            if (!await fileExists(prdPath)) {
+              errors.push("ralph format requires prd.json");
+              break;
+            }
+            try {
+              const raw2 = await readFile3(prdPath, "utf-8");
+              const data = JSON.parse(raw2);
+              if (!data || typeof data !== "object" || !("userStories" in data) || !Array.isArray(data.userStories)) {
+                errors.push("ralph format: prd.json must have userStories array");
+              }
+            } catch {
+              errors.push("ralph format: prd.json must be valid JSON with userStories array");
+            }
+            break;
+          }
+          case "custom":
+          default: {
+            const hasMd = await hasMarkdownFiles(dir);
+            if (!hasMd) {
+              errors.push("custom format requires at least one .md file");
+              break;
+            }
+            const textExtensions = /* @__PURE__ */ new Set([".md"]);
+            const mdFiles = await collectFiles(dir, dir, textExtensions);
+            let hasSubstantialMd = false;
+            for (const f of mdFiles) {
+              try {
+                const content = await readFile3(join4(dir, f), "utf-8");
+                if (content.length > 100) {
+                  hasSubstantialMd = true;
+                  break;
+                }
+              } catch {
+              }
+            }
+            if (!hasSubstantialMd) {
+              errors.push("custom format requires at least one .md file larger than 100 bytes");
+            }
+            break;
+          }
+        }
+      }
+    } catch (err) {
+      errors.push(
+        `${SIDECAR_FILENAME}: Failed to read or parse: ${err.message}`
+      );
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    format,
+    formatDetectedBy
+  };
 }
 function createValidateCommand() {
-  return new Command5("validate").description("Validate a spec directory for completeness and schema compliance").argument("<path>", "Path to the spec directory").action(async (specPath) => {
+  return new Command5("validate").description("Validate a spec directory for completeness and schema compliance").argument("[path]", "Path to the spec directory (defaults to current directory)", ".").action(async (specPath) => {
     try {
       const result = await validateSpec(specPath);
+      if (result.format !== void 0) {
+        console.log(chalk5.gray(`Format: ${result.format}`));
+      }
       if (result.warnings.length > 0) {
         console.log(chalk5.yellow("\nWarnings:"));
         for (const warning of result.warnings) {
@@ -819,9 +1359,9 @@ Validation failed with ${result.errors.length} error(s).`)
 import { Command as Command6 } from "commander";
 import chalk6 from "chalk";
 import ora3 from "ora";
-import { readFile as readFile4, mkdir as mkdir4, writeFile as writeFileFn } from "fs/promises";
-import { join as join5, resolve as resolve4, isAbsolute } from "path";
-import { parse as parseYaml2 } from "yaml";
+import { readFile as readFile6, mkdir as mkdir4, writeFile as writeFileFn } from "fs/promises";
+import { join as join7, resolve as resolve4, isAbsolute } from "path";
+import { parse as parseYaml4 } from "yaml";
 
 // src/lib/telemetry.ts
 import createDebug5 from "debug";
@@ -852,6 +1392,11 @@ async function submitTelemetry(report, opts = {}) {
       specVersion: report.specVersion,
       model: report.model,
       runner: report.runner,
+      harness: report.harness,
+      specFormat: report.specFormat,
+      environmentType: report.environmentType,
+      steeringActionCount: report.steeringActionCount,
+      isPureRun: report.isPureRun,
       loopCount: report.loopCount,
       totalTokens: report.totalTokens,
       totalCostUsd: report.totalCostUsd,
@@ -884,30 +1429,474 @@ async function promptTelemetryOptIn() {
       default: false
     }
   ]);
-  const { saveConfig: saveConfig2 } = await import("./config-R5KWZSJP.js");
+  const { saveConfig: saveConfig2 } = await import("./config-5JMI3YAR.js");
   await saveConfig2({ ...config, telemetry: optIn, telemetryPrompted: true });
   return optIn;
 }
 
 // src/lib/ralph-loop.ts
 import { spawn } from "child_process";
-import { mkdir as mkdir3, writeFile as writeFile3, readFile as readFile3, access as access2 } from "fs/promises";
-import { join as join4 } from "path";
+import { mkdir as mkdir3, writeFile as writeFile3, readFile as readFile5, access as access3 } from "fs/promises";
+import { join as join6 } from "path";
 import { homedir as homedir2 } from "os";
 import { randomUUID } from "crypto";
 import { exec } from "child_process";
 import { promisify } from "util";
 import createDebug6 from "debug";
+
+// src/lib/meta-instructions.ts
+import { readFile as readFile4, readdir as readdir4 } from "fs/promises";
+import { join as join5 } from "path";
+import { parse as parseYaml3 } from "yaml";
+var META_INSTRUCTION_FILENAME = ".specmarket-runner.md";
+async function readSidecarData(dir) {
+  const sidecarPath = join5(dir, SIDECAR_FILENAME);
+  if (!await fileExists(sidecarPath)) return {};
+  try {
+    const raw = await readFile4(sidecarPath, "utf-8");
+    const parsed = parseYaml3(raw);
+    if (parsed && typeof parsed === "object") {
+      const d = parsed;
+      return {
+        display_name: typeof d["display_name"] === "string" ? d["display_name"] : void 0,
+        description: typeof d["description"] === "string" ? d["description"] : void 0,
+        spec_format: typeof d["spec_format"] === "string" ? d["spec_format"] : void 0
+      };
+    }
+  } catch {
+  }
+  return {};
+}
+async function listStoryFiles(dir) {
+  try {
+    const entries = await readdir4(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isFile() && e.name.startsWith("story-") && e.name.endsWith(".md")).map((e) => e.name).sort((a, b) => {
+      const numA = parseInt(a.replace(/^story-(\d+).*/, "$1"), 10);
+      const numB = parseInt(b.replace(/^story-(\d+).*/, "$1"), 10);
+      if (!isNaN(numA) && !isNaN(numB)) return numA - numB;
+      if (!isNaN(numA)) return -1;
+      if (!isNaN(numB)) return 1;
+      return a.localeCompare(b);
+    });
+  } catch {
+    return [];
+  }
+}
+async function presentFiles(dir, candidates) {
+  const found = [];
+  for (const f of candidates) {
+    if (await fileExists(join5(dir, f))) found.push(f);
+  }
+  return found;
+}
+function preamble(sidecar) {
+  const lines = [
+    "# SpecMarket Runner Instructions",
+    "",
+    "You are an AI coding agent executing a software specification.",
+    "Read this file carefully before starting work. Follow the instructions exactly."
+  ];
+  if (sidecar.display_name) {
+    lines.push("", `**Spec:** ${sidecar.display_name}`);
+  }
+  if (sidecar.description) {
+    lines.push(`**Description:** ${sidecar.description}`);
+  }
+  return lines.join("\n");
+}
+function testingSection() {
+  return [
+    "## Running Tests",
+    "",
+    "After completing each major task, run the test suite:",
+    "",
+    "- `package.json` present \u2192 `npm test -- --run` (or `npx vitest run` if vitest is configured)",
+    "- `pytest.ini` or `pyproject.toml` present \u2192 `python -m pytest`",
+    "- `Makefile` with `test` target \u2192 `make test`",
+    "- No test runner found \u2192 verify functionality manually by running the application",
+    "",
+    "Fix all test failures before proceeding to the next task."
+  ].join("\n");
+}
+function completionReminder() {
+  return [
+    "## Important Reminders",
+    "",
+    "- Only mark a task complete when you have **fully implemented and tested** it.",
+    "- Do not skip tasks. Do not leave stubs or placeholders.",
+    "- If you discover a blocking issue, note it in the relevant task file and continue with other tasks if possible.",
+    "- Run the full test suite one final time before declaring the spec complete."
+  ].join("\n");
+}
+async function generateSpecmarketInstructions(dir, sidecar) {
+  const coreFiles = await presentFiles(dir, [
+    "PROMPT.md",
+    "SPEC.md",
+    "SUCCESS_CRITERIA.md",
+    "TASKS.md",
+    "spec.yaml",
+    "stdlib/STACK.md",
+    "stdlib/PATTERNS.md",
+    "stdlib/SECURITY.md"
+  ]);
+  const fileList = coreFiles.length > 0 ? coreFiles.map((f) => `- \`${f}\``).join("\n") : "- *(no standard spec files found \u2014 inspect directory contents)*";
+  const readingOrderParts = [];
+  if (coreFiles.includes("PROMPT.md")) {
+    readingOrderParts.push("`PROMPT.md` for the high-level goal");
+  }
+  if (coreFiles.includes("SPEC.md")) {
+    readingOrderParts.push("`SPEC.md` for full requirements");
+  }
+  if (coreFiles.includes("SUCCESS_CRITERIA.md")) {
+    readingOrderParts.push('`SUCCESS_CRITERIA.md` to understand exactly what "done" means');
+  }
+  const readingOrder = readingOrderParts.length > 0 ? `Start with ${readingOrderParts.join(", then ")}.` : "Read all available files to understand the spec requirements.";
+  const stackNote = coreFiles.some((f) => f.startsWith("stdlib/")) ? "\nRead `stdlib/STACK.md` for technology and coding standards before writing any code." : "";
+  return [
+    preamble(sidecar),
+    "",
+    "## Spec Format: SpecMarket (Native)",
+    "",
+    "## Files to Read First",
+    "",
+    fileList,
+    "",
+    readingOrder + stackNote,
+    "",
+    "## Finding Tasks",
+    "",
+    "Tasks are tracked in `TASKS.md` using this format:",
+    "",
+    "```",
+    "- [ ] Incomplete task",
+    "- [x] Completed task",
+    "```",
+    "",
+    coreFiles.includes("SPEC.md") ? "If `TASKS.md` does not exist, derive tasks from `SPEC.md` and `SUCCESS_CRITERIA.md`." : "If `TASKS.md` does not exist, derive tasks from the available spec files.",
+    "Work through tasks from top to bottom. Complete each fully before moving to the next.",
+    "",
+    "## Marking Tasks Complete",
+    "",
+    "When a task is done, update `TASKS.md`:",
+    "- Change `- [ ]` to `- [x]` for the completed task.",
+    "",
+    "## Completion Criteria",
+    "",
+    "The run is complete when ALL of the following are true:",
+    "",
+    "1. **All tasks checked** \u2014 No `- [ ]` lines remain in `TASKS.md`.",
+    "2. **Tests pass** \u2014 Run the test suite; all tests green.",
+    "3. **Success criteria met** \u2014 Every criterion in `SUCCESS_CRITERIA.md` is checked `- [x]`.",
+    "   Update each criterion in `SUCCESS_CRITERIA.md` as it is satisfied.",
+    "",
+    testingSection(),
+    "",
+    completionReminder()
+  ].join("\n");
+}
+async function generateSpeckitInstructions(dir, sidecar) {
+  const hasTasksMd = await fileExists(join5(dir, "tasks.md"));
+  const hasPlanMd = await fileExists(join5(dir, "plan.md"));
+  const hasSpecifyDir = await directoryExists(join5(dir, ".specify"));
+  const taskFile = hasTasksMd ? "tasks.md" : hasPlanMd ? "plan.md" : "tasks.md";
+  const knownFiles = await presentFiles(dir, [
+    "spec.md",
+    "tasks.md",
+    "plan.md",
+    "requirements.md",
+    "README.md"
+  ]);
+  const fileList = knownFiles.length > 0 ? knownFiles.map((f) => `- \`${f}\``).join("\n") : "- `spec.md` \u2014 primary specification";
+  const specifyNote = hasSpecifyDir ? "\nThe `.specify/` directory contains additional context files. Read them for implementation details.\n" : "";
+  return [
+    preamble(sidecar),
+    "",
+    "## Spec Format: Spec Kit",
+    "",
+    "## Files to Read First",
+    "",
+    fileList,
+    specifyNote,
+    "Start with `spec.md` for the full specification.",
+    `Then read \`${taskFile}\` to find your task list.`,
+    "",
+    "## Finding Tasks",
+    "",
+    `Tasks are listed in \`${taskFile}\`. Look for checkbox items:`,
+    "",
+    "```",
+    "- [ ] Incomplete task",
+    "- [x] Completed task",
+    "```",
+    "",
+    "If the task file uses numbered lists or headings instead of checkboxes,",
+    "treat each actionable item as a task. Work through them in order.",
+    "",
+    "## Marking Tasks Complete",
+    "",
+    `When a task is done, update \`${taskFile}\`:`,
+    "- Change `- [ ]` to `- [x]` for the completed task.",
+    "- If using a different format, add `[DONE]` next to the completed item.",
+    "",
+    "## Completion Criteria",
+    "",
+    "The run is complete when:",
+    "",
+    `1. **All tasks checked** \u2014 No unchecked \`- [ ]\` items remain in \`${taskFile}\`.`,
+    "2. **Tests pass** \u2014 Run the test suite; all tests green.",
+    "3. **Spec satisfied** \u2014 Implementation matches all requirements in `spec.md`.",
+    "",
+    testingSection(),
+    "",
+    completionReminder()
+  ].join("\n");
+}
+async function generateBmadInstructions(dir, sidecar) {
+  const storyFiles = await listStoryFiles(dir);
+  const coreFiles = await presentFiles(dir, ["prd.md", "architecture.md", "epic.md"]);
+  const coreFileList = coreFiles.map((f) => `- \`${f}\``).join("\n") || "- *(no core files found)*";
+  const storySection = storyFiles.length > 0 ? [
+    "**Story files found:**",
+    ...storyFiles.map((f) => `- \`${f}\``)
+  ].join("\n") : "*(No story-*.md files found \u2014 check prd.md for tasks)*";
+  return [
+    preamble(sidecar),
+    "",
+    "## Spec Format: BMAD Method",
+    "",
+    "## Files to Read First",
+    "",
+    coreFileList,
+    "",
+    "Start with `prd.md` for product requirements. Read `architecture.md` for technical design.",
+    "Then read each story file in order.",
+    "",
+    "## Finding Tasks",
+    "",
+    "Work is organized as user stories in `story-*.md` files:",
+    "",
+    storySection,
+    "",
+    "Each story file contains:",
+    "- Story description and goal",
+    "- Acceptance criteria (what must be true for the story to be complete)",
+    "- Technical notes",
+    "",
+    "If no story files exist, derive tasks from `prd.md`.",
+    "",
+    "## Marking Tasks Complete",
+    "",
+    "For each story:",
+    "1. Implement everything required by the acceptance criteria.",
+    "2. Mark each acceptance criterion as met in the story file by checking it: `- [ ]` \u2192 `- [x]`.",
+    "3. Add a `## Status: Done` line at the top of the story file when all criteria are met.",
+    "",
+    "If working from `prd.md` directly, add a `Done:` checklist section as you complete items.",
+    "",
+    "## Completion Criteria",
+    "",
+    "The run is complete when:",
+    "",
+    "1. **All stories done** \u2014 Every `story-*.md` has `Status: Done` and all acceptance criteria checked.",
+    "   (Or: all tasks in `prd.md` implemented if no story files.)",
+    "2. **Tests pass** \u2014 Run the test suite; all tests green.",
+    "3. **Architecture followed** \u2014 Implementation matches the design in `architecture.md`.",
+    "",
+    testingSection(),
+    "",
+    completionReminder()
+  ].join("\n");
+}
+async function generateRalphInstructions(dir, sidecar) {
+  let userStoryList = "";
+  try {
+    const raw = await readFile4(join5(dir, "prd.json"), "utf-8");
+    const data = JSON.parse(raw);
+    if (data && typeof data === "object" && "userStories" in data && Array.isArray(data.userStories)) {
+      const stories = data.userStories;
+      const titles = stories.map((s, i) => {
+        const title = typeof s["title"] === "string" ? s["title"] : typeof s["name"] === "string" ? s["name"] : `Story ${i + 1}`;
+        return `- [ ] ${title}`;
+      }).join("\n");
+      userStoryList = titles ? `
+**User stories in prd.json:**
+
+${titles}
+` : "";
+    }
+  } catch {
+  }
+  const extraFiles = await presentFiles(dir, [
+    "architecture.md",
+    "README.md",
+    "CONTRIBUTING.md"
+  ]);
+  const extraFileList = extraFiles.length > 0 ? "\n**Additional files:**\n" + extraFiles.map((f) => `- \`${f}\``).join("\n") : "";
+  return [
+    preamble(sidecar),
+    "",
+    "## Spec Format: Ralph",
+    "",
+    "## Files to Read First",
+    "",
+    "- `prd.json` \u2014 Product requirements document with user stories",
+    extraFileList,
+    "",
+    "Read `prd.json` carefully. The `userStories` array defines all the work to be done.",
+    "",
+    "## Finding Tasks",
+    "",
+    "Open `prd.json` and read the `userStories` array. Each entry is a task.",
+    userStoryList,
+    "Each user story typically has:",
+    "- `title` or `name` \u2014 what to build",
+    "- `description` or `details` \u2014 how to build it",
+    "- `acceptanceCriteria` \u2014 what must be true for the story to be complete",
+    "",
+    "## Marking Tasks Complete",
+    "",
+    "Ralph format does not have a built-in task-tracking file.",
+    "Create a `PROGRESS.md` file in the working directory and track progress there:",
+    "",
+    "```markdown",
+    "# Progress",
+    "",
+    "- [x] Story title (completed)",
+    "- [ ] Next story title",
+    "```",
+    "",
+    "Update `PROGRESS.md` as you complete each user story.",
+    "",
+    "## Completion Criteria",
+    "",
+    "The run is complete when:",
+    "",
+    "1. **All user stories implemented** \u2014 Every story in `prd.json` has a working implementation.",
+    "2. **All acceptance criteria met** \u2014 Verify each story's `acceptanceCriteria` is satisfied.",
+    "3. **Tests pass** \u2014 Run the test suite; all tests green.",
+    "4. **PROGRESS.md updated** \u2014 All stories checked `[x]` in `PROGRESS.md`.",
+    "",
+    testingSection(),
+    "",
+    completionReminder()
+  ].join("\n");
+}
+async function generateCustomInstructions(dir, sidecar) {
+  let mdFiles = [];
+  try {
+    const entries = await readdir4(dir, { withFileTypes: true });
+    mdFiles = entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name).sort();
+  } catch {
+  }
+  const mdFileList = mdFiles.length > 0 ? mdFiles.map((f) => `- \`${f}\``).join("\n") : "- *(no .md files found at top level)*";
+  return [
+    preamble(sidecar),
+    "",
+    "## Spec Format: Custom",
+    "",
+    "## Files to Read First",
+    "",
+    "Markdown files found in this spec:",
+    "",
+    mdFileList,
+    "",
+    "Read all markdown files to understand the full scope of work.",
+    "Look for a README, specification, or requirements document as your primary source of truth.",
+    "",
+    "## Finding Tasks",
+    "",
+    "This spec uses a custom format. Scan all markdown files for:",
+    "",
+    "1. **Checkbox items**: `- [ ] task description` \u2014 these are explicit tasks",
+    "2. **Numbered lists**: actionable steps in requirements documents",
+    "3. **Heading-based sections**: major features or modules to implement",
+    "",
+    "If you find a file that looks like a task list (TASKS.md, TODO.md, checklist.md, etc.), use it.",
+    "",
+    "## Marking Tasks Complete",
+    "",
+    "If the spec has checkboxes (`- [ ]`), update them to `- [x]` as you complete tasks.",
+    "",
+    "If the spec has no checkboxes, create a `PROGRESS.md` file to track progress:",
+    "",
+    "```markdown",
+    "# Progress",
+    "",
+    "- [x] Task or feature completed",
+    "- [ ] Next task",
+    "```",
+    "",
+    "## Completion Criteria",
+    "",
+    "The run is complete when:",
+    "",
+    "1. **All tasks done** \u2014 All checkbox items checked, or all items in `PROGRESS.md` checked.",
+    "2. **Tests pass** \u2014 Run the test suite; all tests green.",
+    "3. **Requirements satisfied** \u2014 Implementation matches all requirements found in the spec files.",
+    "",
+    testingSection(),
+    "",
+    completionReminder()
+  ].join("\n");
+}
+async function generateMetaInstructions(specDir, format) {
+  const sidecar = await readSidecarData(specDir);
+  switch (format) {
+    case "specmarket":
+      return generateSpecmarketInstructions(specDir, sidecar);
+    case "speckit":
+      return generateSpeckitInstructions(specDir, sidecar);
+    case "bmad":
+      return generateBmadInstructions(specDir, sidecar);
+    case "ralph":
+      return generateRalphInstructions(specDir, sidecar);
+    case "custom":
+    default:
+      return generateCustomInstructions(specDir, sidecar);
+  }
+}
+
+// src/lib/ralph-loop.ts
 var debug6 = createDebug6("specmarket:runner");
 var execAsync = promisify(exec);
+async function checkClaudeCliInstalled(harness) {
+  const h = harness ?? DEFAULT_HARNESS;
+  const binaryName = HARNESS_BINARY[h] ?? "claude";
+  try {
+    await execAsync(`which ${binaryName}`);
+  } catch {
+    const installHint = HARNESS_INSTALL_HINT[h] ?? `Install ${binaryName} and ensure it is in your PATH.`;
+    throw new Error(
+      `Harness "${h}" binary "${binaryName}" is not installed or not in your PATH.
+
+${installHint}
+`
+    );
+  }
+}
+var HARNESS_BINARY = {
+  "claude-code": "claude",
+  "codex": "codex",
+  "opencode": "opencode"
+};
+var HARNESS_INSTALL_HINT = {
+  "claude-code": "Installation instructions:\n  npm install -g @anthropic-ai/claude-code\n\nOr visit: https://www.anthropic.com/claude-code",
+  "codex": "Installation instructions:\n  npm install -g @openai/codex\n\nOr visit: https://github.com/openai/codex",
+  "opencode": "Installation instructions:\n  npm install -g opencode-ai\n\nOr visit: https://opencode.ai"
+};
 async function runSpec(specDir, specYaml, opts, onProgress) {
   const maxLoops = opts.maxLoops ?? RUN_DEFAULTS.MAX_LOOPS;
   const budgetTokens = opts.maxBudgetUsd ? opts.maxBudgetUsd / specYaml.estimatedCostUsd * specYaml.estimatedTokens : specYaml.estimatedTokens * RUN_DEFAULTS.BUDGET_MULTIPLIER;
+  const harness = opts.harness ?? DEFAULT_HARNESS;
   const runId = opts.resumeRunId ?? randomUUID();
-  const runsBaseDir = join4(homedir2(), CONFIG_PATHS.RUNS_DIR);
-  const runDir = opts.outputDir ?? join4(runsBaseDir, runId);
-  await mkdir3(runDir, { recursive: true });
-  debug6("Run directory: %s", runDir);
+  const runsBaseDir = join6(homedir2(), CONFIG_PATHS.RUNS_DIR);
+  const usingWorkdir = opts.workdir !== void 0;
+  const runDir = opts.workdir ?? opts.outputDir ?? join6(runsBaseDir, runId);
+  const environmentType = usingWorkdir ? "existing" : "fresh";
+  if (!usingWorkdir) {
+    await mkdir3(runDir, { recursive: true });
+  }
+  debug6("Run directory: %s (environmentType=%s, harness=%s)", runDir, environmentType, harness);
   if (opts.dryRun) {
     debug6("Dry run mode \u2014 skipping execution");
     const report2 = {
@@ -915,6 +1904,11 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
       specVersion: specYaml.version,
       model: opts.model ?? specYaml.minModel,
       runner: specYaml.runner,
+      harness,
+      specFormat: opts.specFormat,
+      environmentType,
+      steeringActionCount: 0,
+      isPureRun: false,
       loopCount: 0,
       totalTokens: 0,
       totalCostUsd: 0,
@@ -937,8 +1931,13 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
       totalTokens = existingReport.totalTokens;
       debug6("Resuming from iteration %d with %d tokens carried over", startIteration, totalTokens);
     }
+    await ensureMetaInstructions(specDir, runDir, opts.specFormat);
+  } else if (usingWorkdir) {
+    await ensureMetaInstructions(specDir, runDir, opts.specFormat);
+    await initGit(runDir);
   } else {
     await copySpecFiles(specDir, runDir);
+    await ensureMetaInstructions(specDir, runDir, opts.specFormat);
     await initGit(runDir);
   }
   const startTime = Date.now();
@@ -946,14 +1945,24 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
   let consecutiveNoChange = 0;
   let lastOutput = "";
   let consecutiveSameOutput = 0;
+  const steeringLog = [];
+  let steeringActionCount = 0;
+  let testPhaseAttempts = 0;
   let finalStatus = "failure";
   let successCriteriaResults = [];
   for (let i = startIteration; i <= maxLoops; i++) {
     debug6("Starting loop iteration %d/%d", i, maxLoops);
     const iterStart = Date.now();
-    const result = await executeClaudeLoop(runDir, opts.model);
+    const pendingMessages = opts.steeringQueue ? opts.steeringQueue.splice(0) : [];
+    if (pendingMessages.length > 0) {
+      await injectSteeringMessages(runDir, pendingMessages, steeringLog);
+      steeringActionCount += pendingMessages.length;
+      debug6("Injected %d steering message(s); total steeringActionCount=%d", pendingMessages.length, steeringActionCount);
+    }
+    const result = await executeHarness(runDir, harness, opts.model);
     const iterDuration = Date.now() - iterStart;
-    const tokensThisLoop = parseTokensFromOutput(result.stdout);
+    const activeModel = opts.model ?? specYaml.minModel;
+    const tokensThisLoop = parseTokensFromOutput(result.stdout, activeModel);
     totalTokens += tokensThisLoop;
     const gitDiff = await getGitDiff(runDir);
     const iteration = {
@@ -967,7 +1976,7 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
     iterations.push(iteration);
     onProgress?.(iteration);
     await writeFile3(
-      join4(runDir, `iteration-${i}.json`),
+      join6(runDir, `iteration-${i}.json`),
       JSON.stringify(iteration, null, 2)
     );
     await stageAllChanges(runDir);
@@ -999,26 +2008,70 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
       consecutiveSameOutput = 0;
       lastOutput = currentOutputHash;
     }
-    const completionCheck = await checkCompletion(runDir);
-    if (completionCheck.isComplete) {
-      debug6("Success criteria met at iteration %d", i);
-      successCriteriaResults = completionCheck.results;
-      finalStatus = "success";
-      break;
+    const tasksComplete = await isFixPlanEmpty(runDir);
+    if (tasksComplete) {
+      const testResult = await runTestsWithOutput(runDir);
+      if (!testResult.passed) {
+        testPhaseAttempts++;
+        debug6(
+          "Post-task test phase attempt %d/%d: tests failing, writing fix tasks",
+          testPhaseAttempts,
+          RUN_DEFAULTS.TEST_PHASE_MAX_ITERATIONS
+        );
+        if (testPhaseAttempts >= RUN_DEFAULTS.TEST_PHASE_MAX_ITERATIONS) {
+          debug6(
+            "Test phase exceeded max iterations (%d), declaring failure",
+            RUN_DEFAULTS.TEST_PHASE_MAX_ITERATIONS
+          );
+          successCriteriaResults = await evaluateSuccessCriteria(runDir).catch(() => []);
+          finalStatus = "failure";
+          break;
+        }
+        await writeTestFixTasks(runDir, testResult.output);
+        await stageAllChanges(runDir);
+        successCriteriaResults = await evaluateSuccessCriteria(runDir).catch(() => []);
+      } else {
+        const criteriaResults = await evaluateSuccessCriteria(runDir);
+        successCriteriaResults = criteriaResults;
+        if (criteriaResults.every((r) => r.passed)) {
+          debug6("All tasks done, tests pass, criteria met at iteration %d", i);
+          finalStatus = "success";
+          break;
+        }
+        debug6(
+          "Tests pass but not all criteria met at iteration %d; continuing",
+          i
+        );
+      }
+    } else {
+      successCriteriaResults = await evaluateSuccessCriteria(runDir).catch(() => []);
     }
-    successCriteriaResults = completionCheck.results;
   }
   if (finalStatus === "failure" && successCriteriaResults.length === 0) {
     successCriteriaResults = await evaluateSuccessCriteria(runDir).catch(() => []);
   }
+  if (steeringLog.length > 0) {
+    await writeFile3(
+      join6(runDir, "steering-log.json"),
+      JSON.stringify(steeringLog, null, 2),
+      "utf-8"
+    );
+    debug6("Steering log written (%d entries)", steeringLog.length);
+  }
   const totalTimeMinutes = (Date.now() - startTime) / 6e4;
   const costPerToken = specYaml.estimatedCostUsd / specYaml.estimatedTokens;
   const totalCostUsd = totalTokens * costPerToken;
+  const detectedSpecFormat = opts.specFormat ?? (await detectSpecFormat(runDir)).format;
   const report = {
     runId,
     specVersion: specYaml.version,
     model: opts.model ?? specYaml.minModel,
     runner: specYaml.runner,
+    harness,
+    specFormat: detectedSpecFormat,
+    environmentType,
+    steeringActionCount,
+    isPureRun: finalStatus === "success" && steeringActionCount === 0,
     loopCount: iterations.length,
     totalTokens,
     totalCostUsd,
@@ -1030,15 +2083,45 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
     cliVersion: opts.cliVersion
   };
   await writeFile3(
-    join4(runDir, "run-report.json"),
+    join6(runDir, "run-report.json"),
     JSON.stringify(report, null, 2)
   );
   debug6("Run complete: %s (status=%s, loops=%d)", runId, finalStatus, iterations.length);
   return { report, outputDir: runDir };
 }
+async function ensureMetaInstructions(specDir, runDir, formatOverride) {
+  const format = formatOverride ?? (await detectSpecFormat(specDir)).format;
+  debug6("Generating meta-instructions for format=%s", format);
+  const content = await generateMetaInstructions(specDir, format);
+  await writeFile3(join6(runDir, META_INSTRUCTION_FILENAME), content, "utf-8");
+  debug6("Meta-instructions written to %s/%s", runDir, META_INSTRUCTION_FILENAME);
+}
+async function injectSteeringMessages(runDir, messages, steeringLog) {
+  if (messages.length === 0) return;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const entries = messages.map((content) => ({ timestamp, content }));
+  steeringLog.push(...entries);
+  const steeringSection = [
+    "",
+    `## Steering Input (injected at ${timestamp})`,
+    "",
+    "The user has provided the following steering instructions. Incorporate them into your current work:",
+    "",
+    ...messages.map((m) => `> ${m}`),
+    ""
+  ].join("\n");
+  const metaPath = join6(runDir, META_INSTRUCTION_FILENAME);
+  try {
+    const existing = await readFile5(metaPath, "utf-8");
+    await writeFile3(metaPath, existing + steeringSection, "utf-8");
+  } catch {
+    await writeFile3(metaPath, steeringSection, "utf-8");
+  }
+  debug6("injectSteeringMessages: appended %d message(s) to %s", messages.length, META_INSTRUCTION_FILENAME);
+}
 async function copySpecFiles(srcDir, destDir) {
   const { cp } = await import("fs/promises");
-  await cp(srcDir, join4(destDir, "spec"), { recursive: true });
+  await cp(srcDir, join6(destDir, "spec"), { recursive: true });
   await cp(srcDir, destDir, { recursive: true, force: false });
   debug6("Spec files copied from %s to %s", srcDir, destDir);
 }
@@ -1066,36 +2149,54 @@ async function getGitDiff(dir) {
     return "";
   }
 }
-async function executeClaudeLoop(dir, model) {
+function buildHarnessCommand(harness, model) {
+  switch (harness) {
+    case "claude-code": {
+      const args = ["--print", "--output-format", "json"];
+      if (model) args.push("--model", model);
+      return `cat ${META_INSTRUCTION_FILENAME} | claude ${args.join(" ")}`;
+    }
+    case "codex":
+      return `cat ${META_INSTRUCTION_FILENAME} | codex`;
+    case "opencode":
+      return `cat ${META_INSTRUCTION_FILENAME} | opencode`;
+    default:
+      debug6('Unknown harness "%s" \u2014 falling back to claude-code', harness);
+      return `cat ${META_INSTRUCTION_FILENAME} | claude --print --output-format json`;
+  }
+}
+async function executeHarness(dir, harness, model) {
+  const cmd = buildHarnessCommand(harness, model);
+  debug6("executeHarness: %s (harness=%s)", cmd, harness);
   return new Promise((resolve7) => {
-    const args = ["--print", "--output-format", "json"];
-    if (model) {
-      args.push("--model", model);
-    }
-    const proc = spawn("sh", ["-c", `cat PROMPT.md | claude-code ${args.join(" ")}`], {
+    const proc = spawn("sh", ["-c", cmd], {
       cwd: dir,
-      stdio: ["inherit", "pipe", "pipe"]
+      // stdin is 'ignore': the harness reads its instructions from the meta-instructions file
+      // via `cat .specmarket-runner.md | <harness>`, not from parent stdin.
+      // Keeping stdin detached from the parent lets the CLI read steering messages
+      // from process.stdin without conflict.
+      stdio: ["ignore", "pipe", "pipe"]
     });
     let stdout = "";
-    let stderr = "";
     proc.stdout?.on("data", (chunk) => {
       stdout += chunk.toString();
     });
     proc.stderr?.on("data", (chunk) => {
-      stderr += chunk.toString();
       process.stderr.write(chunk);
     });
     proc.on("close", (code) => {
       resolve7({ stdout, exitCode: code ?? 0 });
     });
     proc.on("error", (err) => {
-      debug6("claude-code spawn error: %O", err);
+      debug6("%s spawn error: %O", harness, err);
       resolve7({ stdout: "", exitCode: 1 });
     });
   });
 }
-function parseTokensFromOutput(output) {
+function parseTokensFromOutput(output, model) {
   if (!output || output.trim().length === 0) return 0;
+  const modelLower = (model ?? "").toLowerCase();
+  const costPerToken = modelLower.includes("haiku") ? MODEL_COST_PER_TOKEN.haiku : modelLower.includes("opus") ? MODEL_COST_PER_TOKEN.opus : MODEL_COST_PER_TOKEN.default;
   try {
     const lines = output.trim().split("\n");
     for (const line of lines) {
@@ -1114,7 +2215,13 @@ function parseTokensFromOutput(output) {
           const output_tokens = parsed.usage?.output_tokens ?? parsed.usage?.completion_tokens ?? 0;
           if (input > 0 || output_tokens > 0) return input + output_tokens;
           if (typeof parsed.cost_usd === "number" && parsed.cost_usd > 0) {
-            return Math.round(parsed.cost_usd / 9e-6);
+            debug6(
+              "parseTokensFromOutput: using cost_usd=%f with model=%s (costPerToken=%e)",
+              parsed.cost_usd,
+              model ?? "unknown",
+              costPerToken
+            );
+            return Math.round(parsed.cost_usd / costPerToken);
           }
         }
       } catch {
@@ -1152,63 +2259,114 @@ function parseTokensFromOutput(output) {
 function parseIntComma(s) {
   return parseInt(s.replace(/,/g, ""), 10) || 0;
 }
-async function checkCompletion(dir) {
-  const fixPlanEmpty = await isFixPlanEmpty(dir);
-  if (!fixPlanEmpty) {
-    return {
-      isComplete: false,
-      results: await evaluateSuccessCriteria(dir).catch(() => [])
-    };
-  }
-  const testsPass = await runTests(dir);
-  if (!testsPass) {
-    return {
-      isComplete: false,
-      results: await evaluateSuccessCriteria(dir).catch(() => [])
-    };
-  }
-  const criteriaResults = await evaluateSuccessCriteria(dir);
-  const allPassed = criteriaResults.every((r) => r.passed);
-  return {
-    isComplete: allPassed,
-    results: criteriaResults
-  };
-}
 async function isFixPlanEmpty(dir) {
   try {
-    const content = await readFile3(join4(dir, "fix_plan.md"), "utf-8");
+    const content = await readFile5(join6(dir, "TASKS.md"), "utf-8");
     const hasUncheckedItems = /^- \[ \]/m.test(content);
     return !hasUncheckedItems;
   } catch {
     return true;
   }
 }
-async function runTests(dir) {
+async function runTestsWithOutput(dir) {
   const testRunners = [
-    { file: "package.json", cmd: "npm test -- --run 2>&1 || true" },
-    { file: "vitest.config.ts", cmd: "npx vitest run 2>&1 || true" },
-    { file: "pytest.ini", cmd: "python -m pytest --tb=no -q 2>&1 || true" },
-    { file: "Makefile", cmd: "make test 2>&1 || true" }
+    { file: "package.json", cmd: "npm test -- --run 2>&1" },
+    { file: "vitest.config.ts", cmd: "npx vitest run 2>&1" },
+    { file: "pytest.ini", cmd: "python -m pytest --tb=short -q 2>&1" },
+    { file: "Makefile", cmd: "make test 2>&1" }
   ];
   for (const runner of testRunners) {
     try {
-      await access2(join4(dir, runner.file));
+      await access3(join6(dir, runner.file));
+    } catch {
+      continue;
+    }
+    try {
       const { stdout, stderr } = await execAsync(runner.cmd, {
         cwd: dir,
         timeout: 12e4
       });
       const combined = stdout + stderr;
-      const hasFailed = /\d+ failed|\d+ error|FAILED|ERROR/i.test(combined);
-      return !hasFailed;
-    } catch {
+      const hasFailed = /\d+ failed|\d+ error/i.test(combined);
+      return { passed: !hasFailed, output: combined };
+    } catch (err) {
+      if (err && typeof err === "object") {
+        const execErr = err;
+        if (typeof execErr.code === "number" && execErr.signal == null) {
+          const combined = (execErr.stdout ?? "") + (execErr.stderr ?? "");
+          return { passed: false, output: combined };
+        }
+      }
       continue;
     }
   }
-  return true;
+  return { passed: true, output: "" };
+}
+function extractTestFailures(output) {
+  const failures = [];
+  const failFileMatches = output.match(/^FAIL\s+\S+/gm) ?? [];
+  for (const m of failFileMatches) {
+    const name = m.replace(/^FAIL\s+/, "").trim();
+    if (name && !failures.includes(name)) failures.push(name);
+  }
+  const failTestMatches = output.match(/^[\s]*[×✗✕]\s+(.+)/gm) ?? [];
+  for (const m of failTestMatches) {
+    const name = m.replace(/^[\s]*[×✗✕]\s+/, "").trim();
+    if (name && !failures.includes(name)) failures.push(name);
+  }
+  const pytestMatches = output.match(/^FAILED\s+\S+/gm) ?? [];
+  for (const m of pytestMatches) {
+    const name = m.replace(/^FAILED\s+/, "").trim();
+    if (name && !failures.includes(name)) failures.push(name);
+  }
+  if (failures.length === 0) {
+    const summaryMatch = output.match(/(\d+)\s+failed/i);
+    if (summaryMatch) {
+      failures.push(`${summaryMatch[1]} test(s) failed \u2014 see TEST_FAILURES.md for details`);
+    }
+  }
+  return failures.slice(0, 10);
+}
+async function writeTestFixTasks(dir, testOutput) {
+  await writeFile3(
+    join6(dir, "TEST_FAILURES.md"),
+    [
+      "# Test Failures",
+      "",
+      "> Auto-generated by SpecMarket runner. Delete this file when all tests pass.",
+      "",
+      "## Raw Test Output",
+      "",
+      "```",
+      testOutput.slice(0, 8e3),
+      "```"
+    ].join("\n"),
+    "utf-8"
+  );
+  const failures = extractTestFailures(testOutput);
+  if (failures.length === 0) return;
+  const testFixSection = [
+    "",
+    "## Test Failures (Auto-Generated)",
+    "> These tasks were created by the runner after detecting test failures.",
+    "> Fix each failing test, then delete this section and TEST_FAILURES.md.",
+    "",
+    ...failures.map((f) => `- [ ] Fix: ${f}`)
+  ].join("\n");
+  try {
+    const existing = await readFile5(join6(dir, "TASKS.md"), "utf-8");
+    const withoutPrevious = existing.replace(
+      /\n## Test Failures \(Auto-Generated\)[\s\S]*/,
+      ""
+    );
+    await writeFile3(join6(dir, "TASKS.md"), withoutPrevious + testFixSection, "utf-8");
+  } catch {
+    await writeFile3(join6(dir, "TASKS.md"), `# Tasks${testFixSection}`, "utf-8");
+  }
 }
 async function evaluateSuccessCriteria(dir) {
   try {
-    const content = await readFile3(join4(dir, "SUCCESS_CRITERIA.md"), "utf-8");
+    const content = await readFile5(join6(dir, "SUCCESS_CRITERIA.md"), "utf-8");
     const lines = content.split("\n");
     const results = [];
     for (const line of lines) {
@@ -1227,7 +2385,7 @@ async function evaluateSuccessCriteria(dir) {
 }
 async function loadExistingReport(dir) {
   try {
-    const raw = await readFile3(join4(dir, "run-report.json"), "utf-8");
+    const raw = await readFile5(join6(dir, "run-report.json"), "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -1265,8 +2423,8 @@ async function handleRun(specPathOrId, opts) {
       console.log(chalk6.yellow(`  \u26A0 ${warning}`));
     }
   }
-  const specYamlContent = await readFile4(join5(specDir, "spec.yaml"), "utf-8");
-  const specYamlRaw = parseYaml2(specYamlContent);
+  const specYamlContent = await readFile6(join7(specDir, "spec.yaml"), "utf-8");
+  const specYamlRaw = parseYaml4(specYamlContent);
   const specYaml = specYamlSchema.parse(specYamlRaw);
   console.log("");
   console.log(chalk6.yellow("\u26A0  SECURITY WARNING"));
@@ -1284,15 +2442,57 @@ async function handleRun(specPathOrId, opts) {
   if (authed && !opts.noTelemetry) {
     await promptTelemetryOptIn();
   }
+  if (opts.harness && !KNOWN_HARNESSES.includes(opts.harness)) {
+    console.log(chalk6.red(`
+\u2717 Unknown harness "${opts.harness}". Supported: ${KNOWN_HARNESSES.join(", ")}`));
+    process.exit(EXIT_CODES.VALIDATION_ERROR);
+  }
+  try {
+    await checkClaudeCliInstalled(opts.harness);
+  } catch (err) {
+    console.log(chalk6.red(`
+\u2717 ${err.message}`));
+    process.exit(EXIT_CODES.VALIDATION_ERROR);
+  }
   const maxLoops = opts.maxLoops ? parseInt(opts.maxLoops, 10) : void 0;
   const maxBudget = opts.maxBudget ? parseFloat(opts.maxBudget) : void 0;
+  const harness = opts.harness ?? "claude-code";
   console.log(chalk6.cyan(`
 Running spec: ${chalk6.bold(specYaml.display_name)}`));
   console.log(chalk6.gray(`  Version: ${specYaml.version}`));
   console.log(chalk6.gray(`  Model: ${opts.model ?? specYaml.min_model}`));
+  console.log(chalk6.gray(`  Harness: ${harness}`));
+  if (opts.workdir) {
+    console.log(chalk6.gray(`  Working dir: ${opts.workdir}`));
+  }
   console.log(chalk6.gray(`  Max loops: ${maxLoops ?? 50}`));
   console.log(chalk6.gray(`  Estimated tokens: ${specYaml.estimated_tokens.toLocaleString()}`));
   console.log(chalk6.gray(`  Estimated cost: $${specYaml.estimated_cost_usd.toFixed(2)}`));
+  const steeringQueue = [];
+  let steeringInputBuffer = "";
+  const steeringDataHandler = (chunk) => {
+    const data = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+    steeringInputBuffer += data;
+    const lines = steeringInputBuffer.split("\n");
+    steeringInputBuffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed) {
+        steeringQueue.push(trimmed);
+        process.stderr.write(
+          `
+${chalk6.cyan("[steering]")} Queued: "${trimmed.length > 60 ? trimmed.slice(0, 60) + "\u2026" : trimmed}"
+`
+        );
+      }
+    }
+  };
+  if (!opts.dryRun) {
+    process.stdin.setEncoding("utf-8");
+    process.stdin.resume();
+    process.stdin.on("data", steeringDataHandler);
+    console.log(chalk6.gray("  Tip: Type a message + Enter to steer the agent mid-run."));
+  }
   console.log("");
   const spinner = ora3({ text: "Starting loop iteration 1...", spinner: "dots" }).start();
   try {
@@ -1314,12 +2514,17 @@ Running spec: ${chalk6.bold(specYaml.display_name)}`));
         dryRun: opts.dryRun,
         resumeRunId: opts.resume,
         outputDir: opts.output,
-        cliVersion: CLI_VERSION
+        harness: opts.harness,
+        workdir: opts.workdir,
+        cliVersion: CLI_VERSION,
+        steeringQueue
       },
       (iteration) => {
         spinner.text = `Loop ${iteration.iteration}: ${iteration.tokens.toLocaleString()} tokens, ${(iteration.durationMs / 1e3).toFixed(1)}s`;
       }
     );
+    process.stdin.removeListener("data", steeringDataHandler);
+    process.stdin.pause();
     const { report } = result;
     const statusColor = report.status === "success" ? chalk6.green : report.status === "stall" || report.status === "budget_exceeded" ? chalk6.yellow : chalk6.red;
     spinner.stop();
@@ -1331,6 +2536,9 @@ Running spec: ${chalk6.bold(specYaml.display_name)}`));
     console.log(`  Tokens: ${report.totalTokens.toLocaleString()}`);
     console.log(`  Cost: $${report.totalCostUsd.toFixed(4)}`);
     console.log(`  Time: ${report.totalTimeMinutes.toFixed(1)} minutes`);
+    if (report.steeringActionCount && report.steeringActionCount > 0) {
+      console.log(`  Steering Actions: ${report.steeringActionCount}`);
+    }
     console.log(`  Run ID: ${chalk6.gray(report.runId)}`);
     console.log(`  Output: ${chalk6.gray(result.outputDir)}`);
     if (report.successCriteriaResults.length > 0) {
@@ -1375,10 +2583,10 @@ async function resolveSpecPath(pathOrId) {
     debug7("Treating %s as local path (no registry pattern match)", pathOrId);
     return { specDir: resolve4(pathOrId) };
   }
-  const { access: access3 } = await import("fs/promises");
+  const { access: access4 } = await import("fs/promises");
   const localPath = resolve4(pathOrId);
   try {
-    await access3(localPath);
+    await access4(localPath);
     debug7("Found local directory %s \u2014 using as local spec", localPath);
     return { specDir: localPath };
   } catch {
@@ -1442,7 +2650,7 @@ async function resolveSpecPath(pathOrId) {
   debug7("Got download URL for %s@%s", scopedName, resolvedVersion);
   const { tmpdir } = await import("os");
   const { randomUUID: randomUUID2 } = await import("crypto");
-  const tempDir = join5(tmpdir(), `specmarket-${randomUUID2()}`);
+  const tempDir = join7(tmpdir(), `specmarket-${randomUUID2()}`);
   await mkdir4(tempDir, { recursive: true });
   let response;
   try {
@@ -1459,7 +2667,7 @@ async function resolveSpecPath(pathOrId) {
     throw err;
   }
   const buffer = Buffer.from(await response.arrayBuffer());
-  const zipPath = join5(tempDir, "spec.zip");
+  const zipPath = join7(tempDir, "spec.zip");
   await writeFileFn(zipPath, buffer);
   const { execAsync: execAsync2 } = await import("./exec-K3BOXX3C.js");
   await execAsync2(`unzip -q "${zipPath}" -d "${tempDir}"`);
@@ -1471,7 +2679,13 @@ async function resolveSpecPath(pathOrId) {
   return { specDir: tempDir, registrySpecId };
 }
 function createRunCommand() {
-  return new Command6("run").description("Execute a spec locally using the Ralph Loop").argument("<path-or-id>", "Local path to spec directory or registry ID (@user/name[@version])").option("--max-loops <n>", "Maximum loop iterations (default: 50)").option("--max-budget <usd>", "Maximum budget in USD (default: 2x estimated)").option("--no-telemetry", "Disable telemetry submission for this run").option("--model <model>", "Override AI model (default: spec's min_model)").option("--dry-run", "Validate and show config without executing").option("--resume <run-id>", "Resume a previous run from where it left off").option("--output <dir>", "Custom output directory for run artifacts").action(async (pathOrId, opts) => {
+  return new Command6("run").description("Execute a spec locally using the Ralph Loop").argument("[path-or-id]", "Local path to spec directory or registry ID (@user/name[@version])", ".").option("--max-loops <n>", "Maximum loop iterations (default: 50)").option("--max-budget <usd>", "Maximum budget in USD (default: 2x estimated)").option("--no-telemetry", "Disable telemetry submission for this run").option("--model <model>", "Override AI model (default: spec's min_model)").option("--dry-run", "Validate and show config without executing").option("--resume <run-id>", "Resume a previous run from where it left off").option("--output <dir>", "Custom output directory for run artifacts").option(
+    "--harness <harness>",
+    `Agentic harness to use (default: claude-code). One of: ${KNOWN_HARNESSES.join(", ")}`
+  ).option(
+    "--workdir <dir>",
+    "Run in an existing directory instead of a fresh sandbox (spec files not copied)"
+  ).action(async (pathOrId, opts) => {
     try {
       await handleRun(pathOrId, opts);
     } catch (err) {
@@ -1649,11 +2863,43 @@ async function handleInfo(specId) {
   const spinner = (await import("ora")).default(`Loading info for ${specId}...`).start();
   try {
     const isScopedName = specId.startsWith("@") || specId.includes("/");
-    const [spec, stats, versions] = await Promise.all([
+    const [spec, stats, versionsResult] = await Promise.all([
       client.query(api2.specs.get, isScopedName ? { scopedName: specId } : { specId }),
       client.query(api2.runs.getStats, { specId }).catch(() => null),
-      client.query(api2.specs.getVersions, { specId }).catch(() => [])
+      client.query(api2.specs.getVersions, { specId, paginationOpts: { numItems: 25, cursor: null } }).catch(() => ({ page: [] }))
     ]);
+    const versions = versionsResult.page;
+    let openIssueCount = 0;
+    let maintainers = [];
+    let commentCount = 0;
+    if (spec) {
+      const [issuesResult, maintainersResult, commentsResult] = await Promise.all([
+        client.query(api2.issues.list, {
+          specId: spec._id,
+          status: "open",
+          paginationOpts: { numItems: 1, cursor: null }
+        }).catch(() => null),
+        client.query(api2.specMaintainers.list, { specId: spec._id }).catch(() => []),
+        client.query(api2.comments.list, {
+          targetType: "spec",
+          targetId: spec._id,
+          paginationOpts: { numItems: 1, cursor: null }
+        }).catch(() => null)
+      ]);
+      if (issuesResult) {
+        openIssueCount = issuesResult.page.length;
+        if (!issuesResult.isDone && openIssueCount > 0) {
+          openIssueCount = -1;
+        }
+      }
+      maintainers = maintainersResult;
+      if (commentsResult) {
+        commentCount = commentsResult.page.length;
+        if (!commentsResult.isDone && commentCount > 0) {
+          commentCount = -1;
+        }
+      }
+    }
     spinner.stop();
     if (!spec) {
       console.log(chalk8.red(`Spec not found: ${specId}`));
@@ -1701,6 +2947,18 @@ async function handleInfo(specId) {
     if (spec.forkedFromId) {
       console.log(chalk8.gray(`  (Forked from v${spec.forkedFromVersion})`));
     }
+    const issueDisplay = openIssueCount === -1 ? "many" : String(openIssueCount);
+    const commentDisplay = commentCount === -1 ? "many" : String(commentCount);
+    console.log(
+      `  Open Issues: ${issueDisplay}`
+    );
+    console.log(
+      `  Comments: ${commentDisplay}`
+    );
+    if (maintainers.length > 0) {
+      const names = maintainers.filter((m) => m.user).map((m) => `@${m.user.username}`).join(", ");
+      console.log(`  Maintainers: ${names}`);
+    }
     if (author) {
       console.log("");
       console.log(chalk8.bold("Creator:"));
@@ -1785,9 +3043,9 @@ function createInfoCommand() {
 import { Command as Command9 } from "commander";
 import chalk9 from "chalk";
 import ora4 from "ora";
-import { readFile as readFile5 } from "fs/promises";
-import { join as join6, resolve as resolve5 } from "path";
-import { parse as parseYaml3 } from "yaml";
+import { readFile as readFile7 } from "fs/promises";
+import { join as join8, resolve as resolve5 } from "path";
+import { parse as parseYaml5 } from "yaml";
 import { createWriteStream } from "fs";
 async function handlePublish(specPath, opts = {}) {
   const creds = await requireAuth();
@@ -1808,8 +3066,8 @@ async function handlePublish(specPath, opts = {}) {
       spinner.succeed("Spec validated");
     }
     spinner.start("Reading spec metadata...");
-    const specYamlContent = await readFile5(join6(dir, "spec.yaml"), "utf-8");
-    const specYamlRaw = parseYaml3(specYamlContent);
+    const specYamlContent = await readFile7(join8(dir, "spec.yaml"), "utf-8");
+    const specYamlRaw = parseYaml5(specYamlContent);
     const specYaml = specYamlSchema.parse(specYamlRaw);
     spinner.succeed(`Loaded spec: ${specYaml.display_name} v${specYaml.version}`);
     const client = await getConvexClient(creds.token);
@@ -1824,7 +3082,7 @@ async function handlePublish(specPath, opts = {}) {
     spinner.succeed("Spec archive created");
     spinner.start("Uploading spec to registry...");
     const uploadUrl = await client.mutation(api2.specs.generateUploadUrl, {});
-    const zipContent = await readFile5(zipPath);
+    const zipContent = await readFile7(zipPath);
     const uploadResponse = await fetch(uploadUrl, {
       method: "POST",
       headers: { "Content-Type": "application/zip" },
@@ -1836,7 +3094,7 @@ async function handlePublish(specPath, opts = {}) {
     const { storageId } = await uploadResponse.json();
     spinner.succeed("Spec uploaded");
     spinner.start("Publishing to registry...");
-    const readme = await readFile5(join6(dir, "SPEC.md"), "utf-8").catch(() => void 0);
+    const readme = await readFile7(join8(dir, "SPEC.md"), "utf-8").catch(() => void 0);
     const publishResult = await client.mutation(api2.specs.publish, {
       slug: specYaml.name,
       displayName: specYaml.display_name,
@@ -1850,6 +3108,7 @@ async function handlePublish(specPath, opts = {}) {
       specStorageId: storageId,
       readme,
       runner: specYaml.runner,
+      specFormat: validation.format,
       minModel: specYaml.min_model,
       estimatedTokens: specYaml.estimated_tokens,
       estimatedCostUsd: specYaml.estimated_cost_usd,
@@ -1878,7 +3137,7 @@ async function handlePublish(specPath, opts = {}) {
 async function createSpecZip(dir) {
   const { tmpdir } = await import("os");
   const { randomUUID: randomUUID2 } = await import("crypto");
-  const zipPath = join6(tmpdir(), `spec-${randomUUID2()}.zip`);
+  const zipPath = join8(tmpdir(), `spec-${randomUUID2()}.zip`);
   const archiver = (await import("archiver")).default;
   const output = createWriteStream(zipPath);
   const archive = archiver("zip", { zlib: { level: 9 } });
@@ -1909,9 +3168,9 @@ function createPublishCommand() {
 import { Command as Command10 } from "commander";
 import chalk10 from "chalk";
 import ora5 from "ora";
-import { mkdir as mkdir5, writeFile as writeFile4, readFile as readFile6 } from "fs/promises";
-import { join as join7, resolve as resolve6 } from "path";
-import { parse as parseYaml4, stringify as stringifyYaml } from "yaml";
+import { mkdir as mkdir5, writeFile as writeFile4, readFile as readFile8 } from "fs/promises";
+import { join as join9, resolve as resolve6 } from "path";
+import { parse as parseYaml6, stringify as stringifyYaml } from "yaml";
 async function handleFork(specId, targetPath) {
   const creds = await requireAuth();
   const spinner = ora5("Loading spec info...").start();
@@ -1939,9 +3198,9 @@ async function handleFork(specId, targetPath) {
     const targetDir = resolve6(targetPath ?? spec.slug);
     spinner.text = `Extracting to ${targetDir}...`;
     await downloadAndExtract(url, targetDir);
-    const specYamlPath = join7(targetDir, "spec.yaml");
-    const specYamlContent = await readFile6(specYamlPath, "utf-8");
-    const specYamlData = parseYaml4(specYamlContent);
+    const specYamlPath = join9(targetDir, "spec.yaml");
+    const specYamlContent = await readFile8(specYamlPath, "utf-8");
+    const specYamlData = parseYaml6(specYamlContent);
     specYamlData["forked_from_id"] = spec._id;
     specYamlData["forked_from_version"] = spec.currentVersion;
     specYamlData["version"] = "1.0.0";
@@ -1974,7 +3233,7 @@ async function downloadAndExtract(url, targetDir) {
   const buffer = Buffer.from(await response.arrayBuffer());
   const { tmpdir } = await import("os");
   const { randomUUID: randomUUID2 } = await import("crypto");
-  const zipPath = join7(tmpdir(), `fork-${randomUUID2()}.zip`);
+  const zipPath = join9(tmpdir(), `fork-${randomUUID2()}.zip`);
   const { writeFile: writeFileFn2, unlink: unlink2 } = await import("fs/promises");
   await writeFileFn2(zipPath, buffer);
   await mkdir5(targetDir, { recursive: true });
@@ -2001,15 +3260,15 @@ function createForkCommand() {
 // src/commands/report.ts
 import { Command as Command11 } from "commander";
 import chalk11 from "chalk";
-import { readFile as readFile7 } from "fs/promises";
-import { join as join8 } from "path";
+import { readFile as readFile9 } from "fs/promises";
+import { join as join10 } from "path";
 import { homedir as homedir3 } from "os";
 async function handleReport(runId) {
-  const localPath = join8(homedir3(), CONFIG_PATHS.RUNS_DIR, runId, "run-report.json");
+  const localPath = join10(homedir3(), CONFIG_PATHS.RUNS_DIR, runId, "run-report.json");
   let report = null;
   let source = "local";
   try {
-    const raw = await readFile7(localPath, "utf-8");
+    const raw = await readFile9(localPath, "utf-8");
     report = JSON.parse(raw);
     source = "local";
   } catch {
@@ -2257,6 +3516,438 @@ function createConfigCommand() {
   return configCmd;
 }
 
+// src/commands/issues.ts
+import { Command as Command13 } from "commander";
+import chalk13 from "chalk";
+import Table2 from "cli-table3";
+async function loadApi() {
+  try {
+    return (await import("./api-GIDUNUXG.js")).api;
+  } catch {
+    console.error(
+      chalk13.red("Error: Could not load Convex API bindings. Is CONVEX_URL configured?")
+    );
+    process.exit(EXIT_CODES.NETWORK_ERROR);
+  }
+}
+async function resolveSpec(client, api2, specRef) {
+  const isScopedName = specRef.startsWith("@") || specRef.includes("/");
+  const spec = await client.query(
+    api2.specs.get,
+    isScopedName ? { scopedName: specRef } : { specId: specRef }
+  );
+  if (!spec) {
+    console.error(chalk13.red(`Spec not found: ${specRef}`));
+    process.exit(EXIT_CODES.VALIDATION_ERROR);
+  }
+  return spec;
+}
+function relativeTime(timestamp) {
+  const diff = Date.now() - timestamp;
+  const seconds = Math.floor(diff / 1e3);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  if (days > 0) return `${days}d ago`;
+  if (hours > 0) return `${hours}h ago`;
+  if (minutes > 0) return `${minutes}m ago`;
+  return "just now";
+}
+async function handleIssuesList(specRef, opts) {
+  const api2 = await loadApi();
+  const client = await getConvexClient();
+  const spinner = (await import("ora")).default("Loading issues...").start();
+  try {
+    const spec = await resolveSpec(client, api2, specRef);
+    const statusFilter = opts.status === "all" ? void 0 : opts.status ?? "open";
+    const result = await client.query(api2.issues.list, {
+      specId: spec._id,
+      status: statusFilter,
+      labels: opts.label ? [opts.label] : void 0,
+      paginationOpts: { numItems: 50, cursor: null }
+    });
+    spinner.stop();
+    const issues = result.page;
+    if (issues.length === 0) {
+      const statusLabel = statusFilter ?? "any";
+      console.log(chalk13.gray(`No ${statusLabel} issues for ${spec.scopedName}`));
+      return;
+    }
+    console.log(
+      chalk13.bold(`
+${issues.length} issue(s) for ${spec.scopedName}:
+`)
+    );
+    const table = new Table2({
+      head: [
+        chalk13.cyan("#"),
+        chalk13.cyan("Title"),
+        chalk13.cyan("Author"),
+        chalk13.cyan("Age"),
+        chalk13.cyan("Labels")
+      ],
+      style: { compact: true },
+      colWidths: [6, 40, 16, 10, 20],
+      wordWrap: true
+    });
+    for (const issue of issues) {
+      const statusIcon = issue.status === "open" ? chalk13.green("\u25CF") : chalk13.gray("\u25CB");
+      table.push([
+        `${statusIcon} ${issue.number}`,
+        issue.title.slice(0, 60),
+        issue.author ? `@${issue.author.username}` : chalk13.gray("unknown"),
+        relativeTime(issue.createdAt),
+        issue.labels.length > 0 ? issue.labels.join(", ") : chalk13.gray("\u2014")
+      ]);
+    }
+    console.log(table.toString());
+    console.log(
+      chalk13.gray(
+        `
+View: ${chalk13.cyan(`specmarket issues ${specRef} <number>`)}`
+      )
+    );
+  } catch (err) {
+    spinner.fail(chalk13.red(`Failed to load issues: ${err.message}`));
+    process.exit(EXIT_CODES.NETWORK_ERROR);
+  }
+}
+async function handleIssuesCreate(specRef) {
+  const creds = await requireAuth();
+  const api2 = await loadApi();
+  const client = await getConvexClient(creds.token);
+  const spec = await resolveSpec(client, api2, specRef);
+  const { default: inquirer } = await import("inquirer");
+  const answers = await inquirer.prompt([
+    {
+      type: "input",
+      name: "title",
+      message: "Issue title:",
+      validate: (v) => v.trim().length > 0 || "Title cannot be empty"
+    },
+    {
+      type: "editor",
+      name: "body",
+      message: "Issue body (markdown):",
+      validate: (v) => v.trim().length > 0 || "Body cannot be empty"
+    }
+  ]);
+  const spinner = (await import("ora")).default("Creating issue...").start();
+  try {
+    const result = await client.mutation(api2.issues.create, {
+      specId: spec._id,
+      title: answers.title.trim(),
+      body: answers.body.trim(),
+      labels: []
+    });
+    spinner.succeed(
+      chalk13.green(`Issue #${result.number} created on ${spec.scopedName}`)
+    );
+  } catch (err) {
+    spinner.fail(chalk13.red(`Failed to create issue: ${err.message}`));
+    process.exit(EXIT_CODES.NETWORK_ERROR);
+  }
+}
+async function handleIssuesView(specRef, issueNumber) {
+  const api2 = await loadApi();
+  const client = await getConvexClient();
+  const spinner = (await import("ora")).default(`Loading issue #${issueNumber}...`).start();
+  try {
+    const spec = await resolveSpec(client, api2, specRef);
+    const issue = await client.query(api2.issues.get, {
+      specId: spec._id,
+      number: issueNumber
+    });
+    if (!issue) {
+      spinner.fail(chalk13.red(`Issue #${issueNumber} not found on ${spec.scopedName}`));
+      process.exit(EXIT_CODES.VALIDATION_ERROR);
+    }
+    const commentsResult = await client.query(api2.comments.list, {
+      targetType: "issue",
+      targetId: issue._id,
+      paginationOpts: { numItems: 10, cursor: null }
+    });
+    spinner.stop();
+    const statusBadge = issue.status === "open" ? chalk13.green.bold(" OPEN ") : chalk13.gray.bold(" CLOSED ");
+    console.log("");
+    console.log(
+      `${statusBadge}  ${chalk13.bold(`#${issue.number}: ${issue.title}`)}`
+    );
+    console.log(chalk13.gray("\u2500".repeat(60)));
+    console.log(
+      `${chalk13.bold("Author:")} ${issue.author ? `@${issue.author.username}` : "unknown"}  ${chalk13.bold("Created:")} ${new Date(issue.createdAt).toLocaleDateString()}`
+    );
+    if (issue.labels.length > 0) {
+      console.log(`${chalk13.bold("Labels:")} ${issue.labels.join(", ")}`);
+    }
+    if (issue.closedAt) {
+      console.log(
+        `${chalk13.bold("Closed:")} ${new Date(issue.closedAt).toLocaleDateString()}`
+      );
+    }
+    console.log("");
+    console.log(issue.body);
+    console.log("");
+    if (commentsResult.page.length > 0) {
+      console.log(
+        chalk13.bold(`Comments (${issue.commentCount}):`)
+      );
+      console.log(chalk13.gray("\u2500".repeat(40)));
+      for (const comment of commentsResult.page) {
+        const author = comment.author ? `@${comment.author.username}` : "unknown";
+        const edited = comment.editedAt ? chalk13.gray(" (edited)") : "";
+        console.log(
+          `  ${chalk13.bold(author)} \u2014 ${relativeTime(comment.createdAt)}${edited}`
+        );
+        console.log(`  ${comment.body}`);
+        if (comment.replies && comment.replies.length > 0) {
+          for (const reply of comment.replies) {
+            const replyAuthor = reply.author ? `@${reply.author.username}` : "unknown";
+            const replyEdited = reply.editedAt ? chalk13.gray(" (edited)") : "";
+            console.log(
+              `    ${chalk13.bold(replyAuthor)} \u2014 ${relativeTime(reply.createdAt)}${replyEdited}`
+            );
+            console.log(`    ${reply.body}`);
+          }
+        }
+        console.log("");
+      }
+    } else {
+      console.log(chalk13.gray("No comments yet."));
+    }
+  } catch (err) {
+    spinner.fail(
+      chalk13.red(`Failed to load issue: ${err.message}`)
+    );
+    process.exit(EXIT_CODES.NETWORK_ERROR);
+  }
+}
+async function handleIssuesClose(specRef, issueNumber) {
+  const creds = await requireAuth();
+  const api2 = await loadApi();
+  const client = await getConvexClient(creds.token);
+  const spinner = (await import("ora")).default(`Closing issue #${issueNumber}...`).start();
+  try {
+    const spec = await resolveSpec(client, api2, specRef);
+    const issue = await client.query(api2.issues.get, {
+      specId: spec._id,
+      number: issueNumber
+    });
+    if (!issue) {
+      spinner.fail(chalk13.red(`Issue #${issueNumber} not found on ${spec.scopedName}`));
+      process.exit(EXIT_CODES.VALIDATION_ERROR);
+    }
+    await client.mutation(api2.issues.close, {
+      issueId: issue._id
+    });
+    spinner.succeed(
+      chalk13.green(`Issue #${issueNumber} closed on ${spec.scopedName}`)
+    );
+  } catch (err) {
+    spinner.fail(chalk13.red(`Failed to close issue: ${err.message}`));
+    process.exit(EXIT_CODES.NETWORK_ERROR);
+  }
+}
+async function handleIssuesReopen(specRef, issueNumber) {
+  const creds = await requireAuth();
+  const api2 = await loadApi();
+  const client = await getConvexClient(creds.token);
+  const spinner = (await import("ora")).default(`Reopening issue #${issueNumber}...`).start();
+  try {
+    const spec = await resolveSpec(client, api2, specRef);
+    const issue = await client.query(api2.issues.get, {
+      specId: spec._id,
+      number: issueNumber
+    });
+    if (!issue) {
+      spinner.fail(chalk13.red(`Issue #${issueNumber} not found on ${spec.scopedName}`));
+      process.exit(EXIT_CODES.VALIDATION_ERROR);
+    }
+    await client.mutation(api2.issues.reopen, {
+      issueId: issue._id
+    });
+    spinner.succeed(
+      chalk13.green(`Issue #${issueNumber} reopened on ${spec.scopedName}`)
+    );
+  } catch (err) {
+    spinner.fail(
+      chalk13.red(`Failed to reopen issue: ${err.message}`)
+    );
+    process.exit(EXIT_CODES.NETWORK_ERROR);
+  }
+}
+function createIssuesCommand() {
+  return new Command13("issues").description("Manage issues on a spec").argument("<spec-id>", "Spec scoped name (@user/name) or document ID").argument("[action-or-number]", 'Issue number or "create"').argument("[action]", '"close" or "reopen" (with issue number)').option(
+    "-s, --status <status>",
+    "Filter by status: open, closed, all (default: open)"
+  ).option("--label <label>", "Filter by label").action(
+    async (specId, actionOrNumber, action, opts) => {
+      try {
+        if (!actionOrNumber) {
+          await handleIssuesList(specId, opts);
+        } else if (actionOrNumber === "create") {
+          await handleIssuesCreate(specId);
+        } else {
+          const issueNumber = parseInt(actionOrNumber, 10);
+          if (isNaN(issueNumber) || issueNumber < 1) {
+            console.error(
+              chalk13.red(
+                `Invalid issue number or action: "${actionOrNumber}". Use a number or "create".`
+              )
+            );
+            process.exit(EXIT_CODES.VALIDATION_ERROR);
+          }
+          if (!action) {
+            await handleIssuesView(specId, issueNumber);
+          } else if (action === "close") {
+            await handleIssuesClose(specId, issueNumber);
+          } else if (action === "reopen") {
+            await handleIssuesReopen(specId, issueNumber);
+          } else {
+            console.error(
+              chalk13.red(
+                `Unknown action: "${action}". Use "close" or "reopen".`
+              )
+            );
+            process.exit(EXIT_CODES.VALIDATION_ERROR);
+          }
+        }
+      } catch (err) {
+        const error = err;
+        if (error.code === String(EXIT_CODES.AUTH_ERROR)) {
+          console.error(chalk13.red(error.message));
+          process.exit(EXIT_CODES.AUTH_ERROR);
+        }
+        console.error(chalk13.red(`Error: ${error.message}`));
+        process.exit(EXIT_CODES.NETWORK_ERROR);
+      }
+    }
+  );
+}
+
+// src/commands/comment.ts
+import { Command as Command14 } from "commander";
+import chalk14 from "chalk";
+async function handleComment(targetType, targetRef, body, opts) {
+  const creds = await requireAuth();
+  let api2;
+  try {
+    api2 = (await import("./api-GIDUNUXG.js")).api;
+  } catch {
+    console.error(
+      chalk14.red("Error: Could not load Convex API bindings. Is CONVEX_URL configured?")
+    );
+    process.exit(EXIT_CODES.NETWORK_ERROR);
+  }
+  const client = await getConvexClient(creds.token);
+  const spinner = (await import("ora")).default("Posting comment...").start();
+  try {
+    let resolvedTargetType;
+    let resolvedTargetId;
+    if (targetType === "spec") {
+      resolvedTargetType = "spec";
+      const isScopedName = targetRef.startsWith("@") || targetRef.includes("/");
+      const spec = await client.query(
+        api2.specs.get,
+        isScopedName ? { scopedName: targetRef } : { specId: targetRef }
+      );
+      if (!spec) {
+        spinner.fail(chalk14.red(`Spec not found: ${targetRef}`));
+        process.exit(EXIT_CODES.VALIDATION_ERROR);
+      }
+      resolvedTargetId = spec._id;
+    } else if (targetType === "issue") {
+      resolvedTargetType = "issue";
+      const hashIndex = targetRef.lastIndexOf("#");
+      if (hashIndex === -1) {
+        spinner.fail(
+          chalk14.red(
+            "Invalid issue reference. Use format: @user/spec#<number>"
+          )
+        );
+        process.exit(EXIT_CODES.VALIDATION_ERROR);
+      }
+      const specRef = targetRef.slice(0, hashIndex);
+      const issueNumber = parseInt(targetRef.slice(hashIndex + 1), 10);
+      if (isNaN(issueNumber) || issueNumber < 1) {
+        spinner.fail(
+          chalk14.red(`Invalid issue number in "${targetRef}". Use format: @user/spec#<number>`)
+        );
+        process.exit(EXIT_CODES.VALIDATION_ERROR);
+      }
+      const isScopedName = specRef.startsWith("@") || specRef.includes("/");
+      const spec = await client.query(
+        api2.specs.get,
+        isScopedName ? { scopedName: specRef } : { specId: specRef }
+      );
+      if (!spec) {
+        spinner.fail(chalk14.red(`Spec not found: ${specRef}`));
+        process.exit(EXIT_CODES.VALIDATION_ERROR);
+      }
+      const issue = await client.query(api2.issues.get, {
+        specId: spec._id,
+        number: issueNumber
+      });
+      if (!issue) {
+        spinner.fail(
+          chalk14.red(`Issue #${issueNumber} not found on ${spec.scopedName}`)
+        );
+        process.exit(EXIT_CODES.VALIDATION_ERROR);
+      }
+      resolvedTargetId = issue._id;
+    } else if (targetType === "bounty") {
+      resolvedTargetType = "bounty";
+      resolvedTargetId = targetRef;
+    } else {
+      spinner.fail(
+        chalk14.red(
+          `Invalid target type: "${targetType}". Use "spec", "issue", or "bounty".`
+        )
+      );
+      process.exit(EXIT_CODES.VALIDATION_ERROR);
+    }
+    const args = {
+      targetType: resolvedTargetType,
+      targetId: resolvedTargetId,
+      body: body.trim()
+    };
+    if (opts.reply) {
+      args.parentId = opts.reply;
+    }
+    await client.mutation(api2.comments.create, args);
+    spinner.succeed(chalk14.green(`Comment posted on ${targetType} ${targetRef}`));
+  } catch (err) {
+    spinner.fail(chalk14.red(`Failed to post comment: ${err.message}`));
+    process.exit(EXIT_CODES.NETWORK_ERROR);
+  }
+}
+function createCommentCommand() {
+  return new Command14("comment").description("Post a comment on a spec, issue, or bounty (requires login)").argument(
+    "<target-type>",
+    "Target type: spec, issue, or bounty"
+  ).argument(
+    "<target-ref>",
+    "Target reference (e.g., @user/spec, @user/spec#3, bounty-id)"
+  ).argument("<body>", "Comment body text").option(
+    "--reply <comment-id>",
+    "Reply to a specific comment (threading)"
+  ).action(
+    async (targetType, targetRef, body, opts) => {
+      try {
+        await handleComment(targetType, targetRef, body, opts);
+      } catch (err) {
+        const error = err;
+        if (error.code === String(EXIT_CODES.AUTH_ERROR)) {
+          console.error(chalk14.red(error.message));
+          process.exit(EXIT_CODES.AUTH_ERROR);
+        }
+        console.error(chalk14.red(`Error: ${error.message}`));
+        process.exit(EXIT_CODES.NETWORK_ERROR);
+      }
+    }
+  );
+}
+
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
 var _require2 = createRequire2(import.meta.url);
@@ -2277,6 +3968,8 @@ program.addCommand(createSearchCommand());
 program.addCommand(createInfoCommand());
 program.addCommand(createPublishCommand());
 program.addCommand(createForkCommand());
+program.addCommand(createIssuesCommand());
+program.addCommand(createCommentCommand());
 program.addCommand(createReportCommand());
 program.addCommand(createConfigCommand());
 program.parseAsync(process.argv).catch((err) => {