Skip to content

skill · phase: implementation

Autopilot

Purpose

Turn "do the next 3 items" into one background run. The run builds each ready backlog item in its own worktree with an unattended agent, opens a pull request, waits for CI, and goes as far as the user's stop settings allow — one item at a time through the merge. By default it pauses for a review after requirements and after design, and stops at the pull request for the user to merge.

The CLI does the work. This skill starts it and says how to watch and stop it. Do not build the items yourself in this session.

Instructions

  1. Read the count. "the next 3 items" → --items 3. "all the items", "the whole backlog" → --all. "the next item" → --items 1. If no count is given, ask once: how many items, or all?

  2. Check it is set up. Run aidlc autopilot status. If the user has never run setup, run refuses in step 3 and says so; then go to step 4.

  3. Start the run. From the project, run:

    aidlc autopilot run --items <n>

    or aidlc autopilot run --all. It returns at once. Do not wait for it, and do not poll its status: step 7 is how you stay on watch.

  4. If it refuses:

    • not set up → tell the user to run aidlc autopilot setup in their own terminal. It asks which agent to use and what it may do; that choice is theirs, so do not pick it with flags on their behalf.
    • a run is already active → report its pid and offer aidlc autopilot stop first.
    • the run is paused → offer aidlc autopilot resume.

  5. Report, in six short lines: what it is doing (how many items), the stops: line run printed verbatim, the log file, aidlc autopilot status --watch to watch (cards per item, live, until the run ends; v switches to a table or lanes, q leaves), aidlc autopilot pause before the machine sleeps (aidlc autopilot resume after), and /aidlc-autopilot-stop (or aidlc autopilot stop) to stop. When the stops line says none are set, say plainly that every item will be merged and released with no review, and name aidlc autopilot setup as what changes that.

  6. Where it stops for a person. Three stops. The first two are set in aidlc autopilot setup or aidlc init and on by default; the third needs no setting:

    • After a phase — the agent stops when a phase in pause_after completes (requirements and design by default). The item waits as awaiting-review; it is not parked. The user reads the artifact in the item's worktree, then aidlc autopilot approve <instance> carries it on. A requirements or design phase that wrote "Nothing open" into its artifact, with no unanswered question, is not waited on: the item carries on, and the run log says so.
    • At the pull request — autopilot opens it and waits for the user to merge. Merging is the approval: autopilot then closes the instance out on main and runs no release.
    • At an open question — an unattended agent decides calls inside the item's scope and logs each in the instance's state directory; one it marks open-question needs the user. Whatever stop_at says, that item waits at its pull request like the stop above. The user runs aidlc autopilot review <instance> in the item's worktree to keep, reject or promote each logged decision — promoting adds it to .aidlc/guidance/decisions.md, which every later item reads — then merges.

    One run can change both without touching the saved setup: aidlc autopilot run --items 3 --stop-at merge or --pause-after design (--pause-after none for no pauses, --stop-at release for the old merge-and-release). The flags apply to the items that run starts; an item already in flight keeps the stops it started with. A config saved before stops existed keeps today's behaviour — no pauses, merge and release — until somebody sets them.

    When the user asks what is waiting for them, run aidlc autopilot status: it names the phase, the worktree and the exact approve command for each waiting item, and under it each open decision — the question, why it matters, the options with the recommended one marked, and the file to answer in. Answering is writing the chosen option after that question's [Answer]:, then the approve command. When they ask how the items are getting on, run aidlc autopilot status --watch: called from here it prints each item's phase, tasks done, time in its step and last event once, and returns.

  7. Stay on watch while the run is active. The run's agents can ask nobody, so every decision only a person can make ends up in a file. You are the one session a person is watching: ask them. Do not build, review or fix any item yourself.

    • Read what waits. Run aidlc autopilot pending --json. Each entry has a fingerprint, a kind, blocks (it blocks the run) or not (it only waits), a question, a summary, an artifact to read, and options, the recommended one first. Each option has an id, a label, a one-line consequence, person (only the person may apply it, in their own terminal), applies (what it comes down to) and the command that applies it.
    • Ask. At most four questions a round: blocking entries first, then the oldest. Before each round, write one message with what the person needs to answer: which item, what the agent did, the artifact path, and every command an option will run or hand to them — the question UI cannot copy text, so commands go in the message, never in a question. Ask each entry as a multiple-choice question: its question, and its options by label, recommended first, each with its consequence on one line. For a triage entry the rank and the run mode are one answer. When nothing new waits, say nothing.
    • Apply each answer by running exactly the chosen option's command — aidlc autopilot answer <fingerprint> <option> — and report what it printed. A triage answer with another rank ("rank 2, attended") is that option with --rank 2. A park or decline takes the person's reason as --note "<reason>". An answer you cannot map to an option, run as aidlc autopilot answer <fingerprint> other --note "<their words>", and repeat their words back; never guess an option from it. Approving an item, and keeping or rejecting a decision its agent logged, are applied by answer itself, in the person's name: run that option only when the person chose it. A person-only option prints the command for them to run in their own terminal: pass it on as printed. When the person does not answer, run nothing; the run carries on with everything else.
    • Wait to be woken. Then run aidlc autopilot wait --pending as a background command and end your turn. It exits when something new waits, after 30 minutes with nothing new, or when the run ends, and its exit wakes you. On waking, read aidlc autopilot pending --json again: ask what you have not asked this session, stay silent when there is nothing new, and start the wait again. When it prints run ended, say so in one line and stop watching. This is the one place a session ends its turn to wait: rules/unattended.md "Waiting for a command" binds unattended agents, not you.
    • No background command? Where this agent cannot be woken by a background command's exit, check aidlc autopilot pending --json every 20–30 minutes with a scheduled check instead. Failing both, say once that the person must run aidlc autopilot status themselves to see what waits.
    • Never answer a question yourself, approve or review unless the person chose that option this round (and then only through its answer command; aidlc autopilot approve and aidlc autopilot review are theirs to run in their own terminal), change pause_after or stop_at, merge or release beyond what the run's stops allow, or build an item. An answer already given in another session is refused by answer with who gave it; report that and move on.

  8. Pause and resume. When the user is stepping away or closing the laptop, run aidlc autopilot pause; when they are back, aidlc autopilot resume. Report what each printed. If pause says a pass is in progress — a merge or a release — run it again a minute later rather than stopping the run.

