autopilot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Autopilot

接收一句话，自动拆解成结构化执行计划，然后以无人值守模式完整执行到底。

用户调用 autopilot 意味着：授权 AI 完全自主地完成整套流程—— 调查、实现、部署、E2E 验证、代码 review、二次部署、二次验证、收尾。不需要中途确认，不允许跳过任何阶段，不允许半途而废。

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

来源：Skills.sh

bash

undefined

Source: Skills.sh

bash

undefined

首次全局安装，或更新失败时重新安装

First-time global installation, or reinstall when update fails

npx skills add yan-labs/yan-skills --skill autopilot -g -y

将已安装的全局 Skill 更新到最新版

Update the installed global Skill to the latest version

npx skills update autopilot -g -y


若使用项目级安装，去掉安装命令中的 `-g`；项目级更新使用 `npx skills update autopilot -p -y`。

接收一句话，自动拆解成结构化执行计划，然后以无人值守模式完整执行到底。

用户调用 autopilot 意味着：**授权 AI 完全自主地完成整套流程**——
调查、实现、部署、E2E 验证、代码 review、二次部署、二次验证、收尾。
不需要中途确认，不允许跳过任何阶段，不允许半途而废。

---

npx skills update autopilot -g -y


For project-level installation, remove the `-g` 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 强制执行规则 (CRITICAL · 最高优先级)

Loop Enforcement Rules (CRITICAL · Highest Priority)

调用 autopilot = 必须启动 loop。没有例外。

这条规则的优先级高于一切其他考量。不管任务看起来多简单、多紧急、多"显然可以一口气做完"， autopilot 的执行模型就是 loop + agent-mode，不是"在单次 turn 里连续做完所有事情"。

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

Step 2（计划）完成后、第一行实现代码之前，必须调用 ScheduleWakeup 启动 loop。这是一个不可跳过的检查点：

Step 1: 快速调查 ─── 可以在当前 turn 内完成
Step 2: 拆解计划 ─── 可以在当前 turn 内完成
                ╔══════════════════════════════════════════════╗
                ║  ⛔ GATE: 必须在这里调用 ScheduleWakeup     ║
                ║  传入 loop-goal 作为 prompt                  ║
                ║  不调用 = 不允许进入 Step 3                   ║
                ╚══════════════════════════════════════════════╝
Step 3: 执行 ─── 在 loop 回调中执行，不是在当前 turn 中继续
Step 4: 收尾 ─── 在最后一次 loop 迭代中完成

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 调用规范

ScheduleWakeup Calling Specifications

在 Claude Code 中，启动 loop 的方式是调用 ScheduleWakeup：

ScheduleWakeup({
  delaySeconds: 60,
  reason: "autopilot: starting loop for <简短任务描述>",
  prompt: "<loop-goal 的完整内容，包含所有 phase 的完成判定>"
})

```
delaySeconds
```
: 首次启动用 60（最短），后续按实际需要调整（等部署用 270，等 CI 用更长）
```
prompt
```
: 必须包含完整的 loop-goal，这样每次 loop 唤醒时都能重新评估完成状态
每轮 loop 结束时，如果 loop-goal 未达成，再次调用 ScheduleWakeup 继续下一轮

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>"
})

```
delaySeconds
```
: Use 60 (minimum) for first launch, adjust as needed later (270 for deployment waits, longer for CI waits)
```
prompt
```
: 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"> 在单次 turn 里连续执行多个 phase 而不启动 loop。这是最常见的违规模式：agent 觉得"反正都能做完"，就在一个 turn 里从头干到尾，跳过了 loop 的分阶段迭代。后果：context 满了就停，不会自动续；中间结果堆主 context 加速 compaction；失去跨迭代恢复能力；maker-checker 分离无法实施。 </behavior> <behavior id="loop-defer"> "先做完这几步，等需要的时候再启动 loop"。 loop 不是可选的加速手段，它是 autopilot 的执行骨架。 Plan 一完成就必须进入 loop，不存在"先做一点再 loop"。 </behavior> <behavior id="main-context-execution"> 在主 context 里直接读写大量代码文件而不派 subagent。主循环只编排 + 串结论；实际 coding/验证/review 全部派 subagent。 </behavior> </prohibited-behaviors>

<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

在声称进入 Step 3 执行阶段之前，必须能回答"是"：

progress.md 已创建且包含所有 phase 的初始状态 ⏳？
loop-goal 已定义且可客观判定？
ScheduleWakeup 已调用（不是"打算调用"，是"已经调用了"）？
当前 turn 没有开始执行任何 phase 的实际工作？

如果第三项是"否"，停下来，现在就调用 ScheduleWakeup。

Before claiming to enter Step 3 Execution phase, must be able to answer "Yes" to:

progress.md has been created and contains initial status for all phases ⏳?
loop-goal has been defined and can be objectively determined?
ScheduleWakeup has been called (not "planning to call", but "already called")?
No actual work of any phase has started in the current turn?

If the third item is "No", stop and call ScheduleWakeup now.

核心原则

Core Principles

这些原则来自 loop engineering 的实战经验，是防止 loop 变成烧钱空转的关键。

<core-principles> <principle id="state-file"> <name>State File — agent 会遗忘，文件不会</name> 每轮开始时创建 `progress.md` 记录已完成和待完成的阶段。每个 phase 完成后立即更新。下次迭代从 state file 恢复而非从零开始。这是 loop 能跨迭代续跑的脊柱。 </principle> <principle id="maker-checker-split"> <name>Maker-Checker Split — 写代码的不能自己判卷</name> 实现代码的 subagent 和验证代码的 subagent 必须是不同的 subagent。同一个 agent 写完代码再"review"自己的代码，只是第二个乐观主义者在点头。 E2E 验证、代码 review 必须由独立的 subagent 执行，不接触实现 subagent 的推理过程。 </principle> <principle id="objective-gate"> <name>Objective Gate — 每个验证必须有机器可判定的信号</name> "看起来没问题"不是验证。验证必须有客观的 pass/fail 信号： - 本地验证：tsc 退出码 0 + test 全绿 - 部署验证：gh run 状态 = success - E2E 验证：agent-browser 在 test 环境复现→现象消失 - Review 验证：review skill 输出无 blocking issue 没有客观信号的"验证"不算完成。 </principle> <principle id="hard-stop"> <name>Hard Stop — loop 必须有刹车</name> 每个 loop 必须有明确的停止条件： - 成功停止：loop-goal 的所有条件满足 - 失败停止：连续 3 次同一阶段失败 → 报告原因并停止 - 安全停止：iteration 上限（默认 10 轮）或 token 预算耗尽没有刹车的 loop 会空转到被外部杀掉——这不是停止，是崩溃。 </principle> <principle id="no-ralph-wiggum"> <name>No Ralph Wiggum — 不允许半完成就声称 done</name> agent 可能在只完成了一半的时候提前退出 loop（"看起来差不多了"）。防护措施： - 每个 phase 完成后输出 ✓ PHASE [id] COMPLETE: [客观证据] - loop 结束前逐一核对所有 mandatory phase 的完成标记 - 缺标记 = 未完成 = 不允许退出 </principle> <principle id="failure-classification"> <name>Failure Classification — 先分类再重试</name> phase 失败时不能盲目 loop 回去重试同样的事情。必须先分类失败原因，然后根据分类选择不同的修复路径：

