omc-plan

Plan 通过智能交互制定全面、可执行的工作计划。它会自动检测是访谈用户（宽泛请求）还是直接规划（详细请求），并支持共识模式（迭代式 Planner/Architect/Critic 循环，配合 RALPLAN-DR 结构化审议）和评审模式（由 Critic 评估既有计划）。

<Use_When>

• 用户希望在实施前先做规划 —— “plan this”、“plan the”、“let's plan”
• 用户希望为一个模糊的想法进行结构化需求收集
• 用户希望评审既有计划 —— “review this plan”、--review
• 用户希望就某项计划达成多视角共识 —— --consensus、“ralplan”
• 任务宽泛或模糊，需要在编写任何代码前先界定范围 </Use_When>

<Do_Not_Use_When>

• 用户希望自主端到端执行 —— 改用 autopilot
• 用户任务明确，希望立即开始编码 —— 使用 ralph 或委派给执行器
• 用户提出一个可直接回答的简单问题 —— 直接回答即可
• 任务是范围明确、单一的聚焦修复 —— 使用执行类技能，而不是通过此规划模块来运行 </Do_Not_Use_When>

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

<Execution_Policy>

• 根据请求的具体程度自动检测访谈模式还是直接模式
• 访谈期间一次只问一个问题 —— 绝不要批量提出多个问题
• 在向用户询问代码库相关情况之前，先通过 explore Agent 收集代码库事实
• 计划必须达到质量标准：80% 以上的论断引用文件/行号，90% 以上的验收标准可测试
• 共识模式默认完全自动化运行；添加 --interactive 可在草稿评审和最终批准环节启用用户提示
• 共识模式默认使用 RALPLAN-DR 短模式；使用 --deliberate 或在请求明确表明高风险（认证/安全、数据迁移、破坏性/不可逆更改、生产事故、合规/PII、公共 API 破坏性变更）时切换到审议模式
• 规划/执行边界： 规划模式只检查上下文并产出计划/规格/提案。除非用户在当前轮次中或通过结构化批准 UI 明确选择执行，否则它们必须将产物标记为 pending approval。在明确批准执行之前，规划模式不得运行面向变更的 shell 命令、编辑源文件、提交、推送、开 PR、调用执行类技能或委派实施任务。
• 目标工作流边界： 当某项计划比较 Claude Code /goal、Ralph、Team 或仅产物的 Ultragoal 时，必须精确识别一个主循环权威，并使用确定性冲突策略 refuse、adopt_existing 和 artifact_only，而不是非确定性的警告处理。/goal 相关事实必须仅引用 Claude Code/Anthropic 来源（Claude Code /goal 文档：https://code.claude.com/docs/en/goal；Anthropic Claude Code 变更日志：https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md），且计划不得声称 /goal 评估器会独立运行命令或读取文件；在任何完成声明之前，必须提供已呈现的证明证据。
• 目标工作流文档目标： 对于面向用户的比较，示例应与 docs/shared/mode-selection-guide.md#goal-oriented-workflow-selection 和 docs/REFERENCE.md#goal-workflow-ux-goal-ralph-team-ultragoal 保持一致。 </Execution_Policy>

### 模式选择

模式	触发条件	行为
Interview	宽泛请求的默认模式	交互式需求收集
Direct	--direct，或详细的请求	跳过访谈，直接生成计划
Consensus	--consensus、"ralplan"	Planner -> Architect -> Critic 循环，直至通过 RALPLAN-DR 结构化审议达成一致（默认简短，高风险时使用 --deliberate）；添加 --interactive 可在草拟和批准步骤向用户提问
Review	--review、"review this plan"	Critic 对现有计划进行评估

Interview 模式（宽泛/模糊的请求）

1. 对请求进行分类：宽泛（模糊的动词、没有具体文件、涉及 3 个以上领域）会触发访谈模式
2. 提出一个聚焦的问题，使用 AskUserQuestion 询问偏好、范围和约束
3. 先收集代码库事实：在询问"你的代码使用什么模式？"之前，先启动一个 explore Agent 去查明，然后再提出有依据的后续问题
4. 基于回答逐步推进：每个问题都建立在前一个回答之上
5. 咨询 Analyst（Opus），了解隐藏需求、边缘情况和风险
6. 创建计划：当用户表示已准备好时："create the plan"、"I'm ready"、"make it a work plan"