What the run does on its own

  • Takes items in aidlc roadmap next --autopilot order, which leaves out items marked run: attended. Builds at most two at once, and never more than the count asked for.
  • Parks an item (moves it to hold/ with a reason) when its agent stops short of a stop it was told to reach, when CI fails twice, or when it passes the cost cap. An item waiting for a person is never parked, and holds no build slot, so the run goes on starting others.
  • An agent that loses the network exits, and is parked. Sleep cuts the network, so a run on a laptop needs aidlc autopilot pause first: it freezes the run and its agents where they are, and aidlc autopilot resume carries on.
  • Before each merge, brings the item's branch up to date with main and waits for CI on the new head. A conflict with main goes back to the item's agent, twice at most, then the item is parked. A pull request someone merged by hand is dropped from tracking.
  • Halts the merge queue when a step fails. Running aidlc autopilot run again retries a failure that came before the merge; a failed release is for a person — aidlc autopilot status shows the error. aidlc autopilot forget <instance> stops tracking an item finished by hand.
  • Sends a desktop notification, once each, when an item is parked, fails, waits for the user, or is done, and when the run ends. notify: false under autopilot: in .aidlc/config.yaml turns them off.
  • Ends when the asked-for items are each released or parked, or, with --all, when nothing is ready and nothing is in flight. An item waiting for a person keeps its run alive, so the run is still there to carry the item on after an approval or a merge.

Exit Criteria

  • aidlc autopilot run has started a run, or its refusal has been reported with the one command that fixes it
  • The user knows where it will stop for them, where the log is, how to watch, how to pause, and how to stop
  • While the run is active, this session is on watch: it asks about what waits, applies each answer with its one command, and waits to be woken