/autopilot

name: autopilot
description: >
  Use this skill when running an autonomous session-orchestration loop. Chains session-start → session-plan →
  wave-executor → session-end for N iterations with all 10 kill-switches (SPIRAL, FAILED
  wave, carryover > 50%, max-hours, max-sessions, resource-overload, token-budget,
  stall-timeout, sub-threshold confidence, user-abort). Reads Mode-Selector
  output (Phase B) to decide auto-execute vs. fallback. Writes one autopilot.jsonl
  record per loop run. Phase C scaffold (issue #277); implementation lives in
  scripts/lib/autopilot.mjs (Phase C-1 follow-up).
user-invocable: true
argument-hint: "[--headless] [--verbose] [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]"
tags: [phase-c, autopilot, autonomous, loop]
model: sonnet

Autopilot Skill

Invocation

The user invokes `/autopilot` with arguments: **$ARGUMENTS**. This is autonomous session-orchestration mode — a top-level invocation only, never from inside a running session.

Parse `$ARGUMENTS` before anything else. Unrecognized flags are ignored; out-of-range values silently clamp to bounds. Use `parseFlags` from `scripts/lib/autopilot.mjs` for canonical parsing — never re-implement clamping inline. The loop flags (`--max-sessions`, `--max-hours`, `--confidence-threshold`, `--dry-run`) and their defaults/bounds are tabled once in § Command Surface below. Two further flags belong to the invocation surface only:

| Flag | Default | Meaning | |------|---------|---------| | `--headless` | `false` | Run via the standalone driver `scripts/autopilot.mjs`, which spawns `claude -p '/session <mode>'` as a child process per iteration. Required for unattended walk-away mode. Without it, `/autopilot` runs the in-process driver inside the current chat session (see § Production Wiring). | | `--verbose` | `false` | Verbose driver output. |

Headless (`claude -p`)

Headless requirements:

• Anthropic API key configured for `claude -p` (Claude Code CLI auth).
• `scripts/autopilot.mjs` starts each child with `--session-id <fresh uuid>` and, after it

exits, reads the one canonical `sessions.jsonl` record whose `raw_session_id` is that uuid to construct the `sessionRunner` return shape — the spawned session must complete cleanly and append its record (session-end Phase 3.7 handles this). No such record, or more than one, stops the loop with `failed-wave` instead of reading the ledger tail (#1457). So does a unique record that is only a backfill stub (no waves/agents/token totals — the child never closed): its token usage is unknown, not 0, so it is never counted as a healthy 0-token iteration (#1457 F2).

• `AUTOPILOT_RUN_ID` env var is set in the child's env, but **nothing reads it yet**

(measured 2026-10-01: `rg -n "AUTOPILOT_RUN_ID" scripts hooks skills` finds only the writer in `scripts/autopilot.mjs` and this line). CLI-driven iterations therefore carry no `autopilot_run_id` on their `sessions.jsonl` record yet; join them to `autopilot.jsonl` via the `sessions` list there, not via that field.

Do NOT re-implement loop logic inline — this skill and `scripts/lib/autopilot.mjs` are authoritative. Kill-switches are enforced by `scripts/lib/autopilot.mjs`, not inline by Claude. The runtime writes ONE record to `.orchestrator/metrics/autopilot.jsonl` per invocation via atomic tmp+rename; no other code path appends to that file.

Phase 0.5: Parallel-Aware Preamble

> Skip silently when `persistence: false` in Session Config.

Before any Phase 1 work, run the parallel-aware preamble per `skills/_shared/parallel-aware-preamble.md`. The preamble detects other active sessions in the worktree-family via `findPeers(repoRoot, { mySessionId })`, classifies the caller's mode via `classifyMode(callerMode)` against the exclusivity-matrix, and either:

• Returns `PASS_THROUGH` (no other session / `always-ok` mode) → continue to Phase 1
• Returns `EXCLUSIVE_BLOCKED` → fires Exclusive-Conflict AUQ from `skills/_shared/parallel-aware-auq.md`
• Returns `PROMOTION_OFFER` → fires Worktree-Promotion AUQ (via `enterWorktree()` from `scripts/lib/autopilot/worktree-pipeline.mjs` — see `parallel-aware-auq.md` outcome-handling)

On any non-PASS_THROUGH outcome that does not result in immediate exit, append a Deviation to STATE.md via `appendDeviationOnDisk(repoRoot, isoTimestamp, message)` from `scripts/lib/state-md.mjs`.

**Implementation reference:** `skills/_shared/parallel-aware-preamble.md § Implementation`. **AUQ reference:** `skills/_shared/parallel-aware-auq.md`.

Status

**Phase C-1.b complete (2026-04-25, issues #295 + #300).** Runtime at `scripts/lib/autopilot/kill-switches.mjs:18-32` (the frozen `KILL_SWITCHES` enum is SSOT) enforces all 10 kill-switches:

• **Pre-iteration (6, #295 + #355):** `max-sessions-reached`, `max-hours-exceeded`,

`resource-overload`, `low-confidence-fallback` (with iter-1-fallback / iter-2+-exit asymmetry), `user-abort`, `token-budget-exceeded` (cumulative tokens ≥ `--max-tokens`).

• **Post-iteration (1, ADR-364 §3):** `stall-timeout` — no progress marker in

`autopilot.jsonl` within the threshold (default 600s; missing file → no kill).

• **Post-session (3, #300):** `spiral`, `failed-wave`, `carryover-too-high`.

Read schema-canonical fields off the `sessionRunner` return shape: `agent_summary.{spiral, failed}` (numeric counts) and `effectiveness.{carryover, planned_issues}`. Absent fields → no kill (forward-compatible: a `sessionRunner` that does not yet emit those fields silently no-ops the post-session gates).

Atomic `autopilot.jsonl` writer (tmp+rename, schema_version 1) and silent-clamp `parseFlags` shipped in C-1. `autopilot_run_id` is passed into `sessionRunner` via `args.autopilotRunId`; production callers MUST persist it into the per-iteration `sessions.jsonl` record (additive optional field, schema_version 1 compatible). See `skills/wave-executor/SKILL.md § Return Shape Contract` and `skills/session-end/SKILL.md