git:20260330.65d6f65 to git:20260330.3ff9f87

84 added, 118 removed. Audit A to A.

---

name: autopilot-codex

- description: 在 Codex 中使用本仓库的 autopilot 工作流时使用。适用于用户提到 /autopilot、自动驾驶、红蓝对抗、设计审批、五层 QA、或希望在 Codex 中继续使用 autopilot 的场景。不要在 Claude Code 插件运行时文件上直接操作。

+ description: 在 Codex 中使用本仓库的 autopilot 全闭环 runtime 时使用。适用于用户提到 /autopilot、自动驾驶、红蓝对抗、设计审批、五层 QA、或希望在 Codex 中继续使用 autopilot 的场景。不要在 Claude Code 插件运行时文件上直接操作。

---

# Autopilot for Codex

- 这是本仓库 `autopilot` 的 Codex 兼容入口。你要复用 autopilot 的工程方法论，但不能依赖 Claude Code 专有能力。

+ 这是本仓库 `autopilot` 的 Codex 兼容入口。目标是在 Codex 中恢复与 Claude autopilot 等价的 phase-state runtime，而不是停留在“方法论兼容”。

+ ## 基线文件

+ 把以下文件当作只读基线：

+ - `plugins/autopilot/skills/autopilot/SKILL.md`

+ - `plugins/autopilot/skills/autopilot/references/`

+ Claude 专有机制只作为行为 oracle，不直接把运行时写回 `.claude/`。

## Codex 兼容边界

- - **运行时状态文件**：使用 `.codex/autopilot.local.md`

- - **不要写入** `.claude/autopilot.local.md`

- - **不要依赖** Claude 的 `EnterPlanMode`、`ExitPlanMode`、`Stop hook`、`WorktreeCreate`、`WorktreeRemove`

- - `.claude/knowledge/` 可作为**只读知识库**

- - 需要参考历史工作流时，读取以下只读基线文件：

- - `plugins/autopilot/skills/autopilot/SKILL.md`

- - `plugins/autopilot/skills/autopilot/references/`

+ - 运行时状态文件：`.codex/autopilot.local.md`

+ - 不要写入 `.claude/autopilot.local.md`

+ - 可以依赖 repo-local `.codex/hooks.json` 的 `Stop` runtime

+ - `.claude/knowledge/` 可作为只读知识库

+ - 不恢复历史 plugin-sync、bridge、watcher

- 基线文件里的 Claude 专有机制只作为方法论参考，不直接照搬。

+ ## Runtime Helpers

- ## 用户意图映射

+ 先解析状态脚本路径：

- 把当前用户请求视为以下两类之一：

+ ```bash

+ AUTOPILOT_STATE_SCRIPT="$(git rev-parse --show-toplevel 2>/dev/null)/codex/plugins/autopilot-codex/assets/scripts/autopilot_state.py"

+ if [ ! -f "$AUTOPILOT_STATE_SCRIPT" ]; then

+ AUTOPILOT_STATE_SCRIPT="${CODEX_HOME:-$HOME/.codex}/plugins/cache/string-codex-plugins/autopilot-codex/local/assets/scripts/autopilot_state.py"

+ fi

+ ```

- 1. **启动新流程**

- - 用户描述一个要完成的目标

- 2. **控制已有流程**

- - `approve` / `/autopilot approve`

- - `revise <反馈>` / `/autopilot revise <反馈>`

- - `status` / `/autopilot status`

- - `cancel` / `/autopilot cancel`

+ 统一使用它管理状态：

- 如果用户请求更像提交或诊断：

+ ```bash

+ python3 "$AUTOPILOT_STATE_SCRIPT" start --goal "<GOAL>"

+ python3 "$AUTOPILOT_STATE_SCRIPT" approve [--feedback "<TEXT>"]

+ python3 "$AUTOPILOT_STATE_SCRIPT" revise --feedback "<TEXT>"

+ python3 "$AUTOPILOT_STATE_SCRIPT" status [--json]

+ python3 "$AUTOPILOT_STATE_SCRIPT" cancel [--reason "<TEXT>"]

+ ```

- - `autopilot commit` -> 引导并使用 `$autopilot-commit-codex`

- - `autopilot doctor` -> 引导并使用 `$autopilot-doctor-codex`

