/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
tags: [phase-c, autopilot, autonomous, loop]
model: sonnet

Autopilot Skill

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 § Phase 3.7`.

Purpose

Autopilot collapses the per-session attention cost when Mode-Selector is confident enough to make routine decisions autonomously. A productive day commonly ships 3–7 sessions; each manual session-start costs the user 10–60 seconds of context-switch attention. When the session is genuinely routine (mechanical refactor, post-merge housekeeping, repeated follow-ups from a planned epic), that attention cost is pure overhead.

`/autopilot` reads the Mode-Selector recommendation, executes the recommended session if confidence clears the threshold, then loops — checking kill-switches between iterations. The user invokes the loop once and walks away; autopilot stops itself when work runs out or quality degrades.

This is **opt-in by design**: autopilot never starts itself. The user must run `/autopilot` explicitly. Configuration thresholds (`--max-sessions`, `--max-hours`, `--confidence-threshold`) are CLI flags, not Session Config defaults — the user signals intent for THIS run, not a standing policy.

Command Surface

/autopilot [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]

| Flag | Default | Bounds | Meaning | |------|---------|--------|---------| | `--max-sessions` | `5` | 1..50 | Iteration cap (graceful exit when reached) | | `--max-hours` | `4.0` | 0.5..24.0 | Wall-clock budget for entire loop | | `--confidence-threshold` | `0.85` | 0.0..1.0 | Minimum `selectMode` confidence for auto-execute | | `--dry-run` | `false` | — | Print planned iterations without executing |

Out-of-range values silently clamp to bounds. `--dry-run` exits after printing — never invokes session lifecycle.

Loop Semantics

state := { iterations_completed: 0, started_at: now(), kill_switch: null, sessions: [] }

WHILE state.iterations_completed < max-sessions:
  # Pre-iteration kill-switches (6)
  IF aborted: kill_switch := 'user-abort'; break
  IF state.iterations_completed >= max-sessions:
    kill_switch := 'max-sessions-reached'; break
  IF (now() - state.started_at) > max-hours:
    kill_switch := 'max-hours-exceeded'; break
  IF cumulative_tokens_used >= max-tokens:
    kill_switch := 'token-budget-exceeded'; break
  IF resource_verdict() == 'critical' AND peer_count() > autopilot-peer-abort:
    kill_switch := 'resource-overload'; break

  recommendation := mode-selector.selectMode(<live signals from session-start Phase 7.5>)

  IF recommendation.confidence < confidence-threshold:
    IF state.iterations_completed == 0:
      fallback_to_manual()  # iteration 1: hand off cleanly to manual /session flow
    ELSE:
      kill_switch := 'low-confidence-fallback'  # iteration 2+: exit, let user decide
    break

  cap