---
name: omc-plan
description: 带可选访谈工作流的战略规划
pipeline: [deep-interview, omc-plan, autopilot]
next-skill: autopilot
handoff: .omc/plans/ralplan-*.md
level: 4
---

<Purpose>
Plan 通过智能交互创建全面且可执行的工作计划。它会自动检测是需要先采访用户（宽泛请求）还是直接规划（详细请求），并支持共识模式（基于 RALPLAN-DR 结构化审议的 Planner/Architect/Critic 迭代循环）和评审模式（由 Critic 对现有计划进行评估）。
</Purpose>

<Use_When>
- 用户想在实施前先做规划，例如 "plan this"、"plan the"、"let's plan"
- 用户希望为一个模糊想法进行结构化需求收集
- 用户希望评审一个已有计划，例如 "review this plan"、`--review`
- 用户希望围绕一个计划获得多视角共识，例如 `--consensus`、"ralplan"
- 任务宽泛或模糊，需要在编写任何代码之前先界定范围
</Use_When>

<Do_Not_Use_When>
- 用户希望自主端到端执行，改用 `autopilot`
- 用户希望在任务清晰时立即开始编码，使用 `ralph` 或委派给 executor
- 用户提出的是一个可以直接回答的简单问题，直接回答即可
- 任务是一个范围明显的单点修复，跳过规划，直接去做
</Do_Not_Use_When>

<Why_This_Exists>
在未理解需求的情况下直接写代码，会导致返工、范围蔓延以及遗漏边界情况。Plan 提供结构化的需求收集、专家分析和带质量门禁的计划，让执行从坚实基础开始。共识模式则为高风险项目增加了多视角校验。
</Why_This_Exists>

<Execution_Policy>
- 根据请求具体程度自动检测应使用访谈模式还是直接模式
- 访谈期间一次只问一个问题，绝不把多个问题打包一起问
- 在向用户询问代码库事实之前，先通过 `explore` agent 收集这些事实
- 计划必须满足质量标准：80%+ 的论断要引用文件/行号，90%+ 的标准必须可测试
- 共识模式默认全自动运行；添加 `--interactive` 可在草案评审和最终批准步骤启用用户提示
- 共识模式默认使用 RALPLAN-DR short mode；当使用 `--deliberate` 或请求明确表明高风险（auth/security、数据迁移、破坏性/不可逆变更、生产事故、compliance/PII、公共 API 破坏）时切换到 deliberate mode
</Execution_Policy>

<Steps>

### Mode Selection

| Mode | Trigger | Behavior |
|------|---------|----------|
| Interview | 宽泛请求的默认模式 | 交互式需求收集 |
| Direct | `--direct`，或详细请求 | 跳过访谈，直接生成计划 |
| Consensus | `--consensus`、"ralplan" | Planner -> Architect -> Critic 循环，直到达成一致，并使用 RALPLAN-DR 结构化审议（默认 short mode，高风险时用 `--deliberate`）；添加 `--interactive` 可在草案与批准步骤向用户提问 |
| Review | `--review`、"review this plan" | 由 Critic 对现有计划进行评估 |

### Interview Mode (broad/vague requests)

1. **Classify the request**：宽泛请求（动词模糊、没有具体文件、涉及 3+ 个区域）会触发访谈模式
2. **Ask one focused question**：使用 `AskUserQuestion` 询问偏好、范围和约束
3. **Gather codebase facts first**：在问出“你的代码使用了什么模式？”之前，先启动一个 `explore` agent 去查明，再提出有依据的后续问题
4. **Build on answers**：每个问题都建立在上一个答案之上
5. **Consult Analyst** (Opus)：挖掘隐藏需求、边界情况和风险
6. **Create plan**：当用户表示准备好了时创建计划，例如 "create the plan"、"I'm ready"、"make it a work plan"

### Direct Mode (detailed requests)

1. **Quick Analysis**：可选的简短 Analyst 咨询
2. **Create plan**：立即生成全面的工作计划
3. **Review**（可选）：如有需要，交由 Critic 评审

### Consensus Mode (`--consensus` / "ralplan")

