@specmarket/cli 0.0.4 → 0.0.5

package/dist/index.js

@@ -6,12 +6,14 @@ import {
   REQUIRED_SPEC_FILES,
   REQUIRED_STDLIB_FILES,
   RUN_DEFAULTS,
+  SIDECAR_FILENAME,
   TOKEN_EXPIRY_MS,
   loadConfig,
   saveConfig,
   specYamlSchema,
+  specmarketSidecarSchema,
   transformInfrastructure
-} from "./chunk-MS2DYACY.js";
+} from "./chunk-DLEMNRTH.js";
 import {
   api
 } from "./chunk-JEUDDJP7.js";
@@ -97,6 +99,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,7 +169,7 @@ async function handleTokenLogin(token) {
   }
 }
 async function handleDeviceCodeLogin() {
-  const config = await import("./config-R5KWZSJP.js").then((m) => m.loadConfig());
+  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 client = await getConvexClient();
@@ -355,7 +362,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 +406,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 +416,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 +475,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,6 +489,8 @@ var FIX_PLAN_TEMPLATE = (displayName) => `# Fix Plan
 - [ ] Implement UI/interface
 - [ ] Write integration tests
 - [ ] Update README.md
+
+## Discovered Issues
 `;
 async function handleInit(opts) {
   const { default: inquirer } = await import("inquirer");
@@ -549,7 +558,7 @@ async function handleInit(opts) {
       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(join2(targetDir, "TASKS.md"), TASKS_MD_TEMPLATE(answers.displayName))
     ]);
     spinner.succeed(chalk4.green(`Spec created at ${targetDir}`));
     console.log("");
@@ -557,8 +566,8 @@ 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;
@@ -578,123 +587,173 @@ function createInitCommand() {
 // 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, resolve as resolve2, relative, normalize } from "path";
+import { join as join3 } 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}`);
-    }
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
   }
-  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`);
+}
+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(join3(dir, entry.name));
+        if (found) return true;
       }
-    } catch {
-      errors.push(`Required file missing: stdlib/${file}`);
     }
+    return false;
+  } catch {
+    return false;
   }
