omh-ralplan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OMH Ralplan — Consensus Planning

OMH Ralplan — 共识规划

When to Use

适用场景

  • Before implementing any feature that touches multiple files or components
  • When architectural decisions need validation from multiple perspectives
  • When you need a plan that's been stress-tested against adversarial critique
  • When the user says: "plan this", "consensus plan", "ralplan", "let's think this through"
  • 在实施涉及多个文件或组件的功能之前
  • 当架构决策需要从多视角验证时
  • 当你需要一个经过对抗性评审压力测试的计划时
  • 当用户提出:"规划这个"、"共识规划"、"ralplan"、"让我们仔细梳理一下"时

When NOT to Use

不适用场景

  • Trivial single-file changes (just do them)
  • Tasks where the approach is obvious and low-risk
  • When the user explicitly wants to skip planning
  • 简单的单文件修改(直接执行即可)
  • 方案明显且低风险的任务
  • 当用户明确要求跳过规划时

Prerequisites

前提条件

  • A clear goal or specification (if ambiguous, use
    omh-deep-interview
    first)
  • The
    delegate_task
    tool must be available
  • 清晰的目标或规格说明(如果模糊,先使用
    omh-deep-interview
  • 必须具备
    delegate_task
    工具

Procedure

执行流程

Phase 0: Context Gathering

阶段0:上下文收集

Before planning, gather project context:
  1. Read relevant files to understand the codebase structure
  2. Identify existing patterns, conventions, and constraints
  3. Summarize context into a brief (~500 words) that all agents will receive
规划前,收集项目上下文:
  1. 阅读相关文件以理解代码库结构
  2. 识别现有模式、约定和约束
  3. 将上下文总结为简短内容(约500字),供所有Agent接收

Phase 1: Planning Loop (max 3 rounds)

阶段1:规划循环(最多3轮)

Round 1 — All Sequential (Planner → Architect → Critic):
Step 1 — Planner (single 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}"
)
The goal should include the full specification — don't assume the subagent knows anything.
Step 2 — Architect Review (single 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}"
)
Step 3 — Critic Challenge (single 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}"
)
Step 4 — Consensus Check Check all three verdicts:
  • If ALL three are APPROVE → consensus reached, proceed to output
  • If any is REQUEST_CHANGES → collect all feedback, proceed to Round 2
  • If any is REJECT → output concerns and ask user whether to continue
Round 2+ — Planner Revises, Architect + Critic Re-review in Parallel:
When looping, the Planner must receive ALL feedback (Architect concerns + Critic critical issues + warnings). Be explicit about what needs to change — include the specific concern IDs (A1, C1, W1, etc.).
For Round 2 re-reviews, Architect and Critic are independent — run them in parallel via batch 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}"}
])
This saves significant time (Round 2 re-reviews ran 14 seconds parallel vs ~120 seconds sequential).
第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秒)。

Phase 2: Output

阶段2:输出

Write the consensus plan to
.omh/plans/ralplan-{slug}.md
containing:
  1. Consensus status (rounds, verdicts per round)
  2. Revision summary (what changed from feedback)
  3. The final plan (tasks with dependencies, complexity, acceptance criteria)
  4. Risks and open questions
  5. Round count and consensus status
Use a descriptive slug, not a timestamp:
ralplan-deep-interview-consensus.md
not
ralplan-20260407.md
.
Also write a summary to the user with the key design decisions that emerged from the debate.
将共识计划写入
.omh/plans/ralplan-{slug}.md
,内容包括:
  1. 共识状态(轮次、每轮结论)
  2. 修订摘要(根据反馈做出的修改)
  3. 最终计划(带依赖关系、复杂度、验收标准的任务)
  4. 风险与未解决问题
  5. 轮次数量与共识状态
使用描述性的slug,而非时间戳:比如
ralplan-deep-interview-consensus.md
,而非
ralplan-20260407.md
同时向用户发送一份摘要,说明辩论中得出的关键设计决策。

State Management

状态管理

State is per-instance, keyed on the plan slug (
instance_id="{slug}"
). Multiple ralplan sessions on different goals can run concurrently.
If the
omh
plugin is available, use it for state:
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"
})
If the plugin is not available, write
.omh/state/ralplan--{slug}.json
manually.
If a ralplan session is interrupted, list active instances and resume from the last completed phase:
listed = omh_state(action="list_instances", mode="ralplan")
state  = omh_state(action="read", mode="ralplan", instance_id="{slug}")
Singleton fallback (legacy). Omitting
instance_id
writes
.omh/state/ralplan-state.json
. Acceptable only when running one ralplan at a time.
状态按实例存储,以计划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 Mode (--deliberate)

