Autopilot

Select a configured profile only with /autopilot --workflow <name> <task>. A profile is an autopilot-owned stage schedule, not a command, mode, plugin, filename, or separate state identity. Without --workflow, autopilot retains its legacy lifecycle and behavior.

Named workflow profiles require Linux with the flock utility in v1 because their transcript evidence boundary uses Linux no-follow file-descriptor traversal and their recoverable mutation lock uses kernel advisory locking. Unsupported environments reject explicit --workflow activation before state mutation; use legacy autopilot instead.

Profiles are configured in project or user JSONC as autopilot.workflows.<slug>. Every v1 profile has exactly version: 1 and stages; no other profile keys are accepted. The only admitted stage sequences are:

{
  "autopilot": {
    "workflows": {
      "plan-build-qa": {
        "version": 1,
        "stages": ["ralplan", "execution", "qa"]
      }
    }
  }
}

[ralplan, execution]
[ralplan, execution, ralph]
[ralplan, execution, qa]
[ralplan, execution, ralph, qa]

ralplan creates the plan consumed by execution; execution creates the implemented workspace required by ralph and qa. Thus omitted or reordered prerequisites, duplicate stages, and non-built-in stages are invalid. Profile names use ^[a-z][a-z0-9-]{0,62}$, are validated metadata only, and cannot collide with built-in stages, autopilot/mode names, or deprecated aliases.

User and project configuration sources are each validated before composition. Different names coexist; a project profile with the same name replaces the complete user profile rather than deep-merging it. Environment configuration cannot define or replace profiles.

On successful selection, autopilot atomically creates its existing session-scoped state with an immutable normalized descriptor and selected-only pipeline tracking. The descriptor contains the workflow name, profile version, canonical stages, and a deterministic SHA-256 profile hash; it excludes task text and mutable progress. Resume and Stop verify that hash and refuse a mismatch without reloading configuration or emitting a stage prompt. Cancel, resume, cleanup, state inspection, HUD, and Stop continuation remain owned by autopilot.

The installed plugin and standalone-installed Stop hooks advance only after an authorized assistant completion record for the active stage appears after that stage's persisted activation transcript boundary. They bind evidence to the owner session and bounded, non-symlink transcript; reject user/tool/local-command output and stale or wrong-stage evidence; and use compare-before-write tracking updates so duplicate or concurrent Stop events advance exactly once. Public state, HUD, and Stop output show only safe workflow metadata and progress, never the task, descriptor internals, transcript references, offsets, or record hashes.

V1 deferrals

V1 does not support stageModels, model routing, provider or role selection; inline/no-spawn execution; dynamic commands, modes, or state files; arbitrary stages, prompts, plugins, branches, loops, DAGs, or callbacks; or environment-defined profile definitions. The separate custom-skill inline-array frontmatter parser mismatch is also deferred.

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

   • If ralplan consensus plan exists: Skip — already done in the 3-stage pipeline
   • Architect (Opus): Create plan (direct mode, no interview)
   • Critic (Opus): Validate plan
   • Output: .omc/plans/autopilot-impl.md

3. Phase 2 - Execution: Implement the plan using executor agents with Ralph persistence when needed

   • Executor (Haiku): Simple tasks
   • Executor (Sonnet): Standard tasks
   • Executor (Opus): Complex tasks
   • Run independent tasks in parallel

4. Phase 3 - QA: Cycle until all tests pass

   • Build, lint, test, fix failures
   • Repeat up to 5 cycles
   • Stop early if the same error repeats 3 times (indicates a fundamental issue)

5. Phase 4 - Validation: Multi-perspective review in parallel

   • Architect: Functional completeness
   • Security-reviewer: Vulnerability check
   • Code-reviewer: Quality review
   • All must approve; fix and re-validate on rejection

6. Phase 5 - Cleanup: Delete all state files on successful completion

   • Remove .omc/state/autopilot-state.json, ralph-state.json (plus stale retired ultraqa-state.json/ultrawork-state.json if legacy copies exist)
   • Run /oh-my-claudecode:cancel for clean exit

Parallel session caveats

• Multi-repo workspace anchor: drop a .omc-workspace marker at the parent directory so multiple sessions across sub-repos share one .omc/. Resolution order: OMC_STATE_DIR > .omc-workspace > git > cwd. See docs/REFERENCE.md.
• Session id source: OMC_SESSION_ID env var wins in CLI contexts; hook payload data.session_id wins in hook contexts.
• Plan id (when applicable): Autopilot state is session-scoped. Two autopilots in the same workspace require distinct session IDs.
• Parallel verdict: supported (session-scoped state)

Optional settings in .claude/omc.jsonc (project) or ~/.config/claude-omc/config.jsonc (user):

{
  "autopilot": {
    "maxIterations": 10,
    "maxQaCycles": 5,
    "maxValidationRounds": 3,
    "pauseAfterExpansion": false,
    "pauseAfterPlanning": false,
    "skipQa": false,
    "skipValidation": false,
    "execution": "solo"
  }
}

To run autopilot implementation through the tmux CLI team runtime and prefer Cursor executor workers:

{
  "autopilot": {
    "execution": "team",
    "team": { "agentTypes": ["cursor"] }
  }
}

With that config, the execution stage must launch executor-style work through:

omc team 1:cursor "<implementation task>"

or the Claude Code slash compatibility surface:

/omc-teams 1:cursor "<implementation task>"

Limitations:

• Cursor workers support implementation and reviewer-style team roles. critic, code-reviewer, security-reviewer, and test-engineer workers must emit the structured verdict file consumed by the team leader; final approval remains a lead-session responsibility.
• Cursor requires the cursor-agent CLI to be installed and authenticated. If cursor-agent is unavailable, report that setup requirement instead of silently falling back to Claude-only execution.

Resume

If autopilot was cancelled or failed, run /oh-my-claudecode:autopilot again to resume from where it stopped.

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

Troubleshooting

Stuck in a phase? Check TODO list for blocked tasks, review .omc/autopilot-state.json, 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.

Deep Interview Integration

When autopilot is invoked with a vague input, Phase 0 can redirect to /deep-interview for Socratic clarification:

User: "autopilot build me something cool"
Autopilot: "Your request is open-ended. Would you like to run a deep interview first?"
  [Yes, interview first (Recommended)] [No, expand directly]

If a deep-interview spec already exists at .omc/specs/deep-interview-*.md, autopilot uses it directly as Phase 0 output (the spec has already been mathematically validated for clarity).

3-Stage Pipeline: deep-interview → ralplan → autopilot

The recommended full pipeline chains three quality gates:

/deep-interview "vague idea"
  → Socratic Q&A → spec (ambiguity ≤ 20%)
  → /ralplan --direct → consensus plan (Planner/Architect/Critic approved)
  → /autopilot → skips Phase 0+1, starts at Phase 2 (Execution)

When autopilot detects a ralplan consensus plan (.omc/plans/ralplan-*.md or .omc/plans/consensus-*.md), it skips both Phase 0 (Expansion) and Phase 1 (Planning) because the plan has already been:

• Requirements-validated (deep-interview ambiguity gate)
• Architecture-reviewed (ralplan Architect agent)
• Quality-checked (ralplan Critic agent)

Autopilot starts directly at Phase 2 using executor agents and Ralph persistence.