autopilot

/autopilot

完整交付流水线。一条命令即可从 Issue 推进到已合并的 PR，也可以直接调用子功能。

路由

意图	子功能
规范、规划、设计功能——“梳理这个功能”“编写规范”	references/shape.md
实现、编写代码、TDD——“构建这个功能”“实现”	references/build.md
创建/更新 PR——“打开 PR”“创建 PR”	独立的 /pr 技能
疏通、完善、简化 PR——“修复 PR”“CI 报错”“简化”	独立的 /settle 技能
验证验收标准——“验证 AC”	references/verify-ac.md
Lint、类型检查、测试门禁——“检查质量”	references/check-quality.md
强制执行 TDD、覆盖率——“测试覆盖率”	references/test-coverage.md
捕获可视化证据——“演示流程”	references/pr-walkthrough.md
语义化提交工作流——“提交”	references/commit.md
Issue 检查/补充/拆分——“Issue”	references/issue.md

如果以 /autopilot [issue-id] 的形式调用，则运行完整流水线（如下）。 如果以 /build、/shape 等形式调用，则读取相应参考文档并遵循其中的说明。 如果以 /pr-fix、/pr-polish 或 /simplify 的形式调用，则路由到独立的 /settle 技能。

角色

负责冲刺的工程负责人。寻找工作，确保工作已准备就绪，委派实现并交付。

目标

将 Issue $ARGUMENTS（或优先级最高且符合条件的未关闭 Issue）交付为已合并的 PR，并确保测试通过、dogfood QA 检查干净、所有评审均已处理完毕，且提供清晰说明合并理由的演示流程产物。

该 Issue 对应的未关闭 PR 视为当前交付通道。除非先说明并论证需要启用优先级更高的替代通道，否则不要为同一 Issue 创建重复 PR。

工作权限

• Codex 负责撰写所有内容的初稿（调查、实现、测试、文档）
• 你负责统筹、评审、清理、提交和交付
• 自行补全不完整的 Issue（规范、设计）
• 绝不以“尚未准备就绪”为由跳过 Issue——由你负责让其准备就绪
• 对交付通道端到端负责：如果验证发现交付门禁范围内的相关问题或仓库遗留问题，则予以修复，或明确说明为何无法在当前通道中修复
• 此环境提供 dogfood、agent-browser 和 browser-use；使用它们验证用户流程

LLM 优先实现规则（强制）

解决语义问题（分类、优先级排序、分流、意图映射、验收标准/规范合规性）时，优先采用基于 LLM 推理的方法。

只要 LLM 方案可行，就不要引入仅依赖启发式的语义处理流水线（正则表达式层叠、关键词评分表、静态决策树）。

确定性逻辑仅限于严格的机制性检查：架构检查、精确解析、权限/安全门禁。

优先级选择

始终处理优先级最高且符合条件的 Issue。

首先判断是否符合条件：

• 未分配
• 尚未标记为 In Progress
• 尚无其他 autopilot 运行或未关闭的 PR 正在处理

1. p0 > p1 > p2 > p3 > 无标签
2. 同一优先级内：horizon/now > horizon/next > 无标签
3. 同一时间范围内：Issue 编号较小者优先
4. 符合条件后，范围、整洁度和舒适度均不影响选择

如果优先级最高的 Issue 已分配或已标记为 In Progress，则跳过并转向下一个符合条件的 Issue。 绝不抢占已有人认领的工作。

认领纪律

Autopilot 必须先认领工作，然后才能整理或编写代码。

• 自动选择模式：仅选择没有受派人、状态不是 In Progress、没有未关闭 PR，且尚未关联任何活跃 autopilot 工作线的 issue
• 指定 issue 模式：如果 issue 已由其他操作人员负责、已有其他未关闭 PR，或正在由其他工作线处理，则停止
• 指定 issue 模式可以继续由你认领的工作，包括已分配给你或已由你的工作线标记为 In Progress 的 issue
• 在执行 /issue lint 之前，将 issue 分配给自己
• 在执行 /issue lint 之前，将 issue 的项目状态标记为 In Progress
• 如果 issue 不属于任何项目，或项目没有 Status 字段，请先将其添加到规范的交付项目中，然后设置 Status
• 如果分配、添加到项目或修改状态失败，请在开始实施前停止，并明确报告阻碍因素

核心是确保单一所有权。一个 issue 应对应一条活跃的 autopilot 工作线。

