Autopilot

Operating Modes

• quick: one compact plan, one implementation lane, one validation pass. Use for small, well-scoped work.
• standard: spec -> plan -> execute -> verify with focused artifacts and limited agents. Default mode.
• deep: multiple lanes, explicit boundaries, task graph, review team, and broader validation. Use only for large/risky work or explicit user request.

Autopilot should choose the smallest mode that can genuinely finish the task. The user can override with quick, standard, or deep.

Persistent Artifacts

For non-trivial work, keep a compact artifact set under .omx/autopilot/<task-slug>/:

• checkpoint.md: current phase, root cause/hypothesis, files touched, next action, validation command.
• boundaries.md: do-not-break behavior, forbidden operations, secrets/production constraints, rollback point.
• tasks.md: task list with dependencies, ownership, parallel markers, and verification commands.
• validation.md: commands run, failures, fixes, final evidence.
• survival-guide.md: short handoff for compaction/restart with only the information needed to resume.

Keep artifacts short and update them at phase boundaries and before long repair loops.

Phase Gates

Each phase must pass these gates before advancing:

• Artifact exists and names the next concrete action.
• Open questions are either answered, explicitly deferred, or converted into a safe assumption.
• Risk boundary is clear for files, data, secrets, billing, production, and destructive commands.
• Verification command is known, or the reason no command exists is written down.
• For parallel work, every lane has disjoint ownership or is sequenced.

1. Phase 0 - Expansion: Turn the user's idea into a detailed spec

   • If .omx/specs/deep-interview-*.md exists for this task: reuse it and skip redundant expansion work
   • If prompt is highly vague: route to $deep-interview for Socratic ambiguity-gated clarification
   • Analyst (THOROUGH tier): Extract requirements
   • Architect (THOROUGH tier): Create technical specification
   • Output: .omx/plans/autopilot-spec.md
   • Gate: spec lists acceptance criteria, non-goals, risk boundaries, assumptions, and a concrete evidence target for every criterion (or an explicit human-validation dependency)

2. Phase 1 - Planning: Create an implementation plan from the spec

   • Architect (THOROUGH tier): Create plan (direct mode, no interview)
   • Critic (THOROUGH tier): Validate plan
   • Output: .omx/plans/autopilot-impl.md
   • Break work into tasks with:
     • id
     • owner
     • files/modules
     • dependsOn
     • parallelSafe: true|false
     • verify
     • acceptanceEvidence
   • Mark independent work with [P] and explicit verification work with [VERIFY]
   • Before execution, check for contradictory tasks, overlapping ownership, missing dependencies, stale paths, unverifiable criteria, and commands with external side effects; record rulings.
   • Gate: every task has an owner, dependency decision, acceptance evidence, and verification command or evidence target

3. Phase 2 - Execution: Implement the plan with available execution workflows

   • LOW-tier executor/search roles: Simple tasks
   • STANDARD-tier executor roles: Standard tasks
   • THOROUGH-tier executor/architect roles: Complex tasks
   • Run independent tasks in parallel only when write ownership is disjoint, the integration point is clear, and each lane has an independent verification target. Shared interfaces, migrations, configuration, lockfiles, and generated files are sequential by default.
   • The lead agent keeps the critical path moving while side agents work
   • Before each long edit or test loop, update the checkpoint with changed files, current hypothesis, next action, and verification command
   • Execute tasks one-by-one unless [P] lanes are proven independent
   • For each task, use a fresh compact context: spec summary, relevant files, task definition, boundary notes, and verify command
   • The lead orchestrator should coordinate outputs and integration; avoid filling lead context with full file dumps that belong to specialist lanes

4. Phase 3 - QA: Verify in layers, then repair

   • Start with existence and relevance checks, then focused behavior checks, then integration/regression checks, and finally boundary checks for secrets, private paths, permissions, destructive operations, and generated output.
   • Build, lint, test, and fix failures when those checks exist; never invent a passing result for an unavailable command.
   • Repeat up to 5 cycles
   • Stop early if the same error repeats 3 times (indicates a fundamental issue)
   • Do not rerun broad tests blindly; after one broad failure, switch to the smallest failing test or command until fixed
   • For every failure, record root cause, changed hypothesis, smallest safe fix, covering check, and result. After one broad failure, switch to the smallest failing check before rerunning the broad gate.
   • Use layered gates:
     • existence: changed files and expected artifacts exist
     • relevance: changes address the requested behavior
     • root cause: failure explanation maps to code changed
     • regression: focused tests plus broad gate when available
     • momentum: next step is smaller than the previous loop
   • A gate may pass with an explicitly classified environmental, pre-existing, or unavailable check only when impact and next action are recorded; unresolved failures cannot be silently waived.

