@specmarket/cli 0.0.5 → 0.0.6

package/dist/index.js

@@ -2,7 +2,11 @@
 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,
@@ -13,7 +17,7 @@ import {
   specYamlSchema,
   specmarketSidecarSchema,
   transformInfrastructure
-} from "./chunk-DLEMNRTH.js";
+} from "./chunk-OTXWWFAO.js";
 import {
   api
 } from "./chunk-JEUDDJP7.js";
@@ -169,9 +173,7 @@ async function handleTokenLogin(token) {
   }
 }
 async function handleDeviceCodeLogin() {
-  const config = await import("./config-OAU6SJLC.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 {
@@ -346,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
 
@@ -492,26 +661,26 @@ var TASKS_MD_TEMPLATE = (displayName) => `# Tasks
 
 ## Discovered Issues
 `;
-async function handleInit(opts) {
+async function promptMetadataOnly(defaultDisplayName) {
   const { default: inquirer } = await import("inquirer");
   const answers = await inquirer.prompt([
     {
       type: "input",
-      name: "name",
-      message: "Spec name (lowercase, hyphens only):",
-      default: opts.name ?? "my-spec",
-      validate: (v) => /^[a-z0-9-]+$/.test(v) || "Must be lowercase alphanumeric with hyphens"
+      name: "displayName",
+      message: "Display name for the marketplace:",
+      default: defaultDisplayName ?? "My Spec"
     },
     {
       type: "input",
-      name: "displayName",
-      message: "Display name:",
-      default: (answers2) => answers2.name.split("-").map((w) => w[0]?.toUpperCase() + w.slice(1)).join(" ")
+      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, press Enter to skip):",
+      message: "What SaaS product does this replace? (optional, Enter to skip):",
       default: ""
     },
     {
@@ -540,204 +709,298 @@ async function handleInit(opts) {
       ]
     }
   ]);
-  const targetDir = resolve(opts.path ?? 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 data = {
-      name: answers.name,
-      displayName: answers.displayName,
-      replacesSaas: answers.replacesSaas || void 0,
-      outputType: answers.outputType,
-      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, "TASKS.md"), TASKS_MD_TEMPLATE(answers.displayName))
-    ]);
-    spinner.succeed(chalk4.green(`Spec created at ${targetDir}`));
-    console.log("");
-    console.log(chalk4.bold("Next steps:"));
-    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`)} 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) => {
-    try {
-      await handleInit(opts);
-    } catch (err) {
-      console.error(chalk4.red(`Init failed: ${err.message}`));
-      process.exit(EXIT_CODES.RUNTIME_ERROR);
-    }
-  });
-}
-
-// src/commands/validate.ts
-import { Command as Command5 } from "commander";
-import chalk5 from "chalk";
-import { readFile as readFile3, readdir as readdir2, access as access2 } from "fs/promises";
-import { join as join4, resolve as resolve2, relative, normalize } from "path";
-import { parse as parseYaml2 } from "yaml";
-
-// src/lib/format-detection.ts
-import { readFile as readFile2, readdir, access } from "fs/promises";
-import { join as join3 } from "path";
-import { parse as parseYaml } from "yaml";
-async function fileExists(filePath) {
-  try {
-    await access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
+  return {
+    displayName: answers.displayName,
+    description: answers.description,
+    replacesSaas: answers.replacesSaas || void 0,
+    outputType: answers.outputType,
+    primaryStack: answers.primaryStack
+  };
 }
-async function directoryExists(dirPath) {
+async function dirHasFiles(dir) {
   try {
-    await access(dirPath);
-    return true;
+    const entries = await readdir2(dir, { withFileTypes: true });
+    return entries.some((e) => e.isFile());
   } 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 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;
   }
-}
-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(join3(dir, entry.name));
-        if (found) return true;
+  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;
     }
-    return false;
-  } catch {
-    return false;
+    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;
   }
-}
-async function tryReadSidecar(dir) {
-  const path = join3(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 };
+  const answers = await inquirer.prompt([
+    {
+      type: "input",
+      name: "name",
+      message: "Spec name (lowercase, hyphens only):",
+      default: opts.name ?? "my-spec",
+      validate: (v) => /^[a-z0-9-]+$/.test(v) || "Must be lowercase alphanumeric with hyphens"
+    },
+    {
+      type: "input",
+      name: "displayName",
+      message: "Display name:",
+      default: (ans) => ans.name.split("-").map((w) => w[0]?.toUpperCase() + w.slice(1)).join(" ")
+    },
+    {
+      type: "input",
+      name: "replacesSaas",
+      message: "What SaaS product does this replace? (optional, press 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" }
+      ]
+    }
+  ]);
+  const targetDir = resolve(answers.name);
+  const spinner = ora2(`Creating spec directory at ${targetDir}...`).start();
+  try {
+    await mkdir2(targetDir, { 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;
     }
-    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(join3(dir, "spec.yaml"));
-  const hasPromptMd = await fileExists(join3(dir, "PROMPT.md"));
-  const hasSuccessCriteria = await fileExists(join3(dir, "SUCCESS_CRITERIA.md"));
-  if (hasSpecYaml && hasPromptMd && hasSuccessCriteria) {
-    return {
-      format: "specmarket-legacy",
-      detectedBy: "heuristic",
-      confidence: "high"
-    };
-  }
-  if (hasPromptMd && hasSuccessCriteria) {
-    return {
-      format: "specmarket-legacy",
-      detectedBy: "heuristic",
-      confidence: "high"
-    };
-  }
-  const hasSpecMd = await fileExists(join3(dir, "spec.md"));
-  const hasPlanMd = await fileExists(join3(dir, "plan.md"));
-  const hasTasksMd = await fileExists(join3(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(join3(dir, "prd.md"));
-  const hasArchitectureMd = await fileExists(join3(dir, "architecture.md"));
-  const storyFiles = await hasStoryFiles(dir);
-  if (hasPrdMd && (hasArchitectureMd || storyFiles)) {
-    return {
-      format: "bmad",
-      detectedBy: "heuristic",
-      confidence: "high"
+    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,
+      replacesSaas: answers.replacesSaas || void 0,
+      outputType: answers.outputType,
+      primaryStack: answers.primaryStack
     };
+    await Promise.all([
+      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("");
+    console.log(chalk4.bold("Next steps:"));
+    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")} 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;
   }
-  const prdJsonPath = join3(dir, "prd.json");
-  if (await fileExists(prdJsonPath)) {
+}
+function createInitCommand() {
+  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 {
-      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 {
+      await handleInit(opts);
+    } catch (err) {
+      console.error(chalk4.red(`Init failed: ${err.message}`));
+      process.exit(EXIT_CODES.RUNTIME_ERROR);
     }
-  }
-  if (await hasMarkdownFiles(dir)) {
-    return {
-      format: "custom",
-      detectedBy: "heuristic",
-      confidence: "low"
-    };
-  }
-  return {
-    format: "custom",
-    detectedBy: "heuristic",
-    confidence: "low"
-  };
+  });
 }
 
 // src/commands/validate.ts
+import { Command as Command5 } from "commander";
+import chalk5 from "chalk";
+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 entries = await readdir2(currentDir, { withFileTypes: true });
+    const entries = await readdir3(currentDir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = join4(currentDir, entry.name);
       if (entry.isDirectory()) {
@@ -819,7 +1082,7 @@ async function detectCircularReferences(dir) {
   }
   return cycles;
 }
-async function validateLegacySpec(dir, errors, warnings) {
+async function validateSpecmarketContent(dir, errors, warnings) {
   for (const file of REQUIRED_SPEC_FILES) {
     const filePath = join4(dir, file);
     try {
@@ -926,9 +1189,10 @@ async function validateSpec(specPath) {
   const dir = resolve2(specPath);
   const errors = [];
   const warnings = [];
-  const detection = await detectSpecFormat(dir);
+  let format;
+  let formatDetectedBy = "sidecar";
   try {
-    const entries = await readdir2(dir, { withFileTypes: true });
+    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");
@@ -937,7 +1201,10 @@ async function validateSpec(specPath) {
     errors.push("Directory is empty or unreadable");
   }
   const sidecarPath = join4(dir, SIDECAR_FILENAME);
-  if (await fileExists(sidecarPath)) {
+  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);
@@ -950,28 +1217,92 @@ async function validateSpec(specPath) {
         }
       } else {
         const sidecar = sidecarResult.data;
+        format = sidecar.spec_format;
         if (sidecar.estimated_tokens !== void 0) {
           if (sidecar.estimated_tokens < 1e3) {
             warnings.push(
-              `sidecar estimated_tokens (${sidecar.estimated_tokens}) seems very low.`
+              `estimated_tokens (${sidecar.estimated_tokens}) seems very low.`
             );
           }
           if (sidecar.estimated_tokens > 1e7) {
-            warnings.push(
-              `sidecar estimated_tokens (${sidecar.estimated_tokens}) seems very high.`
-            );
+            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(
-            `sidecar estimated_cost_usd ($${sidecar.estimated_cost_usd}) seems very low.`
+            `estimated_cost_usd ($${sidecar.estimated_cost_usd}) seems very low.`
           );
         }
         if (sidecar.estimated_time_minutes !== void 0 && sidecar.estimated_time_minutes < 1) {
           warnings.push(
-            `sidecar estimated_time_minutes (${sidecar.estimated_time_minutes}) seems unrealistically low.`
+            `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(
@@ -979,90 +1310,12 @@ async function validateSpec(specPath) {
       );
     }
   }
