Autopilot
Accept a single sentence, automatically break it down into a structured execution plan, then execute it fully in unattended mode.
When a user calls autopilot, it means: Authorizing AI to complete the entire process fully autonomously — investigation, implementation, deployment, E2E verification, code review, secondary deployment, secondary verification, and wrap-up. No mid-process confirmation is required, no phases are allowed to be skipped, and no halfway abandonment is permitted.
Installation and Updates
bash
# First-time global installation, or reinstall when update fails
npx skills add yan-labs/yan-skills --skill autopilot -g -y
# Update the installed global Skill to the latest version
npx skills update autopilot -g -y
For project-level installation, remove the
from the installation command; use
npx skills update autopilot -p -y
for project-level updates.
Accept a single sentence, automatically break it down into a structured execution plan, then execute it fully in unattended mode.
When a user calls autopilot, it means: Authorizing AI to complete the entire process fully autonomously — investigation, implementation, deployment, E2E verification, code review, secondary deployment, secondary verification, and wrap-up. No mid-process confirmation is required, no phases are allowed to be skipped, and no halfway abandonment is permitted.
Loop Enforcement Rules (CRITICAL · Highest Priority)
Calling autopilot = Must start loop. No exceptions.
This rule takes precedence over all other considerations. No matter how simple, urgent, or "obviously completable in one go" the task seems, autopilot's execution model is loop + agent-mode, not "completing everything consecutively in a single turn".
Hard Block Gate
After Step 2 (Planning) is completed and before the first line of implementation code is written, must call ScheduleWakeup to start the loop. This is an unskippable checkpoint:
Step 1: Rapid Investigation ─── Can be completed within the current turn
Step 2: Plan Breakdown ─── Can be completed within the current turn
╔══════════════════════════════════════════════╗
║ ⛔ GATE: Must call ScheduleWakeup here ║
║ Pass loop-goal as prompt ║
║ Failure to call = Prohibited from entering Step 3 ║
╚══════════════════════════════════════════════╝
Step 3: Execution ─── Executed in loop callback, not continued in current turn
Step 4: Wrap-up ─── Completed in the final loop iteration
ScheduleWakeup Calling Specifications
In Claude Code, the way to start a loop is to call ScheduleWakeup:
ScheduleWakeup({
delaySeconds: 60,
reason: "autopilot: starting loop for <brief task description>",
prompt: "<full content of loop-goal, including completion criteria for all phases>"
})
- : Use 60 (minimum) for first launch, adjust as needed later (270 for deployment waits, longer for CI waits)
- : Must contain the complete loop-goal so that the completion status can be re-evaluated each time the loop wakes up
- At the end of each loop iteration, if the loop-goal is not achieved, call ScheduleWakeup again to continue the next iteration
Prohibited Behaviors (Absolutely Not Allowed)
<prohibited-behaviors>
<behavior id="single-turn-execution">
Executing multiple phases consecutively in a single turn without starting a loop.
This is the most common violation pattern: the agent thinks "I can finish it anyway",
so it works from start to finish in one turn, skipping the phased iteration of the loop.
Consequences: Stops when context is full, no automatic continuation; intermediate results pile up in main context accelerating compaction;
Loses cross-iteration recovery capability; maker-checker separation cannot be implemented.
</behavior>
<behavior id="loop-defer">
"Finish these steps first, start the loop when needed".
Loop is not an optional acceleration method, it is the execution skeleton of autopilot.
Must enter loop as soon as the plan is completed, there is no "do a little first then loop".
</behavior>
<behavior id="main-context-execution">
Directly reading and writing large numbers of code files in the main context without dispatching subagents.
The main loop only orchestrates + connects conclusions; actual coding/verification/review are all handled by dispatched subagents.
</behavior>
</prohibited-behaviors>
Self-Check Checklist
Before claiming to enter Step 3 Execution phase, must be able to answer "Yes" to:
If the third item is "No", stop and call ScheduleWakeup now.
Core Principles
These principles come from practical experience in loop engineering and are key to preventing loops from becoming costly empty runs.
<core-principles>
<principle id="state-file">
<name>State File — Agents forget, files don't</name>
Create `progress.md` at the start of each iteration to record completed and pending phases.
Update immediately after each phase is completed. Next iteration resumes from state file instead of starting from scratch.
This is the backbone that allows loops to continue across iterations.
</principle>
<principle id="maker-checker-split">
<name>Maker-Checker Split — The one who writes code can't grade their own paper</name>
The subagent implementing code and the subagent verifying code must be different subagents.
Having the same agent write code then "review" their own code is just a second optimist nodding along.
E2E verification and code review must be performed by independent subagents,
with no access to the reasoning process of the implementing subagent.
</principle>
<principle id="objective-gate">
<name>Objective Gate — Every verification must have a machine-verifiable signal</name>
"Looks okay" is not verification. Verification must have objective pass/fail signals:
- Local verification: tsc exit code 0 + all tests pass
- Deployment verification: gh run status = success
- E2E verification: agent-browser reproduces → phenomenon disappears in test environment
- Review verification: review skill output has no blocking issues
"Verification" without objective signals does not count as completed.
</principle>
<principle id="hard-stop">
<name>Hard Stop — Loops must have brakes</name>
Every loop must have clear stop conditions:
- Success stop: All conditions of loop-goal are met
- Failure stop: 3 consecutive failures in the same phase → report reason and stop
- Safety stop: Iteration limit (default 10 rounds) or token budget exhausted
A loop without brakes will run empty until killed externally — this is not stopping, it's crashing.
</principle>
<principle id="no-ralph-wiggum">
<name>No Ralph Wiggum — No claiming done when only half-completed</name>
Agents may exit the loop early when only half-done ("Looks good enough").
Protective measures:
- Output ✓ PHASE [id] COMPLETE: [objective evidence] after each phase is completed
- Check completion marks of all mandatory phases one by one before loop ends
- Missing mark = Not completed = Exit not allowed
</principle>
<principle id="failure-classification">
<name>Failure Classification — Classify before retrying</name>
When a phase fails, don't blindly loop back to retry the same thing.
Must first classify the failure cause, then choose different repair paths based on classification:
<failure-type id="missing-context">
Missing context/information. Fix: Expand investigation scope, read more code/logs/docs.
</failure-type>
<failure-type id="wrong-approach">
The solution itself is problematic. Fix: Fall back to plan phase, use brainstorming to explore alternative paths.
</failure-type>
<failure-type id="environment-issue">
Environment/configuration/dependency issues (non-code bugs). Fix: Use project debug skill to troubleshoot environment.
</failure-type>
<failure-type id="hallucinated-assumption">
Implemented based on wrong assumptions. Fix: Fall back to investigate, verify assumptions then re-implement.
</failure-type>
<failure-type id="incomplete-output">
Done partially but not completely. Fix: Continue current phase, don't start over.
</failure-type>
<failure-type id="external-blocker">
Blocked by external factors (API unavailable, insufficient permissions, etc.). Fix: Degrade or abort and report.
</failure-type>
Record each failure classification in progress.md to avoid repeating mistakes.
</principle>
<principle id="adaptive-retry">
<name>Adaptive Retry — Retries must change strategy</name>
"More retries ≠ better results. If the system repeats the same behavior, it's not improving, it's just running empty."
Each time looping back to retry, must meet at least one of the following conditions:
- Used a different repair solution
- Obtained new context/information
- Narrowed down the problem scope
- Changed tools or skills
- Corrected previous wrong assumptions
If no different approach can be thought of → Don't retry, abort and report directly:
"Failed N consecutive times in the same way, unable to find new repair paths."
This is far more valuable than running empty and burning tokens.
Failure signature = phase + objective gate + observed failure + failure boundary.
Only when all four are identical does the repeat count accumulate; moving failure points downstream is progressive discovery,
resetting the signature count but continuing to accumulate global budget. See `references/execution-budget.md` for details.
</principle>
<principle id="evidence-ladder">
<name>Evidence Ladder — Clearly state what your "verification" actually proves</name>
Every substantive conclusion must be accompanied by evidence level:
L0 Assumption/code reading → L1 Unit test → L2 Integration test/fixture/construction process
→ L3 Original incident identity or explicit equivalent identity on target environment → L4 Real recurrence observation after deployment.
Iron rule: Never claim "historical root cause confirmed" for L0–L2 evidence.
Making it work after adding a fallback only means the fallback works, not what's wrong with the original path.
Passing L2 with fixtures only can never close a user-reported defect.
Root cause terminology must be precise: confirmed root cause / supported mechanism /
defensive hardening / bounded unknown. See `references/evidence-and-verification.md` for details.
</principle>
<principle id="single-writer">
<name>Single Writer — "Only I'm modifying this repo" is an assumption that must be proven</name>
Often multiple agents and multiple worktrees share the same git repo on the same machine.
Only one maker is allowed to write to the same worktree at any time, and one landing owner to perform
commit/push/release. Must hold an atomic lease on git-common-dir before writing;
stop if exclusive access on this machine cannot be proven.
Use precise file lists only for staging, never `git add -A` / `git add .`;
Never stash / checkout / reset / overwrite others' changes; never force push.
After pushing, must fetch and use `git merge-base --is-ancestor` to read back remote ancestry——
Local commits do not count as delivery. See `references/concurrency-and-landing.md` for details.
</principle>
<principle id="bounded-increment">
<name>Bounded Increment — Only advance one bounded increment per iteration</name>
One iteration = Read checkpoint → Verify ownership and lease → Propose a hypothesis or a phase delta
→ Execute a maker or checker action with objective gate → Record results and strongest evidence
→ Choose a bounded next step or stop.
Do not allow "full investigation + implementation + deployment + review" to be packed into one increment.
Read-only fact collection can be parallelized (when outputs are independent), writing is always single maker.
</principle>
</core-principles>
Platform Adaptation
When autopilot runs on different products, use different loop commands:
<platform-detection>
<platform id="claude-code">
<loop-command>/loop</loop-command>
<goal-command>/loop + custom-paced goal-driven</goal-command>
<description>
Use /loop to drive goal iteration in Claude Code.
/loop supports running at intervals, also supports custom pacing (model decides when to continue if no interval is specified).
</description>
</platform>
<platform id="codex">
<loop-command>/goal</loop-command>
<goal-command>/goal [completion condition description]</goal-command>
<description>
Use /goal to drive goal iteration in Codex.
/goal runs continuously until the stated conditions are met, verified by an independent checker model.
</description>
</platform>
<fallback>
If platform cannot be determined, prefer to try /loop.
Key difference: /goal has independent checker verification (built into Codex),
/loop requires checking completion conditions in the loop body yourself.
</fallback>
</platform-detection>
Workflow Overview
<workflow>
<step id="scope">Rapid investigation to understand what the task actually involves (2-5 minutes)</step>
<step id="plan">Classify task → Break down into XML phases → Select skills → Define loop goal → Initialize state file</step>
<step id="execute">loop/goal (outer layer drives goal) + agent-mode (inner layer dispatches subagents per phase) → Fully unattended throughout</step>
<step id="report">Output wrap-up summary + completion marks for all phases</step>
</workflow>
The user calling autopilot is confirmation itself — no need to show the plan and wait for "go" midway.
Only pause to show the plan if the user explicitly says "let me see the plan first". Execute directly by default.
Reference Navigation (Load by phase, don't load all at start)
| Timing | Load |
|---|
| Task shape templates and investigation checklists | Corresponding section in references/phase-library.md
|
| goal / loop / checkpoint / budget / failure tracking | references/execution-budget.md
|
| Ticket ownership, claim, batch, final state, continuation lease | references/ownership-and-tracker.md
|
| Maker editing / commit / rebase / push / release | references/concurrency-and-landing.md
|
| Test design / E2E / root cause expression / closure criteria | references/evidence-and-verification.md
|
| Delivery, review, rule promotion, final audit | references/learning-and-audit.md
|
Red Flags That Must Stop Execution
- Candidate ticket is draft, , has reservation/valid external lease/takeover, or has evidence of being started;
- Started modifying code without successful claim readback;
- A batch only shares tags/modules/symptoms, no shared precise root cause and same verification chain;
- A second maker or second landing owner appears, or local lease readback is inconsistent;
- Trying to close a user-reported defect with mock/fixture, or claiming historical root cause confirmed with fallback success;
- goal has no proof/constraints/cap, or checkpoint has no bounded next action;
- Same failure signature repeats three times without real strategy change, or A→B→A swings back and forth without new evidence;
- Staging contains out-of-task paths, remote readback does not include delivery SHA, or any force-push tendency appears;
- Wanting to modify authoritative rule files without evidence/eval/independent checker for learning rules.
When hitting a red flag: Write final checkpoint first, then stop. Do not bypass the brake by extending turns, repeating waits or
"one last check".
Step 1: Rapid Scope Definition
Before planning, spend 2-5 minutes figuring out what the task actually involves.
A plan without investigation is a castle in the air — look first, then break down.
1a. Automatic Task Type Classification
Judge type based on user input + investigation findings:
<task-types>
<type id="bug-fix"
signals="fix, broken, not working, issue, error, bug, repair, crash, hung">
Fix known defects. Trace from phenomenon to root cause, cure rather than patch.
</type>
<type id="feature"
signals="add, implement, new, create, add, support, spec, feature">
Add new features or capabilities. From requirement to delivery.
</type>
<type id="refactor"
signals="clean up, refactor, simplify, extract, split, organize, slim">
Improve code structure without changing external behavior.
</type>
<type id="test"
signals="test, coverage, add tests, E2E, verify, test, cover">
Supplement test coverage or verify existing features.
</type>
<type id="research"
signals="investigate, why, investigate, why, what's wrong, troubleshoot, analyze">
Understand problems or technical solutions. Output is conclusion/report rather than code.
</type>
<type id="deploy"
signals="deploy, release, launch, deploy, push, ship, publish">
Deploy code to environment and verify.
</type>
<type id="quality"
signals="review, scan, optimize, quality, check, audit, clean">
Perform quality review and improvement on existing code.
</type>
</task-types>
An input may hit multiple types at the same time (e.g., "fix bug then deploy" = bug-fix + deploy).
In this case, combine corresponding phase templates and sort by natural causal order.
1b. Execute Rapid Investigation
Based on the classified type, get the investigation checklist for that type from
in
references/phase-library.md
and execute it quickly. Output is a brief summary of scope, affected areas and key findings.
For user-reported defects, must also record the precise incident identity (standardized source URL/ID, product ID,
session/task ID, target environment and repair watermark, expected vs actual) in this step.
If it cannot be obtained, clearly mark it as bounded unknown — fixtures can verify connections, but cannot close the defect.
1c. Ticket Ownership Gate (If associated ticket exists, claim first then act)
Multiple agents and people share the same ticket system, "No one is working on this" must be proven:
- Eligibility criteria: OPEN, non-draft, no , no reservation/valid external lease/takeover signal,
no branch/PR/coordination comment proving it has been started. Fail closed in case of ambiguity, keep skipped candidates with zero mutation.
- Existing assignee is only weak intent, not an automatic exclusion condition; but before claiming, must re-read the ticket and
completely replace the assignee set, never append to expired assignees.
- Claim sequence: Re-read → Replace assignee → Add → Write structured claim comment →
Read authoritative from ticket system and fill back then verify by re-reading.
Before successful second re-read, prohibit any implementation-oriented editing, commit, deployment or E2E.
- Maximum 4 items per batch, and must share a precise causal boundary + one implementation + one verification chain.
"All bugs""same tag""adjacent modules""happen to modify the same file" are not enough — if divergent, only do the highest priority one.
Complete contract (including continuation lease, final state invariants, executability classification) can be found in
references/ownership-and-tracker.md
.
Step 2: Break Down into XML Phase Plan
2a. XML Phase Schema
Each plan uses this structure:
xml
<execution-plan>
<task>User's original input (retained as-is)</task>
<type>Classified task types (multiple allowed, comma-separated)</type>
<scope>Summary of actual scope found in investigation (2-3 sentences)</scope>
<loop-goal>
Specific, verifiable completion criteria.
Must cover all sub-problems — cannot stop after only doing the most obvious part.
Must include expected outputs of all mandatory verification phases.
Example: "#442 root cause fix + local verification passed + test deployment green +
E2E passed + review passed + secondary deployment green + secondary E2E passed +
issue closed with commit"
</loop-goal>
<hard-stop>
<max-iterations>10</max-iterations>
<consecutive-fail-limit>3</consecutive-fail-limit>
</hard-stop>
<phases>
<phase id="unique identifier" order="N" mandatory="true">
<skill>Skill used to execute this phase</skill>
<goal>What this phase aims to achieve</goal>
<input>What input is needed</input>
<output>What output is produced</output>
<gate>Objective pass/fail signal (not subjective judgment)</gate>
<done-when>Verifiable completion criteria</done-when>
<on-fail>How to handle failure</on-fail>
</phase>
</phases>
</execution-plan>
2b. Skill Selection
Select skills by phase function. Each phase must be completed via skill, no bare-hand execution allowed.
Skill discovery order:
- First use / to scan skills available in current project and globally
- Prioritize project-level skills (e.g., , , , ) — they contain project-specific rules and context
- Fall back to global skills if no dedicated project skills are available
<skill-matrix>
<mapping phase="Investigation / Root Cause Localization" primary="Project dev skill" fallback="systematic-debugging" />
<mapping phase="External Research / Documentation" primary="context7" also="deep-research, anysearch, agent-reach" />
<mapping phase="Solution Planning" primary="writing-plans" also="planning-with-files, brainstorming" />
<mapping phase="Backend / Logic Implementation" primary="Project dev skill" fallback="Direct coding (when no skills available)" />
<mapping phase="Frontend / UI Implementation" primary="frontend-design" also="shadcn-ui" />
<mapping phase="Local Verification" primary="Project test skill" fallback="Direct run tsc + test" />
<mapping phase="Deployment" primary="Project debug/deploy skill" fallback="gh-cli + manual push" />
<mapping phase="E2E Verification" primary="Project test skill" also="agent-browser" />
<mapping phase="Code Review" primary="Project review skill" fallback="simplify, code-review" />
<mapping phase="Deep Review" primary="thermo-nuclear-code-quality-review" also="" />
<mapping phase="Issue Management" primary="gh-cli" also="" />
</skill-matrix>
Note: "Project dev/test/debug/review skill" refers to skills matching the function under
of the current project.
For example, Kollab project has
,
,
,
;
other projects may have
,
or none — use fallback in that case.
2c. Feature Completeness Checklist (Mandatory for feature type)
For feature-type tasks, must check each item in
<feature-completeness-checklist>
from
references/phase-library.md
during design phase. Historical lessons: Share button went online but
share page rendering was inconsistent, user theme settings lost on refresh due to useState-only, public pages had no SEO——
All because "Make it work first, leave the rest for later". The checklist covers five dimensions:
- Multi-surface consistency: All surfaces of the same feature must be completed in the same PR or closed via flag-gate
- Setting persistence: User-adjustable items must be persisted, useState-only is prohibited
- Public page infrastructure: Public URLs must have title/OG tags/reasonable loading states
- Data integrity: Frontend and backend fields must flow end-to-end
- Cross-functional impact: Evaluate impact of new surfaces on navigation/permissions/downstream consumption
Mark each item as Pass/N/A/Not done this time (flag-gated), no blank entries allowed.
Mark N/A for inapplicable items and briefly explain the reason; applicable items not done this time must be feature-flagged off
and recorded in "Uncompleted Items" in progress.md.
2d. Mandatory Phase Rules
For any task type involving code changes (bug-fix / feature / refactor / quality),
must include the following phases, no omission allowed:
<mandatory-phases for="code-change">
<phase-ref>implement — Implementation (via project dev skill or direct coding)</phase-ref>
<phase-ref>local-verify — Local verification (tsc / lint / test, objective gate)</phase-ref>
<phase-ref>deploy-1 — First round deployment to test environment (via project deploy skill or gh-cli)</phase-ref>
<phase-ref>e2e-1 — First round E2E verification (via project test skill + agent-browser, independent subagent)</phase-ref>
<phase-ref>review — Code review (via project review skill or simplify + code-review, independent subagent)</phase-ref>
<phase-ref>deploy-2 — Second round deployment (after review changes)</phase-ref>
<phase-ref>e2e-2 — Second round E2E verification (independent subagent)</phase-ref>
</mandatory-phases>
All autopilot tasks (including research / deploy / quality) must also include the following phases as the last
mandatory phase. It must be included in loop-goal, not remembered temporarily during reporting:
<mandatory-phases for="all-autopilot">
<phase-ref>issue-finalize — When there is an associated Issue, write complete implementation records, final solution, verification evidence and user-visible effects, and close or retain according to real final state</phase-ref>
<phase-ref>cleanup — Clean up temporary files, diagnostic products, independent worktree and temporary branches created by this task, and use Git status to prove no task residues</phase-ref>
</mandatory-phases>
Reasons for these phases:
<phase-justification id="e2e">
Local tests only verify logical correctness. After deployment, performance may differ due to environment differences, configuration missing, migration omissions.
E2E is the only link that can prove "really fixed" from the user's perspective.
Even if you are 100% sure the fix is correct, you must run it — certainty itself is a risk.
Historically, there have been multiple incidents where "all local tests pass, but deployment fails".
E2E judgment must be based on runtime evidence chain (log marker / data row / metrics of the new link itself),
cannot only look at surface success — when a link with silent fallback breaks, the function still responds, only logs can expose it.
Three supporting rules:
- Permission scope of external credentials (model/interface allowlist of gateway key, scope of API key, quota)
is a configuration surface independent of code: Code + deployment completion does not mean credentials are ready; when changing the call target, must check credential permissions in all environments in the same task,
passing test does not mean prod credentials are also ready.
- Empty catch / catch without logging for external calls is a defect not a style issue: It turns configuration drift into
invisible degradation. Must add queryable log marker when found.
- Add monitoring points before verifying a link — adding monitoring often exposes previously silent failures on the spot
(real case: A gateway call returned 401 for six weeks, was discovered the day latency logs were added).
</phase-justification>
<phase-justification id="review">
Implementers have blind spots: Missing comments make it hard for others to troubleshoot links,
compatibility vulnerabilities break others' code when merged, excessive changes make impact scope out of control.
Review is the last line of defense to intercept online accidents in advance.
Historically, the most serious accidents often come from changes "too small to need review".
</phase-justification>
<phase-justification id="deploy-2-and-e2e-2">
Changes in review phase (simplify refactoring, comment supplement, code problem fixing) may introduce new issues.
Second round deployment + verification ensures review changes do not break anything.
Skipping = Treating unverified review changes directly as final output.
</phase-justification>
2d-1. Lane Selection (Determine Phase Order)
Select lane by
runtime consumer, not by file name. Fail closed to
if unsure.
text
local-only (All change consumers are within locally fully executable boundaries, backend/contract/env/migration/runtime prompt all unchanged):
investigate → design(when feature) → implement → local-verify → e2e-1(local full journey)
→ deploy-1(push only) → review → Decide e2e-2 / deploy-2 based on impact classification → deliver
deployed-required (Any backend/h混合 consumer, API contract, migration, env/secret/deployment configuration,
runtime-loaded prompt/skill, authentication callback, SSR/edge, remote-specific behavior, or any uncertainty):
investigate → design(when feature) → implement → local-verify → deploy-1(push + deploy)
→ e2e-1(target environment) → review → Decide deploy-2 / e2e-2 based on impact classification → deliver
2d-2. Post-Review Impact Classification (Determine deploy-2 / e2e-2 form)
Classify by actual impact scope of diff after review, not mindlessly rerun the whole round, nor randomly skip:
| Diff Classification | deploy-2 / e2e-2 |
|---|
| (no changes in review) | Both N/A, reuse reviewed SHA |
| Run a named alternative gate (structure check/eval), final push, no wait for deployment |
| Rerun affected test partitions, final push, no wait for deployment |
| Frontend code diff (local-only lane) | Rerun local check + targeted tests + independent local E2E, then final push |
| Any backend/runtime/uncertain diff | Upgrade to deployed-required: Final push → Deploy → Run affected E2E |
Write classification conclusion and basis into progress.md. Delivery is still executed by the same landing owner,
code changes are routed back to maker — checker does not commit or push.
2e. Assemble Phases
- Load corresponding phase template from
references/phase-library.md
- Fill specific content of each with investigation findings (Step 1)
- Add all mandatory-phases (if not in template)
- Template is a skeleton not a shackle — can add phases according to actual situation, but cannot delete mandatory phases
- Feature type: Confirm that the solution file produced in design phase contains item-by-item judgment of feature-completeness-checklist
2f. Initialize State File
markdown
# Autopilot Progress
## Task
[User's original input]
## Type
[Task type]
## Loop Goal
[Content of loop-goal]
## Budgets
|-----------|---------------|---------|--------|---------------|
| 0/10 | 0/6 | 0/240m | 0/… | 0/0 |
## Phase Status
|-------|----------|-------|---------------|----------------|--------|-----------------------------------|
| 1 | ... | ... | ... | ... | ⏳ | |
## Acceptance Ledger
(For multiple target items/tickets, accept each item independently — no batch closing allowed)
|----|---------|---------|--------------|---------|---------|
## Delivery Ledger
(Each delivery SHA appears exactly once, with its precise diff path; local commits do not count as delivery)
|-------------|-------------|-------------------|
## Failure Log
(Record each failure here — not a retrospective log, but an action memory to avoid repeating mistakes)
Failure signature = phase + objective gate + observed failure + failure boundary; count accumulates only when all four are identical.
One-time shell quote/spelling/harness transient errors are orchestration diagnostic, not counted in repair cycle.
|-----------|-------------------|-------------|----------------|---------------|-------------------|--------|
## Telemetry
(Record only summary per iteration, do not paste full agent output)
Number of spawned/reused/closed agents | Number of maker/checker | Routine/critical routing and upgrade reasons |
Number of waits and status checks | Number of context compactions
## Lessons Learned
(Reusable experience accumulated across iterations, one sentence each)
- [Example] phase implement: This module's tsc requires tsconfig.build.json instead of default tsconfig
- [Example] phase e2e: Test environment test account credentials are in project test skill, don't guess
## Iterations
(Brief summary of each iteration)
Update Status column (⏳ → ✅) and Evidence column immediately after each phase is completed.
Update Failure Log immediately after each failure.
Record reusable experience found across iterations into Lessons Learned.
2g. Define Loop Goal (Goal Contract)
Synthesize a verifiable loop goal from
of all phases.
Only one active goal per task, no separate goals for phases, retries or subagents.
Keep objective within 1-3 sentences, 600 characters, must include five parts:
- Measurable end state — Precise product/ticket final state
- Proof — Named objective gate and required evidence level (L2 or L3)
- Constraints — Ownership, privacy, branch, cost, environment, release boundaries
- Caps — Number of iterations / repair cycles / elapsed time / tokens / approved external costs
- Stop phrase — Attach verbatim at the end of objective:
Stop after <max-iterations> iterations or <max-repair-cycles> repair cycles, whichever comes first.
Stop phrase must be written into the goal text itself: Independent checker only reads goal text,
if upper limits are not in goal, it means this loop has no brakes for the checker.
Default budget: 10 iterations / 6 repair cycles / 240min elapsed / 0 external costs (unless approved).
Do not raise any upper limit without authorization during operation.
Phase table, general rules, acceptance matrix are written into
,
not copied into objective——
goal is an end statement, not a second plan document. Complete budget contract can be found in
references/execution-budget.md
.
Step 3: Execution
3a. Start Loop (Mandatory Block Gate — See "Loop Enforcement Rules")
This step is a hard prerequisite for execution, not optional. After Step 2 is completed and before any actual phase work starts, this step must be completed first.
Use corresponding command according to platform:
<loop-start>
<claude-code>
Call ScheduleWakeup to start loop:
```
ScheduleWakeup({
delaySeconds: 60,
reason: "autopilot: starting loop for <task summary>",
prompt: "<complete loop-goal, paste verbatim content defined in Step 2g>"
})
```
End current turn immediately after calling. Do not continue phase work after calling ScheduleWakeup.
All subsequent phase work is performed in loop callbacks.
</claude-code>
<codex>
Call /goal, condition = loop-goal defined in Step 2g.
Codex's independent checker model verifies completion conditions.
</codex>
</loop-start>
Behavior after calling: After calling ScheduleWakeup, the only allowed action in current turn is to output a confirmation to the user:
"Autopilot loop started, goal: <loop-goal summary>." Then end the turn and wait for loop wakeup.
Behavior in each loop callback:
- Read progress.md to restore state
- Confirm current uncompleted phases
- Use Agent tool to dispatch subagent to execute current phase
- Update progress.md based on subagent results
- If loop-goal is not achieved, call ScheduleWakeup to continue next iteration
- If loop-goal is achieved, enter Step 4 wrap-up
3b. Loop + Agent-Mode Iron Rules
These two must be used in pairs throughout the process, neither can be missing:
- loop/goal (outer layer): Iterate around , do not stop until achieved
- agent-mode (inner layer): Turn each phase into self-contained brief and dispatch to subagent for execution
Execution topology:
loop-goal = completion criteria defined by <loop-goal>
├── iteration 1
│ ├── agent-mode → phase 1 (investigate) [maker subagent]
│ ├── agent-mode → phase 2 (implement) [maker subagent]
│ ├── agent-mode → phase 3 (deploy) [maker subagent]
│ ├── agent-mode → phase 4 (e2e verify) → FAIL [checker subagent ≠ maker]
│ └── loop back to phase 2
│ (Update progress.md)
├── iteration 2
│ ├── agent-mode → phase 2 (re-implement)
│ ├── agent-mode → phase 3 (deploy)
│ ├── agent-mode → phase 4 (e2e verify) → PASS [checker subagent]
│ ├── agent-mode → phase 5 (review) [checker subagent ≠ maker]
│ └── ...continue subsequent phases
│ (Update progress.md)
└── All mandatory phases ✅ + loop-goal achieved → End
3c. Subagent Dispatch Rules
<subagent-rules>
<rule id="self-contained-brief">
Turn each subagent task into self-contained English brief——
Subagents have no main loop context, must write everything they need into the brief.
</rule>
<rule id="model">
Select available native subagent models according to current host platform, do not treat an external CLI as a review prerequisite.
**`model` parameter must be explicitly passed every time, never omitted**——Omission means inheriting main thread model,
which is often the most expensive available one, this is an accident that has actually happened.
**Claude environment: Default to cheapest sufficient tier, i.e., `sonnet`.**
Only upgrade to `opus` when the task really requires it (deep architecture reasoning, adversarial review of subtle logic),
and explain why in the same message. Stages like investigation, file reading, command running, layout measurement, link checking, reporting
all use `sonnet` by default. **Do not translate Codex's "high reasoning configuration" below directly**:
That is a value for Codex side, not "pick the most expensive one on any platform".
Two known limitations on Claude side, clarify to avoid false reports:
- `model` only accepts **four tier aliases: `sonnet` / `opus` / `haiku` / `fable`,
no version granularity**, so specific versions like "Opus 4.8" cannot be pinned in tool calls;
To set a specific version as permanent default, that's the application's own model configuration, not set here.
- **`Agent` tool has no reasoning-effort parameter at all** (only `agent()` inside `Workflow` has `effort`). So "all subagents enable medium reasoning" cannot be enforced per time,
reasoning tier is a session-level setting. **Do not claim to have set effort for a subagent.**
In Codex environment, default to Codex subagent; stages involving implement, E2E, review or quality audit
must use `model="gpt-5.6-terra"` + `reasoning_effort="high"`.
Common bottom line for both sides: **Cost can be reduced, independent review cannot be omitted**——
Do not skip maker-checker separation because model tier is low or a certain CLI is unavailable.
</rule>
<rule id="maker-checker-separation">
Implementation-type phases (investigate / implement / plan) = maker subagent.
Verification-type phases (e2e / review / quality audit) = checker subagent.
Checker subagent cannot access maker's reasoning process——
Only give it code diff, deployment URL and verification standards, let it judge independently.
This is the core mechanism to prevent "grading your own paper".
</rule>
<rule id="context-hygiene">
Main loop only orchestrates, connects conclusions, makes key decisions.
Hand over large files/logs/diffs to subagents for reading, only return conclusions——
Do not pile content that subagents should digest into main context.
</rule>
<rule id="skill-first">
Confirm the skill to use before each phase starts, complete via skill, no bare-hand execution.
Must call using-superpowers once at the start of each iteration.
Specialized skills are discovered and loaded only once per task, write the selection into progress.md for reuse in subsequent phases.
</rule>
<rule id="agent-budget">
Count budget by "number of different agents", prioritize reusing original agents for repair cycles (same agent across multiple rounds does not count repeatedly):
Bounded docs/research/verify-only = 2; single subsystem code change = 3;
Cross-system or multi-repo code change = 4 (max two non-overlapping makers).
When needing to exceed budget, first close completed agents, and record missing capabilities,
why cannot reuse, new roles and objective end conditions in progress.md——"Want to confirm again" is not a reason.
When maker returns fixable findings, send narrow fixes back to the same maker, checker only re-judges does not take over implementation.
</rule>
<rule id="wait-budget">
Only wait if next step is blocked by the result, otherwise proceed immediately with non-overlapping work.
Maximum 90-120 seconds blocking wait per delegation result, do not initiate second wait immediately after timeout.
Perform status check at most once more after completing other work; if still no progress, narrow brief to reuse/interrupt original agent,
or close it and complete by main thread. Prohibit continuous wait / enumerated polling / short-cycle polling.
CI/deployment waits use another set of throttling (5 minutes delay first, 3-5 minutes once for core services,
5-10 minutes once for side services, pull logs only when failed), do not mix with this budget.
</rule>
</subagent-rules>
3d. Phase Completion Tracking
After each phase is completed, must:
- Output completion mark:
✓ PHASE [id] COMPLETE: [one-sentence objective evidence]
- Update corresponding line in
- Check if next phase can be entered
If real objective evidence cannot be written, it means the phase is not completed and must continue.
Perform final check before loop ends:
- Check status of all mandatory phases in progress.md one by one
- All mandatory phases must be ✅
- Missing any = Not completed = Exit loop not allowed
3e. Failure Handling
When a phase fails, must handle in this order — cannot skip classification and retry directly:
<failure-protocol>
<step order="1">
Classification: Judge failure type according to failure-classification in core-principles
(missing-context / wrong-approach / environment-issue /
hallucinated-assumption / incomplete-output / external-blocker)
</step>
<step order="2">
Record: Write classification of this failure, what was tried, why it failed into Failure Log in progress.md
</step>
<step order="3">
Check Adaptive Retry condition: Can a different approach be proposed than last time?
Yes → Enter step 4. No → Enter step 5.
</step>
<step order="4">
Retry according to classification path:
- missing-context → Expand investigation (project debug skill checks remote logs / deep-research)
- wrong-approach → Fall back to plan phase, brainstorming to explore alternative solutions
- environment-issue → Project debug skill troubleshoots environment configuration, or manual check
- hallucinated-assumption → Fall back to investigate to verify assumptions
- incomplete-output → Continue current phase (do not start over)
- external-blocker → Degrade (feature flag off + issue leave explanation)
</step>
<step order="5">
Abort conditions (stop if any triggered):
- Same phase fails 3 consecutive times and strategy changed each time
- Reached iteration limit (default 10 rounds)
- Encountered external-blocker and no degradation path
→ Stop loop, output: All tried solutions + reason for each failure + suggested next steps
</step>
</failure-protocol>
3f. Project Rules
Automatically comply with all rules in current project's CLAUDE.md / AGENTS.md during execution.
autopilot does not hardcode project rules — it reads the project's rule files during Step 1 investigation phase,
then complies during execution.
General reminders (applicable to most projects):
- If project has comment specifications, comply
- If project has i18n requirements, synchronize all languages
- Fetch + rebase before committing to protected branches
- Only commit your own files with pathspec
- Do not watch deployment for long time in foreground
- Tasks must be self-contained for delivery
Step 4: Wrap-Up Cleanup + Report
4a. Issue Finalization Gate (CRITICAL · Cannot claim completion if not passed when there is associated Issue)
When task has associated GitHub/GitLab/Jira Issue, must complete Issue wrap-up before cleaning worktree. Issue is the team's
long-term record to understand "why change, how to change, what actually happened in the end", cannot only leave
, nor let
key implementation evidence only exist in temporary
, chat records or local screenshot directory.
When delivery is successful, use project Issue tool (prefer
for GitHub) to write a structurally complete final comment, at least including:
- Problem and Root Cause: Phenomenon encountered by user, finally confirmed root cause, and important assumptions falsified during investigation.
- Implementation Plan: List actual fixes implemented by component/link, explain key design choices and why this solution was adopted.
- Change Location: Final commit hash, target branch, key files or migrations; list responsibilities of each commit when multiple commits exist.
- Verification Evidence: Local test commands and results, deployment environment, workflow run URL/head SHA, E2E scenarios and results,
independent review conclusion; cannot write canceled, failed or unexecuted verification as passed.
- Final Presentation Effect: Describe real behavior after fix from user's perspective. Attach final screenshots, artifacts,
pages or accessible evidence links when involving UI/products; attach safely public responses, data or log marker summaries when involving API/backend links.
- Scope and Follow-Up: Clearly state completed content, untouched environments (e.g., production), known limitations and actions still requiring external decisions;
Specific issues beyond task scope must link to independent follow-up Issue, cannot hide in comments.
Comments must not contain secrets, tokens, cookies, complete user privacy data or temporary absolute paths only accessible on local machine. Prefer to write a
complete final summary, avoid creating noise with multiple scattered comments.
After writing successful task completion comment, close Issue according to project rules, remove
, and re-read Issue to verify:
- Status is indeed closed/done;
- Final comment contains precise commit hash;
- Deployment/E2E/review evidence and final effect have been recorded;
- Duplicate or sibling Issues have been cross-referenced and handled according to real status.
If task hard-stops, degrades or is incomplete: Do not close Issue. Must leave investigation conclusions, current blockers, tried solutions and next steps,
and release or retain assignee/
according to project rules. Mark
when no associated Issue and explain
"No Issue found or required to be created at task start", do not create meaningless Issue to meet format requirements.
Only after re-read Issue status and comment content pass inspection, allow output
✓ PHASE issue-finalize COMPLETE: <issue URL + commit + evidence summary>
.
4b. Cleanup Gate (CRITICAL · Cannot claim completion if not passed)
After task code, deployment, E2E and review are all completed, must execute cleanup phase.
is temporary state for recovery,
not a repo deliverable; leaving it and diagnostic files in repo root after task ends means the task has not really closed.
Execute in the following order, cannot reverse:
-
First prove results will not be lost
- Run
git status --short --untracked-files=all
- When there are code changes, confirm task commits have been pushed to target remote branch; for example, when target is ,
git log origin/test..HEAD
git merge-base --is-ancestor <task-commit> origin/test
- When valid but unpushed commits are found, push/rebase according to project protected branch rules first, then clean up.
If cannot push, must hard-stop and retain worktree, report rescue path; never delete results for "cleanup".
-
Clean up all task-owned temporary files and products
- Delete , task-specific , temporary plan/state files.
- Delete one-time diagnostic scripts, , , log exports, downloaded workflow artifacts,
temporary screenshots, test outputs, scratchpad content and other files generated only for this round of investigation/verification.
- Deliverables explicitly requested by user, formal tests, formal documents and replayable evidence included in commits are not temporary products, must be retained.
- Only delete paths proven to be created by this task; prohibit using broad glob or deleting untracked files of other concurrent tasks/users.
- is deleted last, because it is still needed to restore scene if previous cleanup fails.
-
Clean up isolated worktree and temporary branches
- Only clean up independent worktree created by this task, never delete shared main working directory.
- Run
git worktree remove "$WORKTREE_DIR" --force
- Mark N/A explicitly when no independent worktree is created, do not delete current worktree to meet format requirements.
-
Objectively review cleanup results
- Run
git status --short --untracked-files=all
- and must no longer show task worktree/temporary branch.
- Others' changes can remain, but must be clearly marked as not owned by this task in report, cannot delete without permission.
Only after all four steps pass, allow output
and enter final report.
4c. Review and Rule Promotion (Mandatory for each task, including those that run smoothly)
Review records: What evidence changed the plan, which gate caught real defects, whether conclusion is task-specific or generalizable,
whether it is already covered by rules, whether promotion is valid.
Do not force promotion just to fill numbers——
+ a reason is a legal and necessary result.
Promotion to persistent rules (skill / project rule files) must meet all of the following: Direct privacy and security evidence from real tasks,
generalizable, with objective gate, with eval that fails before rule and passes after rule,
independent checker has verified scope and non-duplication, and rule+eval+doc are in
the same delivery commit.
Designate unique source of truth by responsibility and
replace it, do not append parallel rules to entry files.
Complete promotion gate can be found in
references/learning-and-audit.md
.
4d. Final Audit Sequence (Execute item by item before claiming completion)
- Each planned phase is completed or has well-justified N/A;
- Each target item/ticket has independent incident identity, evidence, comment and final state decision (read via one authoritative snapshot);
- Each delivery SHA is ancestor of target remote branch, and attributed in Delivery Ledger;
- Diff of each delivery commit falls within precise file list, each file in list is covered,
no residual task-owned uncommitted diff or unpushed commit;
- At least one learning decision has gone through promotion gate, been rejected with reason, or marked as run-specific;
- Run structure check if skill is modified;
- Only after all non-goal audits pass, mark goal as completed and read back final state.
Never take a subagent's "done" as audit evidence.
4e. Wrap-Up Report
Output concise summary after execution is completed:
<report-template>
<item>Execution route (phase → selected skill → result)</item>
<item>Loop goal + achievement status</item>
<item>List of changed files (including cross-repo)</item>
<item>Deployment / verification conclusion (if applicable)</item>
<item>Commit hash</item>
<item>Issue final record: URL, closure status, review conclusion that implementation plan/verification evidence/final effect have been filled back (if applicable)</item>
<item>List of ✓ completion marks for all phases</item>
<item>Cleanup evidence: Temporary files/products cleaned up, worktree/temporary branch deleted or N/A, remote commits confirmed</item>
<item>Number of iterations + failure backtracking records</item>
<item>Uncompleted items + reasons (if any)</item>
</report-template>