# Codex Ride
给 Codex 用的多 agent workflow skill pack。
它做两件事：
1. 用 `rider` + `codex` 跑一套有 gate 的开发 workflow：spec -> plan -> task -> execute -> review -> report
2. 提供一个独立的 detached codex `drive` 模式：用户给任务，codex 静默持续做，只在少数里程碑事件上通知
## 这是什么
核心角色：
- `rider`：面向用户，做状态推进、用户沟通、gate 决策、最终报告
- `codex-worker`：当前只支持 `codex-cli`，负责生成、执行、审查
核心约束：
- 关键阶段都要落盘为 artifact
- workflow 前进要过 review gate
- transport 真源是结果文件，不是 stdout/stderr
- workflow 状态由 `codex-ride` CLI 管理，不手改 `.codex-ride/session.json`
## 什么时候用什么
| 入口 | 用途 | 适合场景 |
| ------------------ | ---------------------------------- | -------------------------------------- |
| `/codex-ride-spec` | 起草或续接 spec | 还没批准 spec，或要重写 spec |
| `/codex-ride-run` | 按 workflow gate 自动推进 | 需要完整 spec / review / report 链 |
| `/codex-ride-drive` | 启动 detached codex 做用户指定任务 | 不想走 workflow，只想让 codex 持续做事 |
CLI 对应入口：
| 命令 | 用途 |
| ------------------------- | ---------------------------------------- |
| `codex-ride init` | 初始化 workflow state |
| `codex-ride state:get` | 读取 workflow state |
| `codex-ride state:set` | 写 workflow state |
| `codex-ride resolve-phase` | 推断当前 workflow phase |
| `codex-ride dispatch` | 高级手动派发单个 codex-worker job |
| `codex-ride job:status` | 查看 workflow active job 或指定 job 状态 |
| `codex-ride run` | 自动推进 workflow |
| `codex-ride drive` | 启动或接管 detached codex drive |
| `codex-ride report` | 手动生成最终报告 |
| `codex-ride prepare-job` | 只生成 prompt 和 run 目录，不实际执行 |
兼容性说明：
- `codex-ride work` 目前仍是 `drive` 的兼容别名
- 新文档和新使用方式都以 `drive` 为准
## 安装
```bash
git clone https://github.com/dualface/codex-ride.git
cd codex-ride
./scripts/install.sh
```
安装脚本会：
- 把 `skills/*` 复制到 `~/.codex/skills/codex-ride--<name>`
- 已有 skill 目录会覆盖同步
- 旧 symlink 会先清掉，再替换成真实目录
- 删除仓库里已不存在的过期 skill 目录
- 在 `~/.local/bin/codex-ride` 写 wrapper
- 运行 `npm run validate`
要求：
- `~/.local/bin` 在 `PATH` 里
- 本机能运行 `node`
- 本机已安装 `codex`
卸载：
```bash
./scripts/uninstall.sh
```
升级：
```bash
./scripts/install.sh --update
```
`--update` 会：
- 先执行 `git pull`
- 重新同步全部 skill
- 替换旧 symlink
- 删除过期 skill
- 在 wrapper 内容变化时重写 wrapper
## 快速上手
### 1. 走完整 workflow
进入目标项目根目录, 并先建一个 worktree (避免 state 被覆盖, 见下文 "Worktree 与多 spec"):
```bash
cd <target-project>
git worktree add worktrees/<task-cluster> -b codex-ride/<task-cluster>
cd worktrees/<task-cluster>
```
在 Codex 里:
```text
/codex-ride-spec
```
spec 通过并批准后:
```text
/codex-ride-run
```
(/codex-ride-spec 内部会强制 worktree gate；Codex 应在目标 worktree CWD 内运行 CLI。)
如果只用 CLI, 最小流程是:
```bash
cd <target-project>
git worktree add worktrees/<task-cluster> -b codex-ride/<task-cluster>
cd worktrees/<task-cluster>
codex-ride init --slug <project-slug>
codex-ride state:set --set spec_path=docs/specs/<workflow-id>.md
codex-ride dispatch --job specAdversarialReview
codex-ride run --write-scope <allowed-write-path>
```
### 2. 直接驱动 detached codex
当你不想走 workflow，只想让 codex 持续干活：
```bash
cd <target-project>
codex-ride drive "实现 xxx；除非遇到真实 blocker，否则一直做下去"
```
如果 `rider` 自己断线、报错、额度耗尽，重新接管当前 drive：
```bash
codex-ride drive
```
## Workflow 模式
### Phase 顺序
| # | Phase | 做什么 | Gate |
| --- | ------------------------- | ----------------------------------------- | ---------------------- |
| 1 | `drafting-specs` | 和用户一起写 spec，codex-worker 做对抗式 review | spec 批准 |
| 2 | `writing-phase-plans` | 基于已批准 spec 写 phase plan list | self review |
| 3 | `writing-phase-tasks` | 为每个 phase 写 task list | self review |
| 4 | `executing-phase-tasks` | 串行执行可运行 phase | 每 phase 完成后 review |
| 5 | `reviewing-phase-results` | phase review + final spec review | 全部 pass 后报告 |
| 6 | `reporting-results` | `rider` 汇总最终报告 | 完成 |
### Workflow 状态文件
默认状态文件:
- `.codex-ride/session.json` (相对于 `codex-ride` 命令的 CWD)
状态里重点字段:
- `workflow_id`
- `current_phase`
- `spec_path`
- `spec_review_passed`
- `spec_approved`
- `phase_plan_list_path`
- `phase_task_dir`
- `phase_result_dir`
- `phase_review_dir`
- `ready_phase_ids`
- `completed_phase_ids`
- `reviewed_phase_ids`
- `active_job_id`
- `last_result_file_path`
不要手改这个文件。只通过 `codex-ride` CLI 读写。
### Worktree 与多 spec
`codex-ride` 把 `.codex-ride/session.json` 写在**当前 CWD** 下 (`process.cwd()` 解析)。同一 CWD 同一时间只能跑一个 workflow; `codex-ride init` 第二次会要求 `--force`, 一旦 force 就**直接覆盖**前一个 workflow 的 state, 历史只剩 `.codex-ride/runs/<workflow-id>/` 里的 artifact。
所以多 spec 推进有两种模式:
1. **串行 (默认)**: 同一 worktree 内, 上一个 workflow `done` 后再 `codex-ride init --slug <new> --force` 起下一个
2. **并行**: 每个 spec 独占一个 git worktree, 路径约定 `worktrees/<task-cluster>/`, 每个 worktree 独立一份 `.codex-ride/session.json`, 互不污染
- 启动: `git worktree add worktrees/<name> -b codex-ride/<name>`
- 单个 rider session 的 CWD 单一, 并行需多开 rider session, 每个 session `cd` 进各自的 worktree
- **必须** 给每个并行 workflow 划独立 `--write-scope` 路径, 否则 phaseExecution 会互相覆盖
- 远端 PR 建议串行 merge, 避免冲突堆积
`/codex-ride-spec` 入口已强制 worktree gate: 不在 `worktrees/<name>` 下不会让你 `init`, 防误覆盖。直用 CLI 时请自行 `cd` 到目标 worktree。
把 `worktrees/` 加到 `.gitignore`, 避免 worktree 子目录意外被主仓提交。
### Workflow 运行目录
每个 codex-worker job 的 transport 文件都在：
- `.codex-ride/runs/<workflow-id>/<job-id>/`
固定文件：
- `prompt.md`
- `stdout.jsonl`
- `stderr.log`
- `result.json`
- `job.json`
`job.json` 用于恢复/续跑。
真正状态真源仍然是 `result.json` + 业务 artifact。
### `run` 的行为
`codex-ride run --write-scope <path>` 会：
- 自动判断当前 phase
- 选下一个 codex-worker job
- 在 detached runner 里执行 `codex exec`
- codex-worker 退出后读 `result.json`
- 更新 workflow state
- 循环直到完成或必须用户介入
`run` 会停下来的典型情况：
- spec 还没批准
- `phaseExecution` 缺 `--write-scope`
- codex-worker blocked
- 需要用户决策
- transport 失败且无法自动恢复
### `job:status` 的用途
`job:status` 只看 workflow job，不看 `drive`。
```bash
codex-ride job:status
codex-ride job:status --job-id <job-id>
```
它会报告：
- active job / 指定 job 是谁
- detached runner / codex-worker 是否还活着
- `result.json` 是否已就绪
- `stdout` / `stderr` / `job.json` 路径和文件状态
- 必要时的 artifact recovery 候选信息
### Workflow 恢复
如果 `rider` 中途挂了，不要手动清状态。
恢复路径：
1. 再执行 `codex-ride run --write-scope <path>`
2. harness 会先检查 `active_job_id`
3. 如果后台 codex-worker 还活着，就接管等待
4. 如果 codex-worker 已退出，就读取 `result.json`
5. 如果 `result.json` 丢了但 artifact 足够，会尝试 artifact recovery
## Drive 模式
### `drive` 的语义
`drive` 独立于 workflow。
它不管：
- phase
- review gate
- spec approval
- 最终报告
它只做：
- 用用户给的 prompt 启动 detached codex
- 在 codex 只是停下来问“是否继续”时自动 `resume`
- 静默等待下一个里程碑事件
### `drive` 只看 4 类里程碑
| 事件 | `milestone.type` | 意义 |
| ------------ | ---------------- | -------------------------------------------- |
| PR merge | `pr_merged` | codex 报告 PR 已合并 |
| CI 失败 | `ci_failed` | codex 报告 CI / checks / pipeline 失败 |
| 需要用户介入 | `needs_user` | 真的需要用户提供输入、做决策、或处理 blocker |
| drive 结束 | `drive_finished` | drive 已经结束 |
非里程碑进展：
- 不通知用户
- 不把 stdout/stderr 转发给 `rider`
- 尽量减少 `rider` token 消耗
### `drive` 返回什么
```bash
codex-ride drive "你的任务"
```
这个命令会静默跑到下一个里程碑再返回 JSON。
重点字段：
- `drive_id`
- `active`
- `stop_reason`
- `milestone.seq`
- `milestone.type`
- `milestone.summary`
- `auto_continue_count`
- `thread_id`
- `stdout_log`
- `stderr_log`
语义：
- `active == true`：drive 还在继续跑，只是出现了一个里程碑
- `active == false`：drive 已结束
### `drive` 状态文件和目录
默认 drive 状态文件：
- `.codex-ride/drive-state.json`
默认 drive 运行目录：
- `.codex-ride/drives/<drive-id>/`
固定文件：
- `prompt.md`
- `stdout.jsonl`
- `stderr.log`
- `drive.json`
- `last-message.txt`
- `attempt-last-message.txt`
`drive.json` 里会记录：
- `drive_id`
- `thread_id`
- 当前 attempt
- 自动 continue 次数
- 最近里程碑
- 进程 pid
- 停止原因
### `drive` 的恢复与接管
不带 prompt 执行：
```bash
codex-ride drive
```
语义：
- 如果当前有 active drive：继续静默等下一个里程碑
- 如果 active 已结束但最近一次 drive 还有未通知里程碑：把那个里程碑取回来
- 如果既没有 active drive，也没有最近 drive：报错
### `drive` 的自动 continue 规则
如果 codex 最后消息只是“是否继续”类提示：
- driver 自动执行 `codex exec resume`
- 不通知用户
如果最后消息看起来像真实 blocker / 真实缺输入 / 真实业务决策：
- 归类为 `needs_user`
- 把控制权交还用户
可调参数：
```bash
codex-ride drive \
--timeout-seconds 1800 \
--max-auto-continue 50 \
--continue-prompt "继续工作。除非真实 blocker，否则不要停下来问我是否继续。" \
"你的任务"
```
## `run` 和 `drive` 的区别
| 维度 | `run` | `drive` |
| ------------------ | ------------------------- | ----------------------------- |
| 目标 | 推 workflow | 跑用户指定任务 |
| 是否依赖 spec/gate | 是 | 否 |
| 状态文件 | `.codex-ride/session.json` | `.codex-ride/drive-state.json` |
| 恢复入口 | `codex-ride run` | `codex-ride drive` |
| 监控对象 | codex-worker job | detached codex session |
| 用户通知 | 每次 `run` 停点 | 只有 4 类里程碑 |
| 推荐用途 | 正式开发流程 | 独立长任务、少打断执行 |
## 外部依赖风险策略
第三方 API / 外部服务 / 网络依赖问题单独归入 `external_dependency_risks`：
- 不触发 spec revise
- 不触发 phase fail
- 不触发 blocked
- 会在 spec -> review -> result -> final report 全链路记录
这条规则只针对 workflow 模式。
`drive` 模式不做这类 workflow 级别归档。
## 目录约定
默认 artifact 目录：
| Artifact | 默认路径 |
| ----------------- | -------------------------- |
| spec | `docs/specs/` |
| spec review | `docs/reviews/specs/` |
| override log | `docs/reviews/overrides/` |
| phase plan list | `docs/plans/` |
| phase task list | `docs/tasks/` |
| phase result | `docs/results/` |
| phase review | `docs/reviews/phases/` |
| final spec review | `docs/reviews/spec-final/` |
| final report | `docs/reports/` |
这些目录不要求预先存在，harness 会在写入时创建。
## 重要文件
| 类别 | 文件 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| manifest | [codex-ride.manifest.json](codex-ride.manifest.json) |
| bootstrap skill | [skills/using-codex-ride/SKILL.md](skills/using-codex-ride/SKILL.md) |
| 用户入口 skill | [skills/spec/SKILL.md](skills/spec/SKILL.md) · [skills/run/SKILL.md](skills/run/SKILL.md) · [skills/drive/SKILL.md](skills/drive/SKILL.md) |
| harness | [scripts/codex-ride-harness.mjs](scripts/codex-ride-harness.mjs) |
| 安装脚本 | [scripts/install.sh](scripts/install.sh) |
| 卸载脚本 | [scripts/uninstall.sh](scripts/uninstall.sh) |
| 校验脚本 | [scripts/validate-skill-pack.mjs](scripts/validate-skill-pack.mjs) |
| smoke 样例 | [scripts/smoke-run.mjs](scripts/smoke-run.mjs) |
| 状态机 | [docs/state-machine.md](docs/state-machine.md) |
| transport 合同 | [docs/transport-contract.md](docs/transport-contract.md) |
| runtime 合同 | [docs/runtime-contract.md](docs/runtime-contract.md) |
| codex-worker prompt 合同 | [docs/worker-prompt-contracts.md](docs/worker-prompt-contracts.md) |
| harness 样例 | [docs/harness-example.md](docs/harness-example.md) |
| artifact 样例 | [docs/examples/minimal-todo/](docs/examples/minimal-todo/) |
## 开发与校验
本仓库常用命令：
```bash
npm run validate
npm run harness -- help
npm run smoke
```
校验脚本会检查：
- manifest / package.json 一致性
- 所有 skill 和 prompt 文件存在
- worker result 模板字段齐全
- examples 链完整
- `.gitignore` 覆盖 `.codex-ride/`
## 当前范围
已实现：
- 完整 workflow skill pack 骨架
- `codex-cli` worker runtime
- detached runner + workflow job 恢复
- `job:status`
- detached codex `drive`
- drive 里程碑监控与自动 continue
- 安装、卸载、校验、自带最小 smoke
未实现：
- 生产级调度服务
- 多 worker 并行调度服务端
- 除 `codex-cli` 之外的 worker runtime
- 自动 merge / worktree 管理系统