omh-autopilot

OMH Autopilot — エンドツーエンドの自律型パイプライン

使用する場面

• アイデアから検証・レビュー済みのコードまで、機能をエンドツーエンドで実装する場合
• ユーザーが「autopilot」「build me」「handle it all」「e2e this」と言った場合

使用しない場面

• 単一ファイルの変更や簡単なタスクの場合（そのまま実行してください）
• 1 回の連続したセッションで作業したい場合（autopilot は複数セッションにまたがります）
• 計画（omh-ralplan）または実行（omh-ralph）だけが必要な場合

前提条件

• omh プラグインがインストールされている必要があります（~/.hermes/plugins/omh/）

アーキテクチャ：呼び出しごとにフェーズステップを 1 つ実行

autopilot は、呼び出されるたびに状態を読み取り、作業単位を 1 つ実行して終了します。呼び出し元が再度呼び出します。 これにより、ralph ループ中も含め、あらゆる段階でコンテキストを新鮮な状態に保ちます。

Invocation 1:   Phase 0 — requirements (or skip)
Invocation 2:   Phase 1 — planning (or skip)
Invocations 3-N: Phase 2 — ralph iterations (one per call)
Invocation N+1: Phase 3 — QA cycle         [FRESH SESSION]
Invocation M:   Phase 4 — validation round  [FRESH SESSION]
Final:          Phase 5 — cleanup → complete

ループの実行方法については、references/caller-examples.md を参照してください。

手順

ステップ 0：インスタンスを解決してロックを取得する

autopilot は、目標を spec → plan → ralph → QA → 検証の順に進めます。 同じ目標に対して 2 つの autopilot セッションを実行すると、 autopilot、ralph、ralph-tasks の状態が同時に競合します。インスタンスごとの状態と アドバイザリロックを使用してください。

1. instance_id を次の順序で解決します：
   • 確認済みの spec が .omh/specs/{name}-spec.md にある場合は、 instance_id = "{name}" を使用します。
   • それ以外で、プランが .omh/plans/ralplan-{slug}.md にある場合は、 instance_id = "{slug}" を使用します。
   • どちらもない場合は、目標から導出します：instance_id = kebab(goal)[:60]。
2. autopilot ロックを取得します：

   lock = omh_state(action="lock", mode="autopilot",
                    lock_key="{instance_id}",
                    session_id="{HERMES_SESSION_ID or uuid}",
                    holder_note="autopilot driving {goal_or_plan}")
   

   acquired=false の場合は、held_by を報告し、待機／キャンセル／別の 目標を選ぶオプションを提示します。古い PID は自動解放されます。
3. この呼び出し内のすべての omh_state 呼び出し（autopilot、ralph、ralph-tasks）に instance_id を渡します。
4. Phase 2 で ralph に処理を委任する場合は、委任コンテキストにも同じ instance_id を渡し、ralph サブエージェントが同じスラッグで mode="ralph" ロックを取得するようにします。
5. すべての終了時点（一時停止、ブロック、完了、例外）で autopilot ロックを 解放します：

   omh_state(action="unlock", mode="autopilot",
             lock_key="{instance_id}",
             session_id="{HERMES_SESSION_ID or uuid}")
   

シングルトンのフォールバック（レガシー）。 instance_id を省略すると、 .omh/state/autopilot-state.json に書き込み、ロックをスキップします。autopilot を一度に 1 つだけ実行する 場合に限り使用できます。

呼び出しごとの処理：ディスパッチ

state = omh_state(action="read", mode="autopilot", instance_id="{instance_id}")

• 見つからない場合：新規開始 → スマート検出（以下を参照）
• 見つかった場合：context_checkpoint フラグを確認 → true の場合はフラグをクリアして終了（フェーズ境界）
• 古さを確認：state.stale = true → 警告し、新規開始を提案
• 一時停止を確認：pause_after_phase が現在の完了済みフェーズと一致する場合 → phase="paused" を設定して終了
• 現在のフェーズのハンドラーにディスパッチ

スマート検出（新規開始）

autopilot の状態が存在しない場合は、成果物を検出します：