工作流

1. 查找符合条件的问题 —
   • 明确指定问题：在进行任何操作前，先检查受指派人、项目状态和未关闭的 PR
   • 自动选择：选择优先级最高的未关闭问题，且该问题尚未指派、不处于 In Progress 状态，也没有未关闭的 PR 或活跃的 autopilot 通道
   • 如果没有未关闭的问题，则停止并报告队列为空
   • 如果存在未关闭的问题，但没有符合条件的问题，则停止并报告所有未关闭的工作都已有人认领
   • 优先检查通道：如果仓库提供该脚本，运行 python3 scripts/issue_lane.py --repo <owner/name> --issue <N>
   • 回退方案：使用 gh pr list --state open --json number,title,body,headRefName,url 查询未关闭的 PR
2. 认领问题 —
   • 将问题指派给自己
   • 确保该问题已关联到规范的交付项目
   • 将关联项目条目的 Status 标记为 In Progress
   • 重新读取问题，并在继续之前确认认领已生效
   • 如果问题已由你所在的通道认领，则视为恢复工作并继续
   • 如果问题已由其他通道认领，则停止，不要争抢
3. 加载上下文 — 阅读 project.md，了解产品愿景、领域术语表和质量标准
4. 就绪门槛 — 运行 /issue lint $1：
   • 得分 >= 70：继续
   • 得分为 50-69：先运行 /issue enrich $1，然后重新 lint
   • 得分 < 50：向用户标记此问题，尝试补充信息，然后重新 lint
   • 绝不要因为问题得分低就跳过 — 由你来让问题达到就绪状态
5. 意图门槛 — 确保问题包含 ## Product Spec 和 ### Intent Contract。 如果缺少，则调用 /shape --spec-only $1，并在编写代码前重新检查。
6. 设计 — 如果没有 ## Technical Design 章节，则调用 /shape --design-only。如果设计包含状态机或并发协议，考虑在开始构建前运行 /formal-verify loop。
7. 构建（强制执行 TDD） — 调用 /build，并要求每项验收标准都有 RED→GREEN 证据：
   • RED：实现前，针对性测试失败
   • GREEN：实现后，相同测试通过
   • 如果测试框架损坏，则停止并标记阻塞问题（未经用户明确允许，不得在没有测试的情况下实现）
   • 在全新项目或面向用户之前的路径中，删除兼容性脚手架，除非真实契约要求保留
8. 视觉 QA — 如果差异涉及前端文件（app/、components/、*.css），运行 /visual-qa --fix。继续前修复 P0/P1 问题。
9. Agentic QA — 如果差异涉及提示词、模型路由、工具架构或 Agent 指令，则运行 /llm-infrastructure，并在发布前检查追踪和评估覆盖情况。
10. 优化 — 运行 /pr-fix --refactor，就地更新文档，然后进行简化检查：
    • 净差异超过 200 LOC 时为强制要求： 运行 /simplify — 不得例外
    • 对于较小的差异：手动检查模块深度，并使用 Ousterhout 检查项进行简化编辑：浅层模块、信息泄漏、直通模块，以及没有有效契约的兼容性垫片
    • 可选加速方式：如果执行环境提供 ousterhout persona/agent，则使用它
11. Dogfood QA — 针对本地开发服务器运行自动化 QA（参见下方 Dogfood QA 章节）。 反复迭代，直到没有 P0/P1 问题。QA 通过前不要创建 PR。 11a. 验证 AC — 针对关联问题的 ## Acceptance Criteria 调用 verify-ac。

• 如果存在明确的 AC 标签（[test]、[command]、[behavioral]），则遵循这些标签；否则，让 verify-ac 根据差异和仓库上下文选择最精确可信的策略
• 对 UNVERIFIED 检查重试一次（总计 2 次尝试）
• 如果第 2 次尝试后仍有任何 AC 为 UNVERIFIED：继续修复代码、测试或文档，并重新运行 verify-ac；门槛未通过时不要提交或发布
• 只有在经过合理的修复尝试后确实无法继续推进时，才向用户升级
• 只有在没有 AC 为 UNVERIFIED 时才可接受 PARTIAL，但必须在最终交接内容和 PR 正文中报告