Direct 模式（详细的请求）

1. 快速分析：可选的简要 Analyst 咨询
2. 创建计划：立即生成全面的工作计划
3. Review（可选）：如有要求则进行 Critic 评估

Consensus 模式（--consensus / "ralplan"）

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

提供商覆盖（在已安装提供商 CLI 时受支持）：

• --architect codex — 用 omc ask codex --agent-prompt architect "..." 替换 Claude Architect 环节，用于实现密集型架构评审
• --critic codex — 用 omc ask codex --agent-prompt critic "..." 替换 Claude Critic 环节，在执行前进行外部评审
• 如果请求的提供商不可用，请简要说明，并在该阶段继续使用默认的 Claude Architect/Critic 步骤

状态生命周期：持久模式停止钩子使用 ralplan-state.json 在共识循环期间强制执行继续执行。该技能 MUST 管理此状态：

• 进入时：在第 1 步之前调用 state_write(mode="ralplan", active=true, session_id=<current_session_id>)
• 交接给执行流程时（批准 → ralph/team）：调用 state_write(mode="ralplan", active=false, session_id=<current_session_id>)。此处不要使用 state_clear——state_clear 会写入 30 秒的取消信号，禁用所有模式的停止钩子强制执行，导致新启动的执行模式不受保护。
• 真正终止退出时（拒绝、非交互式计划输出、错误/中止）：调用 state_clear(mode="ralplan", session_id=<current_session_id>)——后续没有执行模式，因此取消信号窗口不会造成影响。
• 不要在中间步骤（例如 Critic 批准或展示最大迭代次数时）清除状态，因为用户仍可能选择“请求修改”。

如果不进行清理，即使共识工作流已结束，停止钩子仍会使用 [RALPLAN - CONSENSUS PLANNING] 强化消息阻止所有后续停止操作。始终传入 session_id，以免清除其他并发会话的状态。

1. Planner 创建初始计划，并在任何 Architect 审查之前生成精简的 RALPLAN-DR 摘要。摘要必须包含：
   • 原则（3-5 条）
   • 决策驱动因素（前 3 项）
   • 可行选项（>=2 个），并分别列出适度的优缺点
   • 如果最终只剩一个可行选项，须明确说明其他选项被排除的理由
   • 在审慎模式下：提供事前验尸（3 种失败情景）和涵盖单元 / 集成 / 端到端 / 可观测性的扩展测试计划
2. 用户反馈（仅限 --interactive）：如果使用 --interactive 运行，必须使用 AskUserQuestion 展示草案计划以及 RALPLAN-DR 的原则 / 决策驱动因素 / 选项摘要，以便尽早对齐方向，并提供以下选项：
   • 进入审查 — 提交给 Architect 和 Critic 评估
   • 请求修改 — 纳入用户反馈后返回第 1 步
   • 跳过审查 — 直接进入最终批准（第 7 步） 如果未使用 --interactive 运行，则自动进入审查（第 3 步）。
3. Architect 使用 Task(subagent_type="oh-my-claudecode:architect", ...) 审查架构是否合理。Architect 的审查必须包含：针对首选选项的最有力钢人论证反驳（反论点）、至少一个实质性的权衡冲突，以及（如有可能）一条综合方案。在审慎模式下，Architect 应明确指出违反原则之处。Architect 必须评估 Planner 在第 1 步生成的同一份固定计划快照，不得修改该快照；Architect 的输出不得传给 Critic。
4. Critic 使用 Task(subagent_type="oh-my-claudecode:critic", ...) 根据质量标准进行评估。Critic 必须核验原则与选项是否一致、是否公平地探索了备选方案、风险缓解措施是否明确、验收标准是否可测试，以及验证步骤是否具体。Critic 必须明确否决浅显的备选方案、相互矛盾的决策驱动因素、含糊的风险或薄弱的验证方式。在审慎模式下，Critic 必须否决缺失或薄弱的事前验尸，以及缺失或薄弱的扩展测试计划。Critic 必须独立评估同一份固定计划快照，并单独调用一次、等待其完成；Critic 不得使用或接收 Architect 的审查结果。

   对同一固定计划快照进行独立的并行或串行审查（取决于上下文）。 Architect 和 Critic 各自审查 Planner 在步骤 1 中生成的同一固定计划快照，且双方都不会修改该快照。不得将 Architect 的输出传递给 Critic。**当 Architect 和 Critic 都使用 Claude agents（默认）时，可以作为后台子 Agent 并行运行。**当 Architect 或 Critic 使用外部提供方（例如 --architect codex、--critic codex）时，必须作为独立的 Task 调用按顺序运行，并逐个等待完成——绝不可并行运行——以防速率限制错误导致同级调用级联失败。 Critic 不得使用或接收 Architect 的审查结果。只有在两项审查都完成后，Planner 才能在修订或改进综合阶段合并 Architect 和 Critic 的结果。

