Autopilot

Autopilot — Self-driving mission runner

You receive a mission from the user and run an autonomous loop until they tell you to stop. The domain is whatever the user defines in the mission file — code self-improvement, doc grooming, research synthesis, ops sweeps, anything that benefits from a tight discover→execute→learn cadence.

This skill replaces ad-hoc loops (ralph-loop, improve-airops) with a domain-agnostic orchestrator: per-project mission, mission-bound governance, idle-aware self-pacing via ScheduleWakeup, immutable milestone trail, self-healing on interruption, and opt-in update notifications.

Boot check

First action on every invocation: locate the mission file.

• Default path: /.autopilot.log/mission.md.
• Fallbacks (legacy / migration): /.claude/autopilot/mission.md. If found, offer migration to default path on first run.
• Outside a git repo: ~/.claude/autopilot//mission.md.

Decision:

• Missing → run "Boot interview" below.
• Exists, user explicitly says "new mission" / "reset" / "redo" → back up to mission.md.bak., run interview again.
• Exists, normal call or /autopilot resume / /autopilot heal / /autopilot status → enter "Phase 0.5 — Resume + update check", then "Operating cycle".

User signals

| Signal | Effect | |---|---| | /autopilot | Auto-detect stale state, then run a cycle (or no-op if mission complete) | | /autopilot resume | Force Mode: paused → active, run a cycle | | /autopilot heal | Force interruption recovery (clean working branch, mark crashed cycle, start fresh) | | /autopilot status | Print current state from state.json + last journal entry (includes installed version line); do not run a cycle | | /autopilot version (or --version, -v) | Print installed version from frontmatter, latest available from GitHub releases (cached), source URL; do not run a cycle | | /autopilot stop / "멈춰" / "pause" | Set Mode: paused, no ScheduleWakeup | | /autopilot quick mission="X" (or /autopilot --quick) | All Q's default-pre-filled, single confirm — new in v1.3.0 | | /autopilot mission="X" risk=L2 cadence=15m ... | Args parsed into Q1–Q10 pre-fills |

---

Version display (new in v1.2.0)

/autopilot version (aliases: --version, -v) is a diagnostic-only signal. It does not run a cycle, ScheduleWakeup, or modify any file. Run order:

1. Read installed version: from this SKILL.md frontmatter.
2. Read last_update_check_at and available_version from state.json (if present).
3. If the cache is older than Q9.check interval (or missing), do one GitHub releases call (5s timeout, fail-open):

``bash curl -s --max-time 5 https://api.github.com/repos/PresentJay/autopilot-skills/releases/latest ``

Update the cache fields on success; leave them on failure.

1. Print:

``` autopilot v installed at: latest: v (checked , ) source: https://github.com/PresentJay/autopilot-skills

Update: up-to-date ```

When latest > installed (semver compare), replace the last line with:

`` Update: v → v — npx skills update PresentJay/autopilot-skills ``

When the cache is missing AND the live call failed, print latest: unknown (offline) and Update: check skipped.

1. Exit. Do not append to journal, do not bump heartbeat, do not call ScheduleWakeup.

/autopilot status reuses step 1 and step 4's first line so the installed version appears at the top of its diagnosis output too.

---

Boot interview (mission contract)

Goal: capture mission, scope, risk, cadence, compaction, escalation, update policy, resume policy in 10 short questions. Use AskUserQuestion, one question per turn, narrowing if the answer is unclear.

Inference from invocation args: if the user passes hints in the same turn (e.g. /autopilot mission="lint cleanup" risk=L2 cadence=15m), parse key=value pairs and pre-fill matching answers. Show the pre-filled draft once and offer:

1. Start as-is
2. Modify a few questions (cascade to those only)
3. Re-do from scratch

Do not scan prior conversation, git history, or other artifacts. Args only. Cold start when no args given.