<failure-type id="missing-context">
  缺少上下文/信息。修复：扩大调查范围，读更多代码/日志/文档。
</failure-type>
<failure-type id="wrong-approach">
  方案本身有问题。修复：回退到 plan 阶段，用 brainstorming 探索替代路径。
</failure-type>
<failure-type id="environment-issue">
  环境/配置/依赖问题（非代码 bug）。修复：用项目 debug skill 排查环境。
</failure-type>
<failure-type id="hallucinated-assumption">
  基于错误假设实现。修复：回退到 investigate，验证假设再重新实现。
</failure-type>
<failure-type id="incomplete-output">
  做了一部分但不完整。修复：继续当前 phase，不要从头开始。
</failure-type>
<failure-type id="external-blocker">
  被外部因素阻塞（API 不可用、权限不足等）。修复：降级或中止并报告。
</failure-type>

记录每次失败的分类到 progress.md，防止重蹈覆辙。

</principle> <principle id="adaptive-retry"> <name>Adaptive Retry — 重试必须改变策略</name> "更多次重试 ≠ 更好的结果。如果系统重复相同的行为，它不是在改进，它只是在空转。"

每次 loop 回去重试时，必须满足以下条件之一：
- 使用了不同的修复方案
- 获取了新的上下文/信息
- 缩小了问题范围
- 换了工具或 skill
- 修正了之前的错误假设

如果想不出任何不同的做法 → 不要重试，直接中止并报告：
"连续 N 次以相同方式失败，无法找到新的修复路径。"
这比空转烧 token 有价值得多。

失败签名 = phase + 客观 gate + 观察到的失败 + 失败边界。
只有四项全同才累加重复计数；失败点向下游移动是 progressive discovery，
重置该签名计数但全局预算继续累计。详见 `references/execution-budget.md`。

</principle> <principle id="evidence-ladder"> <name>Evidence Ladder — 说清楚你的"验证"到底证明了什么</name> 每条实质性结论都必须带证据等级： L0 假设/读代码 → L1 单测 → L2 集成测试/fixture/构造流程 → L3 目标环境上的原始事故身份或显式等价身份 → L4 部署后真实复发观测。

铁律：绝不能把 L0–L2 说成"历史根因已证实"。
加了兜底之后跑通了，只说明兜底生效，不说明原路径坏在哪。
fixture-only 的 L2 通过永远不能关闭一个用户报告的缺陷。

根因用词必须精确：confirmed root cause / supported mechanism /
defensive hardening / bounded unknown。详见 `references/evidence-and-verification.md`。

</principle> <principle id="single-writer"> <name>Single Writer — "只有我在改这个仓库"是必须被证明的假设</name> 同一台机器上经常有多个 agent、多个 worktree 共享同一个 git 仓库。任何时刻只允许一个 maker 写同一个工作树、一个 landing owner 做 commit/push/发布。写入前必须持有 git-common-dir 的原子租约；证明不了本机独占就停止。

staging 只用精确文件清单，绝不 `git add -A` / `git add .`；
绝不 stash / checkout / reset / 覆盖别人的改动；绝不 force push。
push 后必须 fetch 并用 `git merge-base --is-ancestor` 回读远端 ancestry——
本地 commit 不算交付。详见 `references/concurrency-and-landing.md`。

</principle> <principle id="bounded-increment"> <name>Bounded Increment — 每轮只推进一个有界增量</name> 一轮迭代 = 读 checkpoint → 校验归属与租约 → 提出一个假设或一个 phase delta → 执行一个带客观 gate 的 maker 或 checker 动作 → 记录结果和最强证据 → 选择一个有界的下一步或停止。

不允许把"调查全部 + 实现 + 部署 + review"塞进一个增量。
只读的事实收集可以并行（输出互不依赖时），写入永远单 maker。

</principle> </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

autopilot 运行在不同产品上时，使用不同的 loop 命令：

<platform-detection> <platform id="claude-code"> <loop-command>/loop</loop-command> <goal-command>/loop + 自定步调目标驱动</goal-command> <description> Claude Code 中使用 /loop 驱动目标迭代。 /loop 支持按间隔运行，也支持自定步调（不指定间隔时 model 自行决定何时继续）。 </description> </platform> <platform id="codex"> <loop-command>/goal</loop-command> <goal-command>/goal [完成条件描述]</goal-command> <description> Codex 中使用 /goal 驱动目标迭代。 /goal 持续运行直到声明的条件成立，由独立的 checker model 验证完成。 </description> </platform> <fallback> 如果无法确定平台，优先尝试 /loop。关键区别：/goal 有独立 checker 验证完成（Codex 内建）， /loop 需要自己在 loop body 里检查完成条件。 </fallback> </platform-detection>

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">快速调查，理解任务实际涉及什么（2-5 分钟）</step> <step id="plan">分类任务 → 拆解为 XML 阶段 → 选 skill → 定 loop 目标 → 初始化 state file</step> <step id="execute">loop/goal（外层驱动目标）+ agent-mode（内层按阶段派 subagent）→ 全程无人值守</step> <step id="report">输出收尾总结 + 所有 phase 完成标记</step> </workflow>

用户调用 autopilot 本身就是确认——不需要中途展示计划等"go"。如果用户明确说"先让我看看计划"，才暂停展示。默认直接执行。

<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 导航（按 phase 加载，不要在开始时全部加载）