12. 演练说明 — 运行 /pr-walkthrough，并为分支生成必需的演练材料包。每个 PR 都必须有一个产物，即使改动属于内部改动或架构改动也不例外。
13. 提交 — 为所有剩余改动创建语义化提交：
    • 对文件分类：提交、gitignore、删除、整合
    • 按逻辑分组提交：feat:、fix:、docs:、refactor:、test:、chore:
    • 标题：祈使语气、小写、不加句号，约 50 个字符。正文说明原因，而非内容
    • 推送前运行质量门槛（lint、typecheck、test）
    • 运行 git fetch origin && git push origin HEAD（如果落后，则先 rebase）
    • 绝不强制推送。未经确认，绝不推送到 main。
14. 发布 — 创建或更新一个有效的 PR：
    • 暂存并提交任何未提交的改动，使用语义化提交消息
    • 从分支名称或近期提交中读取关联问题
    • 如果有 python3 scripts/issue_lane.py --repo <owner/name> --issue <N>，则在创建 PR 前立即重新运行
    • 否则，在创建 PR 前立即重新运行在途检查门槛
    • 如果该分支已有未关闭的 PR，则使用 gh pr edit，不要使用 gh pr create
    • 如果同一问题已有其他未关闭的 PR，则停止并指出重复情况，不要创建第二个通道
    • 加载 ../pr/references/pr-body-template.md 并按其要求操作
    • Walkthrough 章节必须链接到产物，并说明用于保障演示路径的持续验证
    • PR 正文必须包含所有章节：
      • 为何重要：问题、增加的价值、为何现在处理、问题链接。置于正文开头。
      • 权衡 / 风险：接受的成本、仍存的顾虑，以及为何值得权衡。
      • 意图参考：复制粘贴问题中的意图契约摘要，并链接到源问题章节。
      • 改动内容：简洁列出完成的工作，包括关键文件/函数。
      • 考虑过的替代方案：什么都不做、可信的替代方案，以及为何最终选择当前方案。
      • 验收标准：来自关联问题，使用复选框。
      • 手动 QA：逐步说明验证方法，包括命令和预期输出。
      • 变更内容：包含基准分支的 Mermaid 流程图、本 PR 的 Mermaid 流程图，以及第三张 Mermaid 架构/状态/时序图；另需说明新结构为何更好。
      • 之前 / 之后：必须提供文字描述。UI 改动需附截图。对于大量证据，使用 <details>。
      • 测试覆盖：列出具体测试文件/函数，并说明覆盖缺口。
      • 合并信心：信心等级、最有力的证据、剩余风险。
    • 在适当情况下，将详细章节放在 <details> 中，但不要隐藏概述中的重要性和权衡说明
    • 对 gh pr create、gh pr edit 和 PR 评论使用 --body-file
    • gh pr create --assignee phrazzld --body-file <path>
    • 如果做出了值得注意的决策，则添加上下文评论
    • 创建或更新 PR 会开启审查通道。这并不意味着 PR 已准备好接受审查。
    • 如果最终推送、gh pr ready 或 PR 编辑触发了异步审查者，除非 /pr-fix 已通过该 PR 的实时结算门槛，否则不要发布任何“PR Unblocked”或“ready for merge”信号
15. CI 门槛 — 等待 PR 上的 CI 完成。
    • 使用 gh pr checks <PR> --watch 或 gh run list --branch <branch> --limit 1 轮询
    • 如果有任何检查失败：调查根因、修复、提交、推送，然后再次等待 CI
    • 重复上述步骤，直到所有检查通过
    • CI 失败时不要进入审查结算阶段
16. 审查结算 — 阅读 PR 中的每一条审查意见和评论，并逐条认真判断。对于每条审查意见，确定以下三种处理方式之一：
    • 属于范围内：在分支中修复。提交、推送，并回复评论确认已修复。
    • 有效但超出范围：创建单独的 GitHub 问题（如果仓库使用 BACKLOG.md，则添加到其中）。回复评论并附上跟踪事项链接。
    • 不成立：清楚说明为何该反馈不适用，并予以回复。
    • PR 上的每条审查意见都必须得到书面回复 — 不得悄然忽略任何一条。
    • 如果推送了修复，则返回第 15 步（CI 门槛），并在继续前重新验证。
17. 收尾优化 — CI 通过且所有审查评论都已处理后：
    • 运行 /pr-polish
    • 运行 /simplify
    • 如果这些步骤产生了改动，则提交并推送，然后返回第 15 步（CI 门槛）重新验证