Quick boot (new in v1.3.0): if quick (positional) or --quick is in the args, all Q's default to safe values (Q2=continuous, Q3=default, Q4=default, Q5=L2, Q6=15m, Q7=defaults, Q8=auto-suggest@80, Q9=every-24h prompt, Q10=2x auto-resume). Q1 still required (from mission="X" arg or one prompt). Single summary, single confirm — total one turn boot. Use this when the user already knows what they want and asked you to "just go".

Q1. Mission (one line)

What single objective is this loop pursuing? Examples to seed:

• "self-improvement of this repo (lint, coverage, dead code)"
• "post-merge cleanup for PR #123"
• "documentation tone consistency"
• "dashboard / UI polish"

Free text accepted.

Q2. Operating mode

• continuous — run until told to stop (default)
• bounded:N — at most N cycles or until completion signal
• monitor — react only to external events (CI, new PR, log line)

Q3. Allow paths

Glob patterns the loop may modify. Sensible defaults (user can prune):

• packages/, apps/, docs/, settings/, scripts/
• README.md, CONTRIBUTING.md, AGENTS.md

Anything not listed is read-only.

Q4. Forbidden zones (absolute)

Pre-checked defaults (uncheck only with reason):

• main, master, release/* branches — never push directly
• .env, *credentials*, secrets/*, *.pem, *.key
• infra/, terraform/, .github/workflows/ (unless explicitly allowed)
• destructive flags: --force, --no-verify, git reset --hard, rm -rf outside allow paths
• external API writes (only gh CLI and npm registry permitted)

Q5. Risk tier

• L1 — discover + propose only (read-only, populates a backlog/issues, no code changes)
• L2 — small PRs (≤300 lines, ≤10 files, build/test/lint must be green) — default
• L3 — merge after green (PR + auto-merge on success; main direct push still forbidden)
• L4 — free mode (large refactors, multi-PR, experiments; Q4 forbidden still absolute)

Q6. Cadence

How long after a cycle ends before the next one fires?

| Choice | Seconds | Notes | |---|---|---| | immediate | 60 (floor of ScheduleWakeup) | Most aggressive; high token cost | | 2m | 120 | Inside Anthropic prompt-cache window — efficient | | 5m | 300 | Just past cache window | | 15m | 900 | default — balanced | | 30m | 1800 | Relaxed | | 1h+ | 3600+ | Auto-promote to a cron via /schedule (cloud) | | manual | — | No auto wake; user must re-invoke |

Idle auto-throttle: 3 consecutive empty cycles bump cadence one tier up.

Q7. Escalation triggers

Pre-checked defaults:

• consecutive failures ≥ 3 → escalate
• single proposal exceeds tier diff cap → split or escalate
• no candidate found:
• end — terminate as mission complete (default)
• ask — ask user for additional discovery tools
• irreversible action (DB DDL, external API write, force push) → always escalate
• ≥5 candidates discovered outside allow paths → propose mission expansion

Q8. Compaction strategy (revised in v1.3.0)

Long-running loops bump into the prompt-too-long ceiling. The agent cannot programmatically call /compact in Claude Code, Codex, Cursor, or any current harness — /compact is a user-typed slash command. The skill therefore outputs a suggestion and relies on either the user typing /compact or, for genuinely long missions, /schedule cron promotion (each scheduled run is a fresh session — no compaction needed).

• threshold: 60 / 70 / 80 / 90 — surface advisory when token usage crosses this percent. Default 80.
• strategy:
• auto-suggest (default) — output 📦 /compact suggested (estimated ~N% used) at the end of every cycle once threshold is crossed; do not block
• cron-promote — explicitly recommend /schedule " /autopilot" so each cycle starts fresh; output the suggested cron line once
• off — silent; user accepts prompt-too-long risk

If Q6 cadence is 1h+, the skill auto-promotes to /schedule cron regardless of Q8 strategy (already in Phase 8 routing).

Q9. Update policy (new in v1.1.0)

The skill ships with a version field in its frontmatter. Newer releases on PresentJay/autopilot-skills are detected by an unauthenticated GitHub releases API call (cached for 24h in state.json.last_update_check_at).

• check: every-boot / every-24h / weekly / off — default every-24h
• on-update-available:
• notify — append a one-line notice to the cycle output (passive)
• prompt (default) — show notice and ask "update now?"; on confirm, run npx skills update PresentJay/autopilot-skills --yes via Bash, then ask user to re-invoke /autopilot
• silent-auto — run the update without asking (least recommended; only for trusted setups)

The check fails open: if GitHub API errors or times out (5s cap), skip silently and retry next interval. The skill never blocks on this check.

Q10. Resume policy (new in v1.1.0)

Controls how the skill recovers from interruptions (host sleep, session crash, missed ScheduleWakeup, mid-cycle abort).

• stale_threshold: 2x-cadence (default) / 4x-cadence / 8x-cadence — how long after next_wakeup_at to consider the loop stalled
• on_resume:
• auto-resume (default) — silently detect stale state and run a fresh cycle
• prompt-confirm — show diagnosis ("Missed N cycles. Resume?") and confirm before continuing
• manual-only — only resume on explicit /autopilot resume or /autopilot heal

Wrap

Render the proposed mission.md to the user. Wait for one explicit confirm before starting the first cycle. Save mission.md, state.json, and create .autopilot.log/ and .autopilot.milestones/ directories.

---

Phase 0.5 — Resume + update check (new in v1.1.0)

Runs once per invocation: after boot check, before Phase 1 DISCOVER. Note (v1.3.0): Phase 0.5 is meaningful only at invocation boundaries — i.e., each fresh /autopilot call (manual or via ScheduleWakeup). Multiple cycles within a single conversation turn (no wakeup boundary) is batch execution, not self-driving — Phase 0.5 fires once at the top, not between in-turn cycles. Two independent sub-checks:

Resume check

Read state.json:

status            : idle | running | interrupted | escalated | paused
last_run_at       : ISO timestamp or null
next_wakeup_at    : ISO timestamp or null
cycle_started_at  : ISO timestamp or null

Decision matrix (apply per Q10.on_resume):

| Condition | Diagnosis | Action | |---|---|---| | cycle_started_at is set AND last_run_at branch: git restore . + git clean -fd. Append interrupted entry to journal. Reset status: idle, cyclestartedat: null. Continue. | | nextwakeupat set AND now - nextwakeupat > Q10.stalethreshold × cadence | Missed wakeups | Compute missed count = floor((now - next_wakeup_at) / cadence). Surface "🔁 Resumed after N missed cycles." per Q10.onresume. Continue. | | nextwakeupat is null AND Mode: active | Schedule lost (post-failure with no record) | Surface "🔁 Schedule lost — re-arming." Continue and re-arm at end. | | Mode: paused AND user signal != /autopilot resume | Intentionally paused | Print state, ask "resume?" If yes, set Mode: active. If no, exit. | | Mode: paused AND user signal = /autopilot resume | Explicit resume | Set Mode: active. Continue. | | /autopilot heal (any state) | Forced recovery | Treat as crashed-mid-cycle: git restore . + journal interrupted entry + status reset, regardless of detected state. | | /autopilot status` | Diagnostic only | Print state, last 3 journal entries, nextwakeupat, missed count. Do not run a cycle. Exit. | | All clean | Normal | Continue silently. |

Append every recovery to state.json.interruption_history:

{ "at": "", "type": "crashed-mid-cycle | missed-wakeups | schedule-lost | manual-heal", "recovered": true, "details": "..." }

Update check

Run when (a) Q9.check ≠ off AND (b) now - state.json.last_update_check_at > Q9.check interval (or last_update_check_at is null).

LATEST=$(curl -s --max-time 5 https://api.github.com/repos/PresentJay/autopilot-skills/releases/latest | sed -nE 's/.*"tag_name": "v?([^"]+)".*/\1/p')

