leek/agent-skills / skills/autopilot
autopilot
VerifiedBuild a whole spec while you are away. Asks every question up front, then a runner drives parallel fresh top-level Claude Code, Codex, or Grok sessions, one per ticket in its own worktree, onto one integration branch, delivered as one PR or a stack of PRs.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.5 KB |
| agents/openai.yaml | config | 264 B |
| references/worker.md | markdown | 9.7 KB |
| scripts/autopilot.shexecutable | script | 13.5 KB |
| scripts/land.shexecutable | script | 6.2 KB |
| scripts/lib/observer.sh | script | 9.9 KB |
| scripts/lib/output.sh | script | 2.4 KB |
| scripts/lib/process.sh | script | 5.0 KB |
| scripts/lib/provider.sh | script | 12.2 KB |
| scripts/lib/runner.sh | script | 33.5 KB |
| scripts/lib/state.sh | script | 7.9 KB |
| scripts/lib/tickets.sh | script | 6.9 KB |
| scripts/lib/tmux.sh | script | 7.5 KB |
| scripts/result-schema.json | config | 526 B |
| scripts/test-land.sh | script | 4.4 KB |
| scripts/test-root-key.shexecutable | script | 8.6 KB |
| scripts/test-run.sh | script | 12.7 KB |
| scripts/test-tmux.shexecutable | script | 10.6 KB |
references/worker.md
View on GitHub# Autopilot Worker
You are one fresh top-level session in an Autopilot run that builds one spec. The runner (a script) owns the task graph: it claims tickets, makes each one a worktree, starts the workers, and checks what they report. Do the one unit in your manifest, then return the structured result. Use the subagents your workflow calls for, wait for them, and keep their output inside this session. Nobody can answer a question during the run.
## Orient
1. Follow the repository instructions the harness loaded; read them from disk only when they are absent. Once you know the work paths, read every deeper `AGENTS.md`, `AGENTS.local.md`, `CLAUDE.md`, `CLAUDE.md.local`, and path-matched project rule that applies.
2. The run ID, the workflow path, and the manifest in the launch prompt are authoritative. The workflow is the `implement-spec` skill: the runner plays its orchestrator for steps 1–4, and the finish worker plays it from step 5 on. Skills it names sit beside it, and `ticket.sh` is `bash <workflow dir>/../setup/scripts/ticket.sh`.
3. The manifest's `mode` picks your section below: `build` or `finish`.
## Build mode: one ticket, in its worktree
The runner has claimed `ticket_file` for this run and created `worktree` on `ticket_branch`, cut from the integration branch `branch`. You are `implement-spec`'s implementer for that ticket: read that skill's **Guardrails**, **Stack references**, and step 3, and follow the implementer rules in step 3.3, with these differences.
- **Make the worktree runnable first**, as step 3.2 says (dependencies, local env config, its own registered database when the tests need one). With `selection: resume`, the worktree already holds an earlier session's work: read `git log` and `git status` there, then finish it rather than starting again. If you cannot tell whose the uncommitted changes are, return `needs_input` naming them.
- **Read** `ticket_file` in full, the Build Contract section of `spec_file` and the headings the ticket names, every file in `decisions_dir`, and each `blockers[].report` that exists (the seams its ticket handed forward). These paths are in the integration checkout: the tracker of record is there, not in your worktree.
- **Never write `.scratch/`**, in any checkout: no claim, no status, no Resolution. The runner and the finish worker own the tracker.
- **An undecided choice never stops you when its answer is reversible.** Build on the recommended answer and add one line to the report: `Assumed: <the question> -> <the answer you built>`. The runner puts each line to the user, and a different answer becomes a follow-up fix. When the choice is not reversible (a schema shape a later ticket builds on, a data migration), stop before building on it and return `needs_input` with the question and your recommended answer in `reason`: the runner releases the ticket and keeps building the rest.
- **Stacked PRs** (`delivery: stack`): before landing, review the ticket on its branch per `implement`'s [Stacked PRs](../../implement/references/spec-run.md#stacked-prs) step 1, and commit the fixes.
- **Land the ticket yourself**, with `bash <land> …` (`land` is in the manifest), from inside the worktree:
1. `begin --notes <notes> --integration <integration>` takes the landing lock and merges the integration tip into your branch. Exit 3 means another worker is landing: call it again. Exit 1 lists conflicts: resolve them (the `resolving-merge-conflicts` skill), commit, and go on. You hold the lock from here.
2. Rerun the ticket's focused tests on the merged tree. A failure you can fix in a few minutes, fix and commit. For a longer one, run `abort --notes <notes>` so other workers can land, fix it, and start again at `begin`.
3. `finish --notes <notes> --integration <integration> --ticket <ticket>`, plus `--stack` for stacked PRs. It merges your branch into the integration branch with a merge commit, marks the ticket landed, and frees the lock. `landed: false` names the reason: fix it and run `finish` again.
- **Stacked PRs, after landing:** `finish` printed `position`, `cut`, and `base`, and pushed `cut` (when `pushed` is false, run `git push -u origin <cut>` yourself). Open the ticket's PR from `cut` onto `base` per [Stacked PRs](../../implement/references/spec-run.md#stacked-prs) step 3. Its `based on` is the PR whose head is `base` (`gh pr list --head <base>`), or the branch name while that PR is not open yet. Add the PR number to the report, and append one line to `board_file`: `{"stack": [{"number": "<PR>", "position": <position>, "status": "safe"}]}`, or `"not-safe"` with a `note`, per [`ticket-board.md`](../../wayfinder/references/ticket-board.md)'s **Stacked PRs**.
- **Write the report** to `report_file`: step 3.3's ten lines (commits, touched paths, seams, the focused test command and result, deviations, anything blocking), then the `Assumed:` lines. The finish worker writes the ticket's Resolution from it, and dependents read it. Screenshots go in `screenshots`, named `<ticket>-<what>.png`.
Return `continue` with `completed_ref` set to `ticket_ref` only after `finish` printed `landed: true` and the report is written. The runner checks both and fails the ticket otherwise.
## Finish mode: review, verify, resolve, deliver
Every buildable ticket is landed on `branch` in `integration`, your working directory. You are `implement-spec`'s orchestrator from step 5 on: read that skill completely, then run its steps 5, 6, 7, and 8 with the manifest's values (`base_sha`, `notes`, `delivery`, `merged`, `delivery_ticket`). `delivery` is `pr` (One PR), `stack` (Stacked PRs), or `branch` (push, no PR). The differences:
- **Nobody answers.** Step 6's full-suite question: follow the repo's rule or the user's saved preference when one settles it, otherwise skip the full run and say so. A finding that needs the user's decision is left open: name it in the PR as a `Left open:` line and in `reason`.
- **Step 7 resolves exactly the `merged` tickets**, each from `<notes>/<NN>.md`, with `ticket.sh --root <tracker_root> resolve`. Work `delivery_ticket` only when it is not null. Tickets named in `left_open` were not built: say so in the PR body, and leave them open.
- **A deploy gate** in `deploy_gates` ends this delivery: say in the PR body that it must be deployed before its dependents are built.
- **Step 8's leftovers** follow `cleanup`: `auto` removes them without asking; `list` leaves them and names each one in `reason`, for the launching session to ask about.
- **The ticket board is a file here.** You have no board tool. Wherever `implement-spec` sends a `stage`, a finding's status, the `open` list, or a stack PR or the `integration` PR, append one JSON object on one line to `board_file` instead, with the fields [`ticket-board.md`](../../wayfinder/references/ticket-board.md) gives: `{"stage": "review and verify round 1"}`, `{"findings": [{"id": "3", "title": "…", "status": "open"}]}`, `{"open": [{…}]}`. One finding or one open entry per line, each line under 400 characters. The runner relays every line to the launching session, which sends it. Ticket statuses are the runner's: do not write them.
- **Retro the sessions that went wrong, report only.** When `retro_sessions` is not empty, do this after delivery. Each entry is a build worker session that `failed` or was `blocked`, newest last. Read `<workflow dir>/../retro/SKILL.md` and follow it with these differences, because `retro` is user-invoked:
- Mine only the listed `events` files, one entry at a time. They are raw provider event streams, not saved session logs. Run its `extract-signal.sh` on each one. When a file gives no events, its format is one the script does not know: read its event types with `jq` and pull the failed commands and errors yourself.
- Apply its evidence and environment lenses, redact secrets, and read each destination before you propose a change.
- Write its numbered proposal list to `<notes>/retro.md`, headed by the run ID and the tickets mined. Then stop: never apply a proposal, never edit a steering file, skill, hook, or config, and ask nothing. Add `retro: <n> proposals in <notes>/retro.md` to `summary`. The PR body leaves it out.
- Skip the end-of-session block: the launching session prints it.
Return `continue` with `completed_ref` set to `spec_file` once every `merged` ticket reads `closed` and the delivery is done; put the PR numbers (or the pushed branch) and anything left open in `summary` and `reason`. The runner checks that each `merged` ticket is closed.
## Report progress
Your first output must be a tool call that reads this contract. JSON-schema sessions constrain assistant text to the result object, so keep intermediate progress in tool calls only. Otherwise emit one short plain-text update when you start building, before landing (build) or before review (finish), and after the last commit. Never put the result object in those updates.
## Return the unit result
Emit the structured result exactly once, as the final action of the session. It always carries all five fields (`status`, `completed_ref`, `next_ref`, `summary`, `reason`): the schema rejects an object missing one, which fails the session even after the work is committed. Keep `summary` and `reason` short.
- `continue`: the unit is done, as its mode defines above. `next_ref` is an empty string, and `reason` a brief completion note.
- `needs_input`: a named human decision is the next dependency. Leave the worktree and its commits as they are.
- `blocked`: an external dependency prevents the unit. Name it in `reason`.
- `failed`: execution or verification failed, or this session leaves its own uncommitted changes. The runner keeps the claim, and the next run of the same command resumes the unit.
On a result other than `continue`, set `completed_ref` to an empty string. Never hold the landing lock when you return: run `abort` first.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |