autopilot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/autopilot

Full delivery pipeline. From issue to merged PR in one command, or invoke sub-capabilities directly.

全交付流水线，一条命令即可完成从issue到PR合并的全流程，也可直接调用子能力。

Routing

路由规则

Intent	Sub-capability
Spec, plan, design a feature — "shape this", "write a spec"	`references/shape.md`
Implement, code, TDD — "build this", "implement"	`references/build.md`
Create/update a PR — "open PR", "create PR"	Standalone `/pr` skill
Unblock, polish, simplify PR — "fix PR", "CI red", "simplify"	Standalone `/settle` skill
Verify acceptance criteria — "verify ACs"	`references/verify-ac.md`
Lint, typecheck, test gates — "check quality"	`references/check-quality.md`
TDD enforcement, coverage — "test coverage"	`references/test-coverage.md`
Visual evidence capture — "walkthrough"	`references/pr-walkthrough.md`
Semantic commit workflow — "commit"	`references/commit.md`
Issue lint/enrich/decompose — "issue"	`references/issue.md`

If invoked as

/autopilot [issue-id]

, run the full pipeline (below). If invoked as

/build

/shape

, etc., read the corresponding reference and follow it. If invoked as

/pr-fix

/pr-polish

, or

/simplify

, route to standalone

/settle

