claude2codex 0.3.1 → 0.3.2

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) 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,22 @@ Add to your Claude Code MCP settings:
 }
 ```
 
+### Skill (optional)
+
+The package includes a Claude Code Skill that teaches Claude the full contract workflow — drafting Goal Contracts, delegating to Codex, reviewing handoffs, and reworking failures. Install it to use `/c2c` from any project:
+
+```sh
+mkdir -p ~/.claude/skills
+cp "$(npm root -g)/claude2codex/c2c.skill.md" ~/.claude/skills/c2c.md
+```
+
+Or download directly:
+
+```sh
+mkdir -p ~/.claude/skills
+curl -fsSL https://raw.githubusercontent.com/PrestoOverture/c2c/main/c2c.skill.md -o ~/.claude/skills/c2c.md
+```
+
 ## 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）和**怎么证明做对了**（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,22 @@ npx claude2codex
 }
 ```
 
+### Skill（可选）
+
+包内附带一个 Claude Code Skill，教 Claude 完整的契约工作流——起草 Goal Contract、委派给 Codex、审查 handoff、失败时返工。安装后可在任何项目中使用 `/c2c`：
+
+```sh
+mkdir -p ~/.claude/skills
+cp "$(npm root -g)/claude2codex/c2c.skill.md" ~/.claude/skills/c2c.md
+```
+
+或直接下载：
+
+```sh
+mkdir -p ~/.claude/skills
+curl -fsSL https://raw.githubusercontent.com/PrestoOverture/c2c/main/c2c.skill.md -o ~/.claude/skills/c2c.md
+```
+
 ## 提供的工具
 
 | 工具 | 说明 |

package/c2c.skill.md

@@ -0,0 +1,58 @@
+---
+name: c2c
+description: Delegate implementation to Codex via Goal Contracts. Draft, send, poll, review, rework.
+trigger: When the user wants to delegate implementation work to Codex, or types /c2c.
+---
+
+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** — `codex_estimate` to check budget, then `codex_implement`.
+4. **You poll** — `codex_status` until terminal. Report progress to the user.
+5. **You review** — `codex_result` for the handoff, then verify independently (see Review below).
+6. **User approves** your findings.
+
+If review fails → draft a **Delta Contract** → `codex_rework` (same `job_id`, thread resumes) → 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 — 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 — 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.

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,9 +246,20 @@ 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" },
@@ -228,6 +268,9 @@ var CodexAppServer = class {
     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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude2codex",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "description": "MCP server bridging Claude (architect/reviewer) and Codex (implementer) via Goal/Delta Contracts and Codex's thread-goal loop.",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "dist",
     "PATTERNS.md",
-    "PATTERNS.zh-CN.md"
+    "PATTERNS.zh-CN.md",
+    "c2c.skill.md"
   ],
   "keywords": [
     "mcp",
@@ -30,8 +31,8 @@
     "start": "bun src/server.ts",
     "build": "tsup",
     "test": "bun test",
-    "prepack": "cp ../README.md ../README.zh-CN.md ../PATTERNS.md ../PATTERNS.zh-CN.md .",
-    "postpack": "rm -f README.md README.zh-CN.md PATTERNS.md PATTERNS.zh-CN.md"
+    "prepack": "cp ../README.md ../README.zh-CN.md ../PATTERNS.md ../PATTERNS.zh-CN.md ../c2c.skill.md .",
+    "postpack": "rm -f README.md README.zh-CN.md PATTERNS.md PATTERNS.zh-CN.md c2c.skill.md"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",