Reference Navigation (Load by phase, don't load all at start)

时机	加载
任务形态模板与调查清单	`references/phase-library.md` 中对应那一节
goal / loop / checkpoint / 预算 / 失败记账	`references/execution-budget.md`
工单归属、认领、批次、终态、续跑租约	`references/ownership-and-tracker.md`
maker 编辑 / commit / rebase / push / 发布	`references/concurrency-and-landing.md`
测试设计 / E2E / 根因表述 / 关闭判定	`references/evidence-and-verification.md`
交付、复盘、规则晋升、最终审计	`references/learning-and-audit.md`

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

候选工单是 draft、
```
in-progress
```
、有预约/有效外来租约/接管，或已有开工证据；
认领回读未成功却已经开始改代码；
一批只共享标签/模块/症状，没有共享精确根因和同一条验证链；
出现第二个 maker 或第二个 landing owner，或本机租约回读不一致；
想用 mock/fixture 关闭用户报告的缺陷，或用兜底成功宣称历史根因已证实；
goal 没有 proof/constraints/cap，或 checkpoint 没有有界的下一步动作；
同一失败签名重复三次而策略没有真正改变，或 A→B→A 无新证据来回摆；
staging 含任务外路径、远端回读不含交付 SHA，或出现任何 force-push 倾向；
学习规则没有证据/eval/独立 checker 就要改权威规则文件。

命中红旗时：先写最终 checkpoint，再停止。不得靠延长 turn、重复等待或 "最后再看一眼"绕过刹车。

Candidate ticket is draft,
```
in-progress
```
, 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: 快速定范围

Step 1: Rapid Scope Definition

在规划之前，先花 2-5 分钟弄清任务实际涉及什么。没有调查的计划是空中楼阁——先看再拆。

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. 自动分类任务类型

1a. Automatic Task Type Classification

根据用户输入 + 调查发现判断类型：

<task-types> <type id="bug-fix" signals="fix, broken, 不工作, issue, error, 报错, 修, crash, 挂了"> 修复已知缺陷。从现象追到根因，根治而非打补丁。 </type> <type id="feature" signals="add, implement, 新增, 做一个, 加上, 支持, spec, 功能"> 新增功能或能力。从需求到交付。 </type> <type id="refactor" signals="clean up, 重构, simplify, extract, 拆, 整理, 瘦身"> 改善代码结构但不改变外部行为。 </type> <type id="test" signals="test, coverage, 补测试, E2E, 验证, 测试, 覆盖"> 补充测试覆盖或验证已有功能。 </type> <type id="research" signals="investigate, why, 调查, 为什么, 怎么回事, 排查, 分析"> 理解问题或技术方案。产出是结论/报告而非代码。 </type> <type id="deploy" signals="deploy, 发布, 上线, 部署, 推, ship, 发版"> 部署代码到环境并验证。 </type> <type id="quality" signals="review, 扫一遍, 优化, 质量, 检查, audit, 清理"> 对已有代码做质量审查和改进。 </type> </task-types>

一个输入可能同时命中多个类型（如"修完 bug 然后部署"= bug-fix + deploy）。此时组合对应的阶段模板，按自然因果排序。

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. 执行快速调查

1b. Execute Rapid Investigation

根据分类出的类型，从

references/phase-library.md

的

<scope-checklist>

拿到该类型的调查清单，快速执行。产出是对范围、受影响区域和关键发现的简短摘要。

用户报告的缺陷还必须在这一步记录精确事故身份（规范化来源 URL/ID、产物 ID、会话/任务 ID、目标环境与修复 watermark、期望 vs 实际）。拿不到就明确标为 bounded unknown——fixture 可以验接线，但不能关闭该缺陷。

Based on the classified type, get the investigation checklist for that type from

<scope-checklist>

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. 工单归属门（有关联工单时，先认领再动手）

1c. Ticket Ownership Gate (If associated ticket exists, claim first then act)

多个 agent 和人共享同一个工单系统，"没人在做这个"必须被证明：

可选资格：OPEN、非 draft、无
```
in-progress
```
、无预约/有效外来租约/接管信号、无分支/PR/协调评论证明已开工。歧义时 fail closed，跳过的候选保持零 mutation。
已有 assignee 只是弱意图，不是自动排除条件；但认领前必须重读工单并 整体替换 assignee 集合，绝不在过期 assignee 上追加。
认领顺序：重读 → 替换 assignee → 加
```
in-progress
```
→ 写结构化认领评论 → 从工单系统读权威
```
createdAt
```
回填并回读校验。 第二次回读成功之前，禁止任何导向实现的编辑、commit、部署或 E2E。
一批最多 4 项，且必须共享一个精确因果边界 + 一个实现 + 一条验证链。 "都是 Bug""标签相同""模块相邻""恰好改同一个文件"都不够——发散就只做优先级最高的那一个。

完整契约（含续跑租约、终态不变量、可执行性分类）见

references/ownership-and-tracker.md

。

Multiple agents and people share the same ticket system, "No one is working on this" must be proven:

Eligibility criteria: OPEN, non-draft, no
```
in-progress
```
, 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
```
in-progress
```
→ Write structured claim comment → Read authoritative
```
createdAt
```
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: 拆解为 XML 阶段计划

Step 2: Break Down into XML Phase Plan

2a. XML Phase Schema

每个计划用这个结构：

xml

<execution-plan>
  <task>用户的原始输入（原文保留）</task>
  <type>分类出的任务类型（可多个，逗号分隔）</type>
  <scope>调查发现的实际范围摘要（2-3 句话）</scope>

  <loop-goal>
    具体的、可判定的完成标准。
    必须涵盖所有子问题——不能只做最明显的就算完。
    必须包含所有强制验证阶段的预期产出。
    示例："#442 根因修复 + 本地验证通过 + test 部署绿 +
           E2E 通过 + review 通过 + 二次部署绿 + 二次 E2E 通过 +
           issue 关闭附 commit"
  </loop-goal>

  <hard-stop>
    <max-iterations>10</max-iterations>
    <consecutive-fail-limit>3</consecutive-fail-limit>
  </hard-stop>

  <phases>
    <phase id="唯一标识" order="N" mandatory="true">
      <skill>执行该阶段使用的 skill</skill>
      <goal>该阶段要达成什么</goal>
      <input>需要什么输入</input>
      <output>产出什么</output>
      <gate>客观的 pass/fail 信号（非主观判断）</gate>
      <done-when>可验证的完成判定</done-when>
      <on-fail>失败时怎么处理</on-fail>
    </phase>
  </phases>
</execution-plan>

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 选择

2b. Skill Selection

按阶段职能选 skill。每个阶段必须通过 skill 完成，不允许裸手做。

Skill 发现顺序：

先用
```
using-superpowers
```
/
```
find-skills
```
扫描当前项目和全局可用的 skill
优先选项目级 skill（如
```
dev-*
```
,
```
test-*
```
,
```
debug-*
```
,
```
review-*
```
）——它们包含项目特定的规则和上下文
项目没有专用 skill 时，退到全局 skill

<skill-matrix> <mapping phase="调查 / 根因定位" primary="项目 dev skill" fallback="systematic-debugging" /> <mapping phase="外部研究 / 文档" primary="context7" also="deep-research, anysearch, agent-reach" /> <mapping phase="方案规划" primary="writing-plans" also="planning-with-files, brainstorming" /> <mapping phase="后端 / 逻辑实现" primary="项目 dev skill" fallback="直接编码（无可用 skill 时）" /> <mapping phase="前端 / UI 实现" primary="frontend-design" also="shadcn-ui" /> <mapping phase="本地验证" primary="项目 test skill" fallback="直接运行 tsc + test" /> <mapping phase="部署" primary="项目 debug/deploy skill" fallback="gh-cli + 手动推送" /> <mapping phase="E2E 验证" primary="项目 test skill" also="agent-browser" /> <mapping phase="代码审查" primary="项目 review skill" fallback="simplify, code-review" /> <mapping phase="深度审查" primary="thermo-nuclear-code-quality-review" also="" /> <mapping phase="Issue 管理" primary="gh-cli" also="" /> </skill-matrix>

说明："项目 dev/test/debug/review skill"指当前项目

.agents/skills/

下与该职能匹配的 skill。例如 Kollab 项目有

dev-kollab

、

test-kollab

、

debug-kollab

、

review-kollab

；其他项目可能有

dev-myapp

、

test-myapp

或者没有——此时用 fallback。

Select skills by phase function. Each phase must be completed via skill, no bare-hand execution allowed.

Skill discovery order:

First use
```
using-superpowers
```
/
```
find-skills
```
to scan skills available in current project and globally
Prioritize project-level skills (e.g.,
```
dev-*
```
,
```
test-*
```
,
```
debug-*
```
,
```
review-*
```
) — 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

.agents/skills/

of the current project. For example, Kollab project has

dev-kollab

test-kollab

debug-kollab

review-kollab

; other projects may have

dev-myapp

test-myapp

or none — use fallback in that case.

2c. Feature Completeness Checklist（feature 类型强制）

2c. Feature Completeness Checklist (Mandatory for feature type)

feature 类型的任务在 design phase 必须通过

references/phase-library.md

中的

<feature-completeness-checklist>

逐项核查。历史教训：share 按钮上线后分享页渲染不一致、用户主题设置 useState-only 刷新丢失、公开页无 SEO—— 全部因为"先做能跑的，剩下的下次说"。checklist 覆盖五个维度：

多表面一致性：同一功能的所有 surface 必须同 PR 完成或 flag-gate 关闭
设置持久化：用户可调节项必须持久化，禁止 useState-only
公开页面基础设施：公开 URL 必须有 title/OG tags/合理加载态
数据完整性：前后端字段必须端到端流通
跨功能影响：评估新 surface 对导航/权限/下游消费的影响

每条标记通过/N/A/本次不做（flag-gated），不允许留空。不适用的条目标 N/A 并简述理由；适用但本次不做的必须 feature-flag 关闭且记入 progress.md 的"未完成项"。

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. 强制阶段规则

2d. Mandatory Phase Rules

任何涉及代码变更的任务类型（bug-fix / feature / refactor / quality），必须包含以下阶段，不允许省略：

<mandatory-phases for="code-change"> <phase-ref>implement — 实现（通过项目 dev skill 或直接编码）</phase-ref> <phase-ref>local-verify — 本地验证（tsc / lint / test，客观 gate）</phase-ref> <phase-ref>deploy-1 — 第一轮部署到测试环境（通过项目 deploy skill 或 gh-cli）</phase-ref> <phase-ref>e2e-1 — 第一轮 E2E 验证（通过项目 test skill + agent-browser，独立 subagent）</phase-ref> <phase-ref>review — 代码审查（通过项目 review skill 或 simplify + code-review，独立 subagent）</phase-ref> <phase-ref>deploy-2 — 第二轮部署（review 修改后）</phase-ref> <phase-ref>e2e-2 — 第二轮 E2E 验证（独立 subagent）</phase-ref> </mandatory-phases>

所有 autopilot 任务（包括 research / deploy / quality）还必须把下面阶段作为最后一个 mandatory phase。它必须进入 loop-goal，不能等报告时才临时想起：

<mandatory-phases for="all-autopilot"> <phase-ref>issue-finalize — 有关联 Issue 时，写入完整实施记录、最终方案、验证证据和用户可见效果，并按真实终态关闭或保留</phase-ref> <phase-ref>cleanup — 清理本任务创建的临时文件、诊断产物、独立 worktree 和临时分支，并用 Git 状态证明没有任务残留</phase-ref> </mandatory-phases>

这些阶段存在的原因：

<phase-justification id="e2e"> 本地测试只验证逻辑正确性。部署后可能因环境差异、配置缺失、迁移遗漏而表现不同。 E2E 是唯一能从用户视角证明"真的修好了"的环节。即使你 100% 确信修复是正确的，也必须跑——确信本身就是风险。历史上多次发生"本地全绿、部署后炸"的事故。

E2E 判定必须以运行时证据链为准（新链路自己的日志 marker / 数据行 / 指标），不能只看表面成功——带静默 fallback 的链路坏掉时功能照常响应，只有日志能暴露。三条配套规则：

外部凭证的权限面（网关 key 的模型/接口 allowlist、API key 的 scope、配额）是独立于代码的配置面：代码+部署完成不代表凭证就绪；改了调用目标就必须同任务核对所有环境的凭证权限，test 验过不代表 prod 凭证同样就绪。
空 catch / 无日志的 catch 包外部调用是缺陷不是风格问题：它把配置漂移变成不可见的降级。发现时必须补 queryable 日志 marker。
验证一条链路前先给它加打点——打点本身经常当场暴露此前静默存在的故障（真实案例：一个网关调用 401 了六周，加耗时日志的当天被发现）。 </phase-justification>

<phase-justification id="review"> 实现者有盲点：注释缺失让后人排查时看不懂链路、兼容性漏洞让别人的代码合并时挂掉、过度修改让影响面失控。审查是提前拦截线上事故的最后一道防线。历史上最严重的事故往往来自"太小了不需要 review"的改动。 </phase-justification> <phase-justification id="deploy-2-and-e2e-2"> review 阶段的修改（simplify 重构、注释补充、代码问题修复）可能引入新问题。第二轮部署+验证确保 review 修改没有破坏任何东西。跳过 = 把未经验证的 review 修改直接当作最终产出。 </phase-justification>

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 选择（决定阶段顺序）

2d-1. Lane Selection (Determine Phase Order)

按运行时消费方选 lane，不按文件名选。拿不准时 fail closed 到

deployed-required

。

text

local-only（所有改动消费方都在本地可完整执行的边界内，后端/契约/env/迁移/运行时 prompt 全未变）：
investigate → design(feature 时) → implement → local-verify → e2e-1(本地完整旅程)
→ deploy-1(仅推送) → review → 按影响分类决定 e2e-2 / deploy-2 → deliver

deployed-required（任何后端/混合消费方、API 契约、迁移、env/secret/部署配置、
运行时加载的 prompt/skill、认证回调、SSR/edge、远端专属行为，或任何不确定）：
investigate → design(feature 时) → implement → local-verify → deploy-1(推送+部署)
→ e2e-1(目标环境) → review → 按影响分类决定 deploy-2 / e2e-2 → deliver

Select lane by runtime consumer, not by file name. Fail closed to

deployed-required

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. Review 后影响分类（决定 deploy-2 / e2e-2 的形态）

2d-2. Post-Review Impact Classification (Determine deploy-2 / e2e-2 form)

review 后按 diff 实际影响面分类，不是无脑重跑一整轮，也不是随便跳过：

diff 分类	deploy-2 / e2e-2
`no-diff` （review 无改动）	两者 N/A，复用已 review 的 SHA
`docs/skill/evals-only`	跑一个点名的替代 gate（结构校验/eval），最终推送，不等部署
`test-only`	重跑受影响测试分区，最终推送，不等部署
前端代码 diff（local-only lane）	重跑本地 check + 针对性测试 + 独立本地 E2E，然后最终推送
任何后端/运行时/不确定的 diff	升级为 deployed-required：最终推送 → 部署 → 跑受影响的 E2E

分类结论和依据写进 progress.md。落地仍由同一个 landing owner 执行，代码修改路由回 maker——checker 不 commit、不 push。

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-diff` (no changes in review)	Both N/A, reuse reviewed SHA
`docs/skill/evals-only`	Run a named alternative gate (structure check/eval), final push, no wait for deployment
`test-only`	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. 组装阶段

2e. Assemble Phases

根据任务类型从
```
references/phase-library.md
```
加载对应的阶段模板
用调查发现（Step 1）填充每个
```
<phase>
```
的具体内容
补上所有 mandatory-phases（如果模板里没有）
模板是骨架不是枷锁——可以根据实际情况增加阶段，但不允许删除 mandatory 阶段
feature 类型：确认 design phase 产出的方案文件包含 feature-completeness-checklist 的逐条判定

Load corresponding phase template from
```
references/phase-library.md
```
based on task type
Fill specific content of each
```
<phase>
```
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. 初始化 State File

2f. Initialize State File

创建

progress.md

：

markdown

undefined

Create

progress.md

markdown

undefined

Autopilot Progress

Task

[用户原始输入]

[User's original input]

Type

[任务类型]

[Task type]

Loop Goal

[loop-goal 内容]

[Content of loop-goal]

Budgets

iterations	repair cycles	elapsed	tokens	external cost
0/10	0/6	0/240m	0/…	0/0

iterations	repair cycles	elapsed	tokens	external cost
0/10	0/6	0/240m	0/…	0/0

Phase Status

Order	Phase ID	Skill	Maker/Checker	Objective Gate	Status	Evidence (含 L0-L4 等级)
1	...	...	...	...	⏳

Order	Phase ID	Skill	Maker/Checker	Objective Gate	Status	Evidence (including L0-L4 levels)
1	...	...	...	...	⏳

Acceptance Ledger

(有多个目标项/工单时，逐项独立验收——不允许整批一起关)

项	事故身份	证据等级	精确/等价论证	客观证据	关闭判定

(For multiple target items/tickets, accept each item independently — no batch closing allowed)

Item	Incident Identity	Evidence Level	Precise/Equivalent Argument	Objective Evidence	Closure Decision

Delivery Ledger

(每个交付 SHA 出现且只出现一次，附其精确 diff 路径；本地 commit 不算交付)

Delivery SHA	精确文件清单	远端 ancestry 回读

(Each delivery SHA appears exactly once, with its precise diff path; local commits do not count as delivery)

Delivery SHA	Precise File List	Remote Ancestry Readback

Failure Log

(每次失败记录在这里——不是用来回顾的流水账，而是用来防止重蹈覆辙的行动记忆) 失败签名 = phase + 客观 gate + 观察到的失败 + 失败边界；四项全同才累加计数。一次性 shell 引号/拼写/harness 瞬态错误是 orchestration diagnostic，不计 repair cycle。

Iteration	Failure Signature	Failure Type	What Was Tried	Why It Failed	What Changed Next	Repeat

(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.

Iteration	Failure Signature	Failure Type	What Was Tried	Why It Failed	What Changed Next	Repeat

Telemetry

(每轮只记汇总，不粘贴 agent 完整输出) spawned/reused/closed agent 数 | maker/checker 数 | routine/critical 路由与升级原因 | wait 与状态检查次数 | context compaction 次数

(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

(跨迭代积累的可复用经验，每条一句话)

[例] phase implement: 这个模块的 tsc 需要用 tsconfig.build.json 而非默认 tsconfig
[例] phase e2e: test 环境的测试账号密码在项目 test skill 里，不要猜

(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

(每次迭代的简要摘要)


每个 phase 完成后立即更新 Status 列（⏳ → ✅）和 Evidence 列。
每次失败立即更新 Failure Log。
跨迭代发现的可复用经验记入 Lessons Learned。

(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. 定义 Loop 目标（Goal 合同）

2g. Define Loop Goal (Goal Contract)

从所有阶段的

<done-when>

合成一个可判定的 loop 目标。 一个任务只保留一个 active goal，phase、重试、subagent 都不另建 goal。 objective 控制在 1-3 句、600 字符以内，必须含五部分：

Measurable end state —— 精确的产品/工单终态
Proof —— 点名的客观 gate 和要求的证据等级（L2 还是 L3）
Constraints —— 归属、隐私、分支、成本、环境、发布边界
Caps —— 迭代数 / 修复回合 / 耗时 / token / 批准的外部花费

Stop phrase —— 逐字附在 objective 末尾：

Stop after <max-iterations> iterations or <max-repair-cycles> repair cycles, whichever comes first.

stop phrase 必须写进 goal 文本本身：独立 checker 只读 goal 文本，上限不进 goal，就等于对 checker 而言这个 loop 根本没有刹车。

默认预算：iterations 10 / repair cycles 6 / elapsed 240min / 外部花费 0（除非批准）。运行中不得未经授权抬高任何上限。

phase 表、通用规则、验收矩阵写进

progress.md

，不复制进 objective—— goal 是终点声明，不是第二份计划文件。完整预算契约见

references/execution-budget.md

。

Synthesize a verifiable loop goal from

<done-when>

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

progress.md

, 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: 执行

Step 3: Execution

3a. 启动 Loop（强制阻断门 — 见"Loop 强制执行规则"）

3a. Start Loop (Mandatory Block Gate — See "Loop Enforcement Rules")

这一步是执行的硬前提，不是可选项。Step 2 完成后、任何 phase 实际工作之前，必须先完成这一步。

根据平台使用对应命令：

<loop-start> <claude-code> 调用 ScheduleWakeup 启动 loop： ``` ScheduleWakeup({ delaySeconds: 60, reason: "autopilot: starting loop for <任务摘要>", prompt: "<完整 loop-goal，逐字粘贴 Step 2g 定义的内容>" }) ``` 调用后当前 turn 立即结束。不要在调用 ScheduleWakeup 之后继续执行 phase 工作。后续所有 phase 工作在 loop 回调中进行。 </claude-code> <codex> 调用 /goal，条件 = Step 2g 定义的 loop-goal。 Codex 的独立 checker model 验证完成条件。 </codex> </loop-start>

调用后的行为：ScheduleWakeup 调用后，当前 turn 的唯一允许动作是向用户输出一句确认： "Autopilot loop 已启动，目标：<loop-goal 摘要>。"然后结束 turn，等待 loop 唤醒。

每轮 loop 回调中的行为：

读 progress.md 恢复状态
确认当前未完成的 phase
用 Agent tool 派 subagent 执行当前 phase
根据 subagent 结果更新 progress.md
如果 loop-goal 未达成，调用 ScheduleWakeup 继续下一轮
如果 loop-goal 达成，进入 Step 4 收尾

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 铁律

3b. Loop + Agent-Mode Iron Rules

这两个 必须成对使用，全程贯穿，缺一不可：

loop/goal（外层）：围绕
```
<loop-goal>
```
迭代，未达成不停
agent-mode（内层）：每个阶段翻成自包含 brief 派 subagent 执行

执行拓扑：

loop-goal = <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 回 phase 2
  │   (更新 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]
  │   └── ...继续后续阶段
  │   (更新 progress.md)
  └── 所有 mandatory phase ✅ + loop-goal 达成 → 结束

These two must be used in pairs throughout the process, neither can be missing:

loop/goal (outer layer): Iterate around
```
<loop-goal>
```
, 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 分派规则

3c. Subagent Dispatch Rules

<subagent-rules> <rule id="self-contained-brief"> 每个 subagent 任务翻成自包含英文 brief—— subagent 没有主循环上下文，必须把它需要的一切都写进 brief。 </rule> <rule id="model"> 根据当前宿主平台选择可用的原生 subagent 模型，不把某个外部 CLI 当作审查前提。 **`model` 参数必须每次显式传，绝不省略**——省略等于继承主线程模型，而主线程往往是当前可用的最贵那一档，这是已经真实发生过的事故。

**Claude 环境：默认派最便宜的够用档，即 `sonnet`。**
只有在任务确实需要时（深层架构推理、对微妙逻辑的对抗性审查）才升到 `opus`，
并在同一条消息里说明为什么。调查、读文件、跑命令、量布局、查链接、汇报
这类阶段一律 `sonnet`。**不要把下面 Codex 那条的「高思考配置」平移过来**：
那是 Codex 侧的取值，不是「在任何平台都挑最贵的」。

两条 Claude 侧的已知限制，说清楚免得误报：
- `model` 只接受 `sonnet` / `opus` / `haiku` / `fable` **四个档位别名，
  没有版本粒度**，所以「Opus 4.8」这种具体版本在工具调用里钉不住；
  要把某个版本定成常驻默认，那是应用自己的模型配置，不在这里设。
- **`Agent` 工具根本没有 reasoning-effort 参数**（只有 `Workflow` 内层的
  `agent()` 有 `effort`）。所以「所有 subagent 都开中等推理」无法逐次强制，
  推理档是会话级设置。**不要声称给某个 subagent 设过 effort。**

在 Codex 环境，默认派 Codex subagent；涉及 implement、E2E、review 或 quality audit
的阶段必须使用 `model="gpt-5.6-terra"` + `reasoning_effort="high"`。

两侧共同的底线：**成本可以降，独立审查不能省**——
不得因为模型档位低或某个 CLI 不可用就跳过 maker-checker 分离。

</rule> <rule id="maker-checker-separation"> 实现类阶段（investigate / implement / plan）= maker subagent。验证类阶段（e2e / review / quality audit）= checker subagent。 checker subagent 不能接触 maker 的推理过程—— 只给它代码 diff、部署 URL 和验证标准，让它独立判断。这是防止"自己给自己判卷"的核心机制。 </rule> <rule id="context-hygiene"> 主循环只编排、串结论、做关键决策。大段文件/日志/diff 交给 subagent 读取，只回传结论—— 不要把 subagent 该消化的内容堆进主上下文。 </rule> <rule id="skill-first"> 每阶段开始前先确认要用的 skill，通过 skill 完成，不裸手做。 using-superpowers 在每轮开始时必须调用一次。专项 skill 每个任务只发现和加载一次，把选择写进 progress.md 供后续 phase 复用。 </rule> <rule id="agent-budget"> 按"不同 agent 数"计预算，修复回合优先复用原 agent（同一 agent 多轮不重复计数）：有界文档/research/verify-only = 2；单子系统代码变更 = 3；跨系统或多仓库代码变更 = 4（最多两个互不相交的 maker）。需要超预算时先 close 已完成 agent，并在 progress.md 记录缺失能力、为什么不能复用、新增角色和客观结束条件——"想再确认一次"不是理由。 maker 返回可修 finding 时把窄修复发回同一个 maker，checker 只复判不接管实现。 </rule> <rule id="wait-budget"> 只有下一步被该结果阻塞时才等待，否则立刻推进不重叠的工作。每个委派结果最多一次 90-120 秒阻塞等待，超时后不立即发起第二次。完成其它工作后最多再做一次状态检查；仍无进展就缩小 brief 复用/中断原 agent，或 close 掉由主线程完成。禁止连续 wait / 列举轮询 / 短周期 polling。 CI/部署等待走另一套节流（首次延后 5 分钟，核心服务 3-5 分钟一次，旁支 5-10 分钟一次，失败才拉日志），不与本预算混用。 </rule> </subagent-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 完成跟踪

3d. Phase Completion Tracking

每个 phase 完成后必须：

输出完成标记：

✓ PHASE [id] COMPLETE: [一句话客观证据]

更新
```
progress.md
```
的对应行
检查是否可以进入下一个 phase

如果无法写出真实的客观证据，说明该 phase 未完成，必须继续。

Loop 结束前执行最终检查：

逐一核对 progress.md 中所有 mandatory phase 的状态
所有 mandatory phase 必须是 ✅
缺任何一个 = 未完成 = 不允许退出 loop

After each phase is completed, must:

Output completion mark:

✓ PHASE [id] COMPLETE: [one-sentence objective evidence]

Update corresponding line in
```
progress.md
```
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. 失败处理

3e. Failure Handling

phase 失败时，必须按这个顺序处理——不能跳过分类直接重试：

<failure-protocol> <step order="1"> 分类：按 core-principles 的 failure-classification 判断失败类型（missing-context / wrong-approach / environment-issue / hallucinated-assumption / incomplete-output / external-blocker） </step> <step order="2"> 记录：在 progress.md 的 Failure Log 写入本次失败的分类、尝试了什么、为什么失败 </step> <step order="3"> 检查 Adaptive Retry 条件：能否提出和上次不同的做法？能 → 进入 step 4。不能 → 进入 step 5。 </step> <step order="4"> 按分类选路径重试： - missing-context → 扩大调查（项目 debug skill 查远程日志 / deep-research） - wrong-approach → 回 plan 阶段，brainstorming 探索替代方案 - environment-issue → 项目 debug skill 排查环境配置，或手动检查 - hallucinated-assumption → 回 investigate 验证假设 - incomplete-output → 继续当前 phase（不从头开始） - external-blocker → 降级（feature flag 关闭 + issue 留说明） </step> <step order="5"> 中止条件（任一触发即停）： - 同一 phase 连续失败 3 次且每次都换了策略 - 达到 iteration 上限（默认 10 轮） - 遇到 external-blocker 且无降级路径 → 停止 loop，输出：已尝试的所有方案 + 每次失败原因 + 建议下一步 </step> </failure-protocol>

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. 项目规则

3f. Project Rules

执行期间自动遵守当前项目的 CLAUDE.md / AGENTS.md 中的所有规则。 autopilot 不硬编码项目规则——它在 Step 1 调查阶段读取项目的规则文件，然后在执行期间遵守。

通用提醒（适用于大多数项目）：

如果项目有注释规范，遵守
如果项目有 i18n 要求，所有语言同步
保护分支提交前先 fetch + rebase
pathspec 只提交自己的文件
部署等待不要长时间前台 watch
任务必须自包含交付

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: 收尾清理 + 报告

Step 4: Wrap-Up Cleanup + Report

4a. Issue Finalization Gate（CRITICAL · 有关联 Issue 时未通过不得声明完成）

4a. Issue Finalization Gate (CRITICAL · Cannot claim completion if not passed when there is associated Issue)

任务有关联 GitHub/GitLab/Jira Issue 时，必须在清理 worktree 之前完成 Issue 收尾。Issue 是团队理解“为什么改、怎么改、最后实际怎样”的长期记录，不能只留一句

Fixed in <hash>

，也不能让关键实施证据只存在于临时

progress.md

、聊天记录或本地截图目录。

成功交付时，用项目 Issue 工具（GitHub 优先

gh-cli

）写一条结构完整的最终评论，至少包含：

问题与根因：用户遇到的现象、最终确认的根因，以及调查中被证伪的重要假设。
实施方案：按组件/链路列出实际落地的修复，说明关键设计选择和为什么采用该方案。
改动定位：最终 commit hash、目标分支、关键文件或迁移；多个 commit 时列出各自职责。
验证证据：本地测试命令与结果、部署环境、workflow run URL/head SHA、E2E 场景与结果、独立 review 结论；不能把取消、失败或未执行的验证写成通过。
最终呈现效果：用用户视角描述修复后的真实行为。涉及 UI/产物时附最终截图、artifact、页面或可访问证据链接；涉及 API/后台链路时附可安全公开的响应、数据或日志 marker 摘要。
范围与后续：明确已完成内容、未触碰的环境（如 production）、已知限制和仍需外部决策的动作；超出本任务范围的具体问题必须链接独立 follow-up Issue，不能藏在评论里。

评论不得包含 secret、token、cookie、完整用户隐私数据或只能在本机访问的临时绝对路径。优先写一条完整的最终总结，避免用多条零散评论制造噪音。

成功任务完成评论后，按项目规则关闭 Issue、移除

in-progress

，并重新读取 Issue 验证：

状态确实为 closed/done；
最终评论包含精确 commit hash；
部署/E2E/review 证据和最终效果均已记录；
重复或兄弟 Issue 已交叉引用并按真实状态处理。

如果任务 hard-stop、降级或未完成：不得关闭 Issue。必须留下调查结论、当前阻塞、已尝试方案和下一步，并按项目规则释放或保留 assignee/

in-progress

。没有关联 Issue 时标记

issue-finalize = N/A

并说明 “任务开始时未发现或未要求创建 Issue”，不得为了满足格式制造无意义 Issue。

只有复读后的 Issue 状态和评论内容通过检查，才允许输出

✓ PHASE issue-finalize COMPLETE: <issue URL + commit + evidence summary>

。

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

Fixed in <hash>

, nor let key implementation evidence only exist in temporary

progress.md

, chat records or local screenshot directory.

When delivery is successful, use project Issue tool (prefer

gh-cli

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

in-progress

, 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/

in-progress

according to project rules. Mark

issue-finalize = N/A

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 · 未通过不得声明完成）

4b. Cleanup Gate (CRITICAL · Cannot claim completion if not passed)

任务代码、部署、E2E 和 review 全部完成后，必须执行 cleanup phase。

progress.md

是恢复用的临时状态，不是仓库交付物；任务结束却把它和诊断文件留在仓库根目录，说明任务没有真正收口。

按下面顺序执行，顺序不能颠倒：

先证明成果不会丢失
- 查看
```
git status --short --untracked-files=all
```
  ，区分任务文件、用户文件和其他并发任务文件。
- 有代码改动时，确认本任务 commit 已推到目标远端分支；例如目标为
```
test
```
  时，
```
git log origin/test..HEAD
```
  必须为空，且
```
git merge-base --is-ancestor <task-commit> origin/test
```
  必须成功。
- 发现有效但未推送的 commit 时，先按项目保护分支规则 push/rebase，再清理。无法推送时必须 hard-stop 并保留 worktree，报告抢救路径；绝不能为了“清理干净”删除成果。
清理所有任务自有临时文件和产物
- 删除
```
progress.md
```
  、任务专用
```
progress-*.md
```
  、临时 plan/state 文件。
- 删除一次性诊断脚本、
```
tmp-*
```
  、
```
cw-*.json
```
  、日志导出、下载的 workflow artifact、临时截图、测试输出、scratchpad 内容和其它只为本轮调查/验证生成的文件。
- 用户明确要求的交付物、正式测试、正式文档和已纳入提交的可重放证据不是临时产物，必须保留。
- 只删除能证明由本任务创建的路径；禁止使用宽泛 glob 或删除其他并发任务/用户的未跟踪文件。
- ```
progress.md
```
  最后删除，因为前面的清理失败时仍需要它恢复现场。
清理隔离 worktree 和临时分支
- 只清理本任务自己创建的独立 worktree，绝不删除共享主工作目录。
- 在主仓库执行
```
git worktree remove "$WORKTREE_DIR" --force
```
  ，然后删除本任务临时分支并
```
git worktree prune
```
  。使用
```
--force
```
  的前提是上一步已经证明没有未推送 commit 或需保留改动。
- 没有创建独立 worktree 时明确标记 N/A，不得为了满足格式去删除当前工作树。
客观复核清理结果
- 再次运行
```
git status --short --untracked-files=all
```
  ，确认没有本任务遗留路径。
- ```
git worktree list
```
  和
```
git branch --list
```
  不得再出现本任务 worktree/临时分支。
- 其他人的改动可以继续存在，但必须在报告里明确标为非本任务所有，不能擅自删除。

只有上述四步全部通过，才允许输出

✓ PHASE cleanup COMPLETE

并进入最终报告。

After task code, deployment, E2E and review are all completed, must execute cleanup phase.

progress.md

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
```
  to distinguish task files, user files and other concurrent task files.
- When there are code changes, confirm task commits have been pushed to target remote branch; for example, when target is
```
test
```
  ,
```
git log origin/test..HEAD
```
  must be empty, and
```
git merge-base --is-ancestor <task-commit> origin/test
```
  must succeed.
- 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
```
progress.md
```
  , task-specific
```
progress-*.md
```
  , temporary plan/state files.
- Delete one-time diagnostic scripts,
```
tmp-*
```
  ,
```
cw-*.json
```
  , 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.
- ```
progress.md
```
  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
```
  in main repo, then delete task temporary branch and
```
git worktree prune
```
  . Use
```
--force
```
  only if previous step has proven no unpushed commits or changes to retain.
- 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
```
  again to confirm no task遗留 paths.
- ```
git worktree list
```
  and
```
git branch --list
```
  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

✓ PHASE cleanup COMPLETE

and enter final report.

4c. 复盘与规则晋升（每个任务强制，包括干净跑通的任务）

4c. Review and Rule Promotion (Mandatory for each task, including those that run smoothly)

复盘记录：什么证据改变了计划、哪个 gate 抓到真实缺陷、结论是任务专属还是可泛化、是否已有规则覆盖、晋升是否成立。不要为了凑数强行晋升——

no-promotion

+ 一个理由是合法且必需的结果。

晋升到持久化规则（skill / 项目规则文件）必须同时满足：真实任务的直接隐私安全证据、可泛化、有客观 gate、加了会在规则前失败规则后通过的 eval、独立 checker 校验过范围与非重复、且规则+eval+文档落在同一个交付 commit。按职责指定唯一真相源并替换它，不要在入口文件追加平行规则。完整晋升门见

references/learning-and-audit.md

。

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——

no-promotion

+ 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. 最终审计序列（声称完成之前逐项执行）

4d. Final Audit Sequence (Execute item by item before claiming completion)

每个计划内 phase 已完成或有理由充分的 N/A；
每个目标项/工单有独立的事故身份、证据、评论和终态决定（用一次权威快照读取）；
每个交付 SHA 都是目标远端分支的 ancestor，且被 Delivery Ledger 归因；
每个交付 commit 的 diff 都落在精确文件清单内、清单每个文件都被覆盖、没有残留的任务自有未提交 diff 或未推送 commit；
至少一条学习决定走完晋升门、被带理由拒绝，或被标为 run-specific；
改了 skill 就跑结构校验；
所有非 goal 审计通过之后，才把 goal 标记完成并终态回读。

绝不把 subagent 的一句 "done" 当作审计证据。

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. 收尾报告

4e. Wrap-Up Report

执行完成后输出简洁总结：

<report-template> <item>执行路线（阶段 → 所选 skill → 结果）</item> <item>Loop 目标 + 达成状态</item> <item>改动文件列表（含跨仓库）</item> <item>部署 / 验证结论（如适用）</item> <item>Commit hash</item> <item>Issue 最终记录：URL、关闭状态、实施方案/验证证据/最终效果已回填的复核结论（如适用）</item> <item>所有 phase 的 ✓ 完成标记清单</item> <item>Cleanup 证据：临时文件/产物已清理，worktree/临时分支已删除或 N/A，远端提交已确认</item> <item>iterations 次数 + 失败回溯记录</item> <item>未完成项 + 原因（如有）</item> </report-template>

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>