@canivel/ralph 0.2.0

package/bin/ralph

@@ -0,0 +1,766 @@
+#!/usr/bin/env node
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const rawArgs = process.argv.slice(2);
+const args = [];
+const cwd = process.cwd();
+const repoRoot = path.resolve(__dirname, "..");
+const globalDir = path.join(repoRoot, ".agents", "ralph");
+const localDir = path.join(cwd, ".agents", "ralph");
+const skillsRoot = path.join(repoRoot, "skills");
+let agentOverride = null;
+let installSkills = false;
+let installForce = false;
+let prdPath = null;
+let progressPath = null;
+let prdOutPath = null;
+
+function exists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readPackageMeta() {
+  try {
+    const pkgPath = path.join(repoRoot, "package.json");
+    const data = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    return { name: data.name || "ralph", version: data.version || "0.0.0" };
+  } catch {
+    return { name: "ralph", version: "0.0.0" };
+  }
+}
+
+function compareVersions(a, b) {
+  const parse = (value) =>
+    String(value || "")
+      .split(".")
+      .map((part) => parseInt(part, 10))
+      .map((n) => (Number.isNaN(n) ? 0 : n));
+  const pa = parse(a);
+  const pb = parse(b);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i += 1) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da > db) return 1;
+    if (da < db) return -1;
+  }
+  return 0;
+}
+
+function checkForUpdate() {
+  if (!process.stdout.isTTY || !process.stdin.isTTY) return null;
+  if (process.env.RALPH_SKIP_UPDATE_CHECK === "1") return null;
+  const { name, version } = readPackageMeta();
+  const result = spawnSync("npm", ["view", name, "version"], { encoding: "utf-8" });
+  if (result.status !== 0) return null;
+  const latest = String(result.stdout || "").trim();
+  if (!latest) return null;
+  if (compareVersions(latest, version) <= 0) return null;
+  return { name, current: version, latest };
+}
+
+function usage() {
+  console.log(`ralph <command>
+
+Commands:
+  install [--skills] [--force]        Copy .agents/ralph into the current repo
+  prd ["<request>"] [--out path]      Generate a PRD (JSON) via agent
+  ping                                Minimal agent health check
+  log "<message>"                     Append to .ralph/activity.log
+  build [n] [--no-commit]             Run build loop (default)
+  overview                            Render a human overview from PRD JSON
+  config                              Configure default agent
+  help                                Show this message
+
+Options:
+  --prd <path>                        Override PRD path
+  --out <path>                        Override PRD output path (prd command)
+  --progress <path>                   Override progress log path
+  --agent <codex|claude|droid|opencode>  Override agent runner
+
+Notes:
+- Uses local .agents/ralph if present; otherwise uses bundled defaults.
+- State and logs are written to .ralph/ in the project.
+- On first run, you'll be prompted to select your default agent.
+`);
+}
+
+function getGlobalConfigPath() {
+  return path.join(os.homedir(), ".ralph", "config.json");
+}
+
+function loadGlobalConfig() {
+  const configPath = getGlobalConfigPath();
+  try {
+    if (exists(configPath)) {
+      return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    }
+  } catch {
+    // ignore parse errors
+  }
+  return {};
+}
+
+function saveGlobalConfig(config) {
+  const configPath = getGlobalConfigPath();
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+async function promptForDefaultAgent(currentDefault) {
+  const { intro, outro, select, isCancel } = await import("@clack/prompts");
+  intro("Ralph Configuration");
+
+  const agent = await select({
+    message: "Select your default agent",
+    options: [
+      { value: "claude", label: "claude (Anthropic Claude CLI)" },
+      { value: "codex", label: "codex (OpenAI Codex CLI)" },
+      { value: "droid", label: "droid (Factory Droid CLI)" },
+      { value: "opencode", label: "opencode (OpenCode CLI)" },
+    ],
+    initialValue: currentDefault || "claude",
+  });
+
+  if (isCancel(agent)) {
+    outro("Cancelled. Using default: codex");
+    return null;
+  }
+
+  outro(`Default agent set to: ${agent}`);
+  return agent;
+}
+
+async function ensureFirstRunConfig() {
+  // Skip if not interactive TTY
+  if (!process.stdout.isTTY || !process.stdin.isTTY) return null;
+
+  const config = loadGlobalConfig();
+  if (config.defaultAgent) {
+    return config.defaultAgent;
+  }
+
+  // First run - prompt for agent selection
+  const agent = await promptForDefaultAgent("claude");
+  if (agent) {
+    config.defaultAgent = agent;
+    config.configuredAt = new Date().toISOString();
+    saveGlobalConfig(config);
+  }
+  return agent;
+}
+
+function findPrdCandidates(baseDir) {
+  const tasksDir = path.join(baseDir, ".agents", "tasks");
+  if (!exists(tasksDir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(tasksDir)
+    .filter((name) => name.toLowerCase().endsWith(".json"))
+    .map((name) => path.join(tasksDir, name));
+}
+
+function defaultPrdOutputPath(baseDir, request) {
+  return path.join(baseDir, ".agents", "tasks");
+}
+
+async function resolvePrdPath({ cwd, explicitPath, label }) {
+  if (explicitPath) {
+    return path.resolve(cwd, explicitPath);
+  }
+  const candidates = findPrdCandidates(cwd);
+  if (candidates.length === 0) {
+    return null;
+  }
+  if (candidates.length === 1) {
+    return candidates[0];
+  }
+  const { intro, select, outro, isCancel } = await import("@clack/prompts");
+  intro(label || "Select PRD");
+  const selection = await select({
+    message: "Pick a PRD JSON file",
+    options: candidates.map((file) => ({
+      value: file,
+      label: path.relative(cwd, file),
+    })),
+  });
+  if (isCancel(selection)) {
+    outro("Cancelled.");
+    process.exit(0);
+  }
+  outro("Selected.");
+  return selection;
+}
+
+for (let i = 0; i < rawArgs.length; i += 1) {
+  const arg = rawArgs[i];
+  if (arg.startsWith("--agent=")) {
+    agentOverride = arg.split("=").slice(1).join("=");
+    continue;
+  }
+  if (arg === "--agent") {
+    agentOverride = rawArgs[i + 1];
+    i += 1;
+    continue;
+  }
+  if (arg === "--skills") {
+    installSkills = true;
+    continue;
+  }
+  if (arg === "--force") {
+    installForce = true;
+    continue;
+  }
+  if (arg.startsWith("--prd=")) {
+    prdPath = arg.split("=").slice(1).join("=");
+    continue;
+  }
+  if (arg.startsWith("--out=")) {
+    prdOutPath = arg.split("=").slice(1).join("=");
+    continue;
+  }
+  if (arg === "--prd") {
+    prdPath = rawArgs[i + 1];
+    i += 1;
+    continue;
+  }
+  if (arg === "--out") {
+    prdOutPath = rawArgs[i + 1];
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith("--progress=")) {
+    progressPath = arg.split("=").slice(1).join("=");
+    continue;
+  }
+  if (arg === "--progress") {
+    progressPath = rawArgs[i + 1];
+    i += 1;
+    continue;
+  }
+  args.push(arg);
+}
+
+const cmd = args[0];
+if (cmd === "help" || cmd === "-h" || cmd === "--help") {
+  usage();
+  process.exit(0);
+}
+
+async function runInstallSkills() {
+  const { intro, outro, select, isCancel } = await import("@clack/prompts");
+  intro("Ralph skills install");
+
+  const agent = await select({
+    message: "Which agent are you using?",
+    options: [
+      { value: "codex", label: "codex" },
+      { value: "claude", label: "claude" },
+      { value: "droid", label: "droid" },
+      { value: "opencode", label: "opencode" },
+    ],
+    initialValue: agentOverride || "codex",
+  });
+  if (isCancel(agent)) {
+    outro("Cancelled.");
+    process.exit(0);
+  }
+
+  const scope = await select({
+    message: "Where should skills be installed?",
+    options: [
+      { value: "local", label: "Local (project)" },
+      { value: "global", label: "Global (home directory)" },
+    ],
+    initialValue: "local",
+  });
+  if (isCancel(scope)) {
+    outro("Cancelled.");
+    process.exit(0);
+  }
+
+  const home = os.homedir();
+  const targetRoot =
+    agent === "codex"
+      ? scope === "global"
+        ? path.join(home, ".codex", "skills")
+        : path.join(cwd, ".codex", "skills")
+      : agent === "claude"
+        ? scope === "global"
+          ? path.join(home, ".claude", "skills")
+          : path.join(cwd, ".claude", "skills")
+        : agent === "droid"
+          ? scope === "global"
+            ? path.join(home, ".factory", "skills")
+            : path.join(cwd, ".factory", "skills")
+          : scope === "global"
+            ? path.join(home, ".local", "share", "opencode", "skills")
+            : path.join(cwd, ".opencode", "skills");
+
+  const skillsToInstall = ["commit", "dev-browser", "prd"];
+  fs.mkdirSync(targetRoot, { recursive: true });
+  const installed = [];
+  const skipped = [];
+
+  for (const skill of skillsToInstall) {
+    const source = path.join(skillsRoot, skill);
+    const target = path.join(targetRoot, skill);
+    if (!exists(source)) {
+      skipped.push(`${skill} (missing in repo)`);
+      continue;
+    }
+    if (exists(target) && !installForce) {
+      skipped.push(`${skill} (already exists)`);
+      continue;
+    }
+    fs.cpSync(source, target, { recursive: true, force: true });
+    installed.push(skill);
+  }
+
+  if (installed.length) {
+    console.log(`Installed skills to ${targetRoot}: ${installed.join(", ")}`);
+  }
+  if (skipped.length) {
+    console.log(`Skipped: ${skipped.join(", ")}`);
+  }
+  outro("Done.");
+}
+
+async function main() {
+  // Handle config command first
+  if (cmd === "config") {
+    const config = loadGlobalConfig();
+    const agent = await promptForDefaultAgent(config.defaultAgent || "claude");
+    if (agent) {
+      config.defaultAgent = agent;
+      config.configuredAt = new Date().toISOString();
+      saveGlobalConfig(config);
+      console.log(`Configuration saved to ${getGlobalConfigPath()}`);
+    }
+    process.exit(0);
+  }
+
+  // Check for first-run configuration (skip for help/install commands)
+  if (cmd !== "help" && cmd !== "-h" && cmd !== "--help" && cmd !== "install") {
+    const configuredAgent = await ensureFirstRunConfig();
+    if (configuredAgent && !agentOverride) {
+      // Use configured agent as default if no override specified
+      process.env.DEFAULT_AGENT = configuredAgent;
+    }
+  }
+
+  const updateInfo = checkForUpdate();
+  if (updateInfo) {
+    const { intro, confirm, outro, isCancel } = await import("@clack/prompts");
+    intro("Ralph update available");
+    const shouldUpdate = await confirm({
+      message: `Update ${updateInfo.name} from ${updateInfo.current} to ${updateInfo.latest}?`,
+      initialValue: true,
+    });
+    if (isCancel(shouldUpdate)) {
+      outro("Skipped update.");
+    } else if (shouldUpdate) {
+      outro("Updating...");
+      const result = spawnSync("npm", ["i", "-g", `${updateInfo.name}@latest`], {
+        stdio: "inherit",
+      });
+      process.exit(result.status ?? 1);
+    } else {
+      outro("Skipped update.");
+    }
+  }
+
+  if (cmd === "install") {
+    if (exists(localDir) && !installForce) {
+      console.log(`.agents/ralph already exists at ${localDir}. Skipping templates.`);
+    } else {
+      if (!exists(globalDir)) {
+        console.error(`Bundled templates not found at ${globalDir}.`);
+        process.exit(1);
+      }
+      fs.mkdirSync(path.dirname(localDir), { recursive: true });
+      fs.cpSync(globalDir, localDir, { recursive: true, force: true });
+      console.log(`Installed .agents/ralph to ${localDir}`);
+    }
+    const readmeSrc = path.join(repoRoot, "README.md");
+    const diagramSrc = path.join(repoRoot, "diagram.svg");
+    const imageSrc = path.join(repoRoot, "ralph.webp");
+    if (exists(localDir)) {
+      const readmeDst = path.join(localDir, "README.md");
+      const diagramDst = path.join(localDir, "diagram.svg");
+      const imageDst = path.join(localDir, "ralph.webp");
+      if (exists(readmeSrc)) fs.copyFileSync(readmeSrc, readmeDst);
+      if (exists(diagramSrc)) fs.copyFileSync(diagramSrc, diagramDst);
+      if (exists(imageSrc)) fs.copyFileSync(imageSrc, imageDst);
+    }
+    if (installSkills) {
+      await runInstallSkills();
+    } else {
+      const { confirm, isCancel } = await import("@clack/prompts");
+      const wantsSkills = await confirm({
+        message: "Install skills (commit + dev-browser + prd)?",
+        initialValue: true,
+      });
+      if (isCancel(wantsSkills)) {
+        console.log("Skipped skills install.");
+      } else if (wantsSkills) {
+        await runInstallSkills();
+      }
+    }
+    process.exit(0);
+  }
+
+  const templateDir = exists(localDir) ? localDir : globalDir;
+  if (!exists(templateDir)) {
+    console.error("No .agents/ralph found locally and no bundled defaults available.");
+    process.exit(1);
+  }
+  if (templateDir === localDir) {
+    console.log(`Using local templates: ${localDir}`);
+  } else {
+    console.log(`Using bundled templates: ${globalDir}`);
+  }
+
+  const loopPath = path.join(templateDir, "loop.sh");
+  if (!exists(loopPath)) {
+    console.error(`loop.sh not found at ${loopPath}`);
+    process.exit(1);
+  }
+
+  const loopArgs = args.length ? args : ["build"];
+  const loadAgentMap = () => {
+    const defaults = {
+      codex: "codex exec --yolo --skip-git-repo-check -",
+      claude: "claude -p --dangerously-skip-permissions \"$(cat {prompt})\"",
+      droid: "droid exec --skip-permissions-unsafe -f {prompt}",
+      opencode: "opencode run \"$(cat {prompt})\"",
+    };
+    const interactiveDefaults = {
+      codex: "codex --yolo {prompt}",
+      claude: "claude --dangerously-skip-permissions {prompt}",
+      droid: "droid --skip-permissions-unsafe {prompt}",
+      opencode: "opencode --prompt {prompt}",
+    };
+    const agentsPath = path.join(templateDir, "agents.sh");
+    if (!exists(agentsPath)) {
+      return {
+        headless: defaults,
+        interactive: interactiveDefaults,
+        defaultAgent: "codex",
+      };
+    }
+    const safePath = agentsPath.replace(/'/g, "'\\''");
+    const bashCmd = [
+      `source '${safePath}'`,
+      'printf "DEFAULT_AGENT=%s\\n" "${DEFAULT_AGENT:-}"',
+      'printf "AGENT_CODEX_CMD=%s\\n" "${AGENT_CODEX_CMD:-}"',
+      'printf "AGENT_CLAUDE_CMD=%s\\n" "${AGENT_CLAUDE_CMD:-}"',
+      'printf "AGENT_DROID_CMD=%s\\n" "${AGENT_DROID_CMD:-}"',
+      'printf "AGENT_OPENCODE_CMD=%s\\n" "${AGENT_OPENCODE_CMD:-}"',
+      'printf "AGENT_CODEX_INTERACTIVE_CMD=%s\\n" "${AGENT_CODEX_INTERACTIVE_CMD:-}"',
+      'printf "AGENT_CLAUDE_INTERACTIVE_CMD=%s\\n" "${AGENT_CLAUDE_INTERACTIVE_CMD:-}"',
+      'printf "AGENT_DROID_INTERACTIVE_CMD=%s\\n" "${AGENT_DROID_INTERACTIVE_CMD:-}"',
+      'printf "AGENT_OPENCODE_INTERACTIVE_CMD=%s\\n" "${AGENT_OPENCODE_INTERACTIVE_CMD:-}"',
+    ].join("; ");
+    const result = spawnSync("bash", ["-lc", bashCmd], { encoding: "utf-8" });
+    if (result.status !== 0) {
+      return {
+        headless: defaults,
+        interactive: interactiveDefaults,
+        defaultAgent: "codex",
+      };
+    }
+    const parsed = new Map();
+    for (const line of String(result.stdout || "").split("\n")) {
+      if (!line) continue;
+      const idx = line.indexOf("=");
+      if (idx === -1) continue;
+      parsed.set(line.slice(0, idx), line.slice(idx + 1));
+    }
+    const readVar = (name) => parsed.get(name) || null;
+    return {
+      headless: {
+        codex: readVar("AGENT_CODEX_CMD") || defaults.codex,
+        claude: readVar("AGENT_CLAUDE_CMD") || defaults.claude,
+        droid: readVar("AGENT_DROID_CMD") || defaults.droid,
+        opencode: readVar("AGENT_OPENCODE_CMD") || defaults.opencode,
+      },
+      interactive: {
+        codex: readVar("AGENT_CODEX_INTERACTIVE_CMD") || interactiveDefaults.codex,
+        claude: readVar("AGENT_CLAUDE_INTERACTIVE_CMD") || interactiveDefaults.claude,
+        droid: readVar("AGENT_DROID_INTERACTIVE_CMD") || interactiveDefaults.droid,
+        opencode: readVar("AGENT_OPENCODE_INTERACTIVE_CMD") || interactiveDefaults.opencode,
+      },
+      defaultAgent: readVar("DEFAULT_AGENT") || "codex",
+    };
+  };
+  const agentDefs = loadAgentMap();
+  const agentMap = agentDefs.headless;
+  const agentInteractiveMap = agentDefs.interactive;
+  const defaultAgent = agentDefs.defaultAgent || "codex";
+  if (agentOverride) {
+    const mapped = agentMap[agentOverride];
+    if (!mapped) {
+      console.error(`Unknown agent: ${agentOverride}`);
+      console.error("Valid values: codex, claude, droid, opencode");
+      process.exit(1);
+    }
+    process.env.AGENT_CMD = mapped;
+  }
+  const env = { ...process.env, RALPH_ROOT: cwd };
+  if (!env.ACTIVITY_CMD) {
+    env.ACTIVITY_CMD = "ralph log";
+  }
+  if (progressPath) env.PROGRESS_PATH = progressPath;
+  if (templateDir === globalDir) {
+    env.PROMPT_BUILD = path.join(templateDir, "PROMPT_build.md");
+    env.GUARDRAILS_REF = path.join(templateDir, "references", "GUARDRAILS.md");
+    env.CONTEXT_REF = path.join(templateDir, "references", "CONTEXT_ENGINEERING.md");
+  }
+
+  if (cmd === "ping") {
+    const agentName = agentOverride || defaultAgent;
+    const agentCmd = agentMap[agentName];
+    if (!agentCmd) {
+      console.error("Unknown agent for ping.");
+      process.exit(1);
+    }
+    const agentBin = agentCmd.split(" ")[0];
+    const existsResult = spawnSync(`command -v ${agentBin}`, { shell: true, stdio: "ignore" });
+    if (existsResult.status !== 0) {
+      console.error(`Agent command not found: ${agentBin}`);
+      process.exit(1);
+    }
+    const promptFile = path.join(os.tmpdir(), `ralph-ping-${Date.now()}.txt`);
+    fs.writeFileSync(promptFile, "Reply with <end>pong</end> only.");
+    const escapePath = (value) => `'${String(value).replace(/'/g, "'\\''")}'`;
+    const rendered = agentCmd.includes("{prompt}")
+      ? agentCmd.replace(/\{prompt\}/g, escapePath(promptFile))
+      : `cat ${escapePath(promptFile)} | ${agentCmd}`;
+    const result = spawnSync(rendered, { shell: true, encoding: "utf-8" });
+    const output = `${result.stdout || ""}${result.stderr || ""}`;
+    if (!output.includes("<end>pong</end>")) {
+      console.error("Ping failed: missing <end>pong</end>.");
+      process.exit(1);
+    }
+    console.log("Ping OK.");
+    process.exit(0);
+  }
+
+  if (cmd === "plan") {
+    console.error("The plan command has been removed. Use `ralph build` with a JSON PRD.");
+    process.exit(1);
+  }
+
+  if (cmd === "log") {
+    const message = args.slice(1).join(" ").trim();
+    if (!message) {
+      console.error('Usage: ralph log "message"');
+      process.exit(1);
+    }
+    const activityLog = path.join(cwd, ".ralph", "activity.log");
+    fs.mkdirSync(path.dirname(activityLog), { recursive: true });
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    const stamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+    fs.appendFileSync(activityLog, `[${stamp}] ${message}\n`);
+    process.exit(0);
+  }
+
+  if (cmd === "prd") {
+    let request = args.slice(1).join(" ").trim();
+    if (!request) {
+      const { intro, outro, text, isCancel } = await import("@clack/prompts");
+      intro("Ralph PRD");
+      const response = await text({
+        message: "Describe the feature you want a PRD for",
+        placeholder: "Example: A lightweight uptime monitor with email alerts",
+      });
+      if (isCancel(response)) {
+        outro("Cancelled.");
+        process.exit(0);
+      }
+      request = String(response || "").trim();
+      if (!request) {
+        outro("No description provided.");
+        process.exit(1);
+      }
+      outro("Generating PRD...");
+    }
+
+    // Determine output path
+    const outputPath = prdOutPath || prdPath || path.join(cwd, ".agents", "tasks");
+    const prdOutputFile = outputPath.endsWith(".json")
+      ? outputPath
+      : path.join(outputPath, "prd.json");
+    fs.mkdirSync(path.dirname(prdOutputFile), { recursive: true });
+
+    // Find PRD skill file
+    let skillContent = "";
+    const skillPaths = [
+      path.join(cwd, ".claude", "skills", "prd", "SKILL.md"),
+      path.join(cwd, "skills", "prd", "SKILL.md"),
+      path.join(repoRoot, "skills", "prd", "SKILL.md"),
+    ];
+    for (const sp of skillPaths) {
+      if (exists(sp)) {
+        skillContent = fs.readFileSync(sp, "utf-8");
+        break;
+      }
+    }
+
+    // Build the prompt
+    const promptLines = [
+      "You are an autonomous coding agent.",
+      "",
+    ];
+    if (skillContent) {
+      promptLines.push(skillContent);
+      promptLines.push("");
+      promptLines.push("---");
+      promptLines.push("");
+    }
+    promptLines.push("# Output Requirements");
+    promptLines.push("");
+    promptLines.push(`Save the PRD JSON to: ${prdOutputFile}`);
+    promptLines.push("");
+    promptLines.push("Do NOT implement anything. Only generate the JSON PRD file.");
+    promptLines.push("");
+    promptLines.push("After saving the PRD, end your response with:");
+    promptLines.push("PRD JSON saved to <path>. Close this chat and run `ralph build`.");
+    promptLines.push("");
+    promptLines.push("---");
+    promptLines.push("");
+    promptLines.push("# User Request");
+    promptLines.push("");
+    promptLines.push(request);
+
+    const promptFile = path.join(os.tmpdir(), `ralph-prd-${Date.now()}.md`);
+    fs.writeFileSync(promptFile, promptLines.join("\n"));
+
+    // Spawn the agent directly
+    const agentName = agentOverride || defaultAgent;
+    console.log(`Using agent: ${agentName}`);
+    console.log(`PRD will be saved to: ${prdOutputFile}`);
+    console.log("");
+
+    let result;
+    if (agentName === "claude") {
+      // Spawn claude directly with proper stdio inheritance
+      result = spawnSync("claude", ["--dangerously-skip-permissions", promptFile], {
+        stdio: "inherit",
+        cwd,
+        env: { ...process.env },
+        shell: true,
+      });
+    } else {
+      // For other agents, use loop.sh
+      const requestFile = path.join(os.tmpdir(), `ralph-prd-req-${Date.now()}.md`);
+      fs.writeFileSync(requestFile, `${request}\n`);
+      env.PRD_PATH = prdOutputFile;
+      const prdAgent = agentInteractiveMap[agentName] || agentMap[agentName];
+      if (prdAgent) {
+        env.PRD_AGENT_CMD = prdAgent;
+      }
+      const prdArgs = ["prd", "--prompt", requestFile];
+      result = spawnSync(loopPath, prdArgs, {
+        stdio: "inherit",
+        env,
+      });
+    }
+    process.exit(result.status ?? 1);
+  }
+
+  if (cmd === "overview") {
+    const resolvedPrdPath = await resolvePrdPath({
+      cwd,
+      explicitPath: prdPath,
+      label: "Ralph overview",
+    });
+    if (!resolvedPrdPath) {
+      console.error("No PRD JSON files found. Run `ralph prd` first.");
+      process.exit(1);
+    }
+    const prdText = fs.readFileSync(resolvedPrdPath, "utf-8");
+    let prd;
+    try {
+      prd = JSON.parse(prdText);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`Invalid PRD JSON: ${message}`);
+      process.exit(1);
+    }
+    const stories = Array.isArray(prd.stories) ? prd.stories : [];
+    const total = stories.length;
+    const done = stories.filter((s) => String(s.status || "open").toLowerCase() === "done").length;
+    const inProgress = stories.filter((s) => String(s.status || "open").toLowerCase() === "in_progress").length;
+    const open = total - done - inProgress;
+    const gates = Array.isArray(prd.qualityGates) ? prd.qualityGates : [];
+    const parsed = path.parse(resolvedPrdPath);
+    const overviewPath = path.join(parsed.dir, `${parsed.name}.overview.md`);
+
+    const lines = [];
+    lines.push(`# PRD Overview${prd.project ? `: ${prd.project}` : ""}`);
+    lines.push("");
+    lines.push(`- File: ${path.relative(cwd, resolvedPrdPath)}`);
+    lines.push(`- Stories: ${total} total (${open} open, ${inProgress} in_progress, ${done} done)`);
+    lines.push("");
+    lines.push("## Quality Gates");
+    if (gates.length === 0) {
+      lines.push("- (none)");
+    } else {
+      for (const gate of gates) lines.push(`- ${gate}`);
+    }
+    lines.push("");
+    lines.push("## Stories");
+    if (total === 0) {
+      lines.push("- (none)");
+    } else {
+      for (const story of stories) {
+        const status = String(story.status || "open").toLowerCase();
+        const depends = Array.isArray(story.dependsOn) && story.dependsOn.length
+          ? ` (depends on: ${story.dependsOn.join(", ")})`
+          : "";
+        lines.push(`- [${status}] ${story.id || "US-???"}: ${story.title || ""}${depends}`);
+      }
+    }
+    fs.writeFileSync(overviewPath, `${lines.join("\n")}\n`);
+    console.log(`Overview written to ${path.relative(cwd, overviewPath)}`);
+    process.exit(0);
+  }
+
+  const needsPrd = cmd === "build" || !cmd;
+  if (needsPrd) {
+    const resolvedPrdPath = await resolvePrdPath({
+      cwd,
+      explicitPath: prdPath,
+      label: "Ralph build",
+    });
+    if (!resolvedPrdPath) {
+      console.error("No PRD JSON files found. Run `ralph prd` first.");
+      process.exit(1);
+    }
+    env.PRD_PATH = resolvedPrdPath;
+  }
+
+  const result = spawnSync(loopPath, loopArgs, {
+    stdio: "inherit",
+    env,
+  });
+
+  process.exit(result.status ?? 1);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});