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

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

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

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.

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

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.

omh-autopilot

NPX Install

Tags

SKILL.md Content