审慎模式(--deliberate)

When the user requests deliberate mode or uses "deliberate", "ADR", or "decision record", the Architect's output should follow Architecture Decision Record (ADR) format. Load
references/adr-template.md
for the template.
当用户请求审慎模式或使用“deliberate”、“ADR”或“decision record”时,架构师的输出应遵循架构决策记录(ADR)格式。加载
references/adr-template.md
作为模板。

Pitfalls

注意事项

  • Use
    [omh-role:NAME]
    markers in the goal field
    — the OMH plugin automatically injects the role prompt into the subagent's system prompt. Never inline role prompt text manually. Available roles: planner, architect, critic, executor, verifier, analyst, security-reviewer, code-reviewer, test-engineer, debugger. Fallback without plugin:
    omh_state(action="load_role", role="NAME")
    and pass returned prompt in context.
  • Include full specifications in the goal — subagents start with zero context. The goal + context must be self-contained.
  • Run Round 2+ reviews in parallel — Architect and Critic are independent in re-review rounds. Use batch delegate_task to save time.
  • Summarize feedback with IDs for the Planner — when looping, label feedback as A1/A2/C1/C2/W1 etc. so the Planner can address each point explicitly and the reviewers can check each one off.
  • Don't let the loop run more than 3 rounds — if no consensus by round 3, output with caveats
  • Each subagent must receive the project context, not just the plan — they need to evaluate against reality
  • The Critic should challenge, not block — if issues are minor, APPROVE with reservations
  • If the goal is ambiguous, stop and suggest
    omh-deep-interview
    instead of planning with unclear requirements
  • Use todo tracking — update a todo list with round/phase status so the user sees progress during what can be a 5-10 minute process
  • When porting/adapting from a reference system, feed actual source to subagents — if designing a skill inspired by another system (e.g., OMC → Hermes), the Planner, Architect, and Critic must read the actual source implementation, not just briefs or summaries. Extract reference docs from the source repo first, pass file paths in the delegate_task goal so subagents read them. Summaries lose critical field names, state schemas, edge cases, and design patterns.
  • The Critic's simplicity test can change architecture — don't dismiss it. In the ralph consensus, the Critic proposed one-task-per-invocation (instead of an in-session loop) which both reviewers then approved as fundamentally better. The consensus process finds the right architecture, not just validates the proposed one.
  • 在目标字段中使用
    [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")
    并将返回的提示传入context。
  • 在目标中包含完整规格说明——子Agent初始无任何上下文。目标+上下文必须自成体系。
  • 第2轮及以后的评审并行执行——架构师和评审师在重审轮次中相互独立。使用批量delegate_task调用节省时间。
  • 为规划师提供带ID的反馈摘要——循环时,将反馈标记为A1/A2/C1/C2/W1等,以便规划师明确处理每个要点,评审人员也能逐一核对。
  • 循环不要超过3轮——如果第3轮仍未达成共识,附带说明后输出结果
  • 每个子Agent都必须接收项目上下文,而不仅仅是计划——他们需要结合实际情况进行评估
  • 评审师应提出质疑而非阻碍——如果问题轻微,可附带保留意见后通过(APPROVE)
  • 如果目标模糊,停止并建议使用
    omh-deep-interview
    ,而非基于不明确的需求进行规划
  • 使用待办事项跟踪——更新待办事项列表,记录轮次/阶段状态,以便用户在5-10分钟的流程中查看进度
  • 从参考系统移植/适配时,向子Agent提供实际源代码——如果设计受其他系统启发的技能(如OMC → Hermes),规划师、架构师和评审师必须阅读实际的源代码实现,而非仅摘要或简介。先从源仓库提取参考文档,在delegate_task目标中传入文件路径,以便子Agent读取。摘要会丢失关键字段名、状态 schema、边缘情况和设计模式。
  • 评审师的简洁性测试可能改变架构——不要忽视它。在ralph共识中,评审师提出每次调用执行一个任务(而非会话内循环),随后两位评审人员都认可这一方案本质上更优。共识流程旨在找到合适的架构,而非仅验证提议的架构。