-  const hasSpecYaml = await fileExists(join4(dir, "spec.yaml"));
-  if (hasSpecYaml || detection.format === "specmarket-legacy") {
-    await validateLegacySpec(dir, errors, warnings);
-  }
-  switch (detection.format) {
-    case "specmarket-legacy":
-      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 raw = await readFile3(prdPath, "utf-8");
-        const data = JSON.parse(raw);
-        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;
-    }
-  }
   return {
     valid: errors.length === 0,
     errors,
     warnings,
-    format: detection.format,
-    formatDetectedBy: detection.detectedBy
+    format,
+    formatDetectedBy
   };
 }
 function createValidateCommand() {
@@ -1070,7 +1323,7 @@ function createValidateCommand() {
     try {
       const result = await validateSpec(specPath);
       if (result.format !== void 0) {
-        console.log(chalk5.gray(`Detected format: ${result.format}`));
+        console.log(chalk5.gray(`Format: ${result.format}`));
       }
       if (result.warnings.length > 0) {
         console.log(chalk5.yellow("\nWarnings:"));
@@ -1106,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 readFile5, mkdir as mkdir4, writeFile as writeFileFn } from "fs/promises";
-import { join as join6, resolve as resolve4, isAbsolute } from "path";
-import { parse as parseYaml3 } 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";
@@ -1139,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,
@@ -1171,45 +1429,474 @@ async function promptTelemetryOptIn() {
       default: false
     }
   ]);
-  const { saveConfig: saveConfig2 } = await import("./config-OAU6SJLC.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 readFile4, access as access3 } from "fs/promises";
-import { join as join5 } 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() {
+async function checkClaudeCliInstalled(harness) {
+  const h = harness ?? DEFAULT_HARNESS;
+  const binaryName = HARNESS_BINARY[h] ?? "claude";
   try {
-    await execAsync("which claude");
+    await execAsync(`which ${binaryName}`);
   } catch {
+    const installHint = HARNESS_INSTALL_HINT[h] ?? `Install ${binaryName} and ensure it is in your PATH.`;
     throw new Error(
-      `Claude CLI is not installed or not in your PATH.
+      `Harness "${h}" binary "${binaryName}" is not installed or not in your PATH.
 
-Installation instructions:
-  npm install -g @anthropic-ai/claude-code
-
-Or visit: https://www.anthropic.com/claude-code
+${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 = join5(homedir2(), CONFIG_PATHS.RUNS_DIR);
-  const runDir = opts.outputDir ?? join5(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 = {
@@ -1217,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,
@@ -1239,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();
@@ -1248,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 = {
@@ -1269,7 +1976,7 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
     iterations.push(iteration);
     onProgress?.(iteration);
     await writeFile3(
-      join5(runDir, `iteration-${i}.json`),
+      join6(runDir, `iteration-${i}.json`),
       JSON.stringify(iteration, null, 2)
     );
     await stageAllChanges(runDir);
@@ -1301,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,
@@ -1332,15 +2083,45 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
     cliVersion: opts.cliVersion
   };
   await writeFile3(
-    join5(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, join5(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);
 }
@@ -1368,36 +2149,54 @@ async function getGitDiff(dir) {
     return "";
   }
 }
-async function executeClaudeLoop(dir, model) {
-  return new Promise((resolve7) => {
-    const args = ["--print", "--output-format", "json"];
-    if (model) {
-      args.push("--model", 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(" ")}`;
     }
-    const proc = spawn("sh", ["-c", `cat PROMPT.md | 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 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 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) {
@@ -1416,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 {
@@ -1454,47 +2259,25 @@ 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 readFile4(join5(dir, "TASKS.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" },
     { file: "vitest.config.ts", cmd: "npx vitest run 2>&1" },
-    { file: "pytest.ini", cmd: "python -m pytest --tb=no -q 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 access3(join5(dir, runner.file));
+      await access3(join6(dir, runner.file));
     } catch {
       continue;
     }
@@ -1505,19 +2288,85 @@ async function runTests(dir) {
       });
       const combined = stdout + stderr;
       const hasFailed = /\d+ failed|\d+ error/i.test(combined);
-      return !hasFailed;
+      return { passed: !hasFailed, output: combined };
     } catch (err) {
-      if (err && typeof err === "object" && "code" in err && typeof err.code === "number") {
-        return false;
+      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 readFile4(join5(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) {
@@ -1536,7 +2385,7 @@ async function evaluateSuccessCriteria(dir) {
 }
 async function loadExistingReport(dir) {
   try {
-    const raw = await readFile4(join5(dir, "run-report.json"), "utf-8");
+    const raw = await readFile5(join6(dir, "run-report.json"), "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -1574,8 +2423,8 @@ async function handleRun(specPathOrId, opts) {
       console.log(chalk6.yellow(`  \u26A0 ${warning}`));
     }
   }
-  const specYamlContent = await readFile5(join6(specDir, "spec.yaml"), "utf-8");
-  const specYamlRaw = parseYaml3(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"));
@@ -1593,8 +2442,13 @@ 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();
+    await checkClaudeCliInstalled(opts.harness);
   } catch (err) {
     console.log(chalk6.red(`
 \u2717 ${err.message}`));
@@ -1602,13 +2456,43 @@ async function handleRun(specPathOrId, opts) {
   }
   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 {
@@ -1630,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();
@@ -1647,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) {
@@ -1758,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 = join6(tmpdir(), `specmarket-${randomUUID2()}`);
+  const tempDir = join7(tmpdir(), `specmarket-${randomUUID2()}`);
   await mkdir4(tempDir, { recursive: true });
   let response;
   try {
@@ -1775,7 +2667,7 @@ async function resolveSpecPath(pathOrId) {
     throw err;
   }
   const buffer = Buffer.from(await response.arrayBuffer());
-  const zipPath = join6(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}"`);
@@ -1787,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) {
@@ -2145,9 +3043,9 @@ function createInfoCommand() {
 import { Command as Command9 } from "commander";
 import chalk9 from "chalk";
 import ora4 from "ora";
-import { readFile as readFile6 } from "fs/promises";
-import { join as join7, resolve as resolve5 } from "path";
-import { parse as parseYaml4 } 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();
@@ -2168,8 +3066,8 @@ async function handlePublish(specPath, opts = {}) {
       spinner.succeed("Spec validated");
     }
     spinner.start("Reading spec metadata...");
-    const specYamlContent = await readFile6(join7(dir, "spec.yaml"), "utf-8");
-    const specYamlRaw = parseYaml4(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);
@@ -2184,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 readFile6(zipPath);
+    const zipContent = await readFile7(zipPath);
     const uploadResponse = await fetch(uploadUrl, {
       method: "POST",
       headers: { "Content-Type": "application/zip" },
@@ -2196,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 readFile6(join7(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,
@@ -2210,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,
@@ -2238,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 = join7(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 } });
@@ -2269,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 readFile7 } from "fs/promises";
-import { join as join8, resolve as resolve6 } from "path";
-import { parse as parseYaml5, 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();
@@ -2299,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 = join8(targetDir, "spec.yaml");
-    const specYamlContent = await readFile7(specYamlPath, "utf-8");
-    const specYamlData = parseYaml5(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";
@@ -2334,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 = join8(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 });
@@ -2361,15 +3260,15 @@ function createForkCommand() {
 // src/commands/report.ts
 import { Command as Command11 } from "commander";
 import chalk11 from "chalk";
-import { readFile as readFile8 } from "fs/promises";
-import { join as join9 } 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 = join9(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 readFile8(localPath, "utf-8");
+    const raw = await readFile9(localPath, "utf-8");
     report = JSON.parse(raw);
     source = "local";
   } catch {
@@ -2664,16 +3563,11 @@ async function handleIssuesList(specRef, opts) {
     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();
-    let issues = result.page;
-    if (opts.label) {
-      const label = opts.label.toLowerCase();
-      issues = issues.filter(
-        (i) => i.labels.some((l) => l.toLowerCase() === label)
-      );
-    }
+    const issues = result.page;
     if (issues.length === 0) {
       const statusLabel = statusFilter ?? "any";
       console.log(chalk13.gray(`No ${statusLabel} issues for ${spec.scopedName}`));