5. 重新审查循环（最多 5 次迭代）：如果 Critic 拒绝，则执行以下闭环： a. 收集 Architect 和 Critic 的所有拒绝反馈（仅由 Planner 综合：只有在两项审查都完成后，Planner 才能合并 Architect 和 Critic 的结果）。 b. 将反馈交给 Planner，以生成修订后的计划 c. 返回步骤 3——由 Architect 审查修订后的计划 d. 返回步骤 4——由 Critic 评估修订后的计划 e. 重复以上步骤，直至 Critic 批准或达到最多 5 次迭代 f. 如果达到最大迭代次数仍未获批准，则通过 AskUserQuestion 向用户展示最佳版本，并注明专家未达成共识
6. 应用改进：当审查者批准计划并提出改进建议时，在继续之前将所有已采纳的改进合并到计划文件中。最终共识输出必须包含一个 ADR 部分，其中包括：决策、驱动因素、考虑过的替代方案、选择理由、后果、后续事项。具体而言： a. 收集 Architect 和 Critic 回复中的所有改进建议 b. 去重并对建议进行分类 c. 在 .omc/plans/ 中更新计划文件，纳入已采纳的改进（补充缺失的细节、完善步骤、强化验收标准、更新 ADR 等） d. 在计划末尾添加简短的变更日志，注明已应用的改进
7. Critic 批准后（且改进已应用）：除非已经明确获得执行批准，否则将计划状态标记为 pending approval。（仅限 --interactive） 如果以 --interactive 运行，请使用 AskUserQuestion 展示计划，并提供以下选项：
   • 通过团队批准执行（推荐）——明确选择通过协调并行团队 Agent（/team）继续执行。自 v4.1.7 起，Team 是规范的编排入口。
   • 通过 ralph 批准执行——明确选择通过 Ralph 持久化执行并进行验证
   • 先压缩上下文，再返回请求执行批准——明确选择先压缩上下文窗口（规划后上下文较大时推荐），然后停留在已保存的待批准计划上，并在启动执行前再次请求批准
   • 请求修改——根据用户反馈返回步骤 1
   • 拒绝——彻底丢弃计划 如果未以 --interactive 运行，则输出标记为 pending approval 的最终计划，调用 state_clear(mode="ralplan", session_id=<current_session_id>)，然后停止。不得自动执行。
8. （仅限 --interactive） 用户必须通过结构化的 AskUserQuestion UI 选择（绝不可用纯文本请求批准）。如果用户选择拒绝，则调用 state_clear(mode="ralplan", session_id=<current_session_id>) 并停止。
9. 用户批准后（仅限 --interactive）：在调用执行技能（ralph/team）之前调用 state_write(mode="ralplan", active=false, session_id=<current_session_id>)，以免停止钩子干扰执行模式自身的强制机制。此处不要使用 state_clear——它会写入取消信号，从而禁用新启动模式的强制机制。
   • 通过团队批准执行：必须调用 Skill("oh-my-claudecode:team")，并将 .omc/plans/ 中已批准的计划路径作为上下文。不得直接实施。Team 技能会在分阶段流水线中协调并行 Agent，从而加快大型任务的执行。这是推荐的默认执行路径。
   • 通过 ralph 批准执行：必须调用 Skill("oh-my-claudecode:ralph")，并将 .omc/plans/ 中已批准的计划路径作为上下文。不得直接实施。规划 Agent 不得编辑源代码文件。Ralph 技能负责持久化执行和验证。
   • 先压缩上下文，再返回请求执行批准：先调用 Skill("compact") 压缩上下文窗口（减少规划期间累积的 token 用量），然后返回已保存的待批准计划路径，并要求在启动任何 ralph/team 流程之前重新明确批准执行。如果规划会话结束后上下文窗口已满 50% 或更多，推荐使用此路径。

审查模式（--review）

