claude2codex 0.3.1 → 0.3.3

package/README.md

@@ -12,14 +12,15 @@ One real contract round-trip, recorded live: Claude drafts the Goal Contract, `c
 
 *Real Codex run (13k tokens, 50s), waits compressed. Replay in your terminal: `asciinema play demo/demo.cast`*
 
-## The Idea
+## Why
 
-Software development has distinct roles: **planning** what to build, **building** it, and **reviewing** the result. This project splits those roles between two AI agents:
+In 2025, AI-assisted coding meant writing detailed prompts that told the model *how* to implement things — which files to edit, what patterns to follow, sometimes nearly pseudocode. The engineer was a director; the AI was a typist that needed constant guidance.
 
-- **Claude Code** — the architect and reviewer. Plans the work, writes specifications, reviews results.
-- **OpenAI Codex** — the implementer. Receives specifications, writes code, runs tests, reports back.
+That has changed. In 2026, models are [strong enough at implementation](https://www.anthropic.com/institute/recursive-self-improvement) that micromanaging the how is no longer the best use of a human's time. The bottleneck has shifted: when implementation is cheap, the expensive mistakes are **defining the wrong problem** and **failing to catch a bad result**. Getting the implementation steps right matters far less than getting the goal right.
 
-You (the user) are the **commander** — you decide what to build and give final approval. Claude drafts the plan, Codex executes it, Claude verifies the output.
+This is why Goal Contracts are structured the way they are. They don't explain how to write the code — they define **what the code must do** (the Goal), **what to avoid** (Constraints), and **how to prove it worked** (Success Conditions). The engineer's role becomes problem definition, context provision, and verification — the same things that make a good engineering manager effective at delegation.
+
+This project is built on that premise: split planning and review (where human judgment still dominates) from implementation (where models now excel), and connect them with a contract format that forces clarity on the parts that matter most.
 
 ```mermaid
 flowchart LR
@@ -30,6 +31,10 @@ flowchart LR
     Claude -.->|Delta Contract if review fails| Codex
 ```
 
+- **You** — decide what to build and give final approval.
+- **Claude Code** — the architect and reviewer. Defines the problem, writes the contract, verifies the result.
+- **OpenAI Codex** — the implementer. Receives the contract, writes code, runs tests, reports back.
+
 ## What is a Goal Contract?
 
 A Goal Contract is a structured specification that tells Codex *exactly* what to build. It has three parts:
@@ -125,6 +130,63 @@ Add to your Claude Code MCP settings:
 }
 ```
 
+### Workflow Prompt (automatic)
+
+The server registers an MCP Prompt (`c2c-workflow`) that teaches Claude the full contract workflow — role assignment, Goal/Delta Contract formats, review protocol. **This is loaded automatically when the MCP server is connected.** No extra installation needed.
+
+### Project Setup: CLAUDE.md and AGENTS.md
+
+The MCP server handles the workflow protocol. Your project files only need to carry **project-specific context** — don't repeat what the server already provides.
+
+**`CLAUDE.md`** (for Claude — the architect/reviewer):
+
+```markdown
+# Claude Code Guidelines
+
+The contract workflow is delivered by the MCP Prompt `c2c-workflow`.
+
+## Session Startup
+Read README.md and docs/design.md at session start.
+
+## Review Additions
+- Flag security issues (OWASP top 10).
+- Run integration tests against staging after each task.
+
+## Constraints
+- Do not modify migrations without explicit approval.
+```
+
+**`AGENTS.md`** (for Codex — the implementer):
+
+```markdown
+# Codex Guidelines
+
+You are the implementer. The contract protocol is delivered by the c2c bridge.
+
+## Toolchain
+Python 3.12, Poetry. Run from project root.
+- `poetry run pytest` — test suite
+- `poetry run ruff check .` — lint
+- `poetry run mypy .` — typecheck
+
+## Boundaries
+- Do not modify alembic migrations directly.
+- Do not add runtime dependencies without a contract constraint.
+```
+
+**What goes where:**
+
+| | MCP server (automatic) | CLAUDE.md | AGENTS.md |
+|---|---|---|---|
+| Role definition | ✓ | — | — |
+| Workflow steps | ✓ | — | — |
+| Contract formats | ✓ | — | — |
+| Review protocol | ✓ | — | — |
+| Session startup | — | ✓ | ✓ |
+| Project-specific review rules | — | ✓ | — |
+| Toolchain & build commands | — | — | ✓ |
+| File/dependency boundaries | — | — | ✓ |
+
 ## Tools Provided
 
 | Tool | Description |

