omh-ralplan

OMH Ralplan — 合意形成による計画立案

使用するタイミング

• 複数のファイルやコンポーネントに関わる機能を実装する前
• アーキテクチャ上の決定を複数の視点から検証する必要がある場合
• 敵対的な批評による厳しい検証を経た計画が必要な場合
• ユーザーが「これを計画して」「合意形成による計画」「ralplan」「よく検討してみましょう」と言った場合

使用しないタイミング

• 些細な単一ファイルの変更（そのまま実行してください）
• アプローチが明らかで、リスクが低いタスク
• ユーザーが明示的に計画を省略したい場合

前提条件

• 明確な目標または仕様があること（曖昧な場合は、まず omh-deep-interview を使用してください）
• delegate_task ツールが利用可能であること

手順

フェーズ 0：コンテキストの収集

計画を立てる前に、プロジェクトのコンテキストを収集します。

1. 関連ファイルを読み、コードベースの構成を把握します
2. 既存のパターン、規約、制約を特定します
3. すべてのエージェントに共有するコンテキストを、簡潔な概要（約 500 語）にまとめます

フェーズ 1：計画の反復（最大 3 ラウンド）

ラウンド 1 — すべて逐次実行（Planner → Architect → Critic）：

ステップ 1 — Planner（delegate_task を 1 回実行）

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

目標には仕様の全容を含めてください。サブエージェントが何も知らない前提で進めてください。

ステップ 2 — Architect によるレビュー（delegate_task を 1 回実行）

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 — Critic による検証（delegate_task を 1 回実行）

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 — 合意の確認 3 つすべての判定を確認します。

• 3 つすべてが APPROVE の場合 → 合意に達したため、出力に進みます
• REQUEST_CHANGES が 1 つでもある場合 → すべてのフィードバックを集め、ラウンド 2 に進みます
• REJECT が 1 つでもある場合 → 懸念事項を出力し、続行するかユーザーに確認します

ラウンド 2 以降 — Planner が修正し、Architect と Critic が並行して再レビュー：

反復する場合、Planner にはすべてのフィードバック（Architect の懸念事項、Critic の重大な指摘、警告）を渡す必要があります。何を変更すべきかを明確にし、具体的な懸念事項 ID（A1、C1、W1 など）を含めてください。

ラウンド 2 の再レビューでは、Architect と Critic は互いに独立しているため、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}"}
])

これにより、大幅に時間を節約できます（ラウンド 2 の再レビューは、逐次実行で約 120 秒かかるところ、並行実行では 14 秒でした）。

フェーズ 2：出力

合意形成された計画を .omh/plans/ralplan-{slug}.md に記述します。内容は次のとおりです。

1. 合意状況（ラウンド数、各ラウンドの判定）
2. 修正の概要（フィードバックを受けて変更した内容）
3. 最終計画（依存関係、複雑度、受け入れ基準を含むタスク）
4. リスクと未解決の質問
5. ラウンド数と合意状況

タイムスタンプではなく、内容がわかる slug を使用してください。ralplan-20260407.md ではなく、ralplan-deep-interview-consensus.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 を一度に 1 つだけ 実行する場合に限り、許容されます。

熟慮モード（--deliberate）

ユーザーが熟慮モードをリクエストした場合、または「deliberate」「ADR」「decision record」を使用した場合、Architect の出力は Architecture Decision Record（ADR）形式に従う必要があります。テンプレートとして references/adr-template.md を読み込んでください。

落とし穴

• goal フィールドでは [omh-role:NAME] マーカーを使用してください — OMH プラグインはロールプロンプトをサブエージェントのシステムプロンプトに自動で挿入します。ロールプロンプトのテキストを手動でインラインに記述しないでください。使用可能なロール：planner、architect、critic、executor、verifier、analyst、security-reviewer、code-reviewer、test-engineer、debugger。プラグインがない場合の代替方法：omh_state(action="load_role", role="NAME") を実行し、返されたプロンプトをコンテキストに渡します。
• goal に仕様をすべて含めてください — サブエージェントはコンテキストがまったくない状態で開始します。goal とコンテキストだけで自己完結している必要があります。
• 第 2 ラウンド以降のレビューは並列で実行してください — 再レビューのラウンドでは、Architect と Critic は互いに独立しています。batch delegate_task を使って時間を節約してください。
• Planner にフィードバックを ID 付きで要約してください — ループする場合は、フィードバックに A1/A2/C1/C2/W1 などのラベルを付け、Planner が各項目に明示的に対応し、レビュアーがそれぞれを確認できるようにします。
• ループを 3 ラウンドを超えて続けないでください — 第 3 ラウンドで合意に至らない場合は、留保事項を添えて出力します。
• 各サブエージェントには計画だけでなく、プロジェクトのコンテキストも渡してください — 現実に照らして評価する必要があります。
• Critic は異議を唱える役割であり、阻止する役割ではありません — 問題が軽微であれば、留保付きで APPROVE します。
• goal が曖昧な場合は、要件が不明確なまま計画を立てず、停止して代わりに omh-deep-interview を提案してください。
• todo で進捗を追跡してください — ラウンド／フェーズの状況を todo リストに更新し、5〜10 分かかることもある処理の進捗をユーザーに示します。
• 参照システムから移植・適応する場合は、実際のソースをサブエージェントに渡してください — 別のシステム（例：OMC → Hermes）に着想を得たスキルを設計する場合、Planner、Architect、Critic は概要や要約だけでなく、実際のソース実装を読む必要があります。まずソースリポジトリから参照ドキュメントを抽出し、サブエージェントがそれらを読めるように、ファイルパスを delegate_task の goal に記載してください。要約では、重要なフィールド名、状態スキーマ、エッジケース、設計パターンが失われます。
• Critic のシンプルさの検証によって、アーキテクチャが変わることがあります — 軽視しないでください。ralph consensus では、Critic が（セッション内ループではなく）1 回の呼び出しにつき 1 タスクを提案し、両方のレビュアーがこれを根本的に優れた方法として承認しました。合意形成のプロセスは、提案されたものを検証するだけでなく、適切なアーキテクチャを見つけ出します。