**RALPLAN-DR modes**：包含 **Short**（默认，有限结构）和 **Deliberate**（用于 `--deliberate` 或明确的高风险请求）两种模式。两种模式都保持相同的 Planner -> Architect -> Critic 流程，以及相同的 `AskUserQuestion` 关卡。

**Provider overrides（当已安装对应 provider CLI 时支持）：**
- `--architect codex`：将 Claude Architect 阶段替换为 `omc ask codex --agent-prompt architect "..."`，用于更偏实现的架构评审
- `--critic codex`：将 Claude Critic 阶段替换为 `omc ask codex --agent-prompt critic "..."`，在执行前增加一次外部评审
- 如果请求的 provider 不可用，简要说明这一点，然后继续使用默认的 Claude Architect/Critic 步骤完成该阶段

**State lifecycle**：持久模式的 stop hook 使用 `ralplan-state.json` 在共识循环期间强制继续执行。此 skill **必须** 管理该状态：
- **On entry**：在步骤 1 之前调用 `state_write(mode="ralplan", active=true, session_id=<current_session_id>)`
- **On handoff to execution**（approval → ralph/team）：调用 `state_write(mode="ralplan", active=false, session_id=<current_session_id>)`。这里不要使用 `state_clear`，因为 `state_clear` 会写入一个 30 秒的取消信号，导致所有模式的 stop-hook 强制机制都被禁用，从而让新启动的执行模式失去保护。
- **On true terminal exit**（rejection、非交互式计划输出、error/abort）：调用 `state_clear(mode="ralplan", session_id=<current_session_id>)`，因为后面不会接执行模式，所以取消信号窗口是无害的。
- 不要在 Critic 批准或达到最大迭代次数展示结果等中间步骤清理状态，因为用户此时仍可能选择 "Request changes"。

如果不做清理，即使共识工作流已经结束，stop hook 仍会持续用 `[RALPLAN - CONSENSUS PLANNING]` 强化消息阻止之后所有 stop。务必传递 `session_id`，避免清除其他并发会话的状态。

1. **Planner** 在任何 Architect 评审之前创建初版计划和精简的 **RALPLAN-DR summary**。该 summary **必须** 包含：
   - **Principles**（3-5 条）
   - **Decision Drivers**（前 3 项）
   - **Viable Options**（>=2），并为每个选项给出有限的 pros/cons
   - 如果只剩下一个可行选项，必须明确说明被拒绝替代方案的 **invalidation rationale**
   - 在 **deliberate mode** 中：加入一个 **pre-mortem**（3 个失败场景）和一个覆盖 **unit / integration / e2e / observability** 的 **expanded test plan**
2. **User feedback** *(`--interactive` only)*：如果使用 `--interactive` 运行，则**必须**使用 `AskUserQuestion` 展示草案计划，**同时附上 RALPLAN-DR Principles / Decision Drivers / Options summary 以便尽早对齐方向**，并提供以下选项：
   - **Proceed to review**：发送给 Architect 和 Critic 评估
   - **Request changes**：带着用户反馈返回步骤 1
   - **Skip review**：直接进入最终批准（步骤 7）
   如果未使用 `--interactive` 运行，则自动进入评审（步骤 3）。
3. **Architect** 使用 `Task(subagent_type="oh-my-claudecode:architect", ...)` 对架构合理性进行评审。Architect 评审 **必须** 包含：针对首选方案的最强 steelman 反对论点（antithesis）、至少一个有意义的权衡张力，以及（在可能时）一个综合路径。在 deliberate mode 中，Architect 应明确标出原则违背。**必须等待此步骤完成后再进入步骤 4。** 不要并行执行步骤 3 和 4。
4. **Critic** 使用 `Task(subagent_type="oh-my-claudecode:critic", ...)` 按质量标准进行评估。Critic **必须** 验证原则与选项的一致性、替代方案探索是否公平、风险缓解是否清晰、验收标准是否可测试、以及验证步骤是否具体。Critic **必须** 明确否决浅层替代方案、驱动因素矛盾、风险模糊或验证薄弱的计划。在 deliberate mode 中，Critic **必须** 否决缺失/薄弱的 pre-mortem 或缺失/薄弱的 expanded test plan。只能在步骤 3 完成后运行。
5. **Re-review loop**（最多 5 次迭代）：如果 Critic 否决，则执行以下闭环：
   a. 收集 Architect + Critic 的所有否决反馈
   b. 将反馈交给 Planner，生成修订版计划
   c. **返回步骤 3**：由 Architect 评审修订版计划
   d. **返回步骤 4**：由 Critic 评估修订版计划
   e. 重复，直到 Critic 批准或达到最多 5 次迭代
   f. 如果达到最大迭代次数仍未获批，则通过 `AskUserQuestion` 将最佳版本展示给用户，并注明专家尚未达成共识