package/README.zh-CN.md

@@ -6,20 +6,21 @@
 
 ## 演示
 
-一次真实的契约往返实录：Claude 起草 Goal Contract，`codex_estimate` 预估成本，Codex 在 goal loop 下自主实现（`codex_status` 实时流式进度），最后 Claude 独立复核 handoff。
+一次完整的workflow实践过程：Claude 起草 Goal Contract，`codex_estimate` 预估成本，Codex 在 goal loop 下自主实现（`codex_status` 实时流式进度），最后 Claude 独立复核 handoff。
 
 ![c2c 演示 — 完整的 Claude→Codex 契约往返](./demo/demo.gif)
 
-*真实 Codex 运行（13k tokens，50 秒），等待时间已压缩。终端回放：`asciinema play demo/demo.cast`*
+*Codex 运行（13k tokens，50 秒），等待时间已压缩。终端回放：`asciinema play demo/demo.cast`*
 
-## 核心理念
+## 为什么做这个项目
 
-软件开发有不同的角色：**规划**做什么、**动手**写代码、**审查**结果。本项目把这些角色分配给两个 AI 智能体：
+2025 年，AI 辅助编程的主流方式是写详细的 prompt 告诉模型*怎么*实现——改哪些文件、用什么模式、有时候几乎是伪代码。工程师是导演，AI 是需要不断指导的执行者。
 
