omh-autopilot

OMH Autopilot — End-to-End Autonomous Pipeline

When to Use

End-to-end feature implementation from idea to verified, reviewed code
The user says: "autopilot", "build me", "handle it all", "e2e this"

When NOT to Use

Single-file changes or trivial tasks (just do them)
You want to stay in one continuous session (autopilot is multi-session)
You only need planning (omh-ralplan) or execution (omh-ralph)

Prerequisites

The omh plugin must be installed (~/.hermes/plugins/omh/)

Architecture: One Phase Step Per Invocation

Each autopilot invocation reads state, does ONE unit of work, exits. The caller re-invokes. This preserves fresh context at every level — including during the ralph loop.

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

See references/caller-examples.md for how to drive the loop.

Procedure

Step 0: Resolve Instance and Acquire Lock

Autopilot drives a goal through spec → plan → ralph → QA → validation. Two autopilot sessions on the same goal would race on autopilot, ralph, and ralph-tasks state simultaneously. Use per-instance state

advisory lock.

Resolve instance_id in this order:
- If a confirmed spec exists at .omh/specs/{name}-spec.md, use instance_id = "{name}".
- Else if a plan exists at .omh/plans/ralplan-{slug}.md, use instance_id = "{slug}".
- Else derive from the goal: instance_id = kebab(goal)[:60].

Acquire the autopilot lock:

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}")

On acquired=false, report held_by, offer wait/cancel/different goal. Stale-pid auto-release applies.

Pass instance_id to every omh_state call in this invocation (autopilot, ralph, ralph-tasks).
When dispatching to ralph in Phase 2, pass the same instance_id in the delegation context so the ralph subagent acquires mode="ralph" lock on the same slug.

Release the autopilot lock at every exit point (paused, blocked, complete, exception):

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

Singleton fallback (legacy). Omitting instance_id writes .omh/state/autopilot-state.json and skips locking. Acceptable only when running one autopilot at a time.

On Every Invocation: Dispatch

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

Not found: Fresh start → Smart Detection (below)
Found: Check context_checkpoint flag → if true, clear it and exit (phase boundary)
Check staleness: state.stale = true → warn, offer fresh start
Check pause: if pause_after_phase matches current completed phase → set phase="paused", exit
Dispatch to current phase handler

Smart Detection (Fresh Start)

When no autopilot state exists, detect artifacts:

Confirmed spec in .omh/specs/*-spec.md → create state at Phase 1
Consensus plan in .omh/plans/ralplan-*.md → create state at Phase 2
Ralph complete (omh_state(action="check", mode="ralph", instance_id="{instance_id}") → phase="complete") → create state at Phase 3
Nothing → create state at Phase 0

Check for active ralph: omh_state(action="check", mode="ralph", instance_id="{instance_id}") → if active, warn about existing session.

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: Requirements

Goal: Ensure a confirmed spec exists.

Check .omh/specs/*-spec.md with status: confirmed → found? Set spec_file, advance to Phase 1, exit
Not found — assess input:
- Concrete (file paths, function names, specific tech): generate inline spec, advance
- Vague: Load omh-deep-interview and follow it. This phase is interactive.
Update state: phase: "planning", spec_file: "<path>". Exit.

For fully autonomous runs: run omh-deep-interview separately first.

Phase 1: Planning

Goal: Ensure a consensus plan exists.

Check .omh/plans/ralplan-*.md → found? Set plan_file, advance to Phase 2, exit
Not found: Load omh-ralplan, follow its procedure with the spec as input
Update state: phase: "execution", plan_file, ralph_iteration: 0, context_checkpoint: true. Exit.

Phase 2: Execution (Ralph Iterations)

Each invocation performs exactly ONE ralph iteration:

Run one ralph iteration via delegate_task with the omh-ralph skill context:

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>")

After ralph completes its step, check ralph status:
```
ralph = omh_state(action="check", mode="ralph", instance_id="{instance_id}")
```
- active=true → increment ralph_iteration, exit (caller re-invokes)
- phase="complete" → advance: phase: "qa", context_checkpoint: true, exit
- phase="blocked" → set autopilot phase: "blocked", report, exit

Phase 3: QA Cycling

Each invocation performs ONE QA cycle. Starts in fresh session (context_checkpoint).

If skip_qa: true → advance to Phase 4, exit.

Gather evidence using the project's actual build/test/lint commands (check for Makefile, package.json, Cargo.toml, pyproject.toml, etc. to determine the right commands):
```
evidence = omh_gather_evidence(commands=["<build>", "<test>", "<lint>"])
```
If evidence.all_pass → advance: phase: "validation", context_checkpoint: true, exit
If failures:
- Increment qa_cycle. Check 3-strike on qa_error_history. If triggered → phase="blocked", exit
- If qa_cycle > max_qa_cycles (default 5) → phase="blocked", exit
- Delegate diagnosis to architect subagent (read-only)
- Delegate fix to executor subagent
- Update state, exit (next invocation re-runs QA)

Phase 4: Multi-Reviewer Validation

Each invocation performs ONE validation round. Starts in fresh session.

If skip_validation: true → advance to Phase 5, exit.

Gather evidence using the project's actual build/test commands:

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

Delegate 3 parallel reviews (exactly 3 = Hermes concurrent limit):

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}"}
])

Record verdicts in validation_verdicts
All APPROVE → advance to Phase 5, exit
Any REQUEST_CHANGES → delegate fix to executor, increment validation_round, exit
If validation_round > max_validation_rounds (default 3) → phase="blocked", exit

Phase 5: Cleanup

Set phase: "complete" (safety — if interrupted, re-invocation retries cleanup)

Delete state files:

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}")

Preserve: .omh/logs/, .omh/plans/, .omh/specs/
Report completion summary: goal, phases completed, ralph iterations, QA cycles, validation rounds

State Management

All state via omh_state tool. Atomic writes and staleness handled automatically.

Sentinel Convention

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

Pitfalls

Don't loop ralph in a single session. Each ralph iteration is a separate invocation. Context exhaustion is real.
Don't reimplement ralph. Load the skill, follow its procedure.
Phase boundaries = fresh sessions. Respect context_checkpoint.
Don't skip QA. Ralph verifies per-task. QA catches integration issues.
Phase 0 is interactive if no spec exists. Pre-create specs for automated runs.
3 subagent limit. Phase 4 uses all 3 slots for parallel review.