+ ## 用户意图映射

- ## 状态文件

+ 把当前用户请求视为以下两类之一：

- 创建或更新 `.codex/autopilot.local.md`。初始化时使用 `assets/autopilot-state-template.md` 作为骨架，并填充真实值。

+ 1. 启动新流程

+ 2. 控制已有流程：`approve` / `revise <反馈>` / `status` / `cancel`

- 必须维护这些 frontmatter 字段：

+ 如果请求更像提交或诊断：

- - `runtime: "codex"`

- - `gate: "" | "design-approval" | "review-accept"`

- - `iteration`

- - `retry_count`

- - `max_retries`

- - `started_at`

- - `updated_at`

- - `goal`

+ - `autopilot commit` -> `$autopilot-commit-codex`

+ - `autopilot doctor` -> `$autopilot-doctor-codex`

- ## 完成提示音

+ ## 状态写回规则

- - 当你因为 `design-approval`、`review-accept`、`done` 或 `cancelled` 准备把控制权还给用户时，先尽力播放一次完成提示音

- - 使用这个 best-effort 命令：

- - `NOTIFY_SCRIPT="${CODEX_HOME:-$HOME/.codex}/plugins/cache/string-codex-plugins/autopilot-codex/local/assets/scripts/play-sound.sh"; [ -f "$NOTIFY_SCRIPT" ] && bash "$NOTIFY_SCRIPT" stop >/dev/null 2>&1 || true`

- - 提示音失败不能阻塞流程，也不要把播放失败当成任务失败

+ - 每次改 `phase`、`gate`、`retry_count`、`qa_scope`、`updated_at`，先写回 `.codex/autopilot.local.md`

+ - design 必须写完 `## 目标`、`## 设计文档`、`## 实现计划`、`## 验证方案`

+ - implement 必须把红队产物写回 `## 红队验收测试`

+ - qa / auto-fix 必须把每轮证据追加到 `## QA 报告`，不要覆盖旧轮次

+ - merge 结束前把最终摘要写回状态文件，再设 `phase=done`

## 工作流

- ### 1. 启动或恢复流程

+ ### 1. 启动或恢复

- - 如果用户是控制命令，先读取 `.codex/autopilot.local.md`

- - 如果状态文件不存在：

- - `approve` / `revise` / `status` / `cancel` 都直接告诉用户当前没有活跃的 Codex autopilot

- - 如果是新目标：

- - 用模板创建状态文件

- - 写入目标、时间戳和初始 frontmatter

- - `phase=design`

- - `gate=""`

- - `retry_count=0`

+ - 新目标：运行 `start`，然后继续当前 phase

+ - 控制命令：运行对应子命令；如果 phase 被推进到活跃阶段（含 `auto-fix`、`merge`），在同一轮继续推进

+ - 如果没有状态文件，`approve/revise/status/cancel` 直接说明没有活跃 autopilot

### 2. Design

- 先做设计，不直接写代码。

- - 读取 `.claude/knowledge/index.md`；没有索引时退回读 `.claude/knowledge/decisions.md` 和 `.claude/knowledge/patterns.md`

+ - 读取 `.claude/knowledge/index.md`；没有索引时退回读 `decisions.md` 和 `patterns.md`

- 探索代码库，识别技术栈、现有模式、测试框架、可复用模块

- - 参考 `plugins/autopilot/skills/autopilot/references/` 中的计划与审查模板

- 在状态文件中写入：

- `## 目标`

- `## 设计文档`

- `## 实现计划`

- `## 验证方案`

- 设计产物至少包含：

- 目标

- 技术方案

- 文件影响范围

- 风险评估

- 测试策略

- 1-3 个真实场景验证步骤

- 完成后：

- - 设置 `gate: "design-approval"`

- - 更新 `updated_at`

- - 向用户展示设计摘要并明确等待 `approve` 或 `revise`

- - 在审批前停止，不进入实现

- ### 3. Approve / Revise

- 当状态文件存在且有 gate 时：

- - `approve`

- - 如果 `gate=design-approval`：进入 `phase=implement`，清空 `gate`

- - 如果 `gate=review-accept`：进入 `phase=merge`，清空 `gate`

- - `revise <反馈>`

- - 把反馈追加到 `## 用户反馈`

