Codex Conductor

Codex 编排器（Codex Orchestrator）

将 Codex 协调为一个纪律严明的交付系统，而非一次性生成工具。

核心模式

必须同时指定以下两项：

• project_mode

  • greenfield：从零开始构建
  • brownfield：接入并现代化现有系统

• execution_mode

  • autonomous：当所有准入检查（gates）通过后自动推进
  • gated：在每个准入检查点暂停，等待用户人工审批

治理原则：规格驱动开发（Spec-Driven Development）

无规格，不编码。 此为不可协商的硬性要求。

任何实现工作启动前，必须存在一份书面规格文档（spec），内容须包含：

• 待构建的内容（What）
• 构建原因与业务动因（Why）
• 可验证的验收标准（Acceptance Criteria）
• 约束条件及明确排除范围（Constraints & Out-of-Scope）

编码代理（coding agent）严禁：

• 对需求进行猜测
• 对系统行为做未经确认的假设
• 添加规格中未明确要求的功能
• 引入规格中未定义的抽象层或架构概念

若规格存在歧义或缺失 → 立即中止 并向用户澄清。绝不允许自行猜测。

完整规格模板与强制执行规则详见：references/spec-driven-development.md

不可跳过的执行序列

1. 需求采集 + 规划问卷填写
2. 规格编写与审批（所有代码编写前，必须完成规格文档）
3. 文档脚手架搭建 + AGENTS.md 协议文件生成
4. 按所选模式执行前置架构工作
5. 架构设计 + ADR 基线确立（需引用已批准的规格）
6. 按垂直切片（vertical slice）方式构建（每项任务均须明确关联对应规格）
7. 基于规格中定义的验收标准开展验证
8. 安全性/质量准入检查（Security/Quality Gates）
9. 发布就绪评估 + 交付移交（handover）

严禁静默跳过任一准入检查；严禁在无规格前提下开展实现工作。

必备参考资料

运行本系统前，请务必通读以下参考文档：

• references/spec-driven-development.md（首要必读——统摄全部工作）
• references/planning-questionnaire.md
• references/modes.md
• references/gate-checklists.md
• references/testing-matrix.md
• references/manual-test-templates.md
• references/codex-runbook.md
• references/gate-prompts.md
• scripts/agent_exec.py
• references/research-playbook.md（仅当 research_mode=true 时需查阅）

脚手架初始化

初始化项目所需基础工件：

python scripts/init_project_docs.py --root--mode

该命令将创建或更新以下内容：

