omh-ralplan

OMH Ralplan — 共识规划

适用场景

• 实现涉及多个文件或组件的功能之前
• 需要从多个角度验证架构决策时
• 需要制定经受过对抗性审查的计划时
• 用户说“规划这个”“共识计划”“ralplan”或“我们仔细想想”时

不适用场景

• 简单的单文件改动（直接执行即可）
• 方法显而易见且风险较低的任务
• 用户明确要求跳过规划时

前置条件

• 有清晰的目标或规范（如果存在歧义，请先使用 omh-deep-interview）
• 必须可以使用 delegate_task 工具

流程

阶段 0：收集上下文

规划前，先收集项目上下文：

1. 阅读相关文件，了解代码库结构
2. 找出已有模式、约定和限制
3. 将上下文概括为一份简要说明（约 500 字），供所有 Agent 使用

阶段 1：规划循环（最多 3 轮）

第 1 轮 — 全部顺序执行（规划者 → 架构师 → 批评者）：

步骤 1 — 规划者（单次 delegate_task）

delegate_task(
    goal="[omh-role:planner] Create an implementation plan for: {goal}\n\n{detailed_requirements}",
    context="# Project Context\n\n{project_context}"
)

目标应包含完整规范，不要假设子 Agent 了解任何信息。

步骤 2 — 架构师评审（单次 delegate_task）

delegate_task(
    goal="[omh-role:architect] Review this implementation plan for architectural soundness:\n\nPLAN:\n{planner_output}",
    context="# Project Context\n\n{project_context}"
)

步骤 3 — 批评者质询（单次 delegate_task）

delegate_task(
    goal="[omh-role:critic] Critically challenge this plan and architect review:\n\nPLAN SUMMARY:\n{plan_summary}\n\nARCHITECT REVIEW:\n{architect_verdict_and_concerns}",
    context="# Project Context\n\n{project_context}"
)

步骤 4 — 共识检查 检查三方的裁决：

• 如果三方都 APPROVE → 达成共识，继续输出
• 如果任一方为 REQUEST_CHANGES → 收集所有反馈，进入第 2 轮
• 如果任一方为 REJECT → 输出顾虑，并询问用户是否继续

第 2 轮及以后 — 规划者修订，架构师和批评者并行复审：

进入循环时，规划者必须收到所有反馈（架构师的顾虑、批评者的关键问题和警告）。明确指出需要修改的内容，并附上具体的顾虑 ID（A1、C1、W1 等）。

第 2 轮复审时，架构师和批评者彼此独立，应通过批量 delegate_task 并行运行：

delegate_task(tasks=[
    {goal: "[omh-role:architect] Re-review revised plan:\n{revised_plan}\n\nPrior concerns: {architect_concerns}", context: "{project_context}"},
    {goal: "[omh-role:critic] Re-review revised plan:\n{revised_plan}\n\nPrior concerns: {critic_concerns}", context: "{project_context}"}
])

这能显著节省时间（第 2 轮复审并行运行耗时 14 秒，顺序运行约需 120 秒）。

阶段 2：输出

将共识计划写入 .omh/plans/ralplan-{slug}.md，包含：

1. 共识状态（轮数、每轮裁决）
2. 修订摘要（根据反馈所做的修改）
3. 最终计划（包含依赖关系、复杂度和验收标准的任务）
4. 风险和未决问题
5. 轮数和共识状态

使用描述性 slug，而非时间戳：例如 ralplan-deep-interview-consensus.md，而不是 ralplan-20260407.md。

另向用户提供摘要，说明讨论中得出的关键设计决策。

状态管理

状态按实例隔离，并以计划 slug 为键（instance_id="{slug}"）。 不同目标的多个 ralplan 会话可以并行运行。

如果 omh 插件可用，请使用它管理状态：

omh_state(action="write", mode="ralplan", instance_id="{slug}", data={
    "goal": "...", "round": 1,
    "phase": "planner|architect|critic|complete",
    "consensus": false, "plan_file": ".omh/plans/ralplan-{slug}.md"
})

如果插件不可用，请手动写入 .omh/state/ralplan--{slug}.json。

如果 ralplan 会话中断，请列出活动实例，并从上次完成的阶段恢复：

listed = omh_state(action="list_instances", mode="ralplan")
state  = omh_state(action="read", mode="ralplan", instance_id="{slug}")

单例回退方案（旧版）。 省略 instance_id 会写入 .omh/state/ralplan-state.json。仅在一次运行一个 ralplan 时可接受。

深思模式（--deliberate）

当用户请求深思模式，或使用“deliberate”“ADR”或“decision record”时，架构师的输出应遵循架构决策记录（ADR）格式。加载 references/adr-template.md 获取模板。

常见陷阱

• 在 goal 字段中使用 [omh-role:NAME] 标记——OMH 插件会自动将角色提示词注入子 Agent 的系统提示词中。切勿手动内联角色提示词文本。可用角色：planner、architect、critic、executor、verifier、analyst、security-reviewer、code-reviewer、test-engineer、debugger。没有插件时的备用方法：omh_state(action="load_role", role="NAME")，并将返回的提示词作为上下文传入。
• 在 goal 中包含完整规格——子 Agent 启动时没有任何上下文。goal 和 context 必须自成一体。
• 并行运行第 2 轮及之后的评审——在复审轮次中，Architect 和 Critic 彼此独立。使用批量 delegate_task 节省时间。
• 为 Planner 总结反馈并添加 ID——进入循环时，将反馈标记为 A1/A2/C1/C2/W1 等，以便 Planner 明确处理每个问题，评审者也能逐项核对。
• 循环不要超过 3 轮——如果到第 3 轮仍未达成共识，请附带注意事项后输出
• 每个子 Agent 都必须收到项目上下文，而不只是计划——它们需要结合实际情况进行评估
• Critic 应提出质疑，而非阻止推进——如果问题较小，应在保留意见的情况下 APPROVE
• 如果 goal 含糊不清，请停止并建议使用 omh-deep-interview，不要在需求不明确时进行规划
• 使用待办事项跟踪——更新待办列表中的轮次/阶段状态，让用户在这个可能持续 5-10 分钟的过程中了解进度
• 从参考系统移植/改编时，向子 Agent 提供实际源代码——如果设计的 skill 受另一个系统启发（例如 OMC → Hermes），Planner、Architect 和 Critic 必须阅读实际源代码实现，而不只是简介或摘要。先从源代码仓库提取参考文档，再在 delegate_task 的 goal 中传入文件路径，让子 Agent 阅读。摘要会遗漏关键字段名称、状态架构、边缘情况和设计模式。
• Critic 的简化性测试可能改变架构——不要忽视它。在 ralph 共识过程中，Critic 提议每次调用只处理一个任务（而不是在会话内循环），之后两位评审者都认可这种方案从根本上更优。共识流程旨在找到正确的架构，而不只是验证提议的架构。