- - 如果当前 gate 是 `design-approval`：保持 `phase=design`

- - 如果当前 gate 是 `review-accept`：回到 `phase=implement`

- - 清空 `gate`

- - `retry_count` 保持不变，除非你明确开始新的 QA 修复轮次

- ### 4. Implement

+ - 必须启动 plan reviewer 子代理，最多 2 轮

+ - 完成后设置 `gate: "design-approval"` 并停下等待用户审批

- Codex 版不依赖 Stop hook 自循环，要在当前会话内明确推进。

+ ### 3. Implement

- 先基于设计产出红队验收标准，再进入编码

- - 如果运行时支持子代理，优先使用并行红蓝分工

- - 如果不支持子代理：

- - 先写 `## 红队验收测试` 或验收检查清单

- - 再按计划实现蓝队部分

- - 绝不为了让实现通过而篡改红队验收标准

- 实现阶段要把产出写回状态文件：

- - 标记已完成任务

- - 记录实现摘要

- - 更新 `updated_at`

- 实现完成后进入 `phase=qa`

- ### 5. QA

- 执行顺序固定：

+ - 必须并行启动蓝队和红队子代理

+ - 红队只能看到目标 + 设计文档，不能看到实现计划和蓝队新代码

+ - 红队产物必须写回 `## 红队验收测试`

+ - 如果子代理不可用：

+ - 记录 `FORCED DOWNGRADE`

+ - 红队降级为验收清单后才能继续

+ - 实现完成后进入 `phase=qa`

- 1. 红队验收测试或验收清单

- 2. 类型检查 / lint / 单元测试 / 构建

- 3. 设计文档中的真实场景验证

- 4. 设计符合性与代码质量审查

+ ### 4. QA

- 规则：

+ 固定顺序：

- - 成功需要证据

- - 假设需要证据

- - 不允许修改红队测试来“修复”实现

- - 实际用户场景验证不能跳过

+ 1. Tier 0 红队验收

+ 2. Tier 1 类型/lint/测试/构建

+ 3. Tier 1.5 真实场景验证

+ 4. Tier 2 设计 reviewer + 代码质量 reviewer，并行

+ 5. Tier 3 / Tier 4 集成与回归

如果 QA 失败：

- - 进入修复循环

+ - 先把失败证据写入 `## QA 报告`

+ - 设置 `phase=auto-fix`

- `retry_count += 1`

- 最多 3 轮

- - 每一轮都先解释根因，再修复，再重跑受影响验证

如果 QA 通过：

+ - 设置 `qa_scope=""`

- 设置 `phase=merge`

- 设置 `gate=review-accept`

- - 更新 `updated_at`

- 向用户展示验收摘要并等待 `approve` 或 `revise`

- ### 6. Merge

- 如果用户明确要提交：

+ ### 5. Auto-fix

- - 调用 `$autopilot-commit-codex`

+ - 逐项记录失败原因、根因假设、修复动作、重跑结果

+ - 绝不修改红队验收标准

+ - `retry_count < max_retries`：设置 `qa_scope="selective"`，再回到 `phase=qa`

+ - `retry_count >= max_retries`：记录未解决项，设置 `gate=review-accept`，停下让用户决策

- 如果用户暂时不提交：

+ ### 6. Merge

- - 输出完成摘要

- - 保留状态文件，直到用户确认后再进入 `done`

+ - 需要提交时调用 `$autopilot-commit-codex`

+ - 不需要立即提交时保留状态文件，直到进入 `done`

+ - 结束前把最终摘要写回状态文件，再设 `phase=done`

### 7. Cancel / Done

- - `cancel`：把 `phase` 设为 `cancelled`，保留最后状态和取消原因，不删除文件

- - 流程正式完成后：把 `phase` 设为 `done`

+ - `cancel`：设为 `cancelled` 并记录原因，由 Stop hook 清理

+ - `done`：由 Stop hook 清理

## 输出要求

- - 面向用户的汇报保持简洁

- - 设计审批和验收审批都必须显式停下等待用户

- - 任何时候都不要把 Codex 的运行时产物写到 `.claude/` 的运行时文件里

+ - 汇报保持简洁

+ - 审批门必须显式停下等待用户

+ - 不把 Codex runtime 写回 `.claude/`