-- **Claude Code** — 架构师和审查者。制定计划，撰写规格说明，审查产出。
-- **OpenAI Codex** — 实现者。接收规格说明，编写代码，运行测试，报告结果。
+这已经变了。2026 年，模型的[实现能力已经足够强](https://www.anthropic.com/institute/recursive-self-improvement)，事无巨细地指挥"怎么写"不再是人最好的时间投入方式。瓶颈转移了：当实现变得廉价，真正昂贵的错误是**定义了错误的问题**和**没有验收出坏的结果**。把实现步骤写对，远不如把目标定义对重要。
 
-你（用户）是**指挥官** — 决定做什么并给最终批准。Claude 起草方案，Codex 执行，Claude 核验产出。
+这就是为什么 Goal Contract 被设计成这样。它不解释怎么写代码——它定义**代码必须做到什么**（Goal），**要避免做什么**（Constraints）和**怎么证明做对了**（Success Conditions）。工程师的角色变成了问题定义、上下文补充和验收——和一个好的工程管理者委派任务时做的事情一样。
+
+这个项目建立在这个前提上：把规划和审查（人的判断力仍然占主导）与实现（模型已经足够强）分开，用一种契约格式把它们连接起来，迫使工程师在最重要的部分(问题定义和验收标准)上做到清晰。
 
 ```mermaid
 flowchart LR
@@ -30,6 +31,10 @@ flowchart LR
     Claude -.->|Delta Contract 修正| Codex
 ```
 
+- **你** — 决定做什么，给最终批准。
+- **Claude Code** — 架构师和审查者。定义问题，撰写契约，验证结果。
+- **OpenAI Codex** — 实现者。接收契约，编写代码，运行测试，报告结果。
+
 ## 什么是 Goal Contract（目标契约）？
 
 Goal Contract 是一份结构化规格说明，精确告诉 Codex **要做什么**。它由三部分组成：
@@ -125,6 +130,63 @@ npx claude2codex
 }
 ```
 
+### 工作流 Prompt（自动）
+
+服务器注册了一个 MCP Prompt（`c2c-workflow`），教 Claude 完整的契约工作流——角色分配、Goal/Delta Contract 格式、审查协议。**连接 MCP 服务器后自动加载。** 无需额外安装。
+
+### 项目配置：CLAUDE.md 和 AGENTS.md
+
+MCP 服务器负责工作流协议。你的项目文件只需要放**项目特有的上下文**——不要重复服务器已经提供的内容。
+
+**`CLAUDE.md`**（给 Claude——架构师/审查者）：
+
+```markdown
+# Claude Code Guidelines
+
+契约工作流由 MCP Prompt `c2c-workflow` 提供。
+
+## 会话启动
+开始时阅读 README.md 和 docs/design.md。
+
+## 审查补充
+- 标记安全问题（OWASP top 10）。
+- 每个任务完成后跑一遍 staging 的集成测试。
+
+## 约束
+- 未经明确批准不得修改 migrations。
+```
+
+**`AGENTS.md`**（给 Codex——实现者）：
+
+```markdown
+# Codex Guidelines
+
+你是实现者。契约协议由 c2c bridge 提供。
+
+## 工具链
+Python 3.12，Poetry。从项目根目录运行。
+- `poetry run pytest` — 测试套件
+- `poetry run ruff check .` — 代码检查
+- `poetry run mypy .` — 类型检查
+
+## 边界
+- 不要直接修改 alembic migrations。
+- 未经合同约束不得添加运行时依赖。
+```
+
+**什么放哪里：**
+
+| | MCP 服务器（自动） | CLAUDE.md | AGENTS.md |
+|---|---|---|---|
+| 角色定义 | ✓ | — | — |
+| 工作流步骤 | ✓ | — | — |
+| 契约格式 | ✓ | — | — |
+| 审查协议 | ✓ | — | — |
+| 会话启动 | — | ✓ | ✓ |
+| 项目特有的审查规则 | — | ✓ | — |
+| 工具链与构建命令 | — | — | ✓ |
+| 文件/依赖边界 | — | — | ✓ |
+
 ## 提供的工具
 
 | 工具 | 说明 |

package/dist/server.js

@@ -137,6 +137,11 @@ var CodexAppServer = class {
   stderrTail = [];
   exitError;
   exited = false;
+  /**
+   * Spawns a new Codex child process and sets up event listeners for stdout and stderr streams.
+   *
+   * @param opts - Configuration options specifying executable path, arguments, environment, and event callbacks
+   */
   constructor(opts) {
     this.opts = opts;
     this.proc = spawn(opts.bin, opts.args, {
@@ -158,6 +163,12 @@ var CodexAppServer = class {
       this.handleExit(null, new Error(`failed to spawn ${opts.bin}: ${err.message}`));
     });
   }
+  /**
+   * Handles Codex child process termination or spawn failure, rejecting pending requests and notifying listeners.
+   *
+   * @param code - Exit code of the child process, or null if terminated abnormally
+   * @param error - Error instance causing process exit, if any (optional)
+   */
   handleExit(code, error) {
     if (this.exited) return;
     this.exited = true;
@@ -172,6 +183,11 @@ var CodexAppServer = class {
     this.pending.clear();
     this.opts.onExit?.(code, this.exitError);
   }
+  /**
+   * Parses a single output line received from Codex stdout and dispatches it as a request response or notification.
+   *
+   * @param line - Raw text line emitted by the child process stdout
+   */
   handleLine(line) {
     const trimmed = line.trim();
     if (!trimmed) return;
@@ -199,10 +215,23 @@ var CodexAppServer = class {
       this.opts.onNotification?.(msg.method, msg.params);
     }
   }
+  /**
+   * Serializes an object to JSON and writes it to the child process's standard input stream.
+   *
+   * @param obj - Object to send to the child process
+   */
   send(obj) {
     if (this.exited) return;
     this.proc.stdin.write(JSON.stringify(obj) + "\n");
   }
+  /**
+   * Sends a correlated JSON-RPC request to Codex and returns a Promise that resolves with the response or times out.
+   *
+   * @param method - RPC method name to invoke
+   * @param params - Optional parameter object passed with the request
+   * @param timeoutMs - Maximum time to wait for a response in milliseconds, defaulting to 60,000ms
+   * @returns Promise resolving with the response result
+   */
   request(method, params, timeoutMs = 6e4) {
     if (this.exited) {
       return Promise.reject(this.exitError ?? new Error("codex app-server is not running"));
@@ -217,17 +246,31 @@ var CodexAppServer = class {
       this.send({ id, method, ...params !== void 0 ? { params } : {} });
     });
   }
+  /**
+   * Sends a one-way notification message to Codex without waiting for a response.
+   *
+   * @param method - Notification method name
+   * @param params - Optional parameter object passed with the notification
+   */
   notify(method, params) {
     this.send({ method, ...params !== void 0 ? { params } : {} });
   }
+  /**
+   * Sends the initial handshake request to Codex and emits the initialized notification upon response.
+   *
+   * @returns Promise resolving with the server initialization response payload
+   */
   async initialize() {
     const result = await this.request("initialize", {
-      clientInfo: { name: "claude2codex", title: "Claude\u2194Codex Contract Bridge", version: "0.3.1" },
+      clientInfo: { name: "claude2codex", title: "Claude\u2194Codex Contract Bridge", version: "0.3.3" },
       capabilities: { experimentalApi: true }
     });
     this.notify("initialized", {});
     return result;
   }
+  /**
+   * Gracefully terminates the running Codex child process via SIGTERM signal.
+   */
   kill() {
     if (!this.exited) this.proc.kill("SIGTERM");
   }
@@ -291,8 +334,24 @@ function createJobStore(dir = defaultStateDir()) {
     warnOnce(error);
   }
   return {
+    /**
+     * Retrieves a job from memory by its unique identifier.
+     *
+     * @param id - Unique job identifier to look up
+     * @returns The matching Job object, or undefined if not found
+     */
     getJob: (id) => records.get(id),
+    /**
+     * Returns a list of all currently cached jobs.
+     *
+     * @returns Array of cached Job objects
+     */
     listJobs: () => [...records.values()],
+    /**
+     * Persists job state and transcript history to memory cache and atomic disk storage.
+     *
+     * @param job - Job object to be saved
+     */
     save(job) {
       const record = { ...job, transcript: job.transcript.slice(-200) };
       records.set(job.id, record);
@@ -871,7 +930,7 @@ function textResult(obj, isError = false) {
     isError
   };
 }
-var server = new McpServer({ name: "c2c-codex", version: "0.3.1" });
+var server = new McpServer({ name: "c2c-codex", version: "0.3.3" });
 var reasoningEffort = z.enum(["low", "medium", "high", "xhigh", "max", "ultra"]);
 var contextFiles = z.array(z.object({
   path: z.string().min(1),
@@ -1124,5 +1183,66 @@ server.registerTool(
     });
   }
 );
+server.registerPrompt("c2c-workflow", {
+  description: "Delegate implementation to Codex via Goal Contracts. Draft, send, poll, review, rework."
+}, () => ({
+  messages: [{
+    role: "user",
+    content: { type: "text", text: `
+You are the **architect and reviewer**. Codex is the **implementer**. You draft contracts, delegate via the \`codex\` MCP server, and review the output. You do not implement the task yourself.
+
+If \`codex_config\` errors, tell the user to install the MCP server (npm: \`claude2codex\`).
+
+## Workflow
+
+1. **User decides** what to build or fix.
+2. **You draft a Goal Contract** (format below). Show it to the user for approval.
+3. **You send it** \u2014 \`codex_estimate\` to check budget, then \`codex_implement\`.
+4. **You poll** \u2014 \`codex_status\` until terminal. Report progress to the user.
+5. **You review** \u2014 \`codex_result\` for the handoff, then verify independently (see Review below).
+6. **User approves** your findings.
+
+If review fails \u2192 draft a **Delta Contract** \u2192 \`codex_rework\` (same \`job_id\`, thread resumes) \u2192 re-enter at step 4.
+
+## Goal Contract
+
+\`\`\`
+### Goal
+What the code must do. First sentence = acceptance test in prose.
+
+### Constraints
+Only what Codex would get wrong without being told. One line of
+"only modify files needed for this task" covers the rest.
+
+### Success Conditions
+- [ ] Assertions, not paragraphs. At least one is a command whose exit code decides.
+- [ ] Handoff includes: Changed Files, Validation, Success Conditions, Risks & Deviations.
+\`\`\`
+
+**Write lean contracts.** Goal and Success Conditions are what Codex acts on. Constraints are for genuine risks only \u2014 don't front-load your review checklist into the contract.
+
+## Delta Contract
+
+\`\`\`
+### Findings
+- What is wrong, with file/line references.
+
+### Failed Success Conditions
+- [ ] The specific conditions that did not pass.
+
+### Constraints
+- Original constraints still apply. Fix only the findings; do not touch work that passed.
+\`\`\`
+
+## Review
+
+1. Handoff must be complete (all four sections). Missing handoff = review failure.
+2. Re-run every verification command yourself \u2014 do not trust the handoff's claims.
+3. Run the project's own typecheck/build/test/lint.
+4. Flag security issues and constraint violations.
+5. Report findings to the user. Fix small issues (typos, imports) directly; do not rewrite the implementation.
+` }
+  }]
+}));
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude2codex",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "MCP server bridging Claude (architect/reviewer) and Codex (implementer) via Goal/Delta Contracts and Codex's thread-goal loop.",
   "bin": {