5. Phase 4 - Validation: Evidence-based independent review

   • Architect: Functional completeness
   • Security-reviewer: Vulnerability check
   • Code-reviewer: Quality review
   • Reviewers receive concise artifacts and diffs, not full session history
   • Review findings must include severity, file/path, and required action
   • Review the actual diff and evidence, not only worker reports.
   • Findings must include severity, path/symbol, evidence, and required action. Critical or important findings require a fix and scoped re-review; use one consolidated fix wave when findings share a cause.
   • After the validation cap, adjudicate each residual finding as fixed, deferred, or blocked with a reason. Do not silently convert disagreement into approval.
   • If reviewers or MCP tools are unavailable, perform a single-agent adversarial review and disclose that limitation.

6. Phase 5 - Handoff and cleanup: Clear only state owned by this run

   • state_clear({mode: "autopilot"})
   • state_clear({mode: "ralph"})
   • state_clear({mode: "ultrawork"})
   • state_clear({mode: "ultraqa"})
   • Or run /cancel for clean exit. Do not delete project artifacts or user changes as cleanup.

Token And Compaction Discipline

• Load router/index files before full catalogs or long references.
• Prefer file paths, symbols, and focused snippets over full file dumps.
• Summarize long command output immediately into the checkpoint instead of replaying it.
• Do not spawn agents to do the same search as the lead agent.
• Treat automatic compaction as a resume event, not a reason to restart the workflow.
• If context is getting large, finish the current fix/verification step before broadening scope.
• Keep a survival-guide.md current enough that a new session can continue without reading the raw conversation.

Multiagent Discipline

• Use subagents only when the user explicitly asks or when independent lanes materially reduce time or risk.
• Assign each subagent a non-overlapping file/module/question scope.
• Require each subagent to return changed paths, commands run, findings, blockers, and residual risk.
• Keep integration, conflict resolution, and final validation with the lead agent.
• If agents would edit the same file, sequence the work instead of parallelizing it.
• Use specialist agents with single responsibilities; do not ask multiple agents to solve the same vague problem.

Boundary Discipline

Before broad or risky execution, write boundaries:

• NEVER: destructive git commands, deleting user work, exposing secrets, unsafe production changes.
• DANGER: payments, auth, RLS, migrations, billing, customer data, cron jobs, external API side effects.
• ROLLBACK: current branch/status, backup path, or command needed to return to the pre-change state.
• VERIFY: the commands or manual evidence that prove the boundary was preserved.

State Management

Use omx_state MCP tools for autopilot lifecycle state when available. The filesystem checkpoint and task ledger remain the source of truth when state tools are unavailable or fail.

• On start: state_write({mode: "autopilot", active: true, current_phase: "expansion", started_at: "<now>", state: {context_snapshot_path: "<snapshot-path>"}})
• On phase transitions: state_write({mode: "autopilot", current_phase: "planning"}) state_write({mode: "autopilot", current_phase: "execution"}) state_write({mode: "autopilot", current_phase: "qa"}) state_write({mode: "autopilot", current_phase: "validation"})
• On completion: state_write({mode: "autopilot", active: false, current_phase: "complete", completed_at: "<now>"})
• On cancellation/cleanup: run $cancel (which should call state_clear(mode="autopilot"))

Scenario Examples

Good: The user says continue after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.

Good: The user changes only the output shape or downstream delivery step (for example make a PR). Preserve earlier non-conflicting workflow constraints and apply the update locally.

Bad: The user says continue, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.

Optional settings in ~/.codex/config.toml:

[omx.autopilot]
maxIterations = 10
maxQaCycles = 5
maxValidationRounds = 3
pauseAfterExpansion = false
pauseAfterPlanning = false
skipQa = false
skipValidation = false

Resume

If autopilot was cancelled or failed, run /autopilot again to resume from where it stopped.

Recommended Clarity Pipeline

For ambiguous requests, prefer:

deep-interview -> ralplan -> autopilot

• deep-interview: ambiguity-gated Socratic requirements
• ralplan: consensus planning (planner/architect/critic)
• autopilot: execution + QA + validation

Best Practices for Input

1. Be specific about the domain -- "bookstore" not "store"
2. Mention key features -- "with CRUD", "with authentication"
3. Specify constraints -- "using TypeScript", "with PostgreSQL"
4. Let it run -- avoid interrupting unless truly needed

Pipeline Orchestrator (v0.8+)

Autopilot can be driven by the configurable pipeline orchestrator (src/pipeline/), which sequences stages through a uniform PipelineStage interface:

RALPLAN (consensus planning) -> team-exec (Codex CLI workers) -> ralph-verify (architect verification)

Pipeline configuration options:

[omx.autopilot.pipeline]
maxRalphIterations = 10    # Ralph verification iteration ceiling
workerCount = 2            # Number of Codex CLI team workers
agentType = "executor"     # Agent type for team workers

The pipeline persists state via pipeline-state.json and supports resume from the last incomplete stage. See src/pipeline/orchestrator.ts for the full API.

Troubleshooting

Stuck in a phase? Check the active task list for blocked tasks, run state_read({mode: "autopilot"}), or cancel and resume.

QA cycles exhausted? The same error 3 times indicates a fundamental issue. Review the error pattern; manual intervention may be needed.

Validation keeps failing? Review the specific issues. Requirements may have been too vague -- cancel and provide more detail.