1. 从 .omc/plans/ 读取计划文件
2. 使用 Task(subagent_type="oh-my-claudecode:critic", ...) 通过 Critic 进行评估
3. 返回结论：APPROVED（批准）、REVISE（修改，并提供具体反馈）或 REJECT（拒绝，需要重新规划）

计划输出格式

每份计划都包括：

• 需求摘要
• 验收标准（可测试）
• 实施步骤（附文件引用）
• 风险与缓解措施
• 验证步骤
• 对于共识/ralplan：RALPLAN-DR 摘要（原则、决策驱动因素、选项）
• 对于共识/ralplan 的最终输出：ADR（决策、驱动因素、考虑过的替代方案、选择理由、后果、后续事项）
• 对于审慎共识模式：事前分析（3 种情景）和扩展测试计划（单元/集成/e2e/可观测性）

计划保存在 .omc/plans/。草稿保存在 .omc/drafts/。

<Tool_Usage>

• 对于偏好类问题（范围、优先级、时间线、风险承受度），使用 AskUserQuestion——它会提供可点击的 UI
• 对于需要具体值的问题（端口号、名称、后续澄清），使用纯文本
• 使用 explore Agent（Haiku，30 秒超时）在询问用户前收集代码库信息
• 对于大型计划的规划验证，使用 Task(subagent_type="oh-my-claudecode:planner", ...)
• 在共识模式和审查模式下审查计划时，使用 Task(subagent_type="oh-my-claudecode:critic", ...)
• 共识模式下 Agent 调用的上下文依赖性： 当 Architect 和 Critic 都是 Claude Agent（默认情况）时，可以并行运行，作为后台子 Agent。当任一方使用外部提供商（如 codex）时，必须按顺序运行，以避免速率限制导致同级任务级联失败。两次审查使用同一个固定计划快照；Architect 的输出不会传递给 Critic；只有在两次审查都完成后，结果才会在 Planner 综合阶段合并。
• 在共识模式下，默认使用简版 RALPLAN-DR；若指定 --deliberate 或存在明确的高风险信号（身份验证/安全、迁移、破坏性变更、生产事故、合规/PII、公共 API 破坏性变更），则启用审慎模式
• 在带有 --interactive 的共识模式下：在步骤 2 的用户反馈环节和步骤 7 的最终批准环节使用 AskUserQuestion——绝不能用纯文本询问是否批准。不带 --interactive 时，跳过这两个提示，将计划标记为 pending approval，输出最终计划并停止。
• 在带有 --interactive 的共识模式下，用户明确批准后，必须调用 Skill("oh-my-claudecode:ralph") 或 Skill("oh-my-claudecode:team") 执行计划（步骤 9）——绝不能由规划 Agent 直接实施
• 在明确获得执行批准前，规划模式不得运行面向变更的 shell 命令、编辑文件、提交、推送、创建 PR、调用执行技能或委派实施任务；只能检查上下文并起草/更新计划、规范或提案文件。
• 当用户在步骤 7（仅限 --interactive）选择“压缩后返回以获取执行批准”时：将计划保持标记为 pending approval，调用 state_write(mode="ralplan", active=false, current_phase="pending_approval", session_id=<current_session_id>)，然后调用 Skill("compact") 压缩累积的规划上下文。压缩后，必须重新获得用户对执行的明确批准，才能启动 ralph/team；绝不能在 compact 后续流程中自动开始实施
• 关键——共识模式状态生命周期： 在停止或移交给执行前，务必停用 ralplan 状态。移交时（批准后 → ralph/team）使用 state_write(active=false)；真正的终止退出（拒绝、错误）则使用 state_clear。启动执行模式前绝不能调用 state_clear——其取消信号会在 30 秒内禁用 stop-hook 强制执行。 </Tool_Usage>

