# Autopilot > Run one explicit bounded Blueprint spec and implementation pass through configured quality gates, then stop before completion or external actions. Use only when the user directly invokes /autopilot, $autopilot, or asks for Autopilot. - Skill: `aiblueprinthq/autopilot` (Agent Skill) - Install (CLI): `npx skillmds@latest add aiblueprinthq/autopilot` - Raw SKILL.md: https://api.skillmd.com/api/skills/aiblueprinthq/autopilot/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: aiblueprinthq (https://skillmd.com/u/aiblueprinthq) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/aiblueprinthq/autopilot --- # autopilot - optional Blueprint loop **Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed. **First action:** Before project inspection, preflight, or any other tool call, publish `running` to `blueprint/.state/run.json` using the dashboard activity contract in `AGENTS.md`. Where this sits in the workflow: /status -> [autopilot] -> review packet -> /complete (where (spec, build, (human review, (log, commit, are we?) configured gates) fixes if needed) merge with approval) Autopilot is an explicit opt-in path. It uses the same Blueprint files and the same quality gates, but it does not stop after every normal review point. A single user request is permission to run one bounded loop until the feature is ready for review, blocked, or unsafe to continue. It combines `/feature` or `/fix` with `/implement` and continues through the spec-review stop retained by the normal workflow. That human spec approval is the main control Autopilot intentionally removes. It does not remove the final review packet or the option to walk through the completed code. It does **not** replace the normal workflow. `/feature`, `/implement`, `/check`, and `/complete` remain the conservative default. Do not suggest Autopilot as the default next action. Use it only when the user explicitly asks for it. The explicit Autopilot request is permission to create checkpoint commits on the feature or fix branch after passing implementation steps when `workflow.checkpointCommits` is enabled. It is not permission to merge, push, deploy, publish, send, delete data, or run destructive actions. ## Input Common forms: - No argument: resume the current feature if one exists, otherwise target the next unchecked build-plan item. - A number or name: target that build-plan feature, for example `/autopilot 3` or `$autopilot "directory listing"`. - `fix ""`: write and build an ad-hoc fix spec. - `resume`: continue the current feature on its existing branch. If the requested target conflicts with a feature already in progress, stop and ask which one should win. Do not overwrite `blueprint/context/current-feature.md` silently. Rollback is intentionally excluded from Autopilot. If the request is a rollback or `current-feature.md` is marked `Type: Rollback`, stop and direct the user to the reviewed `/implement` path. Reversing completed work requires the explicit dependency and conflict gates in `/rollback` and `/implement`. ## Step 1 - preflight like /status Read the same state `/status` reads: - `AGENTS.md` - `blueprint/config.json` - `blueprint/project-plan.md` - `blueprint/build-plan.md` - `blueprint/context/project-overview.md` - `blueprint/context/current-feature.md` - `blueprint/context/findings.md` - `blueprint/context/coding-standards.md` - `blueprint/context/ai-interaction.md` - git branch, status, and recent log Then decide whether it is safe to run. Stop before changing files when: - `blueprint/config.json` exists but is invalid. Point the user to `/doctor`. - The repo is not a git repo. - The working tree is dirty and there is no current feature tying those changes to this run. - `current-feature.md` has real work and the user requested a different target. - `project-overview.md` is missing or stale and the planning docs are not clear enough to regenerate it. - The next feature is visual or replication-heavy and no design reference exists. - The task needs product, data, auth, billing, or destructive decisions the docs do not answer. If the only issue is that `project-overview.md` is stale and the plans are clear, regenerate it using the `/overview` behavior and continue. Include that in the final packet. The initial `blueprint/.state/run.json` record required by `AGENTS.md` must already show command `autopilot` and status `running` before preflight begins. After preflight passes, enrich it with boundary `reviewed`, the target feature or fix, and build-step progress when known. Update it after the spec, each passing build step, and each configured gate. On a hard stop, set status `blocked` with `/autopilot resume` when resuming is safe. At the final review packet, set status `ready` because Autopilot stops before `/complete`. Activity reporting must never weaken or block the workflow itself. ## Step 2 - choose or write the spec If `blueprint/context/current-feature.md` already contains an active spec, resume it. Read checked steps and continue from the first unchecked step. If there is no active spec: 1. Use the `/feature` behavior for a planned feature, or `/fix` behavior for a requested fix. 2. Write `blueprint/context/current-feature.md`. 3. Red-team the spec before building: - missing unhappy paths - oversized steps - undefined contracts - missing design reference - scope creep - vague done-whens - missing testing plan when `AGENTS.md` declares a test command 4. Apply the spec fixes. Autopilot may continue past this spec gate because the user explicitly invoked Autopilot. Still report what the critique changed in the final packet. Follow the proportional-engineering contract in `AGENTS.md` throughout this run. ## Step 3 - create or reuse the branch Use the same branch rules as `/implement`: - Feature: the configured feature prefix, default `feature/` - Fix: the configured fix prefix, default `fix/` If the branch already exists, switch to it only if it matches the active spec. If switching branches would strand unrelated dirty work, stop and report the problem. ## Step 4 - implement in small steps Work through the spec's build steps in order. Each step must remain reviewable. Do not pause for user approval after each passing step, regardless of the configured `workflow.stepReview` value. The review happens at the final packet unless a hard stop is hit. For every step: 1. Implement only that step. 2. Run the relevant verification: - the exact `Verify` command from `AGENTS.md`, when declared - otherwise the build, relevant test, lint, and typecheck commands already documented by the project - browser, CLI, API, or app-level evidence for behavioral done-whens - with `verification.logicTests: "required"`, stop and point to `/tests` if logic changed but no test runner is configured 3. If UI is involved, inspect the running app when possible. Prefer Playwright if it is already installed or declared. Capture screenshots when they add useful evidence. Check for console errors and failed requests. With `verification.uiEvidence: "required"`, direct browser evidence is mandatory and unavailable evidence is a hard stop. 4. Self-review the diff for the step: - does it match the spec? - did it add scope? - is the error path handled? - did it follow `coding-standards.md`? - are tests present for new in-scope logic when the test gate is on? 5. Fix obvious issues and rerun the failed checks. 6. Mark the step checked in `current-feature.md` only after the step passes. 7. When `workflow.checkpointCommits: "enabled"`, create a checkpoint commit on the feature or fix branch for the passing step. Include the code, tests, and the updated `current-feature.md` checkbox. Use a conventional message such as `feat: checkpoint mock snapshot route` or `fix: checkpoint stale service filter`. Keep the message about the step, not about Autopilot. When the value is `disabled`, leave the passing step uncommitted for the final review. Do not batch the whole feature into one large diff. If a step gets too large, split the step in `current-feature.md` and continue with the first smaller step. ## Step 5 - configured acceptance check After all implementation steps are checked, apply `qualityGates.regular.check`: - `manual` - skip the automatic `/check`; it remains available when explicitly requested. - `when-behavioral` - run `/check` when a done-when needs observed runtime behavior such as a click, request, CLI command, download, background job, or multi-screen flow. - `always` - run `/check` for every work item. After the required verification and configured Check gate pass, set the current spec's `**Status:**` to `verified` before any independent-review checkpoint. Audit findings and review state may still block completion. Leave the spec `in progress`, `verification failed`, or `verification incomplete` on any stop that lacks complete verification evidence. For pure library or CLI work, build plus tests and representative command output may be enough. Be explicit about the evidence used. ## Step 6 - configured quality audit and repair Apply `qualityGates.regular.independentReview` before a same-session audit: - `manual` skips automatic independent review unless a request already exists. - `when-sensitive` requires it for authentication, authorization, payments, secrets, personal or user data, migrations, destructive operations, external side effects, security boundaries, or unusually broad changes. - `always` requires it for every work item. The selected review runs after all implementation steps, final Verify, required Check, and the verified spec, before the final review packet and `/complete`. `review.independentExecution` chooses the manual fresh-session handoff or an automatic isolated reviewer; it does not change when the gate is selected. When selected, do not review the builder's work in this session. Ensure application code is in an approved clean checkpoint. Include the verified spec when tracked; an intentionally ignored spec uses Audit's local `Spec snapshot` contract without changing visibility. Then follow Phase A of `/audit independent current`. With automatic execution, spawn and wait for the isolated reviewer, then validate its normal receipt. With manual execution, stop with the handoff. Autopilot may use its existing configured checkpoint authority when checkpoint commits are enabled; otherwise show the exact review-checkpoint candidate and ask before committing. On resume, continue only when a fresh reviewer wrote a current `passed` receipt. Repair `changes-requested` P0/P1 findings within the normal scope and attempt limit, then obtain a new checkpoint and prepare a new review. A passing independent receipt satisfies the configured Audit gate. A local-spec-only revision may reuse the same approved product HEAD after normal spec and verification gates, with a new snapshot/request and full fresh review. Do not create an empty commit for ignored spec changes. Automatic execution must also confirm access to the same local spec/snapshot and installed skills; otherwise retain the request and use the manual handoff in the original checkout. The request records `Requested execution`; the receipt records `Actual execution`. Require the execution and reviewer-context pairing defined by the project-local review contract, including actual manual plus `fresh session` when an automatic request explicitly falls back. On resume, a pending request without `Requested execution` is legacy manual-only. Never add execution fields or run a subagent against it. Apply `qualityGates.regular.audit`: - `manual` - skip the automatic audit; `/audit` remains available when explicitly requested. - `when-sensitive` - run `/audit current` for authentication, authorization, payments, secrets, personal or user data, migrations, destructive operations, external side effects, security boundaries, or unusually broad changes. - `always` - run `/audit current` for every work item. When the gate runs, audit the active feature, its diff, and the nearby code affected by the change. This is a targeted feature audit, not a repository-wide cleanup pass. Findings are recorded in `blueprint/context/findings.md` with durable IDs and statuses, as `/audit` defines; the ledger reports status and never scopes what the audit examines. For every finding: 1. Validate it against the actual code, spec, tests, `coding-standards.md`, and local project patterns. An audit finding is evidence to investigate, not an automatic instruction to edit. 2. Repair confirmed P0 and P1 findings when the fix stays inside the approved feature scope, does not require a product or architecture decision, and does not remove or change shipped behavior. Set the repaired finding to `fixed` in the ledger, never `closed`. 3. Report P2 and P3 findings in the final packet. Fix them only when the change is small, directly caused by the current feature, and clearly required by the project standards. 4. If a confirmed P0 or P1 finding cannot be repaired safely within scope, stop and report it. Do not present the feature as ready for `/complete`. After any audit repair: 1. Rerun the documented `Verify` command when present; otherwise rerun the affected build, lint, typecheck, and test commands. 2. Rerun the acceptance evidence affected by the repair. 3. Recheck the repaired area using the same targeted audit criteria. When that recheck confirms the original defect is gone and the repair introduced no new one, move the `fixed` finding to `closed` under the `/audit` close conditions and name it in the packet. An unrelated new finding gets its own ledger entry and does not keep the repaired one open. 4. Create a checkpoint commit only after the repair and its checks pass, and only when checkpoint commits are enabled. Use the existing two-attempt hard stop for repeated repair failures. Do not widen the feature into a general refactor, silently suppress a finding, or turn this step into a full-project hardening pass. A broader cleanup remains a separate `/audit` followed by planned `/fix` work. ## Step 7 - configured try guide Apply `qualityGates.regular.tryGuide`: - `manual` - skip automatic generation; `/check guide` remains available when explicitly requested. - `when-user-facing` - run `/check guide` when the change affects UI, navigation, copy, a public API or CLI, output, or another workflow a person directly uses. - `always` - generate a guide for every work item. The guide is a review artifact, not proof. Never claim the user performed it. ## Step 8 - final review packet Stop with a concise review packet. Keep it useful enough for `/complete` but not a full audit report: - branch name - target feature or fix - whether the spec was created or resumed - what the spec critique changed - changed files and why each changed - build/test/check commands run, with pass or fail - effective regular quality-gate policies and which automatic gates ran or were skipped - independent-review target, selected reviewer and model, and receipt state - screenshots or output paths, when relevant - how to try it manually, or a pointer to `/check guide` for the full walkthrough - checkpoint commits created - self-review findings - targeted audit scope and findings, when the audit gate ran - audit repairs made and checks rerun, when applicable - P0/P1 findings still `open` or `fixed` in `blueprint/context/findings.md`, which block `/complete` - unresolved risks or skipped checks - exact next action If everything is green, the next action is usually: review the diff, run `/check guide` if its gate was manual and a walkthrough is wanted, then `/complete`. Always offer a read-only walkthrough of the completed code after the packet. Follow the spec's build steps, explain the key files, symbols, flow, and non-obvious decisions, then offer a focused deep dive. Keep `/check guide` distinct as the manual product-review path. If something failed, name the failing check and the next fix target. ## Hard Stops Stop immediately and report instead of continuing when Autopilot would need to: - commit on `main`, merge, delete a branch, push, deploy, publish, or send anything - delete data, reset a database, run irreversible migrations, kill processes, or change system settings - install dependencies or use network access without the current tool's approval flow - make a product decision not covered by the docs - continue after two failed fix attempts on the same issue - hide, skip, or hand-wave a failing check ## Rules - One Autopilot run handles one feature or one fix. - Autopilot creates checkpoint commits on the feature or fix branch after passing steps only when project config enables them. - Autopilot uses `qualityGates.regular`. The Continuous gate policies and the `continuous` section do not change an Autopilot run. - When its audit gate runs, Autopilot audits the active feature and affected code, not the entire project. - A P0 or P1 finding left `open` or `fixed` in `blueprint/context/findings.md` blocks readiness for `/complete`. The ledger is what makes this enforceable. - Autopilot stops before `/complete`. It never merges. - The Blueprint files remain the state machine. Keep `current-feature.md` accurate as steps complete. - Follow `coding-standards.md`, `ai-interaction.md`, and `AGENTS.md`. - Prefer fewer, higher-quality changes over broad coverage. - Report uncertainty plainly. A blocked run is useful if it tells the truth. ## Formatting Format the output to match the project's conventions in `blueprint/context/ai-interaction.md`: concise, scannable markdown, with lists for enumerations and tables for matrices rather than dense paragraphs.