6. **Apply improvements**：当评审者带改进建议批准时，在继续之前将所有接受的改进合并进计划文件。最终的共识输出 **必须** 包含一个 **ADR** 部分，含有：**Decision**、**Drivers**、**Alternatives considered**、**Why chosen**、**Consequences**、**Follow-ups**。具体来说：
   a. 收集 Architect 和 Critic 回复中的所有改进建议
   b. 去重并分类这些建议
   c. 使用接受的改进更新 `.omc/plans/` 中的计划文件（补充缺失细节、细化步骤、强化验收标准、更新 ADR 等）
   d. 在计划末尾用简短 changelog 说明已应用了哪些改进
7. 当 Critic 批准后（且已应用改进）：*(`--interactive` only)* 如果使用 `--interactive` 运行，则使用 `AskUserQuestion` 展示计划，并提供以下选项：
   - **Approve and implement via team**（推荐）—— 通过协调并行 team agents（`/team`）进入实施。自 v4.1.7 起，Team 是规范的编排界面。
   - **Approve and execute via ralph** —— 通过 ralph+ultrawork 进入实施（带验证的顺序执行）
   - **Clear context and implement** —— 先压缩上下文窗口（当规划后上下文较大时推荐），然后基于已保存的计划文件重新开始通过 ralph 实施
   - **Request changes** —— 带着用户反馈返回步骤 1
   - **Reject** —— 彻底丢弃该计划
   如果未使用 `--interactive` 运行，则输出最终批准的计划，调用 `state_clear(mode="ralplan", session_id=<current_session_id>)`，然后停止。不要自动执行。
8. *(`--interactive` only)* 用户必须通过结构化的 `AskUserQuestion` UI 做出选择（绝不要用纯文本请求批准）。如果用户选择 **Reject**，调用 `state_clear(mode="ralplan", session_id=<current_session_id>)` 并停止。
9. 在用户批准时（仅 `--interactive`）：调用执行 skill（ralph/team）**之前**，先调用 `state_write(mode="ralplan", active=false, session_id=<current_session_id>)`，这样 stop hook 就不会干扰执行模式自身的强制机制。这里不要使用 `state_clear`，因为它会写入一个取消信号，导致新启动模式的强制机制被禁用。
   - **Approve and implement via team**：**必须** 以 `.omc/plans/` 中已批准计划的路径作为上下文调用 `Skill("oh-my-claudecode:team")`。不要直接实现。team skill 会在分阶段流水线中协调并行 agents，以更快执行大型任务。这是推荐的默认执行路径。
   - **Approve and execute via ralph**：**必须** 以 `.omc/plans/` 中已批准计划的路径作为上下文调用 `Skill("oh-my-claudecode:ralph")`。不要直接实现。不要在 planning agent 中编辑源代码文件。ralph skill 会通过 ultrawork 并行 agents 处理执行。
   - **Clear context and implement**：先调用 `Skill("compact")` 压缩上下文窗口（减少规划期间积累的 token 使用），然后以 `.omc/plans/` 中已批准计划的路径调用 `Skill("oh-my-claudecode:ralph")`。当规划会话后上下文窗口已使用 50%+ 时，推荐走这条路径。

### Review Mode (`--review`)

1. 从 `.omc/plans/` 读取计划文件
2. 使用 `Task(subagent_type="oh-my-claudecode:critic", ...)` 交给 Critic 评估
3. 返回结论：APPROVED、REVISE（附具体反馈）或 REJECT（需要重新规划）

### Plan Output Format