18. 合并 — CI 通过、所有审查意见均已处理且优化完成后：
    • 使用 gh pr merge --squash 进行 squash 合并
    • 检查失败时绝不合并
    • 存在未处理的审查评论时绝不合并
19. 回顾（可选） — 仅当仓库已有按问题归档的回顾笔记，且相关经验值得保留时，才记录实现经验。
    • 每个问题在 .groom/retro/<issue>.md 下使用一个文件。
    • 绝不要追加到共享的 .groom/retro.md；对于价值较低的笔记，应完全跳过回顾，而不是制造容易发生合并冲突的改动。
    • 如果要追加，优先使用仓库按问题归档的回顾命令/路径（例如 /done append --issue ...），而不是自行设计新的共享日志格式。

Dogfood QA

每个 PR 之前都要运行。没有例外。

/dogfood 是一种 Agent 技能，不是 shell 二进制文件。请按 /dogfood ... 的形式调用。 不要运行 dogfood --help，也不要根据 shell PATH 判断它不可用。 使用 agent-browser / browser-use 进行有针对性的手动复现和后续验证。

设置

# Start dev server if not already running
# Find existing server first
PORT=$(lsof -i :3000 -sTCP:LISTEN -t 2>/dev/null | head -1)
if [ -z "$PORT" ]; then
  bun dev:next &
  DEV_PID=$!
  sleep 10  # wait for compilation
fi

# Confirm it's up
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/

如果端口 3000 被其他项目占用，请使用 bun dev:next -- --port 3001，并相应调整目标 URL。

运行

/dogfood http://localhost:3000

限定范围为差异内容：如果问题只涉及状态页面，请运行 /dogfood http://localhost:3000 Focus on the status page and badge changes。对于完整功能的工作，不限制范围。

问题严重程度门槛

/dogfood 完成后，阅读报告：

• P0 或 P1 问题 → 修复、提交，然后在受影响区域重新运行 /dogfood
• P2 问题 → 如果能快速修复（<15 分钟），则修复；否则在 PR 中记录为已知问题，并创建后续问题
• P3 问题 / 无问题 → 继续执行 /pr

绝不要在 dogfood 报告中的 P0 或 P1 问题尚未修复时打开 PR。

迭代上限

如果同一个 P0/P1 问题在两次修复尝试后再次出现，请停止、记录阻碍，并在继续之前告知用户。不要无限循环。

清理

# Kill the dev server if we started it
[ -n "$DEV_PID" ] && kill $DEV_PID 2>/dev/null || true

如果用户自己的开发服务器已在运行（没有 $DEV_PID），请保持其运行。

并行优化（Agent Teams）

/build 完成后，并行开展优化阶段：

队友	任务
简化者	运行 code-simplifier agent，并提交
深度审查者	手动审查模块深度；如果可用，则运行 ousterhout，并提交
文档更新者	更新文档（README、ADR、API 文档），并提交

所有队友完成后，负责人按顺序整理提交。然后进行 dogfood QA，再执行 /pr。

适用情况：包含多项优化需求的重要功能。 不适用情况：可以通过顺序处理快速完成的小修复。

如果运行环境支持原生批量派发（例如 /batch），请使用。 否则通过常规 Agent 调用依次启动队友。

停止条件

仅在以下情况下停止：问题明确受阻、经过多次尝试后构建仍失败、需要外部操作。

以下情况不构成停止条件：缺少描述、看起来工作量很大、方法不明确。

输出

报告：处理的问题、规格状态、设计状态、TDD 证据（RED/GREEN）、dogfood QA 总结（发现 / 修复的问题）、演练产物摘要、所做提交、PR URL、已解决的审查意见（数量 + 处理方式）以及合并状态。

审查节奏

如果 Agent 不断沿用过时的认知模型，代码就会不断膨胀。每次新迭代或重大工作开始前：

• 完整重读已修改的模块
• 查找仅为保留旧结构而添加的兼容性垫片
• 在添加下一层之前先简化

Harness 加速器（Claude Code）

在 Claude Code 中运行此技能时：

1. 在工作流步骤 8（Refine）中，运行 /pr-fix --refactor 后再运行 /simplify。
2. 在 Parallel Refinement 中，尽可能使用 /batch 一次性派发队友任务。

如果任一命令不可用，请使用基础技能中已定义的通用替代方案。