autopilot-supervisor
Skill1 starsChanged 3 days agoApache-2.0View on GitHub
Use when the user hands over several GitHub issues, or the label `autopilot:queue`, to run as autopilot sessions in parallel under a cap — "supervise these issues", "start the queue", "run #12 #14 #15 with the supervisor". Starts one supervised `/speckit-autopilot` session per issue, only while the machine has room.
In this repository28 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- reclaim-diskSkill
- speckit-analyzeSkill
- speckit-autopilotSkill
- speckit-bugfix-patchSkill
- speckit-bugfix-reportSkill
- speckit-bugfix-switchSkill
- speckit-bugfix-verifySkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-docguard-diagnoseSkill
- speckit-docguard-fixSkill
- speckit-docguard-generateSkill
- speckit-docguard-guardSkill
- speckit-docguard-reviewSkill
- speckit-docguard-scoreSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- speckit-tdd-planSkill
- speckit-tdd-runSkill
- speckit-tdd-setupSkill
- speckit-tdd-verifySkill
- visual-passSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Run at the project root. Decisions come from scripts/autopilot/supervisor.sh (pure, reads the ledger .autopilot/supervisor.md).
- Very specific: line 12
Keep your context small: read the ledger only through supervisor.sh ledger table, and never read a session's transcript.
- Very specific: line 21
Before the first next, and for each issue whose Touches cell is empty (FR-004):
- Very specific: line 33
Create: Leave parent out of the worktree call: the daemon records the creating worktree as the parent (default for a supervisor at the …
- Very specific: line 50
Write first: ledger set <n> State starting, ledger set <n> Started <epoch seconds>, ledger set <n> Tries <tries + 1>.
- Distinctive: line 58
Start each as above, gate first, one at a time.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Autopilot supervisor
Run at the project root. Decisions come from scripts/autopilot/supervisor.sh (pure, reads the
ledger .autopilot/supervisor.md); you do the effects: gh, create_worktree, create_session.
Keep your context small: read the ledger only through supervisor.sh ledger table, and never read a session's transcript.
Build the queue
- Issues named in the arguments, or
gh issue list --label autopilot:queue --state open --limit 1000 --json number -q '.[].number'; sort ascending. scripts/autopilot/supervisor.sh ledger init --owner <this session id> --cap <N> --source "<label autopilot:queue | issues ...>" <issues...>(default cap 3), then run Touches for every issue. It refuses when a ledger exists: that is a restart, see Restart.
Touches
Before the first next, and for each issue whose Touches cell is empty (FR-004):
gh issue view <n> --json body,labels -q '.body' > <scratch>/body-<n>.md, and the label names with-q '[.labels[].name] | join(" ")'.scripts/autopilot/supervisor.sh touches <scratch>/body-<n>.md --labels "<names>"prints the paths (declaredTouches:line first, else inferred fromflow:*labels andspecs/<dir>paths) anddeclared,inferredornoneon stderr. Store them:ledger set <n> Touches <paths>.none(prints-):ledger set <n> Note "no touched files declared or inferable: treated as disjoint".
supervisor.sh next then holds a queued issue whose paths overlap a starting or running row or an earlier queued issue, whatever the cap; supervisor.sh overlap <a> <b> answers yes or no for two lists. Issues with the same flow:* label and no Touches: line or specs/ path share that flow file, so they run one at a time: declare Touches: to avoid it. A held issue stays queued and is released once the earlier one is done, failed, lost or skipped.
Ownership
A run is yours by its worktree's parent, never by its name or by what you remember. Worktree parents: specs/1857-worktree-parent.
- Create. Leave
parentout of the worktree call: the daemon records the creating worktree as the parent (defaultfor a supervisor at the project root). Never pass another worktree's name. - Record.
ledger set <n> Parent <your worktree ref>(defaultat the root, else your own worktree's directory name) besideWorktree, so a restart knows which runs are yours. - List. Run
list_worktreesunfiltered and save the result to<scratch>/worktrees-all.json;scripts/autopilot/runs-of-parent.sh <your ref> --rows <scratch>/worktrees-all.jsonprints therefof each of your runs. (The daemon'sparent: <ref>filter keeps only known children and drops orphans, so a filtered list serves this step but not the orphan scan.) A run'sWorktreecell that is not in that list is not yours: do not map, start, stop, send to or interrupt it. A run is named by itsref, the worktree's directory name, which is the last part of theWorktreepath. - Check before every act on a run (
send_session_input,interrupt_session,stop_session,delete_worktree):runs-of-parent.sh <your ref> --check <ref> --rows <scratch>/worktrees-all.json(the ledger'sWorktreepath is accepted in place of the ref). Exit 1 (another parent, no parent, or a removed parent): refuse, and say so in the ledger Note. Never act on a run of another parent or on one with none. - Removed parent. A run whose
parent_stateisremovedis an orphan:runs-of-parent.sh <your ref> --orphans --rows <scratch>/worktrees-all.jsonlists them, from the unfiltered list. Report each to the person and never adopt it, even if it looks abandoned. - Where the daemon helps. A supervisor in its own worktree is limited by the daemon to its parent, siblings and children, and so is every worker it starts. A supervisor in
defaultis not limited by the daemon, so this rule still applies to it in full: it sees every run and acts only on its own.
Relay
A worker contacts only its parent (you) and its siblings, so its parent and siblings are the whole of its reach. Its questions and any message for another scope come to you, and you forward them up or down with your own send_session_input (FR-017). The supervisor never expects a worker to reach another supervisor's run. Put this in the worker prompt: after /speckit-autopilot #<n> supervised, add the line You can reach only your supervisor and your sibling runs. Send a question or a message for anyone else to your supervisor; it forwards it.
Start an issue
For each issue <n> that supervisor.sh next prints, one at a time:
- Resource gate.
scripts/autopilot/supervisor.sh gate(it counts thestartingandrunningrows of the ledger, so every start is written to the ledger before the next gate).FAIL <check>: start nothing more, report which check failed, retry at the next advance.PASS: go on. gh issue view <n> --json state,title -q .state. A closed or missing issue, or one that already has a worktree or a ledger of its own:supervisor.sh ledger set <n> State skippedandledger set <n> Note "<reason>"; next issue.- Write first:
ledger set <n> State starting,ledger set <n> Started <epoch seconds>,ledger set <n> Tries <tries + 1>. create_worktreewithgithub_issue: <n>and noparent(Ownership);ledger set <n> Worktree <path>andledger set <n> Parent <your ref>.create_sessionin that worktree with the prompt/speckit-autopilot #<n> supervisedand the relay line of Ownership;ledger set <n> Session <id>andledger set <n> State running.- A failed create: leave the state, write the reason with
ledger set <n> Note "<reason>", and go on. Thensupervisor.sh retry <n>(theTriescell counts the start; it printsqueued, orfailedat 3 tries).
Advance loop
supervisor.sh nextlists the issues to start. Nothing printed: say there is nothing to do.- Start each as above, gate first, one at a time.
nextprints nothing: run Report (it ends withsupervisor.sh ledger table) and end the turn. Never pollnext: start the watcher (Watcher) and end the turn.
Restart
A ledger already exists: continue from it, never rebuild the queue.
- Owner.
list_sessions(metadata only), thensupervisor.sh check-owner --live-sessions "<ids>" --me <this session id>.OWN: go on.FREE:supervisor.sh ledger owner <this session id>, go on.HELD <owner>(exit 1): another supervisor owns the ledger; say which session and stop. - Recover half-started rows first. A
startingrow with an empty Worktree or Session cell (the supervisor ended mid-start): look for a worktree and a session of the issue (list_sessions,git worktree list). Found: fill the empty cells, Staterunning. None:supervisor.sh retry <n>(back toqueued, orfailedafter 3 tries). - Map each row that has both Worktree and Session and is
startingorrunning. For<n>with Worktree<dir>:scripts/autopilot/run-status.sh --json <dir> > <scratch>/<n>.json(one file per issue, kept for Report), thensupervisor.sh map <scratch>/<n>.json --started <Started> --ledger .autopilot/supervisor.mdandledger set <n> State <result>. Exit 2 (worktree gone) or 3 (several ledgers):supervisor.sh map --exit <code> --started <Started>giveslost; put the exit code in Note.donefrees the slot;runningkeeps it and is never started twice. - Liveness. A
runningrow with a Session id that is not in thelist_sessionsids while its state is notdone:ledger set <n> State lost, and report it. Rows with an empty Session were handled in step 2. Never restart alostissue yourself. - Re-ask.
supervisor.sh route next --reaskprints everyaskedrow. For each issue in it, use that issue's<scratch>/<n>.jsonfrom step 3 (never a transcript): a session that leftaskingunanswered getssupervisor.sh route drop <issue>and its question is not asked. Then runAUTOPILOT_CONTEXT_CAP=80000 scripts/autopilot/context.py:OVER: make noAskUserQuestioncall, printCheaper: /clear, then /autopilot-supervisor — it asks this again from the ledger.and end the turn. Otherwise ask the remaining rows, without a banner or notification, inAskUserQuestioncalls of at most 4 questions in ascending issue order, each prefixed#<issue>, the next call after each answer, until every printed row is answered; then Route questions steps 8 to 11. Do this before any new start. - Then the advance loop.
Report
For each run the mapping left running whose run-status JSON state is stuck or blocked, and for each lost row (a dead-no-ledger run past Grace is reported through its lost row), tell the person the issue, the state and why, from that issue's <scratch>/<n>.json (the file Restart step 3 wrote; never a second run-status read), its JSON escalation (its banner and questions for blocked), or the reason, without reading the session. A dead-no-ledger run within Grace counts as running: no alarm. An asking run is not only reported: run Route questions for it. Never unblock or restart a stuck, blocked or lost run yourself; the person decides. Finish with supervisor.sh ledger table.
Route questions
For every running row whose <scratch>/<n>.json state is asking (never a transcript), in this order:
- Collect. From that file's JSON
escalation(category,banner,questions):scripts/autopilot/supervisor.sh route add <n> <session id> <scratch>/<n>.json. It writes oneR<n>.Q<k>row per question aspendingand is a no-op for rows already there, so a restart never asks twice. - Resolve. For each
pendingrow, judge its subject, not the category label, against.claude/skills/speckit-autopilot/rules/escalation.mdNever ask about these.supervisor.sh route gate "<category>"printsuser-only(category 2, 3 or 4: never answer it, whatever the evidence; go on to step 3) orjudge(category 1, 5 or 6). Onjudge, a subject that matches a Never ask item overrides the label: look for the answer in the repo (rules/escalation.md, the flow's spec, plan and ledger, the failing command's own output) and, with evidence,supervisor.sh route answer <key> supervisor "<answer> (evidence: <path or command>)"; the row becomesresolvedand stays out of the user batch. A subject that matches no Never ask item, or one with no evidence, is never guessed: the row stayspendingand goes to the user batch. Aroute gatethat exits 2 (a missing or unreadable category) goes to the user too. - Batch. First run
list_sessions(metadata only) into<scratch>/sessions.jsonandsupervisor.sh route target --sessions <scratch>/sessions.json --me <this session id>(it falls back to the row withis_caller: truewhen the id matches no row; exit 2, an unreadable list, means ask the user):parent <id>means Upward relay below replaces steps 4 to 8 for the batch;user(no parent reported, a parent with no session, or a top-tier supervisor indefault) continues here.supervisor.sh route nextprints up to 4pendingquestions, ascending issue then number. Nothing printed: run steps 9 to 11 for each issue whoseroute tablerows are allresolvedoransweredwith an empty Sent cell (a run the supervisor resolved entirely, or a restart), then stop. - Banner. For each question send the banner of
.claude/skills/speckit-autopilot/tasks/ask.mdwith unitsupervisor: first line prefixed#<issue>, a(Recommended)first option with its evidence, written so the person can answer it cold. - Notify. One
PushNotification(load it withToolSearch("select:PushNotification")), text🛑 <issues> need a decision: <topic>. - Mark.
supervisor.sh route state <key> askedfor each row of the batch, after the banners and the notification and before the question call (a restart never asks twice). - Ask. Run
AUTOPILOT_CONTEXT_CAP=80000 scripts/autopilot/context.py.OVER: the batch is already in the ledger (askedrows, step 6), so make noAskUserQuestioncall: after the banners, the notification androute state <key> asked, printCheaper: /clear, then /autopilot-supervisor — it asks this again from the ledger.and end the turn (Restart re-asks it). Otherwise oneAskUserQuestionof at most 4 questions in ascending issue order, each prefixed#<issue>. More than 4 questions: the rest go in the next batch after the first answer (back to step 3). A single question goes alone, at once. - Record.
supervisor.sh route answer <key> user "<answer>"per answer. - Send.
supervisor.sh route compose <issue>. Exit 0: its first line issession <id>;send_session_inputthe remaining lines as one message (they already begin withresume, orresume --by supervisorwhen the supervisor resolved every question) only to that session, never to another. Exit 1 printsmissing: <n> ...: ask the person again for only the missing question, then compose again. - Mark sent.
supervisor.sh route sent <issue> <epoch seconds>. - Confirm. After a
CHANGEDwake shows the run leftasking,supervisor.sh route drop <issue>(the worker's Decisions holds the record). A run stillaskingafter the send:supervisor.sh route overdue --now <epoch seconds> --ceiling <Watcher ceiling seconds>lists the issues whose Sent is older than the Watcher ceiling; report each whose Note does not already say it as not accepting input, thensupervisor.sh ledger set <n> Note "not accepting input"so the next wake does not report it again; never re-sent.
Upward relay (FR-012, FR-013). With route target printing parent <id>, the supervisor is below the top tier and parent is read only from list_sessions, never from the ledger Owner or the environment. Send the step 4 banners for the batch to <id> with send_session_input (no PushNotification, no AskUserQuestion), then supervisor.sh route state <key> asked for each row, Via parent. When the parent's reply arrives, record it with supervisor.sh route answer <key> parent "<answer>" and go on from step 9 (send down, mark sent, confirm). A top-tier supervisor (route target printed user) asks the user directly through steps 4 to 8. A send to the parent refused as not_found (the daemon's sibling visibility put it out of scope) is recorded with supervisor.sh ledger set <n> Note "<refusal>", then the batch is asked of the user through steps 4 to 8 (Via user), never retried.
A send that fails with not_found (the session is gone): route drop <issue> and report the session lost. Any other failure: supervisor.sh ledger set <n> Note "<error>", leave the rows answered, report the issue, and never retry in a loop.
Watcher
After an advance that leaves issues starting or running, start scripts/autopilot/supervisor-watch.sh with run_in_background and end the turn. It exits on the first state change (CHANGED <issue> <old> <new>) or after 10 minutes (CEILING; AUTOPILOT_WATCH_CEILING sets it), and its exit wakes you: run Restart steps 2 to 4, the advance loop and Report again. Never poll with sleep.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