每个计划都包含：
- Requirements Summary
- Acceptance Criteria（可测试）
- Implementation Steps（附文件引用）
- Risks and Mitigations
- Verification Steps
- 对于 consensus/ralplan：**RALPLAN-DR summary**（Principles、Decision Drivers、Options）
- 对于 consensus/ralplan 最终输出：**ADR**（Decision、Drivers、Alternatives considered、Why chosen、Consequences、Follow-ups）
- 对于 deliberate 共识模式：**Pre-mortem（3 个场景）** 和 **Expanded Test Plan**（unit/integration/e2e/observability）

计划保存到 `.omc/plans/`。草稿保存到 `.omc/drafts/`。
</Steps>

<Tool_Usage>
- 用 `AskUserQuestion` 提问偏好类问题（scope、priority、timeline、risk tolerance），它会提供可点击 UI
- 对于需要具体值的问题（端口号、名称、后续澄清），使用纯文本
- 在询问用户之前，使用 `explore` agent（Haiku，30s timeout）收集代码库事实
- 对大范围计划，使用 `Task(subagent_type="oh-my-claudecode:planner", ...)` 做规划校验
- 使用 `Task(subagent_type="oh-my-claudecode:analyst", ...)` 进行需求分析
- 在共识模式和评审模式中，使用 `Task(subagent_type="oh-my-claudecode:critic", ...)` 进行计划评审
- **CRITICAL — 共识模式的 agent 调用必须串行，绝不能并行。** 始终先等待 Architect Task 返回结果，再发起 Critic Task。
- 在共识模式中，默认使用 RALPLAN-DR short mode；当使用 `--deliberate` 或出现明确高风险信号（auth/security、migrations、破坏性变更、生产事故、compliance/PII、公共 API 破坏）时启用 deliberate mode
- 在启用 `--interactive` 的共识模式中：用户反馈步骤（步骤 2）和最终批准步骤（步骤 7）必须使用 `AskUserQuestion`，绝不要用纯文本请求批准。未启用 `--interactive` 时，跳过这两个提示并直接输出最终计划。
- 在启用 `--interactive` 的共识模式中，用户批准后**必须**调用 `Skill("oh-my-claudecode:ralph")` 进入执行（步骤 9），绝不要在 planning agent 中直接实现
- 当用户在步骤 7 选择 "Clear context and implement"（仅 `--interactive`）时：先调用 `state_write(mode="ralplan", active=false, session_id=<current_session_id>)`，然后调用 `Skill("compact")` 压缩累积的规划上下文，接着立即用计划路径调用 `Skill("oh-my-claudecode:ralph")`，compact 步骤对于在实现循环开始前释放上下文至关重要
- **CRITICAL — 共识模式的状态生命周期**：在停止或移交给执行前，始终停用 ralplan 状态。移交路径（approval → ralph/team）使用 `state_write(active=false)`，真正的终止退出（rejection、error）使用 `state_clear`。在启动执行模式之前绝不要使用 `state_clear`，它的取消信号会使 stop-hook 强制机制在 30 秒内失效。
</Tool_Usage>

<Examples>
<Good>
自适应访谈（先收集事实再提问）：
```
Planner: [spawns explore agent: "find authentication implementation"]
Planner: [receives: "Auth is in src/auth/ using JWT with passport.js"]
Planner: "我看到你在 src/auth/ 中使用了基于 JWT 和 passport.js 的认证。
         对于这个新功能，我们应该扩展现有认证，还是新增一套独立的认证流程？"
```
Why good：先回答了它自己关于代码库的问题，再提出一个有依据的偏好问题。
</Good>

<Good>
一次只问一个问题：
```
Q1: "主要目标是什么？"
A1: "提升性能"
Q2: "对于性能来说，你更关心 latency 还是 throughput？"
A2: "Latency"
Q3: "对于 latency，你是在优化 p50 还是 p99？"
```
Why good：每个问题都建立在前一个答案之上，聚焦且循序渐进。
</Good>

<Bad>
询问本可自行查到的内容：
```
Planner: "认证在你的代码库里是在哪里实现的？"
User: "呃，我想大概在 src/auth 的某个地方？"
```
Why bad：planner 应该启动一个 explore agent 来查明，而不是问用户。
</Bad>

<Bad>
把多个问题一次性打包：
```
"范围是什么？时间线是什么？目标受众是谁？"
```
Why bad：一次问三个问题会导致回答很浅。一次只问一个。
</Bad>