• AGENTS.md（定义项目工作流契约）
• docs/*.md（含规划、架构、测试、进度、变更等各类文档）
• brownfield 模式专属文档（仅当 --mode brownfield 时生成）
• .orchestrator/status.json（机器可读的状态快照）
• .orchestrator/context.json（记录项目模式、执行模式、研究模式等上下文）

规划阶段规则

在启动任何其他操作前，必须首先向用户确认：

• 使用的编码代理类型（codex | claude | opencode | pi）
• 备用代理（fallback agent）

随后，须逐项询问 references/planning-questionnaire.md 中列出的所有必需问题。

最低限度必须获取的答案包括：

• 项目使命（mission）
• 核心用户旅程（top user journeys）
• v1 版本范围（v1 scope）
• 部署目标环境（hosting target）
• 技术栈偏好（stack preference），或明确请求技术推荐
• project_mode
• execution_mode
• “完成”定义（definition of done）
• 验收测试方案（acceptance tests）

若启用 research_mode=true，须在 G2 阶段前产出 docs/research-notes.md 及架构推荐方案。

按模式划分的前置要求

Greenfield 模式

G2 阶段前必须完成：

• 需求与“完成”定义（DoD）的清晰共识
• 架构基线（architecture baseline）
• ADR-0001（含至少一项替代方案分析）
• CI/测试基线建设方案（CI/test baseline plan）

Brownfield 模式

G2 阶段前必须完成（且须由编码代理而非编排器撰写）：

• 当前系统架构与组件清单（as-is architecture and system inventory）
• 依赖关系图谱与风险登记册（dependency map and risk register）
• 特征化测试基线（characterization-test baseline）
• 迁移策略与回滚方案（migration strategy + rollback approach）
• 兼容性边界说明（compatibility boundaries documented）

准入检查引擎（Gate Engine）

使用定义于 references/gate-checklists.md 的 G0 至 G7 共八级准入检查。

通过脚本更新准入状态：

python scripts/gate_status.py set --root--gate G3 --state PASS --note "slice-1 verified"

校验状态文件格式合规性：

python scripts/gate_status.py validate --root

允许的状态值：PENDING | IN_PROGRESS | PASS | FAIL | BLOCKED  
默认启用准入前置条件检查（含顺序约束 + 模式感知的文档完备性校验）。

验证规则

依据 references/testing-matrix.md 执行验证。

每次推进至下一阶段时，必须完成以下强制检查项：

• 代码规范（lint）、类型检查（type）、构建（build）
• 单元测试 / 集成测试 / 端到端测试（unit/integration/e2e，视场景适用）
• API 合约合理性检查（若存在 API）
• 安全基线扫描（security baseline）
• 文档同步一致性校验（docs sync verification）

此外，还需执行 references/manual-test-templates.md 中定义的手动测试脚本。

文档管理规则

对每个有实质意义的工作步骤，均须同步更新以下文档：

• docs/tasks.md（任务列表）
• docs/progress.md（进度追踪）
• docs/change-log.md（追加变更记录）
• docs/traceability.md（可追溯性映射）
• docs/test-results.md（记录测试证据）

对于用户提出的变更请求，请先运行：

python scripts/change_impact.py --root--request ""

然后，严格完成其输出的所有待办事项（TODOs），并在受影响的文档中逐一落实。

Codex 执行模式

长时任务请使用 PTY 或后台进程执行；具体命令模式参见 references/codex-runbook.md。

关键规则：每次执行仅处理单个任务，禁止在一个提示（prompt）中驱动整个项目。

G4 阶段须维护 docs/g4-task-plan.md 检查清单，并严格按条目逐项执行任务。

生成面向特定准入检查的 Prompt：

python scripts/generate_gate_prompt.py --gate--agent--project-mode--execution-mode--research-mode--task "" --spec-ref ""

update_docs_step.py 当前仅为故障恢复或人工记账的备用工具。  
主流程预期：编码代理在每次任务完成后，直接更新相关文档。

标准执行循环如下：

1. 验证当前任务已有对应规格（无规格 → 不执行）
2. 使用规格驱动型 Prompt 模板启动选定的编码代理
3. 编码代理在任务完成后立即更新文档（含移交检查清单 handoff checklist）
4. 编码代理唤醒 OpenClaw 代理，并传递任务摘要及验证步骤所在文档路径

5. OpenClaw 代理自主执行验证：

   • CLI 类检查：通过终端工具执行
   • 浏览器/UI 类检查：通过浏览器工具（针对 Web 流程）手动执行
6. 验证输出是否完全符合规格中定义的验收标准
7. 若验证失败，OpenClaw 将精确失败信息返回给编码代理，并触发修复重试循环
8. 仅当全部验证通过后，方可标记准入状态为 PASS；否则标记为 FAIL 或 BLOCKED

强制执行机制：

• run_gate.py 对 G3/G4（实现类准入）任务强制要求 --spec-ref 参数
• run_gate.py 要求提供编码代理与备用代理上下文
• 每项任务均须提供验证证据（通过 --validate-cmd 和/或 --ui-review-note）
• 若任务标记 --requires-browser-check，则必须提供 --ui-review-note
• status=PASS 要求至少存在一项 --validate-cmd
• 使用 --agent-dry-run 时，禁止设置 status=PASS
• G4 阶段 PASS 前，必须确保 docs/g4-task-plan.md 中无未勾选任务
• 所有验证输出均记录至 docs/validation-log.md
• 编码代理须在每次任务后更新文档，包括 docs/agent-handoff.md
• 在 brownfield 模式下，若 G1/G2 阶段的接入文档未由编码代理更新，则准入失败
• 编码代理使用的 Prompt 必须包含 references/spec-driven-development.md 中规定的规格前置说明（spec preamble）
• 任何未引用规格的实现 → 自动判定为 FAIL
• 在 autonomous 模式下，验证失败将自动触发修复重试（默认最多 2 次），并将失败详情透传给编码代理
• 可选严格模式：启用 --auto-block-on-retry-exhaust 后，重试耗尽时将自动将准入状态设为 BLOCKED

进度可视化

生成简明状态看板：

python scripts/progress_dashboard.py --root

该命令汇总当前所处准入阶段、整体完成百分比、阻塞项及近期活动。

单命令执行单任务级准入步骤：

python scripts/run_gate.py --root--gate G2 --agent codex --fallback-agent claude --project-mode brownfield --execution-mode gated --research-mode true --task "architecture baseline refined for API routing" --status IN_PROGRESS --validate-cmd "npm run -s typecheck" --ui-review-note "N/A for architecture-only task"

仅当准入检查清单所有条目均完成时，方可标记 PASS：

python scripts/run_gate.py --root--gate G2 --agent codex --task "architecture gate complete" --status PASS --validate-cmd "npm run -s typecheck"

针对 Web/UI 类任务，必须由 OpenClaw 代理完成浏览器端验证：

python scripts/run_gate.py ... --requires-browser-check --ui-review-note "Verified login + CRUD manually in browser via OpenClaw browser tools"

打包可分发的技能构件（skill artifact）：

python scripts/package_skill.py --skill-dir . --out dist

终态交付物

项目完成时须交付以下成果：

• docs/progress.md 达到 100% 完成度
• 来自 .orchestrator/status.json 的最终准入总结
• 测试结果摘要 + 尚未解决的风险项
• 部署说明与回滚指南
• 下一迭代待办事项清单（next-iteration backlog）

如仍存在阻塞项，须标记为 PARTIAL_COMPLETE，并明确列出各项阻塞原因及责任人（owners）。