| name | ultra-plan |
| description | Use when user invokes /ultra-plan to run an end-to-end loop — interview (Claude clarifies + writes spec) → execute (Codex 默认执行: Single/Todo/Teams 三种粒度，对应 1 次/多次串行/多次并行 `codex exec`) → evaluate (Claude review + AC check) → fix-loop (找到问题派 Codex 修，最多 2 轮) → report. Default Autonomous mode: Phase 1 talks spec clear then AI runs without interrupting user until final report. `/ultra-plan --collaborative` switches to step-by-step user confirmation. **Role split (since 2026-05-10)**: Claude = planner + judge; Codex = executor + fixer. 角色对称。 |
Ultra-Plan — Scheduler for Long-Running Loops
Overview
/ultra-plan 是高层 scheduler，编排 interview → plan → execute → evaluate → fix 五个阶段成一次完整 loop。核心诉求：用户给出需求，AI 问清楚后自己跑完整个链条，最后交一份报告。
核心原则：纯 SKILL.md + 一个 sync 脚本。不带渲染器、不带 server、不带模板引擎。所有产物（spec / findings / ac_results / final_report / 临时 HTML）都是一次性文件，Claude 在需要时按照本 SKILL.md 指令即时生成。
角色分工（2026-05-10 起，对称化）
| 角色 | Phase 1 | Phase 3 | Phase 4a | Phase 4c |
|---|
| Claude | ✅ 规划 / interview | ❌（编排） | ✅ review / judge | ❌（编排） |
| Codex | ❌ | ✅ 执行 (codex exec) | ❌ | ✅ fix (codex exec) |
不再 spawn 子 Claude / writing-plans 内部派活——这些都换成 codex exec --full-auto。Claude 只负责"想清楚要做什么"和"判断做得对不对"，绝不亲自改代码。
When to Use
- 用户有明确任务目标（不是探索性想法），希望扔给 AI 去做
- 任务需要多步执行（改代码 + 跑测试 + 评估）
- 用户不想被中间过程打扰，只看最终报告
- 需要外部 evaluator（Codex 交叉 review + AC 机器评估）保证质量
When NOT to Use
- 纯探索性需求（没有明确完成标准）→
/brainstorm
- 简单一步任务 → 直接执行
- 用户想实时参与每步决策 → 用
--collaborative 或直接 /interview + /spawn
Dual Mode
| Mode | Trigger | Phase 2 行为 | Phase 4 失败 |
|---|
| Autonomous (默认) | /ultra-plan <task> | AI 按 spec 自选执行策略 | 汇报 final_report，不自动修 |
| Collaborative | /ultra-plan --collaborative <task> | AskUserQuestion 4 选项让用户拍板 | 汇报 + 4 选项问用户 |
Phase 0: Mode Detection
- 解析
--collaborative 或 -c flag → mode = collaborative
- 否则 →
mode = auto
- 如果 prompt 已含 spec 文件路径（
docs/orchestrator/specs/*.md）→ 跳过 Phase 1，直接进 Phase 2
- 把
mode 写入后续产出 spec 的 frontmatter
Phase 0.5: Bootstrap TodoList (关键)
进入 Phase 1 前必须做这一步。用 TaskCreate 立刻把 6 个 Phase 写成任务清单，让 spinner 持续显示进度，同时给 AI 自己一个"下一阶段已等待"的视觉信号——避免每阶段结束后误以为要用户确认：
TaskCreate: "Phase 1a — Codebase Scan (自己读代码库)"
TaskCreate: "Phase 1b — Interview (只问 genuine_unknowns)"
TaskCreate: "Phase 2 — Plan Decision"
TaskCreate: "Phase 3 — Execute"
TaskCreate: "Phase 4 — Evaluate (Codex + AC + auto-fix)"
TaskCreate: "Phase 5 — Chat 汇报"
每完成一个 phase 立刻 TaskUpdate 标 completed，同一轮把下一 phase 标 in_progress。两动作连在一起做，不要中间插用户交互。
这个 TodoList 是 autonomous mode 的防线：只要看到 pending tasks，继续执行；不要问"要我继续吗"。
Phase 1a: Codebase Scan (提问前先自己查)
在调用 interview-mode 之前，ultra-plan 自己先做一轮静默探索（不打扰用户），把能从代码里读出来的东西读出来。这是 Opus 4.7 autonomous 精神的核心 —— 能从文件里推断的绝不问用户。
扫描清单（按顺序执行，每项 1-2 个工具调用）：
- 项目身份: 读
CLAUDE.md / README.md / AGENTS.md（如存在）
- 技术栈: 读
package.json / pyproject.toml / Cargo.toml / go.mod / requirements.txt（存在哪个读哪个，不存在跳过）
- 目录结构:
ls 顶层 + 1 级展开（快速把握代码组织）
- 关键词命中: 按用户 prompt 里的关键词 grep 现有代码（例："加一个 login 函数" → grep
login\|auth 定位现有实现或缺失）
- 相关测试: 若有
tests/ 或 __tests__/，看测试命名惯例和跑测命令
扫描产出（内部记录，下一步喂给 interview）：
codebase_scan:
project: <从 CLAUDE.md / README 推断的项目描述>
tech_stack: <从依赖文件推断>
conventions:
- <命名风格：snake_case / camelCase>
- <测试框架：pytest / jest / go test>
- <目录惯例>
existing_related:
- <已有的相关文件和位置>
defaults_inferred:
- <AI 凭扫描结果能填好的 spec 默认值，列出来>
genuine_unknowns:
- <扫完依然没法推断、必须问用户的点>
关键规则：
defaults_inferred 里的东西 → 不要在 interview 里问，直接预填进 spec，在 Auto-Decision Log 里记一句"从 X 推断得到 Y"genuine_unknowns 里的东西 → 这才是 interview 该问的
什么永远不问（因为代码会告诉你）：
- ❌ "这是什么语言/框架？" → 读
package.json 或后缀
- ❌ "测试怎么跑？" → 读
package.json scripts / pyproject.toml
- ❌ "代码风格是 snake_case 还是 camelCase？" → 看现有文件
- ❌ "要放哪个目录？" → 看现有同类文件的位置
- ❌ "要不要加测试？" → 看项目是否有测试目录和覆盖率惯例
- ❌ "要兼容哪个版本？" → 读依赖版本锁定文件
什么必须问（因为代码不会告诉你）：
- ✅ 这次要做什么具体行为 / 功能（用户意图）
- ✅ 成功的硬标准（Acceptance Criteria，必须用户亲自确认）
- ✅ 有没有不能碰的东西（Constraints）
- ✅ 用户的品味偏好（命名某个新概念、UX 风格等）
Phase 1b: Interview (强制)
调用 interview-mode skill，把 Phase 1a 的扫描结果塞进 prompt，这样 interview 不会重复问已知信息。prompt 模板：
被 ultra-plan 调用，mode={auto|collaborative}。
产出 spec 到 docs/orchestrator/specs/YYYY-MM-DD-<topic-slug>.md（按下方 schema）。
日期+slug 冲突 → 追加 -v2, -v3 不覆盖。
## 已完成的 Codebase Scan（ultra-plan Phase 1a 产出）
<把 Phase 1a 的 codebase_scan 整块贴进来 —— 项目、技术栈、约定、existing_related、
defaults_inferred、genuine_unknowns>
## 必须追问到完备的字段
- Intent (1-2 句)
- Context (背景/现有系统 —— 若 Phase 1a 已推断出来，直接填，不问)
- Scope: In / Out
- Acceptance Criteria — Auto-Executable (至少 1 条 CMD 或 METRIC 行)
- Acceptance Criteria — Manual Check (可为空)
- File Locations: Modify / Create / Test (Phase 1a 的 existing_related 应能预填大部分)
- Constraints
- Execution Strategy: Single | Todo | Teams + Rationale
- frontmatter 字段: mode, ralph_loop
## 提问纪律
- 只问 genuine_unknowns 里的点
- defaults_inferred 的内容用"确认式提问"而不是"开放式提问"：
❌ "用什么测试框架？"
✅ "我看到 package.json 里有 jest，默认用 jest 对吗？(推荐) / 换成 vitest / 其他"
- 任何能从 codebase_scan 得出的默认值 → 直接填 spec，不问。在 spec 的 Auto-Decision Log
里记 "Inferred from <source>: <value>"
不输出 "Transition to Next Phase"。返回 spec 路径给 ultra-plan。
Spec Schema
---
topic: <kebab-case-topic>
slug: <slug>
created: YYYY-MM-DD
orchestrator: ultra-plan
mode: auto | collaborative
ralph_loop: false
source: /ultra-plan "<原始用户输入>"
---
# <Topic Title> — Requirements Spec
## Intent
[1-2 句]
## Context
[背景]
## Scope
- In scope: [...]
- Out of scope: [...]
## Acceptance Criteria — Auto-Executable
> Phase 4b 机器执行。必须是可测量指令。
- [ ] CMD: `<shell command>` → <expected>
- [ ] METRIC: `<measurement command>` → <threshold>
## Acceptance Criteria — Manual Check
> Phase 4c 写进 final_report 作为 checklist，人工勾选。
- [ ] <人工判断项>
- 检查方式: <操作步骤>
- 备注:
## File Locations
- Modify: <path:lines>
- Create: <path>
- Test: <path>
## Constraints
- [...]
## Key Insights (from interview)
- [...]
## Execution Strategy
- Recommended: Single | Todo | Teams
- Rationale: [...]
- Parallelization: [...]
## Auto-Decision Log
> Autonomous mode 下 AI 自动决策记录，orchestrator 运行中追加。
Phase 2: Plan Decision (Codex 粒度选择)
并行/串行的规划维度保留不变，只是 actor 全部从 spawn/writing-plans/single-session 统一换成 codex exec。Claude 只负责"切多大块"，不亲自做活。
| Strategy | 含义 | Codex 调用方式 |
|---|
| Single | 一口气搞定 | 1 个 codex exec --full-auto 任务跑全量 spec |
| Todo | 串行多步（前一步 output 是后一步 input） | N 个 codex exec 顺序执行，每步喂上一步的 diff/log |
| Teams | 并行多块（独立可分） | N 个 codex exec 同时跑（每个一片 spec，互不依赖） |
Autonomous Mode (默认)
不打扰用户。按 spec.ExecutionStrategy.Recommended 选 Single/Todo/Teams，然后 Phase 3 起 codex。
如果 spec.ExecutionStrategy 缺失或矛盾 → 属 "Spec 内部矛盾" 关键决策，必须 AskUserQuestion。
Collaborative Mode
AskUserQuestion 让用户拍板：
{
"questions": [{
"question": "如何派 Codex 执行 spec 定义的任务？",
"header": "Codex 粒度",
"options": [
{"label": "Single — 1 个 codex exec", "description": "整份 spec 一次性扔给 codex --full-auto"},
{"label": "Todo — 多个 codex 串行", "description": "拆成 step 1 → step 2 → step 3，每个 step 1 个 codex exec，前后依赖"},
{"label": "Teams — 多个 codex 并行", "description": "拆成独立任务并行派多个 codex exec（spec 必须能解耦才合适）"},
{"label": "修改 spec 后重跑", "description": "回 Phase 1 补齐/调整 spec"}
],
"multiSelect": false
}]
}
Phase 3: Execute (统一派 codex exec)
不再调 writing-plans / spawn / 本 session 自做。所有执行都通过 codex exec --full-auto，差别仅在 Codex 调用次数和拓扑。
通用 codex prompt 模板（所有路径共享）
codex exec --full-auto -c 'sandbox_mode="danger-full-access"' "$(cat <<'EOF'
被 ultra-plan 调用。
Spec: <绝对路径 docs/orchestrator/specs/<spec-file>>
你的职责: 按 spec 实现代码。
- spec.AcceptanceCriteria 是 Phase 4 评估依据，**不要修改或降级**
- spec.Constraints 是硬约束（违反则停下来返回 "CONSTRAINTS_CONFLICT: <原因>"）
- spec.FileLocations 是改动范围（不在范围内的文件不动）
- 完成后跑 spec.AcceptanceCriteria-AutoExecutable 里的命令做自检
输出: 改动文件 + 一句话 summary。不要要求用户确认。
EOF
)"
Single 路径
codex exec --full-auto "<上面的模板>" \
2>&1 | tee docs/orchestrator/evaluations/<slug>/exec_single.log
Todo 路径（串行）
把 spec 拆成 step1/step2/step3，每个 step 一次 codex exec，前一步完成后下一步起。每步 prompt 含 "前置步骤完成的 summary" + "本步要做的子任务"：
for STEP in 1 2 3; do
codex exec --full-auto "$(cat <<EOF
被 ultra-plan Todo 路径调用，第 $STEP 步。
Spec: <path>
前置步骤已完成: <prev_summary，第 1 步则写"无">
本步任务: <step-specific 子目标>
其余约束同 spec。
EOF
)" 2>&1 | tee docs/orchestrator/evaluations/<slug>/exec_step$STEP.log
done
Teams 路径（并行）
把 spec 拆成独立任务 A/B/C（前提是它们之间无依赖），用 & + wait 并行起多个 codex exec：
codex exec --full-auto "<Spec A 子集>" > exec_A.log 2>&1 &
PID_A=$!
codex exec --full-auto "<Spec B 子集>" > exec_B.log 2>&1 &
PID_B=$!
codex exec --full-auto "<Spec C 子集>" > exec_C.log 2>&1 &
PID_C=$!
wait $PID_A $PID_B $PID_C
Teams 路径前置检查：若 spec 没明确说"可并行"且各任务之间共享同一些文件 → 自动降级为 Todo（防止 codex 之间互相冲突 git working tree）。
Phase 3 通用规则
- 始终用
--full-auto（已授权 sandbox），不允许 codex 反过来问 Claude / 用户
- 始终重定向 stdout/stderr 到
docs/orchestrator/evaluations/<slug>/exec_*.log（Phase 4 review 要读）
CONSTRAINTS_CONFLICT 字符串出现 → 停下来转 Phase 4 边界，由 Claude 判断是否上报用户- 任何 codex exec 超过
30 min 没结束 → 视为 hang，超时杀掉，Phase 4 标 "execution timeout"
Phase 4: Evaluate (Claude review + Codex auto-fix, 最多 2 轮)
4a. Claude Review (Claude 自己读 diff，不再派 Codex)
Claude 直接读 Codex Phase 3 的产物——git diff + exec_*.log——按 spec 逐条比对。不再调用 codex exec review，因为我们现在的角色分工是 Claude = judge。
mkdir -p docs/orchestrator/evaluations/<spec-slug>
git --no-pager diff --stat
git --no-pager diff
tail -200 docs/orchestrator/evaluations/<slug>/exec_*.log
Claude review 流程（在 ultra-plan 内部完成，不调外部 skill）：
- 逐条比对 AC：把每条
Acceptance Criteria — Auto-Executable 拿出来，看 diff 里有没有对应实现
- Constraints 复核：每条
Constraints 都对 diff 验一遍
- 回归 / 边界 / 安全风险：用代码阅读判断
- 写 findings.md 到
docs/orchestrator/evaluations/<slug>/findings.md：
# Findings — <slug>
## BLOCKER
- [B1] <file:line> — <what's wrong> — <why it matters> — <breaking scenario>
## MAJOR
- [M1] ...
## MINOR
- [m1] ...
## Out of Scope (列出但不动)
- ...
⚠️ Claude review 阶段绝不亲自改代码——发现的问题全部写进 findings.md，等 Phase 4c 派 Codex 修。这是角色对称的核心约束。
4b. Auto-Executable AC 逐条执行
解析 spec 的 "Acceptance Criteria — Auto-Executable" 段。每条：
- CMD 行 →
bash -c "<cmd>"，记 stdout / stderr / exit_code
- METRIC 行 → 跑命令，按 regex 提取数值，对比阈值
写入 docs/orchestrator/evaluations/<spec-slug>/ac_results.json：
[
{"criterion": "pytest tests/auth/ -v", "type": "CMD", "status": "PASS", "exit_code": 0, "stdout_head": "…"},
{"criterion": "login p50 < 200ms", "type": "METRIC", "status": "FAIL", "measured": 345, "threshold": 200}
]
4c. Auto-Fix Loop (派 Codex 修, autonomous 核心)
Phase 4a + 4b 跑完后，若有以下之一 → 立刻派 Codex 修（不问用户）：
- Claude findings 含
BLOCKER 或 MAJOR
- Auto-Executable AC 有 FAIL
修复流程：
iteration = 1
while iteration <= 2 and (has_blocker_or_major_findings or has_ac_fail):
# 派 codex exec 修（不再用 spawn）
codex exec --full-auto -c 'sandbox_mode="danger-full-access"' "$(cat <<EOF
被 ultra-plan Phase 4c 调用修 bug。第 $iteration 轮。
Spec: <spec-path>
Findings: docs/orchestrator/evaluations/<slug>/findings.md
AC results: docs/orchestrator/evaluations/<slug>/ac_results.json
修复以下具体问题：
- <failing AC 1>
- <BLOCKER finding 1>
- <MAJOR finding 1>
约束:
- 不得违反 spec.Constraints
- 不得降级 spec.AcceptanceCriteria（让它能通过当前 AC，不要改 AC 文本）
- 若唯一可行修复会违反 Constraints → 停下来在 stdout 输出
'CONSTRAINTS_CONFLICT: <原因>'，由 Claude 判断是否上报用户
完成后再跑一次 spec 的 Auto-Executable AC 自检。
EOF
)" 2>&1 | tee docs/orchestrator/evaluations/<slug>/fix_iter$iteration.log
# 修完 Claude 重新跑 4a + 4b
重跑 Claude review → findings.md (overwrite)
重跑 auto AC → ac_results.json (overwrite)
iteration += 1
# 退出循环后：
if 仍有 BLOCKER / AC FAIL:
→ 继续到 4d，把"无法自动修复的问题"明确标出来
else:
→ 继续到 4d，全绿
什么时候不自动修、转而打扰用户：
- Codex 修复尝试 stdout 含
CONSTRAINTS_CONFLICT → 属"Constraints 违反"关键决策
- 修复需要新增外部依赖（新 API key / 装新 deps）→ 属"外部 API/资源依赖"关键决策
- 修了 2 轮仍不过 → 不再修，进 4d 标注"自动修复失败，需要人工"
什么情况不触发自动修：
- Claude review 只有
MINOR findings（命名风格、轻微冗余等）→ 不修，4d 列在"可选改进"供用户看
- Manual Check AC 为 FAIL → 本来就是人工项，不该自动修
4d. 生成 final_report.md（归档用）
⚠️ final_report.md 是归档，不是主输出。主输出是 4e 的 chat 汇报。
写入 docs/orchestrator/evaluations/<spec-slug>/final_report.md，结构：
# <topic> — Final Report
**Date:** YYYY-MM-DD
**Mode:** auto | collaborative
**Spec:** docs/orchestrator/specs/<spec-file>
## Summary
- **Status:** ✅ All auto AC passed, no BLOCKER findings / ⚠️ Partial: N failures
- **Phase 3 execution:** <what was built, 1-3 sentences>
- **Files changed:** <list or `git diff --stat`>
## Phase 4a Claude Findings (Claude reviewing Codex's output)
### BLOCKER
- <finding or "(none)">
### MAJOR
- <finding or "(none)">
### MINOR
- <finding or "(none)">
## Phase 4b AC Results
| Criterion | Type | Status | Details |
|-----------|------|--------|---------|
| <raw criterion string> | CMD | ✅ PASS | exit 0 |
| <raw criterion string> | METRIC | ❌ FAIL | measured 345, threshold 200 |
## Phase 4c Manual AC Checklist
> 以下 AC 无法自动执行，请人工验证后在本文件勾选。
- [ ] <item 1>
- 检查方式: <操作步骤>
- 备注:
- [ ] <item 2>
- 检查方式: ...
- 备注:
## Auto-Decision Log (autonomous mode only)
> 本次运行中 AI 做过的"不打扰的决策"。
- <decision 1>
- <decision 2>
## Recommended Next Steps
> 针对失败 AC / BLOCKER findings 的建议。**不自动执行**，由用户决定。
- 建议 1
- 建议 2
4e. Chat 汇报（主输出，最关键）
Phase 4 完成后直接在 chat 输出以下结构化文字——这是用户唯一真正看的东西。不要只给 final_report.md 路径让用户自己去看。
汇报模板（必须包含这 4 个段，按顺序）：
## ✅/⚠️ 完成: <topic>
**做了什么** (2-4 句)
<用动词主导：添加了 X 函数 / 修改了 Y 文件 / 跑通了 Z 测试。不要只贴文件名>
**检查结果**
- Phase 3 执行: Codex × <Single|Todo×N|Teams×N> 跑了 <N> 个 codex exec
- Auto AC: <N/M> 通过<若全过就写 "全过"，否则列出失败的>
- Claude review findings: <BLOCKER: N, MAJOR: N, MINOR: N>（被 Codex 自动修的标✓，未修的简述）
- Auto-fix 迭代: <N> 轮（如果有）
**⚡ 需要你拍板** (如果有关键决策触发 或 auto-fix 失败项)
- <具体问题 1>: <两个选项，一个推荐>
- <具体问题 2>: <...>
**📋 待人工验证** (Non-auto AC，通常 1-3 条，不用超过)
- [ ] <item 1> —— <如何检查>
- [ ] <item 2>
**下一步建议** (一句话)
<最常见的下一步：commit / 跑更多测试 / 部署 / 继续开发 XXX>
<详细归档: docs/orchestrator/evaluations/<slug>/ — 有需要再看>
什么不该放在 chat 输出：
- ❌ 完整的 findings 列表（放 findings.md 里）
- ❌ 每条 AC 的命令和 stdout（放 ac_results.json 里）
- ❌ 详细的 Auto-Decision Log（放 final_report.md 里）
- ❌ "欢迎回来" / "以下是总结" 之类的开场白
- ❌ Phase 4 流程说明（用户不需要看到内部机制）
什么必须放在 chat 输出：
- ✅ 做了什么（动词化的动作描述）
- ✅ 最终状态（绿灯还是有问题）
- ✅ 需要用户拍板的决定（明确列选项）
- ✅ 人工验证 checklist（短，≤5 条）
- ✅ 下一步建议（一句话）
- ✅ 归档路径（一行，不强调）
为什么 Phase 4 要 auto-fix（Codex 执行）
- 用户在 Phase 1 已经定好了 Acceptance Criteria = 验收标准
- AC FAIL 和 BLOCKER findings 是技术问题，不是需要用户价值观判断的事
- Claude judge + Codex fix 是角色对称的极限：Claude 永远只判断，Codex 永远只动手
- 让 Codex 自动修 = 尊重用户时间（这就是 autonomous mode 承诺）
- 2 轮上限 = 防止无限循环烧 token
- 仍不过的 → 清晰告诉用户什么修不了 + 为什么，不要藏起来
Key Decision Table
Autonomous mode 下，AI 根据下表判断是否打扰用户：
| 类型 | 判定 | 示例 | 处理 |
|---|
| 用户意图不明确 | ✅ 必须问 | prompt 太短/多义，AI 判断"我在猜" | AskUserQuestion 列 2-4 种解读 |
| 不可逆副作用 | ✅ 必须问 | git push --force, rm -rf, prod 部署 | AskUserQuestion 确认 |
| 品味/价值观 | ✅ 必须问 | UI 风格, 命名偏好, API 风格 | AskUserQuestion 给选项 |
| Spec 内部矛盾 | ✅ 必须问 | 两条 AC 互相打架 | 展示矛盾让用户取舍 |
| Constraints 违反 | ✅ 必须问 | 唯一修复路径违反 Constraints | 让用户选放宽/保留/放弃 |
| 外部 API/资源依赖 | ✅ 必须问 | 需新 API key、新 deps、新云资源 | 说明原因 |
| 实现技术选型 | ❌ AI 自选 | requests vs httpx | 记录到 final_report |
| 需求默认补全 | ❌ AI 自选（借模糊时问） | "加个 login" → email+password | 记到 Auto-Decision Log |
| Phase 3 内部修复 | ❌ AI 自选 | teammate 跑 test 报错自修 | 在 Phase 3 scope 内 |
| 文件结构细节 | ❌ AI 自选 | 拆文件粒度、module 组织 | 遵循项目惯例 |
| Phase 3 Codex 粒度 | ❌ AI 自选 | Single / Todo / Teams | 用 spec.Recommended |
| Phase 3 Codex 执行细节 | ❌ AI 自选 | Codex --full-auto 内部决策 | Codex 在 sandbox 内自治 |
| Phase 4 AC FAIL / BLOCKER / MAJOR | ❌ AI 自动修 | 报错、测试挂、regression | 派 codex exec 修 → Claude 重跑 4a/4b，最多 2 轮 |
| Phase 4 MINOR findings | ❌ AI 自选不修 | 命名风格、轻微冗余 | 列在 chat 汇报的"可选改进"供用户看 |
| Phase 4 auto-fix 失败 (2 轮仍不过) | — | 2 轮修复后还有 BLOCKER/FAIL | 停修，4e chat 汇报里明确列"未修的问题 + 原因" |
Codex 输出 CONSTRAINTS_CONFLICT | ✅ 必须问 | Codex 表明唯一修复路径违反 Constraints | AskUserQuestion 让用户选 |
核心原则：
- 真正会把事情搞砸的决策 → 必须打扰
- AI 判断"我在猜用户意图"时 → 必须打扰（哪怕技术上能跑）
- 其他默认不打扰 → 记
Auto-Decision Log 和 final_report.md
Anti-Pattern: "要我继续吗？"
Autonomous mode 下，阶段切换不是打扰点。以下所有行为都是违反契约：
| ❌ 违反契约 | ✅ 正确做法 |
|---|
| "Phase 1 完成了，要我继续吗？" | 直接 TaskUpdate → 进 Phase 2 |
| "spec 写好了，你先看一下再继续？" | 直接进 Phase 2，spec 是否 OK 交给 Phase 4 Codex review |
| "确认没问题回复'继续'或'go'" | 不需要确认，pending task 在等就是 go 信号 |
| "我稍微停一下让你过一眼" | 不要停。任何"停一下"都是违反 autonomous |
| 把 spec 摘要列出来请用户快速 review | spec 文件已在 disk，用户要看自己会看 |
| Claude review 发现 BLOCKER/MAJOR → 问用户"派人修还是手动改？" | 直接派 codex exec 修，最多 2 轮。修完汇报结果，不问方法 |
| Claude review 时手痒自己用 Edit/Write 改代码 | 严禁。Claude 只在 findings.md 写问题，所有 fix 必须经 codex exec 走 |
| AC FAIL → "你想怎么处理？" | AC 是用户自己在 Phase 1 定的 → FAIL 是技术问题，直接 auto-fix |
| 最终只回复 "done, see docs/orchestrator/evaluations/.../final_report.md" | chat 里直接写出：做了啥 + 检查结果 + 待拍板 + 下一步。文件归档只作附注 |
| 把 findings.md 完整内容粘进 chat | chat 只放分级计数（BLOCKER: N, MAJOR: N, MINOR: N），详情在归档文件里 |
| 上来就问"你用什么语言/框架/测试？" | 先做 Phase 1a Codebase Scan，读 package.json / README / CLAUDE.md 自己推断，confirm 式问（默认值 + 推荐标） |
| 问"代码放哪个目录？" | 看现有同类文件在哪，直接预填 spec.FileLocations，不问 |
| 问"要不要加测试？" | 看 tests/ 目录是否存在、覆盖率惯例，默认跟随项目习惯 |
判断是否该打扰的唯一标准：是否触发"关键决策表"12 类里的 ✅ 行。spec 已写好 不在里面。意图不明确 在里面——但如果 interview 都没问出来，就别指望在 Phase 2 起点问出来。
用户选择 /ultra-plan (autonomous mode) 的语义 = 授权跑完整个 loop，不是"每步等我点头"。想要每步点头的用户会用 --collaborative。
如果你（AI）此刻正想问"要继续吗"——停下这个念头，直接继续。spec 的瑕疵会在 Phase 4 被发现，修复决策会在 final_report 里让用户事后看。Autonomous mode 的全部价值就在于用户不在场也能跑完。
Phase 切换纪律
每完成一个 phase：
- 立刻
TaskUpdate <current-phase>: completed + TaskUpdate <next-phase>: in_progress（同一轮工具调用内）
- 不要输出"Phase X 完成，接下来..."的旁白
- 不要在 phase 之间插入任何 AskUserQuestion，除非触发关键决策表
- Phase 1 → Phase 2 之间没有用户交互，不需要摘要 spec 内容（spec 已存盘，用户需要时自己看）
- Phase 2 → Phase 3 之间没有用户交互（auto mode），直接调下游 skill
Operating Principles (Opus 4.7 best practices)
- Upfront specification: Phase 1 把 intent / constraints / AC / file locations 一次问全，不要让 Phase 3 executor 再回头问
- Batch interactions: AskUserQuestion 1-4 题/次，紧耦合时批量；减少 user turn 数
- Auto mode as default: Phase 2/4 默认不打扰，靠"关键决策表"判断介入
- Spec is source of truth: Phase 3 所有 agent 以 spec 为权威；spec 没写的 = 不做；要调整 → 回 Phase 1 重跑
-v2
- Role-symmetric bounded auto-fix: Phase 4a Claude 自己 review（不再调 codex review）；对 BLOCKER / MAJOR / AC FAIL 派
codex exec --full-auto 修（最多 2 轮），Claude 重审。MINOR 不修只列。AC FAIL 是技术问题，不需要用户拍板价值观
- Don't notify about cache misses: 中间进度用 TaskUpdate spinner，不打文字
- Ask when guessing user intent: 感到"我在猜"必须 AskUserQuestion（关键决策表第 1 行）
- Chat output > file archive: Phase 4 主输出是直接写在 chat 里的结构化汇报（做了啥 + 检查结果 + 拍板项 + 下一步），不是 "final_report.md 路径让你自己看"。文件归档是 secondary
Integration Contracts
与 interview-mode
见 Phase 1 的 prompt 模板。interview-mode 识别 "被 ultra-plan 调用" 信号 →
- 走标准 AskUserQuestion 澄清
- 追加对 AC (auto + manual) 和 File Locations 的显式追问
- Summary 写入 spec 路径（按 schema），不输出 Transition 章节
与 codex CLI（Phase 3 + 4c）
所有执行（Phase 3 实现 + Phase 4c 修复）都通过 codex exec --full-auto -c 'sandbox_mode="danger-full-access"' 调用，prompt 始终含 spec 路径作为唯一权威需求源。不再调 writing-plans / spawn / executing-plans / subagent-driven-development。
与 codex-review skill
Phase 4a 不再调 codex-review skill（它现在是 standalone：用户直接 Skill(codex-review) 时启用，并支持 review-and-fix 两种模式）。ultra-plan 的 review 永远是 Claude 自己读 diff + 写 findings.md。
File Layout (runtime 产物)
docs/orchestrator/
├── specs/
│ └── YYYY-MM-DD-<slug>.md # Phase 1 产出
└── evaluations/
└── YYYY-MM-DD-<slug>/
├── exec_single.log # Phase 3 Single 路径 codex stdout
├── exec_step1.log etc. # Phase 3 Todo 路径每步 codex stdout
├── exec_A.log / B / C # Phase 3 Teams 路径并行 codex stdout
├── findings.md # Phase 4a (Claude 写)
├── ac_results.json # Phase 4b
├── fix_iter1.log / iter2.log # Phase 4c codex 修复 stdout
└── final_report.md # Phase 4d
命名冲突规则：同日期同 slug 冲突 → 追加 -v2, -v3，不覆盖。
Sync
2026-04-22 起：ultra-plan / interview-mode / spawn 三个 skill 在本地走 symlink：
~/.claude/skills/ultra-plan → copeee-skills/skills/ultra-plan (实文件, git-tracked)
~/.claude/skills/interview-mode → copeee-skills/skills/interview-mode
~/.claude/skills/spawn → copeee-skills/skills/spawn
编辑任一侧都改的是同一份文件，不需要再跑 sync。sync-skills.sh 只对非 symlink 的 skill 有用（新加了 symlink 检测，symlink 会自动跳过）。
其他 skill 仍用 sync-skills.sh push/pull/diff 管理。