自适应访谈（先收集事实，再提问）： ``` Planner: [spawns explore agent: "find authentication implementation"] Planner: [receives: "Auth is in src/auth/ using JWT with passport.js"] Planner: "I see you're using JWT authentication with passport.js in src/auth/. For this new feature, should we extend the existing auth or add a separate auth flow?" ``` 为何有效：先回答有关自身代码库的问题，再提出有依据的偏好问题。 每次只问一个问题： ``` Q1: "What's the main goal?" A1: "Improve performance" Q2: "For performance, what matters more -- latency or throughput?" A2: "Latency" Q3: "For latency, are we optimizing for p50 or p99?" ``` 为何有效：每个问题都基于上一个回答展开。重点明确，循序渐进。 询问可以自行查明的内容： ``` Planner: "Where is authentication implemented in your codebase?" User: "Uh, somewhere in src/auth I think?" ``` 为何不妥：规划器应启动一个探索 Agent 来查明此事，而不是询问用户。 一次提出多个问题： ``` "What's the scope? And the timeline? And who's the audience?" ``` 为何不妥：一次问三个问题会导致回答流于表面。每次只问一个。 一次性列出所有设计选项： ``` "Here are 4 approaches: Option A... Option B... Option C... Option D... Which do you prefer?" ``` 为何不妥：这会造成决策疲劳。先提出一个选项及其利弊，征求反馈，再提出下一个。

<Escalation_And_Stop_Conditions>

• 需求足够清晰、可以开始规划时，就停止访谈——不要过度访谈
• 在共识模式下，经过 5 轮 Planner/Architect/Critic 迭代后停止，并给出最佳版本。此处不要清除 ralplan 状态——用户仍可能在后续步骤中选择“Request changes”。只有用户做出最终选择（批准/拒绝）或在非交互模式下输出计划时，才清除状态。
• 在未启用 --interactive 的共识模式下，输出标记为 pending approval 的最终计划并停止；启用 --interactive 时，必须获得用户明确批准后才能开始任何实施。务必在停止前调用 state_clear(mode="ralplan", session_id=<current_session_id>)。
• 如果用户说“直接做”或“跳过规划”，但没有明确指定执行路径，则将其视为要求结束规划：输出当前计划/规范/提案，标记为 pending approval，并通过结构化批准界面请求明确的执行批准。在获得批准前，规划模块不得调用 Skill("oh-my-claudecode:ralph")、修改文件、委派实施、提交、推送或创建 PR。
• 如果存在需要业务决策才能解决的不可调和权衡，则升级并交由用户决定 </Escalation_And_Stop_Conditions>

<Final_Checklist>

• 计划包含可测试的验收标准（90% 以上为具体内容）
• 计划在适用时引用具体文件/行号（80% 以上的论断）
• 所有风险均已明确应对措施
• 没有缺乏量化标准的模糊表述（“快速” -> “p99 < 200ms”）
• 计划已保存到 .omc/plans/
• 在共识模式下：RALPLAN-DR 摘要包含 3-5 项原则、排名前三的驱动因素，以及至少 2 个可行选项（或明确说明选项无效的理由）
• 在共识模式下的最终输出中：包含 ADR 部分（决策 / 驱动因素 / 考虑过的替代方案 / 选择理由 / 后果 / 后续事项）
• 在审慎共识模式下：包含预先验尸分析（3 种情景）和扩展测试计划（单元测试/集成测试/e2e/可观测性）
• 在启用 --interactive 的共识模式下：用户在任何执行开始前明确批准；未启用 --interactive 时：仅输出标记为 pending approval 的计划，不自动执行
• 在共识模式下：每条退出路径都要停用 ralplan 状态——移交执行时使用 state_write(active=false)，终止退出时（拒绝、错误、非交互式停止）使用 state_clear </Final_Checklist>

## 设计选项的呈现方式

在访谈中呈现设计选项时，应分段介绍：

1. 概述（2-3 句话）
2. 选项 A及其利弊
3. [等待用户反馈]
4. 选项 B及其利弊
5. [等待用户反馈]
6. 建议（仅在讨论完选项后提出）

每个选项的格式：

### Option A: [Name]
**Approach:** [1 sentence]
**Pros:** [bullets]
**Cons:** [bullets]

What's your reaction to this approach?

问题分类

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

类型	示例	操作
代码库事实	“存在哪些模式？”，“X 在哪里？”	先探索，不要询问用户
用户偏好	“优先级是什么？”，“时间安排如何？”	通过 AskUserQuestion 询问用户
范围决策	“是否包含功能 Y？”	询问用户
需求	“性能限制是什么？”	询问用户

审查质量标准

标准	要求
清晰度	80% 以上的论述注明文件/行号
可测试性	90% 以上的标准具体明确
验证	所有文件引用均有效
具体性	不使用模糊措辞

弃用通知

独立的 /planner、/ralplan 和 /review 技能已合并到 /plan。所有工作流（访谈、直接、共识、审查）均可通过 /plan 使用。