planforge 0.1.0

package/dist/commands/plan.js

@@ -0,0 +1,153 @@
+/**
+ * planforge plan <goal> - generate .cursor/plans/<summary>-<hash>.plan.md via configured planner provider
+ */
+import fs from "fs-extra";
+import { resolve } from "path";
+import { readFile } from "fs/promises";
+import { randomBytes } from "crypto";
+import { spawnSync } from "child_process";
+import { romanize } from "@daun_jung/korean-romanizer";
+import { getProjectRoot, getPlansDir } from "../utils/paths.js";
+import { getRepoContext } from "../utils/repo-context.js";
+import { getProjectContext } from "../utils/project-context.js";
+import { loadConfig } from "../config/load.js";
+import { getPlannerRunner } from "../providers/registry.js";
+/** Characters disallowed in filenames on Windows / macOS / Linux */
+const FILENAME_UNSAFE = /[\\/:*?"<>|]/g;
+function isSlugValid(slug) {
+    return slug.length > 0 && !/^-+$/.test(slug);
+}
+/** ASCII-only slug (a-z, 0-9, -). Used for ASCII-only mode and after romanization. */
+function slugifyAscii(text) {
+    const slug = text
+        .toLowerCase()
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/-+/g, "-")
+        .slice(0, 40);
+    return isSlugValid(slug) ? slug : "";
+}
+/** Slug that keeps Korean and Unicode; only removes filesystem-unsafe characters. */
+function slugifyForFilename(text) {
+    const s = text
+        .trim()
+        .replace(FILENAME_UNSAFE, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^[-.\s]+|[-.\s]+$/g, "")
+        .slice(0, 40);
+    return isSlugValid(s) ? s : "";
+}
+function shortHash() {
+    return randomBytes(4).toString("hex");
+}
+/** Extract first # title or first non-empty line from plan markdown for use as slug source. */
+function extractTitleFromPlanBody(planBody) {
+    const line = planBody
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (!line)
+        return "";
+    const match = line.match(/^#+\s*(.+)$/);
+    return (match ? match[1].trim() : line).slice(0, 80);
+}
+async function resolveContext(opts, cwd) {
+    if (!opts)
+        return undefined;
+    const parts = [];
+    if (opts.contextFile) {
+        const absPath = resolve(cwd, opts.contextFile);
+        try {
+            const content = await readFile(absPath, "utf-8");
+            if (content.trim())
+                parts.push(content.trim());
+        }
+        catch (err) {
+            console.error("Failed to read context file:", err.message);
+            process.exit(1);
+        }
+    }
+    if (opts.context?.trim())
+        parts.push(opts.context.trim());
+    if (parts.length === 0)
+        return undefined;
+    return parts.join("\n\n");
+}
+export async function runPlan(args, opts) {
+    const goal = args.join(" ").trim();
+    if (!goal) {
+        console.error("Usage: planforge plan <goal>");
+        process.exit(1);
+    }
+    const cwd = process.cwd();
+    const projectRoot = getProjectRoot(cwd);
+    const context = await resolveContext(opts, cwd);
+    const config = await loadConfig(projectRoot);
+    const runner = getPlannerRunner(config.planner.provider);
+    if (!runner) {
+        console.error(`Unknown planner provider: ${config.planner.provider}. Check planforge.json.`);
+        process.exit(1);
+    }
+    if (!runner.check()) {
+        console.error(`${config.planner.provider} CLI not found. Install the provider CLI to use planforge plan.`);
+        process.exit(1);
+    }
+    const repoContext = getRepoContext(projectRoot, goal);
+    const projectContext = getProjectContext(projectRoot);
+    try {
+        const planBody = await runner.runPlan(goal, {
+            cwd: projectRoot,
+            context,
+            repoContext,
+            projectContext,
+        });
+        const asciiOnly = config.planner.asciiSlug ?? process.env.PLANFORGE_ASCII_SLUG === "1";
+        let slug = asciiOnly ? slugifyAscii(goal) : slugifyForFilename(goal);
+        if (!isSlugValid(slug)) {
+            try {
+                const romanized = romanize(goal);
+                slug = slugifyAscii(romanized);
+            }
+            catch {
+                /* ignore romanization errors */
+            }
+        }
+        if (!isSlugValid(slug)) {
+            const title = extractTitleFromPlanBody(planBody);
+            if (title) {
+                slug = asciiOnly ? slugifyAscii(title) : slugifyForFilename(title);
+                if (!isSlugValid(slug)) {
+                    try {
+                        slug = slugifyAscii(romanize(title));
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+        }
+        if (!isSlugValid(slug)) {
+            slug = "plan";
+        }
+        const hash = shortHash();
+        const plansDir = getPlansDir(projectRoot);
+        await fs.ensureDir(plansDir);
+        const filename = `${slug}-${hash}.plan.md`;
+        const filePath = resolve(plansDir, filename);
+        await fs.writeFile(filePath, planBody, "utf-8");
+        console.log("Created:", filePath);
+        // Open the plan file in Cursor for review (user can then run /i when ready)
+        try {
+            spawnSync("cursor", [filePath], { stdio: "ignore", windowsHide: true });
+        }
+        catch {
+            /* cursor not in PATH or open failed; leave as-is */
+        }
+    }
+    catch (err) {
+        console.error("Plan generation failed:", err.message);
+        process.exit(1);
+    }
+}

package/dist/config/load.js

@@ -0,0 +1,17 @@
+/**
+ * Load planforge.json or fall back to preset for current providers.
+ */
+import fs from "fs-extra";
+import { resolve } from "path";
+import { getPresetForProviders } from "./presets.js";
+import { checkClaude } from "../providers/claude.js";
+import { checkCodex } from "../providers/codex.js";
+export async function loadConfig(projectRoot) {
+    const configPath = resolve(projectRoot, "planforge.json");
+    if (await fs.pathExists(configPath)) {
+        return (await fs.readJson(configPath));
+    }
+    const hasClaude = checkClaude();
+    const hasCodex = checkCodex();
+    return getPresetForProviders(hasClaude, hasCodex);
+}

package/dist/config/presets.js

@@ -0,0 +1,31 @@
+/**
+ * planforge.json presets per provider combination (both / claude-only / codex-only)
+ */
+const PRESET_BOTH = {
+    planner: { provider: "claude", model: "claude-opus-4-6", effort: "high" },
+    implementer: { provider: "codex", model: "gpt-5.4" },
+    plansDir: ".cursor/plans",
+};
+const PRESET_CLAUDE_ONLY = {
+    planner: { provider: "claude", model: "claude-opus-4-6", effort: "high" },
+    implementer: { provider: "claude", model: "claude-sonnet-4-6", effort: "medium" },
+    plansDir: ".cursor/plans",
+};
+const PRESET_CODEX_ONLY = {
+    planner: { provider: "codex", model: "gpt-5.4", reasoning: "high" },
+    implementer: { provider: "codex", model: "gpt-5.4", reasoning: "low" },
+    plansDir: ".cursor/plans",
+};
+/**
+ * Return the recommended preset for the given installed providers.
+ * Both -> p=Claude Opus 4.6, i=Codex 5.4; Claude only -> p=Opus, i=Sonnet; Codex only -> p/i=GPT-5.4 with different reasoning.
+ */
+export function getPresetForProviders(hasClaude, hasCodex) {
+    if (hasClaude && hasCodex)
+        return PRESET_BOTH;
+    if (hasClaude)
+        return PRESET_CLAUDE_ONLY;
+    if (hasCodex)
+        return PRESET_CODEX_ONLY;
+    return PRESET_CLAUDE_ONLY;
+}

package/dist/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * PlanForge CLI entry point.
+ */
+import { Command } from "commander";
+import { runInit } from "./commands/init.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runInstall } from "./commands/install.js";
+import { runPlan } from "./commands/plan.js";
+import { runImplement } from "./commands/implement.js";
+import { runConfigShow, runConfigSuggest } from "./commands/config.js";
+const program = new Command();
+program
+    .name("planforge")
+    .description("Bring your own AI to Cursor. Use Claude or Codex inside Cursor Free.")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Detect providers, run claude /init, create AGENTS.md, install Cursor slash commands, create .cursor/plans and planforge.json")
+    .option("--skip-provider-install", "Skip interactive provider (Claude/Codex) install prompt")
+    .action(async (opts) => {
+    await runInit(opts.skipProviderInstall ? ["--skip-provider-install"] : []);
+});
+program
+    .command("doctor")
+    .description("Check environment: Claude CLI, Codex CLI, CLAUDE.md, AGENTS.md, planforge.json, .cursor/plans")
+    .action(async () => {
+    await runDoctor([]);
+});
+program
+    .command("install")
+    .description("Install Cursor slash commands and templates to .cursor/skills and .cursor/rules")
+    .option("-f, --force", "Overwrite existing planforge.json")
+    .action(async (opts) => {
+    await runInstall(opts.force ? ["--force"] : []);
+});
+program
+    .command("plan")
+    .description("Generate a development plan and save to .cursor/plans (uses planner from planforge.json)")
+    .argument("[goal...]", "Planning goal (e.g. design auth refresh token)")
+    .option("--context-file <path>", "Path to conversation context file (e.g. .cursor/chat-context.txt)")
+    .option("--context <text>", "Conversation context text to pass to the planner")
+    .action(async (goalParts, opts) => {
+    await runPlan(goalParts, opts);
+});
+program
+    .command("implement")
+    .description("Run implementation (uses implementer from planforge.json)")
+    .argument("[prompt...]", "Implementation prompt or task")
+    .option("--context-file <path>", "Path to conversation context file (e.g. .cursor/chat-context.txt)")
+    .option("--context <text>", "Conversation context text to pass to the implementer")
+    .option("--plan-file <path>", "Path to plan file (default: index.json activePlan or latest .plan.md)")
+    .option("--files <paths...>", "File paths to focus on (overrides plan's Files Likely to Change)")
+    .action(async (promptParts, opts) => {
+    await runImplement(promptParts, opts);
+});
+const configCmd = program
+    .command("config")
+    .description("Show or suggest planforge.json config")
+    .action(async () => {
+    await runConfigShow([]);
+});
+configCmd
+    .command("show")
+    .description("Show current planforge.json")
+    .action(async () => {
+    await runConfigShow([]);
+});
+configCmd
+    .command("suggest")
+    .description("Suggest config for your installed providers (Current vs Suggested)")
+    .option("--apply", "Write suggested config to planforge.json")
+    .action(async (opts) => {
+    await runConfigSuggest(opts.apply ? ["--apply"] : []);
+});
+program.parse();

package/dist/providers/claude.js

@@ -0,0 +1,164 @@
+/**
+ * Claude provider - planning (e.g. /p)
+ */
+import { execSync, spawn } from "child_process";
+import { readFile } from "fs/promises";
+import { resolve, dirname } from "path";
+import { hasCommand } from "../utils/shell.js";
+import { getTemplatesRoot } from "../utils/paths.js";
+/** npm package for global install: npm install -g @anthropic-ai/claude-code */
+export const CLIENT_NPM_PACKAGE = "@anthropic-ai/claude-code";
+export function checkClaude() {
+    return hasCommand("claude");
+}
+/**
+ * Run Claude to generate a plan. Returns plan markdown.
+ */
+export async function runPlan(goal, opts) {
+    const cwd = opts?.cwd ?? process.cwd();
+    const templatesRoot = getTemplatesRoot();
+    const repoRoot = dirname(templatesRoot);
+    const defaultPromptPath = resolve(repoRoot, "packages", "core", "prompts", "planner-system.md");
+    let fullPrompt;
+    try {
+        const systemPrompt = await readFile(opts?.systemPromptPath ?? defaultPromptPath, "utf-8");
+        let body = systemPrompt.trim();
+        if (opts?.projectContext?.trim()) {
+            body += "\n\n---\n\nProject context (AGENTS.md):\n" + opts.projectContext.trim();
+        }
+        if (opts?.repoContext?.trim()) {
+            body += "\n\n---\n\nRepository context:\n" + opts.repoContext.trim();
+        }
+        if (opts?.context?.trim()) {
+            body += "\n\n---\n\nConversation context:\n" + opts.context.trim();
+        }
+        fullPrompt = body + "\n\n---\n\nUser goal: " + goal;
+    }
+    catch {
+        let fallback = "Produce a development plan with sections: Goal, Assumptions, Relevant Codebase Areas, Proposed Changes, Step-by-Step Plan, Files Likely to Change, Risks, Validation Checklist.";
+        if (opts?.projectContext?.trim()) {
+            fallback += "\n\n---\n\nProject context (AGENTS.md):\n" + opts.projectContext.trim();
+        }
+        if (opts?.repoContext?.trim()) {
+            fallback += "\n\n---\n\nRepository context:\n" + opts.repoContext.trim();
+        }
+        if (opts?.context?.trim()) {
+            fallback += "\n\n---\n\nConversation context:\n" + opts.context.trim();
+        }
+        fullPrompt = fallback + "\n\n---\n\nUser goal: " + goal;
+    }
+    try {
+        const out = execSync("claude", {
+            encoding: "utf-8",
+            input: fullPrompt,
+            cwd,
+            maxBuffer: 1024 * 1024,
+        });
+        return typeof out === "string" ? out.trim() : String(out).trim();
+    }
+    catch (err) {
+        const msg = err.stdout
+            ?? err.stderr
+            ?? err.message;
+        throw new Error("Claude plan failed: " + msg);
+    }
+}
+const DEFAULT_IMPLEMENTER_FALLBACK = "Implement the user request. Produce code or concrete changes as requested.";
+/**
+ * Run Claude to perform implementation. Returns implementation output (e.g. code or instructions).
+ */
+export async function runImplement(prompt, opts) {
+    const cwd = opts?.cwd ?? process.cwd();
+    const templatesRoot = getTemplatesRoot();
+    const repoRoot = dirname(templatesRoot);
+    const defaultPromptPath = resolve(repoRoot, "packages", "core", "prompts", "implementer-system.md");
+    let fullPrompt;
+    try {
+        const systemPrompt = await readFile(opts?.systemPromptPath ?? defaultPromptPath, "utf-8");
+        let body = systemPrompt.trim();
+        if (opts?.projectContext?.trim()) {
+            body += "\n\n---\n\nProject context (AGENTS.md):\n" + opts.projectContext.trim();
+        }
+        if (opts?.context?.trim()) {
+            body += "\n\n---\n\nConversation context:\n" + opts.context.trim();
+        }
+        if (opts?.planContent?.trim()) {
+            body += "\n\n---\n\nCurrent plan (follow this):\n" + opts.planContent.trim();
+        }
+        if (opts?.filesToChange?.length) {
+            body += "\n\n---\n\nFiles to focus on:\n" + opts.filesToChange.join("\n");
+        }
+        if (opts?.recentCommitsPerFile?.trim()) {
+            body += "\n\n---\n\nRecent commit (per file):\n" + opts.recentCommitsPerFile.trim();
+        }
+        if (opts?.codeContext?.trim()) {
+            body += "\n\n---\n\nRelevant file contents:\n" + opts.codeContext.trim();
+        }
+        fullPrompt = body + "\n\n---\n\nUser request: " + prompt;
+    }
+    catch {
+        let fallback = DEFAULT_IMPLEMENTER_FALLBACK;
+        if (opts?.projectContext?.trim()) {
+            fallback += "\n\n---\n\nProject context (AGENTS.md):\n" + opts.projectContext.trim();
+        }
+        if (opts?.context?.trim()) {
+            fallback += "\n\n---\n\nConversation context:\n" + opts.context.trim();
+        }
+        if (opts?.planContent?.trim()) {
+            fallback += "\n\n---\n\nCurrent plan (follow this):\n" + opts.planContent.trim();
+        }
+        if (opts?.filesToChange?.length) {
+            fallback += "\n\n---\n\nFiles to focus on:\n" + opts.filesToChange.join("\n");
+        }
+        if (opts?.recentCommitsPerFile?.trim()) {
+            fallback += "\n\n---\n\nRecent commit (per file):\n" + opts.recentCommitsPerFile.trim();
+        }
+        if (opts?.codeContext?.trim()) {
+            fallback += "\n\n---\n\nRelevant file contents:\n" + opts.codeContext.trim();
+        }
+        fullPrompt = fallback + "\n\n---\n\nUser request: " + prompt;
+    }
+    try {
+        return await runClaudeStreaming(fullPrompt, cwd);
+    }
+    catch (err) {
+        const msg = err.stdout
+            ?? err.stderr
+            ?? err.message;
+        throw new Error("Claude implement failed: " + msg);
+    }
+}
+/**
+ * Run Claude with streaming: forward stdout/stderr to the current process so the user
+ * sees logs in real time (e.g. in Cursor chat terminal). Returns collected stdout when done.
+ */
+function runClaudeStreaming(fullPrompt, cwd) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const child = spawn("claude", [], {
+            cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        child.stdin?.write(fullPrompt, "utf-8", (err) => {
+            if (err)
+                reject(err);
+            else
+                child.stdin?.end();
+        });
+        child.stdout?.on("data", (chunk) => {
+            chunks.push(chunk);
+            process.stdout.write(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+        });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error("Claude exited with code " + code));
+                return;
+            }
+            resolve(Buffer.concat(chunks).toString("utf-8").trim());
+        });
+        child.on("error", (err) => reject(err));
+    });
+}