<Bad>
一次性展示所有设计选项：
```
"这里有 4 种方案：Option A... Option B... Option C... Option D... 你更喜欢哪个？"
```
Why bad：会造成决策疲劳。先给出一个带权衡的选项，获得反馈，再展示下一个。
</Bad>
</Examples>

<Escalation_And_Stop_Conditions>
- 当需求已经足够清晰、可以开始制定计划时，就停止访谈，不要过度访谈
- 在共识模式中，最多进行 5 轮 Planner/Architect/Critic 迭代后停止，并展示最佳版本。这里不要清除 ralplan state，因为用户在后续步骤中仍可能选择 "Request changes"。只有在用户做出最终选择（approval/rejection）或在非交互模式下输出计划时才清除状态。
- 未启用 `--interactive` 的共识模式会输出最终计划并停止；启用 `--interactive` 时，在任何实施开始前都必须获得用户明确批准。停止前**始终**调用 `state_clear(mode="ralplan", session_id=<current_session_id>)`。
- 如果用户说 "just do it" 或 "skip planning"，调用 `state_write(mode="ralplan", active=false, session_id=<current_session_id>)`，然后**必须**调用 `Skill("oh-my-claudecode:ralph")` 切换到执行模式。不要在 planning agent 中直接实现。
- 当存在无法调和、需要业务决策取舍时，升级给用户处理
</Escalation_And_Stop_Conditions>

<Final_Checklist>
- [ ] 计划具有可测试的验收标准（90%+ 具体）
- [ ] 在适用处引用了具体文件/行号（80%+ 的论断）
- [ ] 所有风险都识别出了对应缓解措施
- [ ] 没有不带指标的模糊术语（"fast" -> "p99 < 200ms"）
- [ ] 计划已保存到 `.omc/plans/`
- [ ] 在共识模式中：RALPLAN-DR summary 包含 3-5 条 principles、前 3 个 drivers，以及 >=2 个可行选项（或明确的 invalidation rationale）
- [ ] 在共识模式最终输出中：已包含 ADR 部分（Decision / Drivers / Alternatives considered / Why chosen / Consequences / Follow-ups）
- [ ] 在 deliberate 共识模式中：已包含 pre-mortem（3 个场景）+ expanded test plan（unit/integration/e2e/observability）
- [ ] 在启用 `--interactive` 的共识模式中：任何执行开始前，用户已明确批准；未启用 `--interactive` 时：仅输出计划，不自动执行
- [ ] 在共识模式中：每条退出路径都已停用 ralplan state，移交执行时使用 `state_write(active=false)`，终止退出（rejection、error、非交互停止）使用 `state_clear`
</Final_Checklist>

<Advanced>
## Design Option Presentation

在访谈期间展示设计选项时，要分块进行：

1. **Overview**（2-3 句）
2. **Option A** 及其权衡
3. [等待用户反馈]
4. **Option B** 及其权衡
5. [等待用户反馈]
6. **Recommendation**（仅在选项讨论之后）

每个选项的格式：
```
### Option A: [Name]
**Approach:** [1 sentence]
**Pros:** [bullets]
**Cons:** [bullets]

你对这个方案的反应是什么？
```

## Question Classification

在提出任何访谈问题之前，先对其分类：

| Type | Examples | Action |
|------|----------|--------|
| Codebase Fact | "现有模式有哪些？", "X 在哪里？" | 先 Explore，不要问用户 |
| User Preference | "优先级？", "时间线？" | 通过 AskUserQuestion 问用户 |
| Scope Decision | "要包含功能 Y 吗？" | 问用户 |
| Requirement | "性能约束是什么？" | 问用户 |

## Review Quality Criteria

| Criterion | Standard |
|-----------|----------|
| Clarity | 80%+ 的论断引用文件/行号 |
| Testability | 90%+ 的标准是具体的 |
| Verification | 所有文件引用都存在 |
| Specificity | 没有模糊术语 |

## Deprecation Notice

独立的 `/planner`、`/ralplan` 和 `/review` skills 已合并到 `/plan`。所有工作流（访谈、直接、共识、评审）现在都通过 `/plan` 提供。
</Advanced>