1. .omh/specs/*-spec.md に確認済みの spec がある → 状態を Phase 1 で作成
2. .omh/plans/ralplan-*.md にコンセンサスプランがある → 状態を Phase 2 で作成
3. ralph が完了している（omh_state(action="check", mode="ralph", instance_id="{instance_id}") → phase="complete"）→ 状態を Phase 3 で作成
4. 何もない → 状態を Phase 0 で作成

アクティブな ralph があるか確認します：omh_state(action="check", mode="ralph", instance_id="{instance_id}") → アクティブな場合は、既存のセッションについて警告します。

omh_state(action="write", mode="autopilot", instance_id="{instance_id}", data={
    "phase": "requirements", "goal": "...", "ralph_iteration": 0,
    "qa_cycle": 0, "max_qa_cycles": 5, "validation_round": 0,
    "max_validation_rounds": 3, "validation_verdicts": {},
    "skip_qa": false, "skip_validation": false, "pause_after_phase": null
})

Phase 0：要件

目標：確認済みの spec が存在することを確認します。

1. status: confirmed の .omh/specs/*-spec.md を確認 → 見つかった場合は spec_file を設定し、Phase 1 に進んで終了
2. 見つからない場合は、入力を評価します：
   • 具体的（ファイルパス、関数名、具体的な技術）：spec をインラインで生成して先に進みます
   • 曖昧：omh-deep-interview を読み込み、その手順に従います。このフェーズは対話形式です。
3. 状態を更新します：phase: "planning"、spec_file: "<path>"。終了します。

完全自律で実行する場合：先に omh-deep-interview を別途実行してください。

Phase 1：計画

目標：コンセンサスプランが存在することを確認します。

1. .omh/plans/ralplan-*.md を確認 → 見つかった場合は plan_file を設定し、Phase 2 に進んで終了
2. 見つからない場合：omh-ralplan を読み込み、spec を入力としてその手順に従います
3. 状態を更新します：phase: "execution"、plan_file、ralph_iteration: 0、context_checkpoint: true。終了します。

フェーズ 2：実行（Ralph の反復）

呼び出しごとに、Ralph の反復を正確に 1 回実行します。

1. omh-ralph スキルのコンテキストを使い、delegate_task で Ralph の反復を 1 回実行します。

   delegate_task(goal="[omh-role:executor] Follow the omh-ralph skill procedure:
     read state, pick the next incomplete task, execute it, verify, update state, exit.",
     context="<current ralph state + plan file contents>")
   

2. Ralph がステップを完了したら、Ralph のステータスを確認します。

   ralph = omh_state(action="check", mode="ralph", instance_id="{instance_id}")
   

   • active=true → ralph_iteration をインクリメントして終了します（呼び出し元が再度呼び出します）。
   • phase="complete" → 次へ進みます：phase: "qa"、context_checkpoint: true を設定して終了します。
   • phase="blocked" → autopilot の phase: "blocked" を設定し、報告して終了します。

フェーズ 3：QA サイクル

呼び出しごとに、QA サイクルを1 回実行します。新しいセッションで開始します（context_checkpoint）。

skip_qa: true の場合 → フェーズ 4 に進んで終了します。

1. プロジェクトで実際に使われているビルド／テスト／lint コマンドを使って証拠を収集します（適切なコマンドを特定するため、Makefile、package.json、Cargo.toml、pyproject.toml などを確認します）。

   evidence = omh_gather_evidence(commands=["<build>", "<test>", "<lint>"])
   

2. evidence.all_pass の場合 → 次へ進みます：phase: "validation"、context_checkpoint: true を設定して終了します。
3. 失敗がある場合：
   • qa_cycle をインクリメントします。qa_error_history で 3 回連続の失敗を確認します。該当する場合 → phase="blocked" にして終了します。
   • qa_cycle > max_qa_cycles（デフォルトは 5）の場合 → phase="blocked" にして終了します。
   • アーキテクトサブエージェントに診断を委任します（読み取り専用）。
   • エグゼキューターサブエージェントに修正を委任します。
   • 状態を更新して終了します（次の呼び出しで QA を再実行します）。

フェーズ 4：複数レビュアーによる検証

呼び出しごとに、検証ラウンドを1 回実行します。新しいセッションで開始します。

skip_validation: true の場合 → フェーズ 5 に進んで終了します。

1. プロジェクトで実際に使われているビルド／テストコマンドを使って証拠を収集します。

   evidence = omh_gather_evidence(commands=["<build>", "<test>"])
   

2. 3 件のレビューを並列で委任します（正確に 3 件＝Hermes の同時実行上限）。

   delegate_task(tasks=[
       {goal: "[omh-role:architect] Architectural review:\n{spec + plan}", context: "{evidence}"},
       {goal: "[omh-role:security-reviewer] Security review:\n{changed files list}", context: "{evidence}"},
       {goal: "[omh-role:code-reviewer] Code quality review:\n{changed files list}", context: "{evidence}"}
   ])
   

3. validation_verdicts に判定を記録します。
4. すべてが APPROVE → フェーズ 5 に進んで終了します。
5. REQUEST_CHANGES がある場合 → エグゼキューターに修正を委任し、validation_round をインクリメントして終了します。
6. validation_round > max_validation_rounds（デフォルトは 3）の場合 → phase="blocked" にして終了します。

フェーズ 5：クリーンアップ

1. phase: "complete" を設定します（安全対策 — 中断された場合、再呼び出しでクリーンアップを再試行します）。
2. 状態ファイルを削除します。

   omh_state(action="clear", mode="autopilot", instance_id="{instance_id}")
   omh_state(action="clear", mode="ralph", instance_id="{instance_id}")
   omh_state(action="clear", mode="ralph-tasks", instance_id="{instance_id}")
   

3. 次を保持します：.omh/logs/、.omh/plans/、.omh/specs/
4. 完了概要を報告します：目標、完了したフェーズ、Ralph の反復回数、QA サイクル数、検証ラウンド数

状態管理

すべての状態は omh_state ツールを介して管理します。アトミック書き込みと古さの処理は自動で行われます。

センチネルの規約

omh_state(action="check", mode="autopilot", instance_id="{instance_id}")
→ {exists, active, phase, stale}

注意事項

• 1 つのセッション内で Ralph をループさせないでください。 Ralph の反復ごとに個別の呼び出しが必要です。コンテキストの枯渇は現実に起こります。
• Ralph を再実装しないでください。 スキルを読み込み、その手順に従ってください。
• フェーズの境界では新しいセッションを開始します。 context_checkpoint を遵守してください。
• QA を省略しないでください。 Ralph はタスクごとに検証します。QA では統合時の問題を検出します。
• 仕様が存在しない場合、フェーズ 0 では対話が必要です。 自動実行では、事前に仕様を作成してください。
• サブエージェントは 3 つまでです。 フェーズ 4 では、並列レビューに 3 つの枠すべてを使用します。