---
name: autopilot
description: Full autonomous execution from idea to working code
---

<Purpose>
Autopilot takes a brief product idea and autonomously handles the full lifecycle: requirements analysis, technical design, planning, parallel implementation, QA cycling, and multi-perspective validation. It produces working, verified code from a 2-3 line description.
</Purpose>

<Use_When>
- User wants end-to-end autonomous execution from an idea to working code
- User says "autopilot", "auto pilot", "autonomous", "build me", "create me", "make me", "full auto", "handle it all", or "I want a/an..."
- Task requires multiple phases: planning, coding, testing, and validation
- User wants hands-off execution and is willing to let the system run to completion
</Use_When>

<Do_Not_Use_When>
- User wants to explore options or brainstorm -- use `plan` skill instead
- User says "just explain", "draft only", or "what would you suggest" -- respond conversationally
- User wants a single focused code change -- use `ralph` or delegate to an executor agent
- User wants to review or critique an existing plan -- use `plan --review`
- Task is a quick fix or small bug -- use direct executor delegation
</Do_Not_Use_When>

<Why_This_Exists>
Most non-trivial software tasks require coordinated phases: understanding requirements, designing a solution, implementing in parallel, testing, and validating quality. Autopilot orchestrates all of these phases automatically so the user can describe what they want and receive working code without managing each step.
</Why_This_Exists>

<Execution_Policy>
- Each phase must complete before the next begins
- Default to the lightest mode that can finish the task; do not expand into a heavy workflow unless the task truly needs multiple phases
- Parallel execution is used only for independent workstreams with clear ownership (Phase 2 and Phase 4)
- QA cycles repeat up to 5 times; if the same error persists 3 times, stop and report the fundamental issue
- Validation requires approval from all reviewers; rejected items get fixed and re-validated
- Cancel with `/cancel` at any time; progress is preserved for resume
- If a deep-interview spec exists, use it as high-clarity phase input instead of re-expanding from scratch
- If input is too vague for reliable expansion, offer/trigger `$deep-interview` first
- Do not enter expansion/planning/execution-heavy phases until pre-context grounding exists; if fast execution is forced, proceed only with explicit risk notes
- Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail
- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints
- If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the workflow is grounded
- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent
- After compaction or resume, continue from the latest checkpoint and newest user message; do not restart discovery unless the checkpoint is missing or contradicted
- If the same diagnosis appears twice, make the next smallest safe fix or report the exact blocker; do not repeat the same investigation loop
- State MCP tools are helpful but optional; if an OMX MCP call fails, write a local checkpoint and continue instead of blocking
- Before changing code, define boundaries: files/behaviors that must not break, destructive commands that are forbidden, and the rollback point
- Every phase must have a gate: required artifact, owner, next action, and verification command; do not advance on vague outputs
- Prefer task-by-task execution with fresh context from checkpoint artifacts instead of relying on the full conversation history
</Execution_Policy>

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

<Steps>
0. **Pre-context Intake (required before Phase 0 starts)**:
   - Derive a task slug from the request.
   - Load the latest relevant snapshot from `.omx/context/{slug}-*.md` when available.
   - If this is a resumed or compacted conversation, read the newest local checkpoint before opening new files.
   - If no snapshot exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
     - Task statement
     - Desired outcome
     - Known facts/evidence
     - Constraints
     - Unknowns/open questions
     - Likely codebase touchpoints
     - Current phase
     - Next concrete action
     - Validation command
   - Create or update `.omx/autopilot/{slug}/survival-guide.md` with only the context needed after compaction.
   - Create or update `.omx/autopilot/{slug}/boundaries.md` before code edits when the task is broad, risky, or production-facing.
   - If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` before proceeding.
   - Carry the snapshot path into autopilot artifacts/state so all phases share grounded context.
   - Keep the checkpoint short enough to read quickly in a new session.

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, and validation strategy

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`
   - Mark independent work with `[P]` and explicit verification work with `[VERIFY]`
   - Gate: every task has a verification command or evidence target

3. **Phase 2 - Execution**: Implement the plan using Ralph + Ultrawork
   - 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 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**: Cycle until all tests pass (UltraQA mode)
   - Build, lint, test, fix failures
   - 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
   - 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

5. **Phase 4 - Validation**: Multi-perspective review in parallel
   - 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
   - All must approve; fix and re-validate on rejection

6. **Phase 5 - Cleanup**: Clear all mode state via OMX MCP tools on successful completion
   - `state_clear({mode: "autopilot"})`
   - `state_clear({mode: "ralph"})`
   - `state_clear({mode: "ultrawork"})`
   - `state_clear({mode: "ultraqa"})`
   - Or run `/cancel` for clean exit
</Steps>

<Tool_Usage>
- Use available MCP tools directly when present; do not block on discovery tooling that is unavailable in the current runtime
- Use `ask_codex` with `agent_role: "architect"` for Phase 4 architecture validation
- Use `ask_codex` with `agent_role: "security-reviewer"` for Phase 4 security review
- Use `ask_codex` with `agent_role: "code-reviewer"` for Phase 4 quality review
- Agents form their own analysis first, then consult Codex for cross-validation
- If ToolSearch finds no MCP tools or Codex is unavailable, proceed without it -- never block on external tools
</Tool_Usage>

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

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

<Examples>
<Good>
User: "autopilot A REST API for a bookstore inventory with CRUD operations using TypeScript"
Why good: Specific domain (bookstore), clear features (CRUD), technology constraint (TypeScript). Autopilot has enough context to expand into a full spec.
</Good>

<Good>
User: "build me a CLI tool that tracks daily habits with streak counting"
Why good: Clear product concept with a specific feature. The "build me" trigger activates autopilot.
</Good>

<Bad>
User: "fix the bug in the login page"
Why bad: This is a single focused fix, not a multi-phase project. Use direct executor delegation or ralph instead.
</Bad>

<Bad>
User: "what are some good approaches for adding caching?"
Why bad: This is an exploration/brainstorming request. Respond conversationally or use the plan skill.
</Bad>
</Examples>

<Escalation_And_Stop_Conditions>
- Stop and report when the same QA error persists across 3 cycles (fundamental issue requiring human input)
- Stop and report when validation keeps failing after 3 re-validation rounds
- Stop when the user says "stop", "cancel", or "abort"
- If requirements were too vague and expansion produces an unclear spec, pause and redirect to `$deep-interview` before proceeding
</Escalation_And_Stop_Conditions>

<Final_Checklist>
- [ ] All 5 phases completed (Expansion, Planning, Execution, QA, Validation)
- [ ] All validators approved in Phase 4
- [ ] Tests pass (verified with fresh test run output)
- [ ] Build succeeds (verified with fresh build output)
- [ ] State files cleaned up
- [ ] User informed of completion with summary of what was built
</Final_Checklist>

<Advanced>
## Configuration

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

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

```toml
[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.
</Advanced>