package/dist/providers/codex.js

@@ -0,0 +1,224 @@
+/**
+ * Codex provider - planning (/p) and implementation (/i)
+ */
+import { randomBytes } from "crypto";
+import { spawnSync, spawn } from "child_process";
+import { writeFileSync, unlinkSync } from "fs";
+import { tmpdir } from "os";
+import { readFile } from "fs/promises";
+import { resolve, dirname, join } from "path";
+import { hasCommand } from "../utils/shell.js";
+import { getTemplatesRoot } from "../utils/paths.js";
+/** npm package for global install: npm install -g @openai/codex */
+export const CLIENT_NPM_PACKAGE = "@openai/codex";
+export function checkCodex() {
+    return hasCommand("codex");
+}
+function getRepoRoot() {
+    return dirname(getTemplatesRoot());
+}
+/**
+ * Run "codex exec" with the given prompt. On Windows uses temp file + PowerShell to avoid
+ * EINVAL from spawning .cmd directly (CVE-2024-27980) and to avoid shell splitting long args.
+ */
+function runCodexExec(fullPrompt, cwd) {
+    const opts = { cwd, encoding: "utf-8", maxBuffer: 1024 * 1024 };
+    if (process.platform === "win32") {
+        const tempPath = join(tmpdir(), "planforge-" + randomBytes(8).toString("hex") + ".txt");
+        try {
+            writeFileSync(tempPath, fullPrompt, "utf-8");
+            const escapedPath = tempPath.replace(/'/g, "''");
+            const script = `Get-Content -Raw -LiteralPath '${escapedPath}' | codex exec -`;
+            const result = spawnSync("powershell", ["-NoProfile", "-Command", script], opts);
+            if (result.status !== 0) {
+                const msg = result.stderr ?? result.stdout ?? result.error?.message ?? "Codex exited non-zero";
+                throw new Error(String(msg));
+            }
+            return (result.stdout ?? "").trim();
+        }
+        finally {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch {
+                // ignore cleanup failure
+            }
+        }
+    }
+    const result = spawnSync("codex", ["exec", fullPrompt], { ...opts, shell: false });
+    if (result.status !== 0) {
+        const msg = result.stderr ?? result.stdout ?? result.error?.message ?? "Codex exited non-zero";
+        throw new Error(String(msg));
+    }
+    return (result.stdout ?? "").trim();
+}
+/**
+ * Run "codex exec" with streaming: forward stdout/stderr to the current process so the user
+ * sees logs in real time (e.g. in Cursor chat terminal). Returns collected stdout when done.
+ */
+function runCodexExecStreaming(fullPrompt, cwd) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const opts = { cwd };
+        if (process.platform === "win32") {
+            const tempPath = join(tmpdir(), "planforge-" + randomBytes(8).toString("hex") + ".txt");
+            writeFileSync(tempPath, fullPrompt, "utf-8");
+            const escapedPath = tempPath.replace(/'/g, "''");
+            const script = `Get-Content -Raw -LiteralPath '${escapedPath}' | codex exec -`;
+            const child = spawn("powershell", ["-NoProfile", "-Command", script], {
+                ...opts,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            child.on("close", (code) => {
+                try {
+                    unlinkSync(tempPath);
+                }
+                catch {
+                    // ignore
+                }
+                if (code !== 0) {
+                    reject(new Error("Codex exited with code " + code));
+                    return;
+                }
+                resolve(Buffer.concat(chunks).toString("utf-8").trim());
+            });
+            child.stdout?.on("data", (chunk) => {
+                chunks.push(chunk);
+                process.stdout.write(chunk);
+            });
+            child.stderr?.on("data", (chunk) => {
+                process.stderr.write(chunk);
+            });
+            return;
+        }
+        const child = spawn("codex", ["exec", fullPrompt], {
+            ...opts,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout?.on("data", (chunk) => {
+            chunks.push(chunk);
+            process.stdout.write(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+        });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error("Codex exited with code " + code));
+                return;
+            }
+            resolve(Buffer.concat(chunks).toString("utf-8").trim());
+        });
+        child.on("error", (err) => reject(err));
+    });
+}
+const DEFAULT_PLANNER_FALLBACK = "Produce a development plan with sections: Goal, Assumptions, Relevant Codebase Areas, Proposed Changes, Step-by-Step Plan, Files Likely to Change, Risks, Validation Checklist.";
+/**
+ * Run Codex to generate a plan. Returns plan markdown.
+ */
+export async function runPlan(goal, opts) {
+    const cwd = opts?.cwd ?? process.cwd();
+    const repoRoot = getRepoRoot();
+    const defaultPromptPath = resolve(repoRoot, "packages", "core", "prompts", "planner-system.md");
+    let fullPrompt;
+    try {
+        const systemPrompt = await readFile(opts?.systemPromptPath ?? defaultPromptPath, "utf-8");
+        let body = systemPrompt.trim();
+        if (opts?.projectContext?.trim()) {
+            body += "\n\n---\n\nProject context (AGENTS.md):\n" + opts.projectContext.trim();
+        }
+        if (opts?.repoContext?.trim()) {
+            body += "\n\n---\n\nRepository context:\n" + opts.repoContext.trim();
+        }
+        if (opts?.context?.trim()) {
+            body += "\n\n---\n\nConversation context:\n" + opts.context.trim();
+        }
+        fullPrompt = body + "\n\n---\n\nUser goal: " + goal;
+    }
+    catch {
+        let fallback = DEFAULT_PLANNER_FALLBACK;
+        if (opts?.projectContext?.trim()) {
+            fallback += "\n\n---\n\nProject context (AGENTS.md):\n" + opts.projectContext.trim();
+        }
+        if (opts?.repoContext?.trim()) {
+            fallback += "\n\n---\n\nRepository context:\n" + opts.repoContext.trim();
+        }
+        if (opts?.context?.trim()) {
+            fallback += "\n\n---\n\nConversation context:\n" + opts.context.trim();
+        }
+        fullPrompt = fallback + "\n\n---\n\nUser goal: " + goal;
+    }
+    try {
+        return runCodexExec(fullPrompt, cwd);
+    }
+    catch (err) {
+        const msg = err.stdout
+            ?? err.stderr
+            ?? err.message;
+        throw new Error("Codex plan failed: " + msg);
+    }
+}
+const DEFAULT_IMPLEMENTER_FALLBACK = "Implement the user request. Produce code or concrete changes as requested.";
+/**
+ * Run Codex to perform implementation. Returns implementation output.
+ */
+export async function runImplement(prompt, opts) {
+    const cwd = opts?.cwd ?? process.cwd();
+    const repoRoot = getRepoRoot();
+    const defaultPromptPath = resolve(repoRoot, "packages", "core", "prompts", "implementer-system.md");
+    let fullPrompt;
+    try {
+        const systemPrompt = await readFile(opts?.systemPromptPath ?? defaultPromptPath, "utf-8");
+        let body = systemPrompt.trim();
+        if (opts?.projectContext?.trim()) {
+            body += "\n\n---\n\nProject context (AGENTS.md):\n" + opts.projectContext.trim();
+        }
+        if (opts?.context?.trim()) {
+            body += "\n\n---\n\nConversation context:\n" + opts.context.trim();
+        }
+        if (opts?.planContent?.trim()) {
+            body += "\n\n---\n\nCurrent plan (follow this):\n" + opts.planContent.trim();
+        }
+        if (opts?.filesToChange?.length) {
+            body += "\n\n---\n\nFiles to focus on:\n" + opts.filesToChange.join("\n");
+        }
+        if (opts?.recentCommitsPerFile?.trim()) {
+            body += "\n\n---\n\nRecent commit (per file):\n" + opts.recentCommitsPerFile.trim();
+        }
+        if (opts?.codeContext?.trim()) {
+            body += "\n\n---\n\nRelevant file contents:\n" + opts.codeContext.trim();
+        }
+        fullPrompt = body + "\n\n---\n\nUser request: " + prompt;
+    }
+    catch {
+        let fallback = DEFAULT_IMPLEMENTER_FALLBACK;
+        if (opts?.projectContext?.trim()) {
+            fallback += "\n\n---\n\nProject context (AGENTS.md):\n" + opts.projectContext.trim();
+        }
+        if (opts?.context?.trim()) {
+            fallback += "\n\n---\n\nConversation context:\n" + opts.context.trim();
+        }
+        if (opts?.planContent?.trim()) {
+            fallback += "\n\n---\n\nCurrent plan (follow this):\n" + opts.planContent.trim();
+        }
+        if (opts?.filesToChange?.length) {
+            fallback += "\n\n---\n\nFiles to focus on:\n" + opts.filesToChange.join("\n");
+        }
+        if (opts?.recentCommitsPerFile?.trim()) {
+            fallback += "\n\n---\n\nRecent commit (per file):\n" + opts.recentCommitsPerFile.trim();
+        }
+        if (opts?.codeContext?.trim()) {
+            fallback += "\n\n---\n\nRelevant file contents:\n" + opts.codeContext.trim();
+        }
+        fullPrompt = fallback + "\n\n---\n\nUser request: " + prompt;
+    }
+    try {
+        return await runCodexExecStreaming(fullPrompt, cwd);
+    }
+    catch (err) {
+        const msg = err.stdout
+            ?? err.stderr
+            ?? err.message;
+        throw new Error("Codex implement failed: " + msg);
+    }
+}