# Autopilot > Strict autonomous delivery loop that runs deep-interview, ralplan, ultragoal, code-review, and ultraqa in order with automatic re-planning when gates are not clean. Use on "autopilot", "autonomous", "build me", "create me", "make me", "full auto", "handle it all", or "I want a/an…". - Skill: `mrzhangguoguo/autopilot` (Agent Skill) - Install (CLI): `npx skillmds@latest add mrzhangguoguo/autopilot` - Raw SKILL.md: https://api.skillmd.com/api/skills/mrzhangguoguo/autopilot/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: mrzhangguoguo (https://skillmd.com/u/mrzhangguoguo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mrzhangguoguo/autopilot --- > Ported from oh-my-codex `autopilot`. OMX runtime conventions (`$macro` invocation, `omx` CLI, `.omx/` state directory) are replaced with WorkBuddy idioms (Skill tool, Agent tool, task list, `.omw/autopilot//` sidecar). # Autopilot Autopilot is the strict autonomous delivery loop for non-trivial work. Its recommended/default contract is exactly: ```text deep-interview -> ralplan -> ultragoal (+ team if needed) -> code-review -> ultraqa ``` If `code-review` or `ultraqa` is not clean, Autopilot returns to `ralplan` with the findings as the next planning input, then continues again through `ultragoal`, `code-review`, and `ultraqa` until the gates are clean or a hard blocker is reported. Ralph is a legacy/explicit alternate execution loop only; do not advertise any legacy alternate loop as the default Autopilot path. ## Use when - User wants hands-off execution from a concrete idea, issue, PRD, or requirements artifact to reviewed and QA-checked code. - User says "autopilot", "auto pilot", "autonomous", "build me", "create me", "make me", "full auto", "handle it all", or "I want a/an…". - Task needs clarification, planning, durable execution, verification, code review, and QA with automatic follow-up when gates are not clean. ## Do not use when - User wants to explore options or brainstorm — invoke the `plan` / `ralplan` skill. - User says "just explain", "draft only", or "what would you suggest" — respond conversationally. - User wants a single focused code change — invoke `ultragoal` directly, or do focused executor work. - User wants only review/critique of existing code — invoke `code-review`. ## Strict loop contract Autopilot must not run a separate broad expansion/planning/execution/QA/validation lifecycle as its primary behavior. It delegates those concerns to the canonical workflow phases below. Represent progress with the **task list** (TaskCreate/TaskUpdate/TaskList), and persist durable artifacts under `.omw/autopilot//`. Do not invent a separate execution framework. 1. **Phase `deep-interview`** — Socratic requirements clarification gate - Invoke the `deep-interview` skill (`skill: deep-interview`) to clarify intent, scope, non-goals, constraints, and decision boundaries. - Deep-interview is a structured question chain, not a one-question gate; treat the round cap as a ceiling, not a target. - After the user answers, re-score ambiguity against the active profile threshold. Ask another question only when a readiness gate is still unresolved and the answer would materially change execution; otherwise crystallize the spec and hand off. - Required handoff artifact: a clarified spec or concise requirements summary suitable for `ralplan`, including an explicit interview-complete rationale when leaving deep-interview. 2. **Phase `ralplan`** — consensus planning gate - Ground the task with pre-context intake and the deep-interview artifact. - Current ownership rule: Autopilot records `planning_routing` in state before heavy planning. When the main session resolves to a cheap/mini model lane (for example a `*-mini`, `*spark*`, or explicitly cheap/economy/lite model name), the initial planning/decomposition owner is a dedicated `[planner]` role (spawn a planner Agent); otherwise `[main]` may keep ownership for backward compatibility. A configured `agentModels.planner` is an explicit opt-in that forces dedicated `[planner]` ownership even when `[main]` is not cheap/mini. - Invoke the `ralplan` skill (`skill: ralplan`) to produce/update PRD and test-spec artifacts. If `planning_routing.owner` is `planner`, use a dedicated `[planner]` Agent for the initial Planner draft/decomposition before the Architect→Critic consensus gates. - PRD/test-spec files alone are not completion evidence. Ralplan may hand off only after durable consensus evidence records a subsequent `architect` approval first and a subsequent `critic` approval second. - When returning from a non-clean review or QA pass, include `return_to_ralplan_reason` and the findings as first-class planning input. - If either review is missing, blocked, out of order, or non-approving, remain in `ralplan` or report an explicit blocker/max-iteration outcome; do not progress to `ultragoal`, `team`, or implementation. - Required handoff artifact: an approved plan/test spec plus `ralplan_consensus_gate` evidence suitable for `ultragoal`. 3. **Phase `ultragoal`** — durable implementation + verification loop - Invoke the `ultragoal` skill (`skill: ultragoal`) from the approved ralplan artifacts. - Ultragoal owns implementation, tests, build/lint/typecheck evidence, cleanup, and final review gate discipline. Persist progress in `.omw/autopilot//ledger.jsonl`. - Use `team` only inside an active Ultragoal story when the story clearly benefits from coordinated parallel execution (for example independent file/module lanes, broad test matrix work, or multi-domain implementation). Team remains explicit and leader-owned; Ultragoal keeps the goal/ledger state. - Required handoff artifact: implementation evidence, changed-file summary, verification evidence, and ledger/checkpoint references suitable for `code-review`. 4. **Phase `code-review`** — merge-readiness gate - Invoke the `code-review` skill (`skill: code-review`) on the diff/artifacts produced by `ultragoal`. - A clean review means final recommendation `APPROVE` with architectural status `CLEAR`. - `COMMENT`, `REQUEST CHANGES`, any architectural `WATCH`/`BLOCK`, or any unresolved finding is not clean. - If not clean because the implementation must be repaired, increment the review cycle, set `current_phase:"rework"`, and carry the findings as the sanctioned execution-fix input. Return to Phase `ralplan` only when the review shows the plan/requirements are wrong or incomplete. 5. **Phase `ultraqa`** — adversarial QA gate - Invoke the `ultraqa` skill (`skill: ultraqa`) after a clean code review when user-facing behavior, workflows, CLI/runtime behavior, integration surfaces, or regression risk warrant adversarial QA. - For docs-only or trivially non-runtime changes, record `ultraqa` as skipped with an explicit condition and evidence. - If UltraQA finds issues, set `return_to_ralplan_reason`, and transition back to Phase `ralplan`. The only normal terminal state is `complete` after clean code review and a passed or explicitly skipped UltraQA gate. Cancellation, blocked credentials, unrecoverable repeated failures, or explicit user stop may terminate earlier with preserved state. ## Pre-context intake Before Phase `deep-interview` or `ralplan` starts or resumes: 1. Derive a task slug from the request. 2. Reuse the latest relevant `.omw/autopilot//context.md` snapshot when available. 3. If none exists, create `.omw/autopilot//context.md` (UTC `YYYYMMDDTHHMMSSZ`) with: - activation prompt / task seed - original task status (`activation-prompt`, `legacy-unverified`, or `unavailable`) - desired outcome - known facts/evidence - constraints - unknowns/open questions - likely codebase touchpoints - a scope note that the seed is the Autopilot activation prompt, not guaranteed prior conversation context 4. If brownfield facts are missing, run normal repo inspection (Read, Grep, Glob, read-only Bash) before or during `deep-interview`; do not skip the clarification gate merely because the task sounds actionable. 5. Carry the snapshot path in the task list and all handoff artifacts. ## Execution policy - Always execute the recommended phases in order: `deep-interview`, then `ralplan`, then `ultragoal`, then `code-review`, then `ultraqa`. - `team` is conditional and explicit: use it only within an Ultragoal story when parallel execution materially improves throughput, quality, or safety. - Never skip directly from vague/freeform expansion to implementation; unclear input must be clarified and planned through `deep-interview` and `ralplan`. - A non-clean `code-review` that requires implementation repair enters Phase `rework`; a non-clean review that changes the plan/requirements, or failed `ultraqa`, returns to `ralplan`. - Each phase must write/update Autopilot state (task list + sidecar) before handing off. - Use existing skills and Workflow tools (`deep-interview`, `ralplan`, `ultragoal`, optional `team`, `code-review`, `ultraqa`); do not invent a separate execution framework. - Preserve legacy compatibility: if a user explicitly requests the old Ralph execution lane, use the `ralph` skill as an intentional alternate execution phase, but do not present it as Autopilot's default recommended loop. - Continue automatically through safe reversible phase transitions. Ask only for destructive, credential-gated, or materially preference-dependent branches. - Apply the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step execution, local overrides for the active workflow branch, validation proportional to risk, explicit stop rules, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches. ## State management (task list + sidecar, not `omx`) There is no `omx` binary in WorkBuddy. Represent Autopilot lifecycle state with the **task list** and a small JSON sidecar at `.omw/autopilot//state.json`. State must be session-aware when a session id exists. If a richer MCP state surface becomes available later, equivalent tool calls remain acceptable but are not required. Inside active Autopilot, named child phases such as `ralplan` are supervised phases, not peer workflow activations: keep `mode:"autopilot"` active and update `current_phase:"ralplan"` rather than starting a standalone `mode:"ralplan"` over Autopilot. Required fields: ```json { "mode": "autopilot", "active": true, "current_phase": "deep-interview", "iteration": 1, "review_cycle": 0, "max_iterations": 10, "phase_cycle": ["deep-interview", "ralplan", "ultragoal", "code-review", "ultraqa"], "handoff_artifacts": { "context_snapshot_path": ".omw/autopilot//context.md", "deep_interview": null, "ralplan": null, "ralplan_consensus_gate": { "required": true, "sequence": ["architect-review", "critic-review"], "planning_artifacts_are_not_consensus": true, "required_review_roles": ["architect", "critic"], "ralplan_architect_review": null, "ralplan_critic_review": null, "complete": false }, "ultragoal": null, "code_review": null, "ultraqa": null }, "review_verdict": null, "qa_verdict": null, "return_to_ralplan_reason": null } ``` - **On start**: create tasks for each phase; write `state.json` with `mode:"autopilot"`, `active:true`, `current_phase:"deep-interview"`, `iteration:1`, `review_cycle:0`, `phase_cycle:[...]`, and empty handoff slots. - **On deep-interview -> ralplan**: only after a gate proves the interview chain is explicitly complete or the user authorized a skip. Persist `deep_interview_gate:{status:"complete", rationale:"", handoff_summary:""}` (or equivalent non-empty rationale/summary) plus the clarified spec under `handoff_artifacts.deep_interview`. If a final question was involved, keep its same-session answered record linked by `question_id`/`satisfied_at`. For skip, persist `deep_interview_gate:{status:"skipped", skip_authorized_by_user:true, skip_reason:"", skipped_at:"", source:"user"}`. Do not leave deep-interview merely because the first question was answered or cleared. - **Optional execution contract foundation**: when a downstream handoff explicitly sets `execution_contract_required:true`, persist a complete structured `execution_contract` under `handoff_artifacts.deep_interview` before leaving deep-interview. The canonical schema is `version:1`, `execution_stride:"task"|"deliverable"|"milestone"`, `source:"deep-interview"`, `selected_by:"user"|"default"`, `allow_task_shrink:`, non-empty `completion_unit`, non-empty `stop_condition`, `acceptance_coverage_scope:"task"|"deliverable"|"milestone"`, and `shrink_policy:"allowed"|"ask_before_shrink"|"deny_unless_blocked"`. - Stride semantics are binding only when `execution_contract_required:true`: `task` means `allow_task_shrink:true`, `acceptance_coverage_scope:"task"`, `shrink_policy:"allowed"`; `deliverable` means `allow_task_shrink:false`, `acceptance_coverage_scope:"deliverable"`, `shrink_policy:"ask_before_shrink"`; `milestone` means `allow_task_shrink:false`, `acceptance_coverage_scope:"milestone"`, `shrink_policy:"deny_unless_blocked"`. - Preserve legacy behavior when `execution_contract_required` is absent or false. Do not infer stride from prose, broadness, phase names, snapshots, or task size; this foundation only validates an explicit structured contract and deliberately uses `milestone` rather than `phase`. New artifacts must write canonical snake_case keys under `handoff_artifacts.deep_interview`; any runtime may read legacy camelCase field/marker aliases and direct/nested `execution_contract` locations only as compatibility input. - **On ralplan -> ultragoal**: only after `ralplan_consensus_gate.complete:true`, with a recorded `ralplan_architect_review.agent_role:"architect"` and `ralplan_architect_review.verdict:"approve"` recorded before a `ralplan_critic_review.agent_role:"critic"` and `ralplan_critic_review.verdict:"approve"`. Set `current_phase:"ultragoal"` and persist the plan/test-spec paths under `handoff_artifacts.ralplan`. - **On missing ralplan consensus evidence**: keep `current_phase:"ralplan"`, persist `ralplan_consensus_gate.complete:false` with `blocked_reason`, and report an explicit blocker or max-iteration outcome instead of handing off to execution. - **On ultragoal -> code-review**: set `current_phase:"code-review"`, persist implementation/test/ledger evidence under `handoff_artifacts.ultragoal`. - **On code-review -> ultraqa**: set `current_phase:"ultraqa"` only after a real `code-review` pass produced durable evidence; persist the clean review under `handoff_artifacts.code_review` with its source thread/skill/stage reference. Do not author `review_verdict:{clean:true}` from the leader's own summary. - **On non-clean code-review requiring implementation repair**: increment `review_cycle`, set `current_phase:"rework"`, persist `review_verdict`, persist the phase handoff under `handoff_artifacts.code_review`, and keep the fix scoped to the review findings before returning to `code-review`. - **On clean review + passed/skipped QA**: set `active:false`, `current_phase:"complete"`, persist `review_verdict:{recommendation:"APPROVE", architectural_status:"CLEAR", clean:true}`, `qa_verdict:{clean:true, skipped:, reason:}`, and `completed_at` only when both gates have durable source evidence. Required evidence is either (a) actual `code-review`/`ultraqa` skill passes or agent/thread/tool records, or (b) for QA only, an explicit persisted skip reason for a documented docs-only/trivially non-runtime condition. If that evidence is missing, keep the active phase at `code-review` or `ultraqa` and record a blocker instead of self-attesting a clean gate. - **On non-clean review requiring plan changes or failed QA**: increment `iteration` and `review_cycle`, set `current_phase:"ralplan"`, persist `review_verdict` or `qa_verdict`, persist the phase handoff, and set `return_to_ralplan_reason` to a concise findings-driven reason. - **Legacy Ralph state**: if a user explicitly selected the legacy Ralph execution lane, phase names and handoff keys may include `ralph`; preserve and resume them rather than rewriting history to Ultragoal. - **On cancellation**: run the `cancel` skill; preserve progress for resume rather than deleting handoff artifacts. ## Continuation and resume When the user says `continue`, `resume`, or `keep going` while Autopilot is active, read `.omw/autopilot//state.json` and continue from `current_phase`: - `deep-interview`: clarify requirements and record the handoff artifact. - `ralplan`: run/update consensus planning from current handoffs and any `return_to_ralplan_reason`. - `ultragoal`: execute the approved plan durably and record verification/ledger evidence. - `rework`: perform only the implementation fixes required by the current code-review findings, record fresh implementation/verification evidence, and return to `code-review`. - `team`: continue explicit team work only when it is nested under the active Ultragoal story and report evidence back to the leader. - `code-review`: review the current diff and decide clean vs return-to-ralplan. - `ultraqa`: run or explicitly skip adversarial QA based on the documented condition, then finish if clean or transition to `ralplan` with findings if not clean. - `ralph`: resume only for explicit legacy Ralph-path Autopilot state. - `complete`: report completion evidence; do not restart. Do not restart discovery or discard handoff artifacts on continuation. ## Pipeline orchestrator Autopilot may be represented by a configurable pipeline orchestrator when useful. The default Autopilot pipeline contract is: ```text deep-interview -> ralplan -> ultragoal -> code-review -> ultraqa ``` Pipeline state should use `current_phase` values that match the same phase names (`deep-interview`, `ralplan`, `ultragoal`, `rework`, `code-review`, `ultraqa`, `complete`, `failed`) and should carry `iteration`, `review_cycle`, `handoff_artifacts`, `review_verdict`, `qa_verdict`, and `return_to_ralplan_reason` alongside stage results. `team` is not a default pipeline stage; it is an explicit conditional execution engine inside an Ultragoal story. ## Escalation and stop conditions - Stop and report a blocker when required credentials/authority are missing. - Stop and report when the same review or QA failure recurs across 3 review cycles with no meaningful new plan. - Stop when the user says "stop", "cancel", or "abort" and run the `cancel` skill. - Otherwise, continue the loop until `code-review` is clean and `ultraqa` has passed or been explicitly skipped with evidence. ## Final checklist - [ ] Phase `deep-interview` produced/updated clarified requirements or a concise spec - [ ] Phase `ralplan` produced/updated approved planning artifacts and durable sequential evidence from a subsequent `architect` approval followed by a subsequent `critic` approval - [ ] Phase `ultragoal` implemented and verified the plan with fresh evidence and durable ledger/checkpoint references - [ ] Phase `rework` was used for implementation-only review fixes when applicable, with findings scoped to a fresh code-review cycle - [ ] `team` was used only if the active Ultragoal story needed coordinated parallel work, or explicitly recorded as not needed - [ ] Phase `code-review` returned a clean verdict (`APPROVE` + `CLEAR`) - [ ] Phase `ultraqa` passed, or was explicitly skipped because the change was docs-only/trivially non-runtime with evidence - [ ] Clean `review_verdict` cites durable source evidence from a real `code-review` pass; `qa_verdict` cites durable `ultraqa` evidence or an explicit persisted low-risk skip reason; leader-authored summaries alone are not gate evidence - [ ] `review_verdict.clean` is true, `qa_verdict.clean` is true, and `return_to_ralplan_reason` is null - [ ] Tests/build/lint/typecheck evidence from Ultragoal is available in handoff artifacts - [ ] Autopilot state is marked `complete` or cancellation state is preserved coherently - [ ] User receives a concise summary with clarification, plan, implementation, verification, review, and QA evidence ## Examples **Good:** User: `autopilot implement GitHub issue #42` Flow: create/load context snapshot -> `deep-interview` requirements check -> `ralplan` issue plan -> `ultragoal` durable implementation + tests (launch `team` only if a story needs parallel lanes) -> `code-review` -> `ultraqa`; if review or QA requests changes, return to `ralplan` with findings. **Good:** User: `continue`, state says `current_phase:"code-review"`. Flow: run `code-review` on current diff, persist verdict, transition to `ultraqa` if clean or to `ralplan` with findings if not clean. **Good:** User: `autopilot --legacy-ralph finish the migration` Flow: preserve the explicit legacy Ralph execution choice and run the old Ralph execution lane as an alternate, without changing the documented default Autopilot recommendation. **Bad:** Autopilot invents independent "Expansion", "QA", and "Validation" phases and treats them as the primary lifecycle. Why bad: this bypasses the strict `deep-interview -> ralplan -> ultragoal -> code-review -> ultraqa` contract.