意图	子能力
功能的规格定义、规划、设计 — "梳理需求", "编写规格说明"	`references/shape.md`
功能实现、编码、TDD — "开发功能", "实现需求"	`references/build.md`
创建/更新PR — "打开PR", "创建PR"	独立 `/pr` 技能
解锁阻塞、优化、简化PR — "修复PR", "CI变红", "简化代码"	独立 `/settle` 技能
验证验收标准 — "验证AC"	`references/verify-ac.md`
代码检查、类型校验、测试门禁 — "检查质量"	`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

能力。

Role

角色定位

Engineering lead running a sprint. Find work, ensure it's ready, delegate implementation, ship.

运行迭代的工程负责人，负责查找工作项、确认就绪状态、分配实现任务、完成发布。

Objective

目标

Deliver Issue

$ARGUMENTS

(or highest-priority eligible open issue) as a merged PR with tests passing, a clean dogfood QA pass, all reviews settled, and a walkthrough artifact that makes the merge case legible.

An open PR for that issue counts as the active delivery lane. Do not create a duplicate PR for the same issue unless you first surface and justify a superseding lane.

将输入的issue

$ARGUMENTS

（或优先级最高的符合条件的未处理issue）转化为已合并的PR，要求测试全部通过、内测QA验证通过、所有评审意见闭环、附带清晰的走查材料说明合并合理性。

针对该issue已有的公开PR视为活跃交付链路，除非你先提出并证明需要新的替代链路，否则不要为同一个issue创建重复PR。

Latitude

执行权限

Codex writes first draft of everything (investigation, implementation, tests, docs)
You orchestrate, review, clean up, commit, ship
Flesh out incomplete issues yourself (spec, design)
Never skip an issue because it's "not ready" — YOU make it ready
Own the lane end-to-end: if validation surfaces adjacent breakage or stale repo debt in scope of the ship gate, fix it or explicitly justify why it cannot be fixed in this lane
```
dogfood
```
,
```
agent-browser
```
, and
```
browser-use
```
are available in this environment; use them for user-flow validation

Codex负责产出所有内容的初稿（调研、实现、测试、文档）
你负责协调、评审、清理、提交、发布全流程
自行补全不完整的issue信息（规格、设计）
永远不要因为issue「未就绪」就跳过，你负责让它达到就绪状态
端到端负责交付链路：如果验证过程中发现发布范围内存在相邻功能损坏或陈旧的技术债务，要么修复它，要么明确说明无法在本次链路中修复的原因
本环境提供
```
dogfood
```
、
```
agent-browser
```
、
```
browser-use
```
能力，可用于用户流程验证

LLM-First Implementation Rule (Mandatory)

大语言模型优先实现规则（强制）

When solving semantic problems (classification, prioritization, triage, intent mapping, AC/spec compliance), use LLM reasoning-first approaches.

Do not introduce heuristic-only semantic pipelines (regex ladders, keyword scorecards, static decision trees) when an LLM path is viable.

Deterministic logic is limited to strict mechanics: schema checks, exact parsing, permission/safety gates.

解决语义类问题（分类、优先级排序、分诊、意图映射、AC/规格合规校验）时，优先使用LLM推理方案。

当LLM方案可行时，不要引入仅基于启发式规则的语义流水线（正则匹配、关键词打分、静态决策树）。

确定性逻辑仅适用于严格的机械类场景：Schema校验、精确解析、权限/安全门禁。

Priority Selection

优先级选择规则

Always work on the highest-priority eligible issue.

Eligibility comes first:

unassigned
not already marked
```
In Progress
```
not already being worked by another autopilot run or open PR

```
p0
```
>
```
p1
```
>
```
p2
```
>
```
p3
```
> unlabeled
Within tier:
```
horizon/now
```
>
```
horizon/next
```
> unlabeled
Within same horizon: lower issue number first
Scope, cleanliness, comfort don't matter after eligibility is satisfied

If the highest-priority issue is already assigned or already

In Progress

, skip it and move to the next eligible issue. Never steal claimed work.

永远优先处理优先级最高的符合条件的issue。

首先判断是否符合处理条件：

未分配处理人
未标记为
```
In Progress
```
没有其他autopilot运行实例或公开PR正在处理该issue

优先级排序规则：

```
p0
```
>
```
p1
```
>
```
p2
```
>
```
p3
```
> 无优先级标签
同优先级内：
```
horizon/now
```
>
```
horizon/next
```
> 无时间标签
同时间范围：issue编号更小的优先
符合条件后，范围、复杂度、开发难度不影响优先级排序

如果最高优先级的issue已经被分配或标记为

In Progress

，跳过它处理下一个符合条件的issue，永远不要抢占已被认领的工作。

Claim Discipline

认领规则

Autopilot must claim work before shaping or coding.

Auto-pick mode: only select issues with no assignees, no
```
In Progress
```
status, no open PR, and no active autopilot lane already attached
Explicit issue mode: stop if the issue is owned by another operator, already has another open PR, or is otherwise being worked by another lane
Explicit issue mode may resume work already claimed by you, including an issue already assigned to you or already marked
```
In Progress
```
by your lane
Before
```
/issue lint
```
, assign the issue to yourself
Before
```
/issue lint
```
, mark the issue's project status as
```
In Progress
```
If the issue is not in a project or the project has no
```
Status
```
field, attach it to the canonical delivery project first, then set
```
Status
```
If assignment, project attach, or status mutation fails, stop before implementation and report the blocker explicitly

The point is single ownership. One issue should map to one active autopilot lane.

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链路。

Workflow

工作流程

Find eligible issue —
- Explicit issue: inspect assignees, project status, and open PRs before doing anything else
- Auto-pick: choose the highest-priority open issue that is unassigned, not
```
In Progress
```
  , and has no open PR or active autopilot lane
- If there are no open issues, stop and report that the queue is empty
- If open issues exist but none are eligible, stop and report that all open work is already claimed
- Preferred lane check: run
```
python3 scripts/issue_lane.py --repo <owner/name> --issue <N>
```
  when the repo provides it
- Fallback: query open PRs with
```
gh pr list --state open --json number,title,body,headRefName,url
```
Claim issue —
- Assign the issue to yourself
- Ensure the issue is attached to the canonical delivery project
- Mark the linked project item
```
Status
```
  as
```
In Progress
```
- Re-read the issue and confirm the claim stuck before proceeding
- If the issue is already claimed by your lane, treat this as resume and continue
- If the issue is claimed by another lane, stop instead of competing
Load context — Read
```
project.md
```
for product vision, domain glossary, quality bar
Readiness gate — Run
```
/issue lint $1
```
:
- Score >= 70: proceed
- Score 50-69: run
```
/issue enrich $1
```
  first, then re-lint
- Score < 50: flag to user, attempt enrichment, re-lint
- Never skip an issue because it scored low — YOU make it ready
Intent gate — Ensure issue has
```
## Product Spec
```
and
```
### Intent Contract
```
. If missing, invoke
```
/shape --spec-only $1
```
and re-check before coding.
Design — Invoke
```
/shape --design-only
```
if no
```
## Technical Design
```
section. If design contains a state machine or concurrent protocol, consider
```
/formal-verify loop
```
before proceeding to build.
Build (TDD Enforced) — Invoke
```
/build
```
and require RED→GREEN evidence per acceptance criterion:
- RED: failing targeted tests before implementation
- GREEN: same tests passing after implementation
- If test harness is broken, stop and flag blocker (no implementation without explicit user bypass)
- Delete compatibility scaffolding in greenfield/pre-user paths unless a real contract requires it
Visual QA — If diff touches frontend files (
```
app/
```
,
```
components/
```
,
```
*.css
```
), run
```
/visual-qa --fix
```
. Fix P0/P1 before proceeding.
Agentic QA — If diff touches prompts, model routing, tool schemas, or agent instructions, run
```
/llm-infrastructure
```
and inspect trace/eval coverage before shipping.
Refine —
```
/pr-fix --refactor
```
, update docs inline, then run simplification pass:
- Mandatory when diff >200 LOC net: run
```
/simplify
```
  — no exceptions
- For smaller diffs: manual module-depth review + simplification edits using Ousterhout checks: shallow modules, information leakage, pass-throughs, and compatibility shims with no active contract
- Optional accelerator: use an
```
ousterhout
```
  persona/agent if the harness provides one
Dogfood QA — Run automated QA against local dev server (see Dogfood QA section below). Iterate until no P0/P1 issues remain. Do not open a PR until QA passes. 11a. Verify ACs — Invoke
```
verify-ac
```
against the linked issue's
```
## Acceptance Criteria
```
.

Honor explicit AC tags (
```
[test]
```
,
```
[command]
```
,
```
[behavioral]
```
) when present; otherwise let
```
verify-ac
```
choose the narrowest credible strategy from the diff and repo context
Retry
```
UNVERIFIED
```
checks once (2 attempts total)
If any AC remains
```
UNVERIFIED
```
after attempt 2: keep remediating the code, tests, or docs and rerun
```
verify-ac
```
; do not commit or ship while the gate is failing
Escalate to the user only when further progress is genuinely blocked after reasonable remediation attempts
```
PARTIAL
```
may proceed only if no AC is
```
UNVERIFIED
```
, but it must be reported in the final handoff and PR body

Walkthrough — Run
```
/pr-walkthrough
```
and produce the mandatory walkthrough package for the branch. Every PR needs an artifact, even if the change is internal or architectural.
Commit — Create semantic commits for all remaining changes:
- Categorize files: commit, gitignore, delete, consolidate
- Group into logical commits:
```
feat:
```
  ,
```
fix:
```
  ,
```
docs:
```
  ,
```
refactor:
```
  ,
```
test:
```
  ,
```
chore:
```
- Subject: imperative, lowercase, no period, ~50 chars. Body: why not what.
- Run quality gates (
```
lint
```
  ,
```
typecheck
```
  ,
```
test
```
  ) before pushing
- ```
git fetch origin && git push origin HEAD
```
  (rebase if behind)
- Never force push. Never push to main without confirmation.
Ship — Open or update a live PR:
- Stage and commit any uncommitted changes with semantic message
- Read linked issue from branch name or recent commits
- Re-run
```
python3 scripts/issue_lane.py --repo <owner/name> --issue <N>
```
  immediately before opening the PR when available
- Otherwise re-run the in-flight gate immediately before opening the PR
- If an open PR already exists for the branch, use
```
gh pr edit
```
  , not
```
gh pr create
```
- If another open PR already exists for the same issue, stop and surface the duplication instead of creating a second lane
- Load
```
../pr/references/pr-body-template.md
```
  and follow it
- The
```
Walkthrough
```
  section must link the artifact and name the persistent verification that protects the demonstrated path
- PR body must contain all sections:
  - Why This Matters: Problem, value added, why now, issue link. This is top-of-line.
  - Trade-offs / Risks: Costs accepted, remaining concerns, why the trade is worthwhile.
  - Intent Reference: Copy/paste issue intent contract summary + link to source issue section.
  - Changes: Concise list of what was done. Key files/functions.
  - Alternatives Considered: Do nothing, credible alternative(s), and why current approach won.
  - Acceptance Criteria: From linked issue. Checkboxes.
  - Manual QA: Step-by-step verification. Commands, expected output.
  - What Changed: Mermaid flow chart for base branch, Mermaid flow chart for this PR, and a third Mermaid architecture/state/sequence diagram, plus explanation of why the new shape is better.
  - Before / After: Text description mandatory. Screenshots for UI changes. Use
```
<details>
```
    for heavy evidence.
  - Test Coverage: Specific test files/functions. Note gaps.
  - Merge Confidence: Confidence level, strongest evidence, residual risk.
- Keep deep sections under
```
<details>
```
  where useful, but do not hide the topline significance/trade-off story
- Use
```
--body-file
```
  for
```
gh pr create
```
  ,
```
gh pr edit
```
  , and PR comments
- ```
gh pr create --assignee phrazzld --body-file <path>
```
- Add context comment if notable decisions were made
- Opening or updating the PR creates the review lane. It does not mean the PR is review-clean.
- If your final push,
```
gh pr ready
```
  , or PR edit triggers async reviewers, do not post any "PR Unblocked" or "ready for merge" signal unless
```
/pr-fix
```
  has passed its live settlement gate on that PR
CI Gate — Wait for CI to complete on the PR.
- Poll with
```
gh pr checks <PR> --watch
```
  or
```
gh run list --branch <branch> --limit 1
```
- If any checks are red/failing: investigate root cause, fix, commit, push, then wait for CI again
- Repeat until all checks pass
- Do not proceed to review settlement while CI is red
Review Settlement — Read every single PR review and comment. Think critically about each. For every review point, determine one of three dispositions:
- In scope: Fix it in the branch. Commit, push. Reply to the comment confirming the fix.
- Valid but out of scope: Create a separate GitHub issue (or add to BACKLOG.md if the repo uses one). Reply to the comment linking the tracking item.
- Invalid: Reply with clear reasoning for why the feedback doesn't apply.
- Every review point gets a written response on the PR — none are silently ignored.
- If fixes were pushed, return to step 15 (CI Gate) and re-verify before proceeding.
Polish — Once CI is green and every review comment is addressed:
- Run
```
/pr-polish
```
- Run
```
/simplify
```
- If these generate changes, commit and push, then return to step 15 (CI Gate) to re-verify
Merge — Once CI is green, all reviews are settled, and polish is complete:
- Squash merge via
```
gh pr merge --squash
```
- Never merge with failing checks
- Never merge with unaddressed review comments
Retro (Optional) — Only capture implementation signals when the repo already uses issue-scoped retro notes and the signal is worth keeping.
- Use one file per issue under
```
.groom/retro/<issue>.md
```
  .
- Never append to a shared
```
.groom/retro.md
```
  ; skip retro entirely instead of creating merge-hot churn for low-value notes.
- If you do append, prefer the repo's issue-scoped retro command/path (for example
```
/done append --issue ...
```
  ) rather than inventing a new shared log format.

查找符合条件的issue —
- 指定issue场景：在做任何操作前先检查处理人、项目状态、公开PR情况
- 自动选择场景：选择优先级最高的未分配、未
```
In Progress
```
  、无公开PR或活跃autopilot链路的公开issue
- 如果没有公开issue，停止执行并上报队列为空
- 如果存在公开issue但都不符合条件，停止执行并上报所有公开工作已被认领
- 优先链路检查：如果仓库提供对应脚本，运行
```
python3 scripts/issue_lane.py --repo <owner/name> --issue <N>
```
- fallback方案：通过
```
gh pr list --state open --json number,title,body,headRefName,url
```
  查询公开PR
认领issue —
- 将issue分配给自己
- 确保issue关联到标准交付项目
- 将关联的项目条目
```
Status
```
  标记为
```
In Progress
```
- 重新读取issue确认认领成功后再继续
- 如果issue已经被你的链路认领，视为恢复工作继续执行
- 如果issue被其他链路认领，停止执行不要竞争
加载上下文 — 读取
```
project.md
```
了解产品愿景、领域术语表、质量标准
就绪门禁 — 运行
```
/issue lint $1
```
：
- 得分 >= 70：继续执行
- 得分50-69：先运行
```
/issue enrich $1
```
  ，再重新校验
- 得分 < 50：上报给用户，尝试补全信息后重新校验
- 永远不要因为issue得分低就跳过，你负责让它达到就绪状态
意图门禁 — 确认issue包含
```
## Product Spec
```
和
```
### Intent Contract
```
部分。如果缺失，调用
```
/shape --spec-only $1
```
补全后再开始编码。
设计 — 如果没有
```
## Technical Design
```
部分，调用
```
/shape --design-only
```
。如果设计包含状态机或并发协议，在开始开发前考虑执行
```
/formal-verify loop
```
。
开发（强制TDD） — 调用
```
/build
```
，要求每个验收标准都提供红→绿的证据：
- 红：实现前针对性测试用例运行失败
- 绿：实现后相同测试用例运行通过 n - 如果测试框架损坏，停止执行上报阻塞问题（没有用户明确绕过许可不得开始实现）
- 新功能/未上线路径中删除兼容性脚手架，除非有真实的契约要求保留
可视化QA — 如果差异涉及前端文件（
```
app/
```
、
```
components/
```
、
```
*.css
```
），运行
```
/visual-qa --fix
```
，修复P0/P1问题后再继续。
Agent QA — 如果差异涉及Prompt、模型路由、工具Schema或Agent指令，发布前运行
```
/llm-infrastructure
```
检查链路追踪/评估覆盖率。
优化 — 执行
```
/pr-fix --refactor
```
，同步更新文档，然后执行简化流程：
- 净差异超过200行代码时强制要求：运行
```
/simplify
```
  — 无例外
- 更小的差异：手动模块深度评审 + 基于Ousterhout原则的简化编辑：检查浅模块、信息泄露、透传逻辑、无活跃契约要求的兼容垫片
- 可选加速：如果框架提供
```
ousterhout
```
  角色/Agent可以直接使用
内测QA — 对本地开发服务运行自动化QA（见下文内测QA部分），迭代直到没有P0/P1问题。QA通过前不要创建PR。 11a. 验证AC — 针对关联issue的
```
## Acceptance Criteria
```
调用
```
verify-ac
```
：

存在明确AC标签（
```
[test]
```
、
```
[command]
```
、
```
[behavioral]
```
）时遵循标签要求，否则让
```
verify-ac
```
根据差异和仓库上下文选择最合理的窄范围验证策略
```
UNVERIFIED
```
的检查项重试一次（共2次尝试）
如果2次尝试后仍有AC处于
```
UNVERIFIED
```
状态：持续修复代码、测试或文档后重新运行
```
verify-ac
```
，门禁不通过不得提交或发布
仅当合理修复后确实无法继续推进时，才可以上报给用户
没有
```
UNVERIFIED
```
AC的情况下
```
PARTIAL
```
状态可以继续，但必须在最终交接和PR正文中说明

走查 — 运行
```
/pr-walkthrough
```
生成分支必须的走查包。每个PR都需要附带相关材料，哪怕是内部或架构变更。
提交代码 — 为所有剩余变更创建语义化提交：
- 文件分类：提交、gitignore、删除、合并
- 按逻辑分组提交：
```
feat:
```
  、
```
fix:
```
  、
```
docs:
```
  、
```
refactor:
```
  、
```
test:
```
  、
```
chore:
```
- 提交标题：祈使句、小写、无句号、约50字符。提交正文：说明原因而非改动内容
- 推送前运行质量门禁（
```
lint
```
  、
```
typecheck
```
  、
```
test
```
  ）
- 执行
```
git fetch origin && git push origin HEAD
```
  （落后于远程时先rebase）
- 永远不要强制推送，没有确认前永远不要推送到main分支
发布 — 创建或更新公开PR：
- 暂存所有未提交的变更，用语义化信息提交
- 从分支名或最近提交读取关联的issue
- 创建PR前如果仓库提供对应脚本，立即运行
```
python3 scripts/issue_lane.py --repo <owner/name> --issue <N>
```
- 否则创建PR前立即运行运行中的门禁校验
- 如果分支已经存在公开PR，使用
```
gh pr edit
```
  而非
```
gh pr create
```
- 如果同一个issue已经存在其他公开PR，停止执行上报重复问题，不要创建第二个链路
- 读取
```
../pr/references/pr-body-template.md
```
  并遵循模板要求
- ```
Walkthrough
```
  部分必须关联走查材料，说明保护演示路径的持久化验证规则
- PR正文必须包含所有以下部分：
  - 变更价值：问题、新增价值、上线原因、issue链接，放在最前面
  - 权衡/风险：接受的成本、剩余问题、说明权衡的合理性
  - 意图参考：复制粘贴issue意图契约摘要 + 关联issue对应部分的链接
  - 变更内容：简洁的改动列表，核心文件/函数
  - 备选方案：不做改动、其他可行方案、说明当前方案胜出的原因
  - 验收标准：来自关联issue，用复选框展示
  - 手动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已解锁」或「可合并」的信号
CI门禁 — 等待PR的CI执行完成：
- 通过
```
gh pr checks <PR> --watch
```
  或
```
gh run list --branch <branch> --limit 1
```
  轮询状态
- 如果任何检查变红/失败：排查根因、修复、提交、推送，然后重新等待CI
- 重复直到所有检查通过
- CI变红时不要进入评审闭环环节
评审闭环 — 阅读每一条PR评审和评论，批判性思考每条意见。对每条评审意见选择三种处理方式之一：
- 属于本次范围：在分支中修复，提交推送，回复评论确认已修复
- 有效但不属于本次范围：创建单独的GitHub issue（如果仓库使用BACKLOG.md则添加到该文件），回复评论关联跟踪项
- 无效：清晰回复说明反馈不适用的原因
- 每条评审意见都需要在PR上有书面回复，不得静默忽略
- 如果推送了修复内容，回到第15步（CI门禁）重新验证后再继续
优化 — CI全部通过且所有评审意见处理完成后：
- 运行
```
/pr-polish
```
- 运行
```
/simplify
```
- 如果产生了变更，提交推送，回到第15步（CI门禁）重新验证
合并 — CI全部通过、所有评审闭环、优化完成后：
- 通过
```
gh pr merge --squash
```
  执行压缩合并
- 检查失败时永远不要合并
- 有未处理的评审评论时永远不要合并
回顾（可选） — 仅当仓库已经使用issue维度的回顾记录，且记录的信息有保留价值时才执行：
- 每个issue对应
```
.groom/retro/<issue>.md
```
  下的单独文件
- 不要追加到共享的
```
.groom/retro.md
```
  文件；如果是低价值的记录，直接跳过回顾不要制造合并冲突
- 如果要追加记录，优先使用仓库的issue维度回顾命令/路径（例如
```
/done append --issue ...
```
  ），不要发明新的共享日志格式

Dogfood QA

内测QA

Run before every PR. No exceptions.

/dogfood

is an agent skill, not a shell binary. Invoke it as

/dogfood ...

. Do not run

dogfood --help

or declare it unavailable based on shell PATH. Use

agent-browser

browser-use

for focused manual repro and follow-up verification.

每个PR创建前必须运行，无例外。

/dogfood

是Agent技能，不是shell二进制文件，按

/dogfood ...

格式调用。不要运行

dogfood --help

，也不要因为shell PATH中找不到就声明该能力不可用。使用

agent-browser

browser-use

做针对性的手动复现和后续验证。

Setup

环境准备

bash

undefined

bash

undefined

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

PORT=$(lsof -i :3000 -sTCP:LISTEN -t 2>/dev/null | head -1) if [ -z "$PORT" ]; then bun dev:next & DEV_PID=$! sleep 10 # 等待编译完成 fi

Confirm it's up

确认服务已启动

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/


If port 3000 is taken by another project, use `bun dev:next -- --port 3001` and adjust the
target URL accordingly.

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/


如果3000端口被其他项目占用，使用`bun dev:next -- --port 3001`启动，对应调整目标URL。

Run

执行

/dogfood http://localhost:3000

Scope to the diff: if the issue only touches status pages,

/dogfood http://localhost:3000 Focus on the status page and badge changes

. For full-feature work, no scope restriction.

/dogfood http://localhost:3000

可以限定差异范围：如果issue仅修改状态页，执行

/dogfood http://localhost:3000 Focus on the status page and badge changes

。全功能开发则不加范围限制。

Issue Severity Gate

问题严重程度门禁

After

/dogfood

completes, read the report:

P0 or P1 issues → fix them, commit, re-run
```
/dogfood
```
on the affected area
P2 issues → fix if quick (<15 min), otherwise document in PR as known and create a follow-up issue
P3 issues / no issues → proceed to
```
/pr
```

Never open a PR with unfixed P0 or P1 issues from the dogfood report.

/dogfood

执行完成后读取报告：

P0或P1问题 → 修复、提交、在受影响区域重新运行
```
/dogfood
```
P2问题 → 可以快速修复（<15分钟）则修复，否则在PR中记录为已知问题并创建跟进issue
P3问题/无问题 → 继续执行
```
/pr
```
流程

内测QA报告中存在未修复的P0或P1问题时，永远不要创建PR。

Iteration Cap

迭代上限

If the same P0/P1 issue resurfaces after two fix attempts, stop, document the blocker, and flag to the user before proceeding. Don't loop indefinitely.

如果同一个P0/P1问题在两次修复尝试后仍然复现，停止执行、记录阻塞问题、上报给用户后再继续，不要无限循环。

Teardown

环境清理

bash

undefined

bash

undefined

Kill the dev server if we started it

如果是本流程启动的开发服务则关闭

[ -n "$DEV_PID" ] && kill $DEV_PID 2>/dev/null || true


If the user's own dev server was already running (no `$DEV_PID`), leave it alone.

[ -n "$DEV_PID" ] && kill $DEV_PID 2>/dev/null || true


如果用户自己的开发服务已经在运行（无`$DEV_PID`），不要关闭。

Parallel Refinement (Agent Teams)

并行优化（Agent团队）

After

/build

completes, parallelize the refinement phase:

Teammate	Task
Simplifier	Run code-simplifier agent, commit
Depth reviewer	Run manual module-depth review, or `ousterhout` if available, commit
Doc updater	Update docs (README, ADRs, API docs), commit

Lead sequences commits after all teammates finish. Then dogfood QA, then

/pr

Use when: substantial feature with multiple refinement needs. Don't use when: small fix where sequential is fast enough.

If native batch dispatch is available in the harness (e.g.

/batch

), use it. Otherwise launch teammates sequentially with normal agent calls.

/build

执行完成后，优化阶段可以并行执行：

团队角色	任务
简化专员	运行代码简化Agent，提交变更
深度评审员	运行手动模块深度评审，或使用可用的 `ousterhout` 能力，提交变更
文档更新员	更新文档（README、ADR、API文档），提交变更

所有团队成员完成后，负责人整理提交顺序，然后执行内测QA，再运行

/pr

。

适用场景：有多个优化需求的大型功能开发。不适用场景：小修复，串行执行速度更快的场景。

如果框架支持原生批量调度（例如

/batch

），直接使用。否则通过普通Agent调用顺序启动各角色任务。

Stopping Conditions

停止条件

Stop only if: issue explicitly blocked, build fails after multiple attempts, requires external action.

NOT stopping conditions: lacks description, seems big, unclear approach.

仅在以下场景停止：issue明确被阻塞、多次尝试后构建仍然失败、需要外部介入才能推进。

不属于停止条件的场景：缺少描述、看起来规模大、实现思路不清晰。

Output

输出内容

Report: issue worked, spec status, design status, TDD evidence (RED/GREEN), dogfood QA summary (issues found/fixed), walkthrough artifact summary, commits made, PR URL, review comments settled (count + dispositions), and merge status.

报告需包含：处理的issue、规格状态、设计状态、TDD证据（红/绿）、内测QA摘要（发现/修复的问题）、走查材料摘要、提交记录、PR URL、闭环的评审意见（数量+处理方式）、合并状态。

Review Cadence

评审节奏

Agents accrete bloat when they keep extending stale mental models. Before each new sprint or major chunk:

Re-read the touched modules fully
Look for compatibility shims added only to preserve old structure
Simplify before adding the next layer

如果Agent一直沿用陈旧的思维模型，会不断产生冗余代码。每个新迭代或大型开发块开始前：

完整重读涉及的模块
查找仅为了保留旧结构新增的兼容性垫片
在添加新层前先做简化

Harness Accelerator (Claude Code)

框架加速（Claude Code）

When this skill runs in Claude Code:

In workflow step 8 (
```
Refine
```
), run
```
/simplify
```
after
```
/pr-fix --refactor
```
.
In
```
Parallel Refinement
```
, use
```
/batch
```
to dispatch teammate tasks in one call when possible.

If either command is unavailable, use the portable fallback path already defined in the base skill.

本技能在Claude Code中运行时：

工作流程第8步（
```
优化
```
）中，
```
/pr-fix --refactor
```
执行完成后运行
```
/simplify
```
```
并行优化
```
阶段，如果支持
```
/batch
```
能力，优先使用单命令调度所有团队任务

如果任意命令不可用，使用基础技能中定义的通用 fallback 路径。