-  let specYaml = null;
-  const specYamlPath = join3(dir, "spec.yaml");
+}
+async function tryReadSidecar(dir) {
+  const path = join3(dir, SIDECAR_FILENAME);
+  if (!await fileExists(path)) return null;
   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}`
-      );
+    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 };
     }
-  } else {
-    const parsed = parseResult.data;
+    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 prdJsonPath = join3(dir, "prd.json");
+  if (await fileExists(prdJsonPath)) {
     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"
-        );
+      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 {
     }
-    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(", ")})`
-            );
-          }
+  }
+  if (await hasMarkdownFiles(dir)) {
+    return {
+      format: "custom",
+      detectedBy: "heuristic",
+      confidence: "low"
+    };
+  }
+  return {
+    format: "custom",
+    detectedBy: "heuristic",
+    confidence: "low"
+  };
+}
+
+// src/commands/validate.ts
+async function collectFiles(currentDir, baseDir, extensions) {
+  const results = [];
+  try {
+    const entries = await readdir2(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 +763,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 +772,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 +819,259 @@ async function detectCircularReferences(dir) {
   }
   return cycles;
 }
-async function collectFiles(currentDir, baseDir, extensions) {
-  const results = [];
+async function validateLegacySpec(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 = [];
+  const detection = await detectSpecFormat(dir);
+  try {
+    const entries = await readdir2(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);
+  if (await fileExists(sidecarPath)) {
+    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;
+        if (sidecar.estimated_tokens !== void 0) {
+          if (sidecar.estimated_tokens < 1e3) {
+            warnings.push(
+              `sidecar estimated_tokens (${sidecar.estimated_tokens}) seems very low.`
+            );
+          }
+          if (sidecar.estimated_tokens > 1e7) {
+            warnings.push(
+              `sidecar 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.`
+          );
+        }
+        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.`
+          );
+        }
+      }
+    } catch (err) {
+      errors.push(
+        `${SIDECAR_FILENAME}: Failed to read or parse: ${err.message}`
+      );
+    }
+  }
+  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
+  };
 }
 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(`Detected format: ${result.format}`));
+      }
       if (result.warnings.length > 0) {
         console.log(chalk5.yellow("\nWarnings:"));
         for (const warning of result.warnings) {
@@ -819,9 +1106,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 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";
 
 // src/lib/telemetry.ts
 import createDebug5 from "debug";
@@ -884,15 +1171,15 @@ async function promptTelemetryOptIn() {
       default: false
     }
   ]);
-  const { saveConfig: saveConfig2 } = await import("./config-R5KWZSJP.js");
+  const { saveConfig: saveConfig2 } = await import("./config-OAU6SJLC.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 readFile4, access as access3 } from "fs/promises";
+import { join as join5 } from "path";
 import { homedir as homedir2 } from "os";
 import { randomUUID } from "crypto";
 import { exec } from "child_process";
@@ -900,12 +1187,27 @@ import { promisify } from "util";
 import createDebug6 from "debug";
 var debug6 = createDebug6("specmarket:runner");
 var execAsync = promisify(exec);
+async function checkClaudeCliInstalled() {
+  try {
+    await execAsync("which claude");
+  } catch {
+    throw new Error(
+      `Claude CLI 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
+`
+    );
+  }
+}
 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 runId = opts.resumeRunId ?? randomUUID();
-  const runsBaseDir = join4(homedir2(), CONFIG_PATHS.RUNS_DIR);
-  const runDir = opts.outputDir ?? join4(runsBaseDir, runId);
+  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);
   if (opts.dryRun) {
@@ -967,7 +1269,7 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
     iterations.push(iteration);
     onProgress?.(iteration);
     await writeFile3(
-      join4(runDir, `iteration-${i}.json`),
+      join5(runDir, `iteration-${i}.json`),
       JSON.stringify(iteration, null, 2)
     );
     await stageAllChanges(runDir);
@@ -1030,7 +1332,7 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
     cliVersion: opts.cliVersion
   };
   await writeFile3(
-    join4(runDir, "run-report.json"),
+    join5(runDir, "run-report.json"),
     JSON.stringify(report, null, 2)
   );
   debug6("Run complete: %s (status=%s, loops=%d)", runId, finalStatus, iterations.length);
@@ -1038,7 +1340,7 @@ async function runSpec(specDir, specYaml, opts, onProgress) {
 }
 async function copySpecFiles(srcDir, destDir) {
   const { cp } = await import("fs/promises");
-  await cp(srcDir, join4(destDir, "spec"), { recursive: true });
+  await cp(srcDir, join5(destDir, "spec"), { recursive: true });
   await cp(srcDir, destDir, { recursive: true, force: false });
   debug6("Spec files copied from %s to %s", srcDir, destDir);
 }
@@ -1072,7 +1374,7 @@ async function executeClaudeLoop(dir, model) {
     if (model) {
       args.push("--model", model);
     }
-    const proc = spawn("sh", ["-c", `cat PROMPT.md | claude-code ${args.join(" ")}`], {
+    const proc = spawn("sh", ["-c", `cat PROMPT.md | claude ${args.join(" ")}`], {
       cwd: dir,
       stdio: ["inherit", "pipe", "pipe"]
     });
@@ -1089,7 +1391,7 @@ async function executeClaudeLoop(dir, model) {
       resolve7({ stdout, exitCode: code ?? 0 });
     });
     proc.on("error", (err) => {
-      debug6("claude-code spawn error: %O", err);
+      debug6("claude spawn error: %O", err);
       resolve7({ stdout: "", exitCode: 1 });
     });
   });
@@ -1176,7 +1478,7 @@ async function checkCompletion(dir) {
 }
 async function isFixPlanEmpty(dir) {
   try {
-    const content = await readFile3(join4(dir, "fix_plan.md"), "utf-8");
+    const content = await readFile4(join5(dir, "TASKS.md"), "utf-8");
     const hasUncheckedItems = /^- \[ \]/m.test(content);
     return !hasUncheckedItems;
   } catch {
@@ -1185,22 +1487,29 @@ async function isFixPlanEmpty(dir) {
 }
 async function runTests(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=no -q 2>&1" },
+    { file: "Makefile", cmd: "make test 2>&1" }
   ];
   for (const runner of testRunners) {
     try {
-      await access2(join4(dir, runner.file));
+      await access3(join5(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);
+      const hasFailed = /\d+ failed|\d+ error/i.test(combined);
       return !hasFailed;
-    } catch {
+    } catch (err) {
+      if (err && typeof err === "object" && "code" in err && typeof err.code === "number") {
+        return false;
+      }
       continue;
     }
   }
@@ -1208,7 +1517,7 @@ async function runTests(dir) {
 }
 async function evaluateSuccessCriteria(dir) {
   try {
-    const content = await readFile3(join4(dir, "SUCCESS_CRITERIA.md"), "utf-8");
+    const content = await readFile4(join5(dir, "SUCCESS_CRITERIA.md"), "utf-8");
     const lines = content.split("\n");
     const results = [];
     for (const line of lines) {
@@ -1227,7 +1536,7 @@ async function evaluateSuccessCriteria(dir) {
 }
 async function loadExistingReport(dir) {
   try {
-    const raw = await readFile3(join4(dir, "run-report.json"), "utf-8");
+    const raw = await readFile4(join5(dir, "run-report.json"), "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -1265,8 +1574,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 readFile5(join6(specDir, "spec.yaml"), "utf-8");
+  const specYamlRaw = parseYaml3(specYamlContent);
   const specYaml = specYamlSchema.parse(specYamlRaw);
   console.log("");
   console.log(chalk6.yellow("\u26A0  SECURITY WARNING"));
@@ -1284,6 +1593,13 @@ async function handleRun(specPathOrId, opts) {
   if (authed && !opts.noTelemetry) {
     await promptTelemetryOptIn();
   }
+  try {
+    await checkClaudeCliInstalled();
+  } 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;
   console.log(chalk6.cyan(`
@@ -1375,10 +1691,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 +1758,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 = join6(tmpdir(), `specmarket-${randomUUID2()}`);
   await mkdir4(tempDir, { recursive: true });
   let response;
   try {
@@ -1459,7 +1775,7 @@ async function resolveSpecPath(pathOrId) {
     throw err;
   }
   const buffer = Buffer.from(await response.arrayBuffer());
-  const zipPath = join5(tempDir, "spec.zip");
+  const zipPath = join6(tempDir, "spec.zip");
   await writeFileFn(zipPath, buffer);
   const { execAsync: execAsync2 } = await import("./exec-K3BOXX3C.js");
   await execAsync2(`unzip -q "${zipPath}" -d "${tempDir}"`);
@@ -1471,7 +1787,7 @@ 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").action(async (pathOrId, opts) => {
     try {
       await handleRun(pathOrId, opts);
     } catch (err) {
@@ -1649,11 +1965,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 +2049,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 +2145,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 readFile6 } from "fs/promises";
+import { join as join7, resolve as resolve5 } from "path";
+import { parse as parseYaml4 } from "yaml";
 import { createWriteStream } from "fs";
 async function handlePublish(specPath, opts = {}) {
   const creds = await requireAuth();
@@ -1808,8 +2168,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 readFile6(join7(dir, "spec.yaml"), "utf-8");
+    const specYamlRaw = parseYaml4(specYamlContent);
     const specYaml = specYamlSchema.parse(specYamlRaw);
     spinner.succeed(`Loaded spec: ${specYaml.display_name} v${specYaml.version}`);
     const client = await getConvexClient(creds.token);
@@ -1824,7 +2184,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 readFile6(zipPath);
     const uploadResponse = await fetch(uploadUrl, {
       method: "POST",
       headers: { "Content-Type": "application/zip" },
@@ -1836,7 +2196,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 readFile6(join7(dir, "SPEC.md"), "utf-8").catch(() => void 0);
     const publishResult = await client.mutation(api2.specs.publish, {
       slug: specYaml.name,
       displayName: specYaml.display_name,
@@ -1878,7 +2238,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 = join7(tmpdir(), `spec-${randomUUID2()}.zip`);
   const archiver = (await import("archiver")).default;
   const output = createWriteStream(zipPath);
   const archive = archiver("zip", { zlib: { level: 9 } });
@@ -1909,9 +2269,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 readFile7 } from "fs/promises";
+import { join as join8, resolve as resolve6 } from "path";
+import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
 async function handleFork(specId, targetPath) {
   const creds = await requireAuth();
   const spinner = ora5("Loading spec info...").start();
@@ -1939,9 +2299,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 = join8(targetDir, "spec.yaml");
+    const specYamlContent = await readFile7(specYamlPath, "utf-8");
+    const specYamlData = parseYaml5(specYamlContent);
     specYamlData["forked_from_id"] = spec._id;
     specYamlData["forked_from_version"] = spec.currentVersion;
     specYamlData["version"] = "1.0.0";
@@ -1974,7 +2334,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 = join8(tmpdir(), `fork-${randomUUID2()}.zip`);
   const { writeFile: writeFileFn2, unlink: unlink2 } = await import("fs/promises");
   await writeFileFn2(zipPath, buffer);
   await mkdir5(targetDir, { recursive: true });
@@ -2001,15 +2361,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 readFile8 } from "fs/promises";
+import { join as join9 } 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 = join9(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 readFile8(localPath, "utf-8");
     report = JSON.parse(raw);
     source = "local";
   } catch {
@@ -2257,6 +2617,443 @@ 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,
+      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)
+      );
+    }
+    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 +3074,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) => {