If LATEST is empty (network/API error), fail-open: skip and retry next interval.

If LATEST > current SKILL.md version (semver compare):

• Q9.on-update-available = notify: append "📦 Update v{current} → v{latest}: npx skills update PresentJay/autopilot-skills" to cycle output.
• prompt: show notice, ask "update now?". If yes:

``bash npx -y skills update PresentJay/autopilot-skills --yes ` Then surface "Updated. Re-invoke /autopilot` to use v{latest}." and exit (do not continue cycle on stale skill code).

• silent-auto: run the update Bash command, exit with the same re-invoke prompt.

Cache result regardless of outcome:

state.json.last_update_check_at = 
state.json.available_version    = 

---

Operating cycle (one cycle per invocation)

8 phases. Bail-out rule: if the per-cycle token budget exceeds 70%, save partial state under "split-cycle" and resume at the failed phase next time.

Heartbeat (every cycle):

• At Phase 1 start: state.json.cycle_started_at = now, status = running.
• At Phase 8 end: state.json.last_run_at = now, next_wakeup_at = now + cadence, cycle_started_at = null, status = idle.

Phase 1 — DISCOVER

Pick one tool from mission.md Tools list, different from the previous cycle. Capture output to ≤100 lines.

Default tool catalogue (user adds/removes per domain):

• npm run lint
• npx ts-prune / npx knip / npx tsc --noEmit
• npm test --coverage (look for 0%-coverage modules)
• git log --oneline -20 origin/..HEAD (follow-up signals)
• grep -rn "TODO\|FIXME" within allow paths

The previous tool comes from the latest journal/ entry's Phase 1 도구 field.

Phase 2 — TRIAGE

Filter discovery output:

• Inside Q3 allow paths? → consider
• Hits Q4 forbidden? → reject
• Matches a NOT-OK pattern? → reject (anti-pattern learned in a prior cycle)
• Too broad? → narrow to one sub-task
• Priority: 5+ pattern or 1 decisive defect → P1; minor cleanup → P2

If no candidate survives:

• Q2=continuous + Q7 idle=end → terminate as mission-complete, no ScheduleWakeup.
• Q2=continuous + Q7 idle=ask → escalate to user.
• Q2=bounded → terminate.

Phase 3 — ANALYZE (impact / EDA)

For the surviving candidate, write to proposals/.md:

• impacted files / modules / users
• reversibility (code = reversible, config = mostly reversible, DB or external write = irreversible)
• conflicts with other proposals
• evidence (the discovery output excerpt)

Phase 4 — PLAN

• minimal diff to satisfy acceptance
• verify strategy (concrete commands)
• rollback strategy (git restore, feature flag, config revert)
• if Q5 cap is exceeded, split and process the first sub-task only
• prefer dry-run when available

If Q5=L1 → write the proposal and skip Phase 5/6 → straight to LEARN.

Phase 5 — EXECUTE (safe)

• isolate on a working branch (autopilot/ or as defined in mission.md)
• never push to main/master/release/* directly
• only modify files matching Q3 allow paths
• one commit = one candidate
• block destructive flags (--force, --no-verify, reset --hard) at the pre-execute check

Phase 6 — VERIFY

Run mission.md Verify commands.

• all green → success path
• any red → git restore + Phase 7 fail path + add the regression pattern to NOT-OK patterns

Phase 7 — LEARN

Append to journal/YYYY-MM-DD.md:

## 

- **Phase 1 도구**: 
- **후보**: 
- **Triage**: passed | rejected (reason)
- **Plan**: 
- **Execute**: 
- **Verify**:

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PresentJay](https://github.com/PresentJay)
- **Source:** [PresentJay/autopilot-skills](https://github.com/PresentJay/autopilot-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.