engineer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Engineer

工程师工作流

You carry ONE ticket forward, then stop. Your state lives in the board, in GitHub/Linear, and in the repo, never only in your head. This is the single workflow for both an autonomous worker (e.g.

ralph

) and a human picking up a card locally.

engineer always branches and opens a PR for

reviewer

to sign off and merge. This is the deliberate exception to the global "commit straight to main, no branches" rule: that rule governs ad-hoc solo edits; engineer is the structured, reviewed path, so it gets a branch and a PR every run.

Heavy detail is in

references/

and

scripts/

; pull those in only when you actually need them (e.g. scripting Linear MCP calls). The spine below is what you always need.

你每次推进一个工单，然后停止。你的工作状态记录在看板（GitHub/Linear）和仓库中，绝不能仅存在于你的记忆中。这是自主工作代理（例如

ralph

）和本地人工处理卡片的统一工作流。

engineer工作流始终会创建分支并为
reviewer
打开PR以进行审批和合并。这是全局“直接提交到main分支，不创建分支”规则的特殊例外：该规则适用于临时的单人编辑；而engineer是结构化的、需要审核的流程，因此每次运行都要创建分支并提交PR。

详细内容位于

references/

和

scripts/

目录中；仅在实际需要时才查阅这些内容（例如编写Linear MCP调用脚本）。以下是你必须始终遵循的核心流程。

Model

模型选择

The engineering in this workflow (the test-first implementation, sections 6-9) runs on Sonnet 5, pinned (

claude-sonnet-5

, never an older Sonnet). The strongest model is overkill for mechanical red-green-refactor coding. If you are orchestrating on a stronger model (Fable 5; Opus 4.8 fallback), dispatch the implementation to a Sonnet 5 subagent (Task/Agent tool,

model: claude-sonnet-5

): hand it the ticket, the acceptance criteria, the failing-test-first discipline, and the applicable

LEARNINGS.md

AGENTS.md

docs/adr/

constraints, and have it implement and run the gates. Keep the judgment work on the strongest model: ticket selection, the vertical-slice gate, the Triage/Needs-Info interview, the human walkthrough, and the PR/reviewer interaction. If the session is already Sonnet 5, just implement inline. (Decided routing: ENG-98, interactive/reviewer on Fable 5, workers on Sonnet 5, all on the Max sub via headless

claude -p

此工作流中的开发环节（第6-9节的测试优先实现）固定使用Sonnet 5（

claude-sonnet-5

，绝不使用旧版本的Sonnet）。对于机械性的红-绿-重构编码，更强的模型属于过度使用。如果你在使用更强的模型（Fable 5；备用Opus 4.8）进行编排，请将实现任务分派给Sonnet 5子Agent（使用Task/Agent工具，

model: claude-sonnet-5

）：向其提供工单、验收标准、先写失败测试的规则，以及适用的

LEARNINGS.md

AGENTS.md

docs/adr/

约束条件，让它完成实现并执行验证。将决策类工作保留给更强的模型：工单选择、垂直切片验证、Triage/信息补充访谈、人工走查，以及PR/审核者交互。如果当前会话已使用Sonnet 5，则直接在会话内完成实现。（路由决策：ENG-98，交互式/审核者使用Fable 5，工作代理使用Sonnet 5，均通过无头

claude -p

在Max子系统上运行。）

0. Resolve the tracker (AFK registry)

0. 解析跟踪器（AFK注册表）

Look up the repo root (

git rev-parse --show-toplevel

) in

~/.claude/afk.json

under

repos

. The entry names the

tracker

(

github

linear

, or any other), the board coordinates, the board's

readyStatus

humanStatus

strings, and

shipMode

. If there is no entry, suggest running

/afk-setup

to pin it.

Every board speaks the same shared status vocabulary (

Triage

Ready for Agent

Ready for Human

In Progress

In Review

Changes Requested

Done

), the same one

triage

and

reviewer

use. Only the mechanics differ (GitHub via

gh

, Linear via the MCP, any future tracker via the same five operations); see Trackers at the bottom. Resolve the actual status strings from

afk.json

(they should match the canonical names verbatim).

在

~/.claude/afk.json

的

repos

字段中查找仓库根目录（通过

git rev-parse --show-toplevel

获取）。该条目包含

tracker

类型（

github

、

linear

或其他）、看板坐标、看板的

readyStatus

humanStatus

字符串，以及

shipMode

。如果没有对应条目，建议运行

/afk-setup

来配置。

所有看板使用相同的标准状态词汇（

Triage

、

Ready for Agent

、

Ready for Human

、

In Progress

、

In Review

、

Changes Requested

、

Done

），与

triage

和

reviewer

使用的词汇一致。仅操作方式不同（GitHub使用

gh

命令，Linear使用MCP，未来的跟踪器使用相同的五种操作）；详见底部的跟踪器部分。从

afk.json

解析实际的状态字符串（它们应与标准名称完全匹配）。

1. Pick exactly one ticket

1. 精确选择一个工单

Gather the project's eligible issues. Ready means the board's

readyStatus

(canonically

Ready for Agent

). Pick in this priority order, never skipping a step:

In Progress (mine): work I already started. "Mine" = an open branch for this ticket whose latest commit is mine, or a PR I opened. NOT just any In Progress card. Resume it.
Changes Requested: work the reviewer kicked back. Finish this before any new work; the context is freshest and it clears the board cheapest.
Ready for Agent: fresh work, only if (1) and (2) are empty.

Within a group, order by the board's native priority field highest-first (

Urgent

High

Medium

Low

, with

No priority

last), then by older

createdAt

as the tie-break. So a

High

ticket is picked before a

Medium

one in the same group regardless of age, and equal-priority tickets go oldest-first. (A

Ready for Agent

ticket with

No priority

should have been kicked back by the priority audit below; if you still see one, it sorts last.) Skip a ticket whose blockers are not all Done. Skip any ticket carrying a

Needs Triage

/ parked marker (it is for a human). In Progress / In Review cards that are not mine belong to other agents; do not touch them. Scope filter: if

afk.json

names a worker label for the project, only work tickets carrying it.

If nothing is eligible, print

<promise>NO_TICKETS</promise>

and STOP. (The loop runner greps this token to know the board is clear.)

收集项目中符合条件的议题。“就绪”指看板的

readyStatus

（标准为

Ready for Agent

）。按以下优先级顺序选择，绝不跳过任何步骤：

进行中（我的工单）： 我已经开始处理的工作。“我的工单”指为此工单创建的开放分支，且最新提交由我完成，或我已打开的PR。并非所有“进行中”的卡片都属于此类。继续处理该工单。
需要修改： 审核者退回的工作。在处理任何新工作前先完成此项；上下文记忆清晰，且能最快清理看板。
Agent就绪： 新工作，仅当(1)和(2)为空时才选择。

在同一优先级组内，按看板的原生优先级字段从高到低排序（

Urgent

High

Medium

Low

，

No priority

排在最后），然后按创建时间

createdAt

从早到晚作为平局决胜规则。因此，同一组内的

High

优先级工单无论创建时间早晚，都优先于

Medium

优先级工单；优先级相同的工单按创建时间从早到晚排序。（

Ready for Agent

状态且

No priority

的工单应已被下方的优先级审核退回；如果仍存在，排在最后。）跳过所有前置依赖未完成的工单。跳过带有

Needs Triage

/暂停标记的工单（此类工单需人工处理）。不属于我的“进行中/审核中”卡片属于其他Agent；请勿触碰。范围过滤：如果

afk.json

为项目指定了工作代理标签，则仅处理带有该标签的工单。

如果没有符合条件的工单，输出

<promise>NO_TICKETS</promise>

并停止。（循环 runner 会通过 grep 此标记来判断看板是否已清空。）

2. Load the project's LEARNINGS

2. 加载项目的LEARNINGS

Before writing any code, look for

LEARNINGS.md

at the repo root.

If present, read it in full. These are hard-won rules the senior reviewer distilled from past PR-review kickbacks on this project. Treat every entry as a binding constraint, equal in force to
```
AGENTS.md
```
and repo conventions.
If absent or empty, fine. Proceed. Empty is normal for a young project.
Never write to
LEARNINGS.md
. You read it; only the reviewer curates it. If you find a lesson worth recording, surface it in your PR description so the reviewer can decide.

3. Route by status (the state machine)

3. 按状态路由（状态机）

Read the ticket's title, labels, body, any agent-brief comment, and its board status. Status is the canonical state machine; labels carry kind-of-work (bug / enhancement / security / tech-debt / documentation / research), which is orthogonal. First, refuse if truly not actionable (tell the user why):

Closed, or status
```
Done
```
(already shipped),
```
Canceled
```
, or
```
Duplicate
```
.
Status
```
Backlog
```
(parked): ask if they want to revive it before doing anything.

Otherwise route by status:

Status	Path
`Triage` (+ `needs-info` label)	Interview: resolve open design questions (see Interview discipline). Resolution flips status/label, NOT code. This is `triage` 's job; engineer only interviews if asked.
`Ready for Human`	Human walkthrough (see below). You co-pilot; the user does the work.
`Ready for Agent`	Execute: sections 4-10.
`In Progress` (mine) / `Changes Requested`	Resume / rework: section 9, skip the gate.

No exceptions for the interview paths. Even if the body looks well-spec'd, run the interview; the maintainer needs the structured Q&A, not your read of the body.

Priority audit (before executing
Ready for Agent
/
Ready for Human
). A fully groomed ticket carries a priority (the board's native priority field). If it is unset (

No priority

), the ticket skipped triage's final step: do NOT execute it. Kick it back, set status

Triage

, post a comment saying the priority is missing, and STOP.

triage

owns grooming completeness and assigns the priority (default Medium;

bug

security

at least High) before the ticket returns to

Ready for Agent

阅读工单的标题、标签、正文、任何Agent备注评论，以及其看板状态。状态是标准状态机；标签代表工作类型（bug/增强/安全/技术债务/文档/研究），二者相互独立。首先，如果工单确实无法处理，拒绝执行并告知用户原因：

已关闭，或状态为
```
Done
```
（已发布）、
```
Canceled
```
或
```
Duplicate
```
。
状态为
```
Backlog
```
（暂停）：在执行任何操作前，询问用户是否要恢复该工单。

否则，按状态路由：

状态	处理路径
`Triage` （附带 `needs-info` 标签）	访谈：解决未明确的设计问题（参见访谈规范）。解决后仅更新状态/标签，不修改代码。这是 `triage` 的职责；仅当被要求时，工程师才执行访谈。
`Ready for Human`	人工走查（详见下文）。你作为副驾驶；用户执行实际工作。
`Ready for Agent`	执行：第4-10节内容。
`In Progress` （我的工单）/ `Changes Requested`	继续/返工：第9节内容，跳过验证环节。

访谈路径无例外。即使工单正文看起来规格明确，也要执行访谈；维护者需要结构化的问答，而非你对正文的解读。

优先级审核（在执行
Ready for Agent
/
Ready for Human
前）。完全梳理后的工单必须带有优先级（看板的原生优先级字段）。如果未设置（

No priority

），说明工单跳过了triage的最后一步：切勿执行。将其退回，设置状态为

Triage

，发布评论说明缺少优先级，然后停止。

triage

负责确保工单梳理完整并分配优先级（默认Medium；

bug

security

至少为High），之后工单才能回到

Ready for Agent

状态。

4. Vertical-slice gate (new tickets only; never re-gate started work)

4. 垂直切片验证（仅针对新工单；已开始的工作无需重新验证）

Before starting NEW work, confirm the ticket is a TRUE vertical slice:

<vertical-slice-rules> - Cuts END-TO-END through all layers (data/schema -> logic -> API -> UI -> tests), NOT a horizontal slice of one layer. - Independently demoable/verifiable on its own. - As THIN as possible while still complete; prefer many thin slices over few thick. </vertical-slice-rules>

The gate FAILS if the ticket is horizontal, not independently demoable, or could be thinned further while staying a full slice. (Thickness alone is not a failure; a fat-but-complete slice is fine.)

Interactive (you, locally): STOP. Surface the failure and prompt the user to help thin/split it; offer to run
```
/to-issues
```
. Do not "just start on the first bit"; wait for the decision on how to slice it.
Autonomous (worker): add a
```
Needs Triage
```
label, post a comment explaining why and how to split/sharpen, do NOT branch or code, and STOP.

Only a passing ticket proceeds.

在开始新工作前，确认工单是真正的垂直切片：

<vertical-slice-rules> - 贯穿所有层级（数据/架构 -> 逻辑 -> API -> UI -> 测试），而非单一层级的水平切片。 - 可独立演示/验证。 - 在保持完整性的前提下尽可能精简；优先选择多个薄切片，而非少数厚切片。 </vertical-slice-rules>

如果工单是水平切片、无法独立演示，或在保持完整切片的前提下可进一步精简，则验证失败。（仅厚度大并不构成失败；完整但较厚的切片是可接受的。）

交互式（本地操作）： 停止执行。告知用户验证失败，提示用户帮助精简/拆分工单；可提议运行
```
/to-issues
```
。切勿“先处理第一部分”；等待用户决定如何拆分。
自主式（工作代理）： 添加
```
Needs Triage
```
标签，发布评论说明原因及拆分/优化方法，不创建分支或编写代码，然后停止。

只有通过验证的工单才能继续执行。

5. Claim the ticket

5. 认领工单

Once picked (and, for new tickets, only after passing section 4):

Set status In Progress before coding, so an interrupted run leaves the ticket resumable, not stranded.
Assign it to James (the board owner) as the live "an agent is working this now" marker: his avatar on the card while it is
```
In Progress
```
means the engineer is on it. Set
```
assignee
```
to James explicitly, overriding whatever the board auto-assigned on the started transition. Do this on every claim, not just the first. (This is the assign half of the activity-marker rule; the unassign half is section 10.)

一旦选定工单（对于新工单，需通过第4节验证后）：

在编写代码之前将状态设置为In Progress，这样即使运行中断，工单仍可恢复，不会停滞。
将工单分配给James（看板所有者）作为“当前有Agent正在处理”的实时标记：当工单处于
```
In Progress
```
状态时，他的头像显示在卡片上，表示工程师正在处理。明确将
```
assignee
```
设置为James，覆盖看板在启动转换时自动分配的任何人员。每次认领工单时都要执行此操作，而非仅第一次。（这是活动标记规则的分配部分；取消分配部分在第10节。）

6. Create the branch (gitflow naming)

6. 创建分支（gitflow命名规范）

git checkout main && git pull

, then branch:

```
feature/<slug>
```
by default, or
```
bug/<slug>
```
if the issue carries a
```
bug
```
label (case-insensitive).
Derive
```
<slug>
```
from the issue's own branch name / identifier: drop the leading prefix segment (up to and including the first
```
/
```
) and keep the rest, so
```
<prefix>/<identifier>-<title>
```
->
```
feature/<identifier>-<title>
```
. The identifier stays so the branch traces back to the ticket.

When resuming, find the existing branch by identifier (

git branch -a --list "*<identifier>-*"

) or the open PR's head branch; check it out. Do NOT reset or check out main (that discards in-flight work).

执行

git checkout main && git pull

，然后创建分支：

默认使用
```
feature/<slug>
```
，如果议题带有
```
bug
```
标签（不区分大小写），则使用
```
bug/<slug>
```
。
```
<slug>
```
从议题自身的分支名称/标识符派生：去掉前缀部分（包括第一个
```
/
```
），保留剩余部分，例如
```
<prefix>/<identifier>-<title>
```
->
```
feature/<identifier>-<title>
```
。保留标识符以便分支可追溯到工单。

当继续处理时，通过标识符查找现有分支（

git branch -a --list "*<identifier>-*"

）或已打开PR的源分支；切换到该分支。切勿重置或切换到main分支（这会丢弃正在进行的工作）。

7. Implement test-first, routed by label (NON-NEGOTIABLE)

7. 测试优先实现，按标签路由（不可协商）

Every code path is done test-first (use the

tdd

skill; follow red-green-refactor):

RED FIRST: write the failing test and see it fail for the right reason. A new/changed test green on first run is wrong; fix the test.
Assert behaviour/structure, not substrings. A substring check that passes on broken output is a defect.
Honor every applicable
```
LEARNINGS.md
```
entry,
```
AGENTS.md
```
, and
```
docs/adr/
```
.
Then refactor, then run the full gates (e.g.
```
typecheck && lint && test && build
```
).

Route the kind of work by label:

Label	How to work it
`enhancement`	Test-first vertical slice. One failing test -> one slice of impl -> repeat. Tracer bullets, not horizontal layers.
`bug`	Reproduce with a failing test FIRST, then minimal fix. Never AskUserQuestion about fix direction before the repro confirms the shape.
`bug` (hard repro / perf)	Diagnose discipline: reproduce -> minimise -> hypothesise -> instrument -> fix -> regression-test.
`security`	Treat as a bug: failing test demonstrating the vuln, then patch.
`tech-debt`	Refactor / rename / dead-code removal, no behaviour change. Tests still pass; ideally no test changes beyond renames.
`documentation`	Edit the doc; no code change. Treat as P0.

If multiple labels apply or routing is ambiguous, state your read and ask which path.

每个代码路径都必须采用测试优先的方式（使用

tdd

技能；遵循红-绿-重构流程）：

先红： 编写失败的测试，并确认测试因正确的原因失败。新/修改的测试首次运行就通过是错误的；需修复测试。
断言行为/结构，而非子字符串。通过子字符串检查但输出实际错误的测试存在缺陷。
遵守所有适用的
```
LEARNINGS.md
```
条目、
```
AGENTS.md
```
和
```
docs/adr/
```
内容。
然后进行重构，再运行完整的验证（例如
```
typecheck && lint && test && build
```
）。

按标签路由工作类型：

标签	处理方式
`enhancement`	测试优先的垂直切片。先写一个失败的测试 -> 实现一部分切片 -> 重复此过程。采用 tracer bullets 方式，而非水平分层。
`bug`	首先用失败的测试重现问题，然后进行最小化修复。在重现确认问题形态前，切勿询问用户修复方向。
`bug` （难以重现/性能问题）	诊断流程：重现 -> 最小化 -> 假设 -> 监控 -> 修复 -> 回归测试。
`security`	视为bug处理：先写演示漏洞的失败测试，然后打补丁。
`tech-debt`	重构/重命名/删除死代码，不改变行为。测试仍需通过；理想情况下除重命名外无需修改测试。
`documentation`	编辑文档；不修改代码。视为最高优先级（P0）。

如果多个标签适用或路由不明确，说明你的判断并询问用户选择哪种路径。

8. Finish like

/go

: verify end-to-end, then simplify

8. 按/go标准收尾：端到端验证，然后简化

Once the gates from section 7 are green, run the two finishing steps the

/go

skill defines, in order, BEFORE you commit and open the PR:

Verify end-to-end (
```
/go
```
step 1). Green units are not proof the change works. Exercise the touched surface the way a user hits it, per the repo's verification rules: UI through the repo's browser method (Chrome extension / agent browser), a backend by hitting the running service, a CLI by running it. Fix what you find before moving on. If the ticket has no runtime surface to drive (documentation-only, naming-only, pure config), say so and skip this step; do not fake a verification.
Simplify (
```
/go
```
step 2). Make one reduction pass over the full diff: delete anything that does not earn its place (single-caller abstractions, dead branches, speculative handling, leftovers from abandoned approaches). Behaviour must not change. Use the
```
code-simplifier
```
agent for a large diff, inline for a small one; re-run the section 7 gates if the pass changed code. If nothing comes out, say so and move on.

Keep engineer's own stricter discipline: do NOT adopt

/go

's "skip the local pipeline" shortcut (engineer runs the full gates in section 7), and do NOT use

/go

's step 3 to open the PR. Engineer owns the PR and board transitions itself, via sections 9 and 10 below.

当第7节的验证通过后，在提交并打开PR之前，按顺序执行

/go

技能定义的两个收尾步骤：

端到端验证（
```
/go
```
第一步）。单元测试通过并不代表变更有效。按照仓库的验证规则，以用户的方式测试受影响的部分：UI通过仓库的浏览器方法（Chrome扩展/Agent浏览器），后端通过运行服务并调用接口，CLI通过直接运行。在继续执行前修复发现的问题。如果工单没有可运行的表面（仅文档、仅命名、纯配置），说明情况并跳过此步骤；切勿伪造验证。
简化（
```
/go
```
第二步）。对完整的代码差异进行一次精简：删除任何不必要的内容（单一调用者的抽象、无效分支、推测性处理、废弃方案的残留代码）。行为必须保持不变。对于大型差异，使用
```
code-simplifier
```
Agent；对于小型差异，直接在会话内处理；如果精简修改了代码，重新运行第7节的验证。如果没有可精简的内容，说明情况并继续。

保持engineer自身更严格的规范：不要采用

/go

的“跳过本地流水线”捷径（engineer在第7节运行完整的验证），不要使用

/go

的第三步来打开PR。engineer通过以下第9和10节自行负责PR和看板状态转换。

9. Per-path specifics

9. 各路径的具体操作

Each path runs the section 8 finish (verify end-to-end, then simplify) after its gates are green and before it opens the PR.

In Progress (resume): inspect what exists (
```
git status
```
,
```
git log main..HEAD
```
), finish every acceptance criterion, gates green, commit, push. Open the PR if none exists (body: "Closes <ID>" + each AC mapped to how it's met); else the push updates it. Move to In Review.
Changes Requested (rework): find the open PR + branch, read ALL feedback (PR reviews, inline comments, latest board comments). Write a failing test per reported bug, address every requested change scoped to the feedback, gates green, commit, push, reply on the PR + board, move back to In Review.
Ready for Agent (new): after the gate, claim+assign (5), branch (6), read
```
AGENTS.md
```
+
```
docs/adr/
```
first, implement test-first to satisfy every AC, gates green, commit, push, open the PR, move to In Review.

每个路径在验证通过后、打开PR前，都要执行第8节的收尾步骤（端到端验证，然后简化）：

进行中（继续处理）： 检查现有内容（
```
git status
```
、
```
git log main..HEAD
```
），完成所有验收标准，验证通过，提交，推送。如果尚未打开PR，则打开PR（正文：“Closes <ID>” + 每个验收标准对应实现方式）；否则推送更新PR。将状态改为In Review。
需要修改（返工）： 找到已打开的PR和分支，阅读所有反馈（PR审核、行内评论、最新看板评论）。针对每个报告的bug编写失败的测试，处理所有反馈范围内的修改请求，验证通过，提交，推送，在PR和看板上回复，将状态改回In Review。
Agent就绪（新工单）： 通过验证后，认领+分配（第5节），创建分支（第6节），先阅读
```
AGENTS.md
```
+
```
docs/adr/
```
，采用测试优先方式实现所有验收标准，验证通过，提交，推送，打开PR，将状态改为In Review。

10. Stop at the PR (do not merge)

10. 在PR环节停止（不要合并）

Open/advance the PR and move the card to In Review, then STOP. When you move it to In Review, unassign it (

assignee: null

): the engineer is done, so James's activity marker comes off until the reviewer picks it up (section 5 assigned it when work began; this clears it now that work has stopped). The senior reviewer (

reviewer

) owns the merge. Even if a repo's

AGENTS.md

grants self-merge, do not push the merge button, do not auto-merge via CI, do not delete the branch. The reviewer signals completion by moving the card to Done (or to Changes Requested, which comes back to you on the next engineer run).

Acceptance-criteria honesty (STRICT). Do not tick an AC because the code that would make it true is merged and the tests pass. An AC is met only when you can show it is true. If an AC needs evidence you cannot produce here (production secrets or credentials, observing a deployed cron/webhook actually firing, a "morning after" behavior, a migration on the live DB), you may NOT silently mark it done: either flag it via the Manual-QA gate below so the reviewer parks it for James, or split it into a linked

Ready for Human

follow-up and name that in your closing summary. Shipping config-dependent automation (cron, webhook, scheduled job) without its config provisioned and seen working is not done.

Manual-QA flag (do this as you move to In Review). If your closing summary's Manual QA is a real item (anything other than "none needed"), the change needs a human check before it can ship. So that the reviewer parks it instead of auto-merging:

Add the Needs Manual QA
label to the card.
Post a board comment titled Manual QA required before merge
(with the AI disclaimer). It MUST lead with where to look, on its own lines at the very top, so James never has to guess what he is QA-ing:
- ```
**Branch:** <branch-name>
```
- ```
**Preview:** <vercel-preview-url>
```
  (the deploy of THIS branch, not prod). Get it from the PR's Vercel comment /
```
gh pr view
```
  . If no preview exists yet, say so and how to get one (push, or run locally on that branch) rather than leaving it blank, and flag it so previews get fixed. Then list the exact steps James must run or eyeball and why an agent cannot do them. Keep it concrete; this is the checklist James works from and the text the reviewer puts in its Discord ping. The Discord
```
qa-hold
```
  ping must also name the branch and preview URL.
Linear: also pin the preview as a clickable chip. In addition to the comment, add a Linear link attachment titled
```
Preview
```
pointing at the same branch-alias preview URL, so it renders as a chip at the top of the card and James does not have to open the comment to reach it. Mechanism:
```
save_issue
```
with
```
links: [{title: "Preview", url}]
```
(the
```
create_attachment
```
tool is for file uploads, NOT this).
```
links
```
is append-only, so first read the card's existing attachments (
```
get_issue
```
) and only add when there is no
```
Preview
```
attachment already, to avoid stacking duplicates on a re-run. On GitHub or other trackers, skip this; the comment above is enough. When the only thing left on an approved, CI-green PR is this manual QA, the reviewer will leave the card parked in
```
In Review
```
, NOT merge it, and ping James; James QAs, then merges (or asks an agent to). If Manual QA is "none needed", do not add the label, and the reviewer merges as usual.

Non-execution outcomes (from any path):

Needs Info: implementation surfaced a question only the reporter can answer. Post a comment (with the disclaimer) listing the specific questions; set status Needs Info /
```
Backlog
```
. Do NOT commit speculative code.
Blocked: a dependency surfaced mid-flight. Add a
```
blocked
```
/
```
blockedBy
```
marker, comment naming the blocker, leave status as-is.

打开/更新PR并将卡片状态改为In Review，然后停止。当将状态改为In Review时，取消分配（

assignee: null

）：工程师已完成工作，因此James的活动标记移除，直到审核者认领（第5节在工作开始时分配；现在工作结束，清除标记）。资深审核者（

reviewer

）负责合并。即使仓库的

AGENTS.md

允许自行合并，也不要点击合并按钮，不要通过CI自动合并，不要删除分支。审核者通过将卡片状态改为Done（或Changes Requested，下一次engineer运行时会回到你这里）来标记完成。

验收标准诚实性（严格要求）。不要因为代码已合并且测试通过就勾选验收标准。只有当你能证明验收标准已满足时，才能标记为完成。如果验收标准需要你无法在此处提供的证据（生产密钥或凭证、观察已部署的定时任务/ webhook实际运行、“次日”行为、实时数据库迁移），切勿默默标记为完成：要么通过下方的手动QA标记，让审核者将其分配给James，要么拆分为关联的

Ready for Human

后续工单，并在收尾总结中提及。未配置并验证其工作状态就发布依赖配置的自动化任务（定时任务、webhook、计划任务），不算完成。

手动QA标记（在改为In Review状态时执行）。如果你的收尾总结中的Manual QA是实际内容（而非“无需手动QA”），则变更在发布前需要人工检查。为了让审核者暂停合并：

为卡片添加**
```
Needs Manual QA
```
**标签。
发布标题为**
```
Manual QA required before merge
```
的看板评论（附带AI免责声明）。评论必须以检查位置**开头，单独成行放在最顶部，以便James无需猜测需要检查的内容：
- ```
**Branch:** <branch-name>
```
- ```
**Preview:** <vercel-preview-url>
```
  （此分支的部署预览，而非生产环境）。从PR的Vercel评论/
```
gh pr view
```
  获取。如果尚未生成预览，说明情况及获取方式（推送分支，或在本地运行该分支），而非留空，并标记以修复预览问题。然后列出James必须执行或检查的具体步骤，以及Agent无法执行的原因。内容要具体；这是James的检查清单，也是审核者在Discord中提及的文本。Discord的
```
qa-hold
```
  消息也必须包含分支和预览URL。
Linear：还需将预览链接固定为可点击的芯片。除评论外，添加标题为
```
Preview
```
的Linear链接附件，指向相同的分支别名预览URL，使其在卡片顶部显示为芯片，James无需打开评论即可访问。实现方式：使用
```
save_issue
```
并传入
```
links: [{title: "Preview", url}]
```
（
```
create_attachment
```
工具用于文件上传，不适用此场景）。
```
links
```
是追加式的，因此先读取卡片的现有附件（
```
get_issue
```
），仅当尚未存在
```
Preview
```
附件时才添加，避免重复添加。在GitHub或其他跟踪器上，跳过此步骤；上述评论已足够。当已批准、CI通过的PR仅剩下手动QA时，审核者会将卡片停留在
```
In Review
```
状态，不合并，并通知James；James完成QA后，再合并（或要求Agent合并）。如果Manual QA为“无需手动QA”，则不要添加标签，审核者按常规流程合并。

非执行结果（来自任何路径）：

需要信息： 实现过程中发现只有报告者才能解答的问题。发布评论（附带免责声明）列出具体问题；设置状态为Needs Info/
```
Backlog
```
。切勿提交推测性代码。
阻塞： 执行过程中出现依赖项问题。添加
```
blocked
```
/
```
blockedBy
```
标记，发布评论说明阻塞原因，保持状态不变。

Closing summary (STRICT: exactly four items)

收尾总结（严格要求：恰好四个条目）

Write each as a standalone paragraph (bold label + text), separated by blank lines (list markers render tight in the terminal;

&nbsp;

prints literally). No file lists, no diffs, no per-file walkthrough. The user does not read them.

**What the card was:** <the issue in one line>

**What we did:** <the change in plain terms, outcomes not file paths>

**How it was verified:** <tests run + result, typecheck/lint, any visual check>

**Manual QA:** <"none needed (covered by X)" OR the specific thing the human must
eyeball/click and why an agent couldn't>

每个条目作为独立的段落（加粗标签+文本），用空行分隔（列表标记在终端中显示紧凑；

&nbsp;

会被原样打印）。不要包含文件列表、差异、逐文件说明。用户不会阅读这些内容。

**工单内容：** <用一句话描述议题>

**完成工作：** <用通俗语言描述变更，聚焦结果而非文件路径>

**验证方式：** <运行的测试+结果，类型检查/代码检查，任何可视化检查>

**手动QA：** <"无需手动QA（由X覆盖）" 或 人工必须检查/点击的具体内容，以及Agent无法执行的原因>

Interview discipline (Triage / Needs Info / Backlog)

访谈规范（Triage / 需要信息 / 待办）

The triage state means "needs the human's brain." Resolve design questions BEFORE applying labels or flipping state.

Plain English. Talk about the actual app (alert emails, dashboard cards, Form 4, 8-K), not jargon ("consumer", "registry", "coupling") unless defined.
One question at a time. Never batch decisions.
Vertical slices. Every shaped issue must describe a tracer-bullet slice end-to-end. If horizontal, narrow it.
No "when does this ship?" questions. Scheduling is the user's call.
No code dumps. Default reply shape: Issue -> Options -> Recommendation -> Effects.
No AskUserQuestion about bug-fix direction before reproducing. Failing test first.

When the issue plausibly introduces/renames a domain term, changes the data model, sets tier/gating semantics, or warrants an ADR, the interview must update

CONTEXT.md

and/or

docs/adr/

inline as decisions crystallise. Otherwise the conversation alone is enough. After resolving, apply the category label and the new status; don't auto-advance to implementation in the same session unless told to.

Triage状态意味着“需要人工决策”。在应用标签或更改状态前，先解决设计问题：

使用通俗语言。讨论实际应用（提醒邮件、仪表板卡片、Form 4、8-K），除非已定义，否则不要使用行话（“consumer”、“registry”、“coupling”）。
一次一个问题。切勿批量决策。
垂直切片。每个明确的议题必须描述一个端到端的tracer-bullet切片。如果是水平切片，缩小范围。
不要问“什么时候发布？” 排期由用户决定。
不要粘贴代码。默认回复结构：议题 -> 选项 -> 建议 -> 影响。
在重现问题前，不要询问用户bug修复方向。先写失败的测试。

当议题可能引入/重命名领域术语、更改数据模型、设置层级/门控语义，或需要ADR时，访谈必须在决策明确时同步更新

CONTEXT.md

和/或

docs/adr/

。否则仅对话即可。解决问题后，应用分类标签和新状态；除非被告知，否则不要在同一会话中自动推进到实现环节。

Human walkthrough (Ready for Human)

人工走查（Ready for Human）

The user does the work (reads samples, exercises the UI, makes the judgement call, accesses systems you can't reach). Keep them in flow: hold the rubric, surface one step at a time, capture findings, draft the closeout.

First check for blockers (issue body / sub-issue tree). If a needed dependency is still open, surface it and stop. Otherwise:

Parse the work plan (the body's Work / Acceptance / numbered steps). Build the step list in your head; do not dump it on the user.
Restate the goal in one sentence, then state step 1 with the minimum context they need (rubric, file/URL, what "good" looks like).
Wait for their finding (clean / drift / question / tangent).
Capture it in a running log, one line per step in the AC format.
Surface the next step, same shape.
If they get stuck, pause and help resolve before continuing.
At the end, draft the closeout comment (per-step findings + verdict + any prompt changes); show the user before posting.

用户执行实际工作（阅读示例、操作UI、做出决策、访问你无法访问的系统）。保持用户流畅：遵循规则，逐步展示步骤，记录发现，起草收尾内容。

首先检查是否存在阻塞因素（议题正文/子议题树）。如果所需依赖项仍未完成，告知用户并停止。否则：

解析工作计划（正文的工作/验收/编号步骤）。在脑中构建步骤列表；不要直接展示给用户。
用一句话重述目标，然后展示第一步，并提供用户所需的最少上下文（规则、文件/URL、“正确”的标准）。
等待用户的反馈（正常/偏差/问题/题外话）。
记录反馈，按验收标准格式逐行记录。
展示下一步，格式相同。
如果用户遇到困难，暂停并帮助解决后再继续。
结束时，起草收尾评论（按步骤记录反馈+结论+任何提示变更）；在发布前展示给用户。

Comment disclaimer

评论免责声明

Any comment you post on a ticket during engineer must start with:

> *This was generated by AI during engineer.*

在engineer工作流中发布的任何工单评论，必须以以下内容开头：

> *This was generated by AI during engineer.*

Trackers (mechanics only; the vocabulary is shared)

跟踪器（仅操作方式；词汇统一）

Every board uses the same status vocabulary; only the API differs. Resolve the tracker and the actual status strings from

afk.json

GitHub Projects:

gh issue view

to read;

gh project item-edit

to set status;

gh issue edit --add-label

for labels.

Linear: load MCP tools via ToolSearch (
```
get_issue
```
,
```
list_comments
```
,
```
save_issue
```
,
```
save_comment
```
); fetch by identifier (e.g.
```
JAM-6
```
); set status with
```
save_issue { state }
```
.
Any other tracker: implement the same five operations (fetch, set status, add/remove label, comment, close). Nothing else here is tracker-specific.

Kind-of-work labels (bug/enhancement/etc.) may not exist in a young workspace; infer the route from the body and say so. If a specific CLI/MCP call isn't to hand, ask the user once rather than doing it manually.

所有看板使用相同的状态词汇；仅API不同。从

afk.json

解析跟踪器和实际状态字符串。

GitHub Projects： 使用
```
gh issue view
```
读取；使用
```
gh project item-edit
```
设置状态；使用
```
gh issue edit --add-label
```
添加标签。
Linear： 通过ToolSearch加载MCP工具（
```
get_issue
```
、
```
list_comments
```
、
```
save_issue
```
、
```
save_comment
```
）；通过标识符（例如
```
JAM-6
```
）获取工单；使用
```
save_issue { state }
```
设置状态。
其他跟踪器： 实现相同的五种操作（获取、设置状态、添加/移除标签、评论、关闭）。此处其他内容均与跟踪器无关。

工作类型标签（bug/增强等）在新工作区中可能不存在；从正文推断路由并说明情况。如果缺少特定的CLI/MCP调用，询问用户一次，而非手动执行。

Rules & habits

规则与习惯

ONE ticket per run, then stop with the closing summary.
Communicate through the board, not chat: file progress as ticket comments; keep chat replies terse. The user reads the board.
Never push to
```
main
```
outside a PR. Never merge your own PR.
Commit working progress as you go; never end a run with unrecoverable uncommitted work; the next run resumes from your commits. If you can't make the gates pass or the ticket is unclear, commit what you have, comment the blocker, leave it In Progress, and stop. Don't open a broken PR.
For ad-hoc tooling on this machine, use TypeScript (
```
bun
```
/
```
tsx
```
), not Python. Query open work; don't pull the whole board "to be thorough."

每次运行处理一个工单，然后停止并输出收尾总结。
通过看板沟通，而非聊天：将进度记录为工单评论；聊天回复保持简洁。用户会查看看板。
切勿在PR外推送到
```
main
```
分支。切勿合并自己的PR。
随时提交工作进度；运行结束时切勿留下无法恢复的未提交工作；下一次运行将从你的提交恢复。如果无法通过验证或工单不明确，提交已完成的内容，评论说明阻塞因素，保持状态为In Progress，然后停止。切勿打开有问题的PR。
在此机器上编写临时工具时，使用TypeScript（
```
bun
```
/
```
tsx
```
），而非Python。查询未完成的工作；不要为了“全面”而拉取整个看板。

Discipline that survives across all paths

所有路径通用的规范

Default to DELETE, not "gate behind a flag" when reviewing pre-revenue features.
UI changes verify both light AND dark mode.
High-risk surfaces (pricing/checkout/auth/public copy) need a Playwright spec.
Paid-service call sites get audited for token waste.
Out-of-scope bugs surfaced mid-run -> open an issue immediately, don't just mention inline.

默认删除，而非“用标记门控”，在审核营收前的功能时。
UI变更需同时验证浅色和深色模式。
高风险界面（定价/结账/认证/公开文案）需要Playwright测试用例。
付费服务调用点需审核令牌浪费情况。
执行过程中发现的超出范围的bug -> 立即打开议题，不要仅在行内提及。

References (load on demand)

参考资料（按需加载）

```
references/linear-mcp-schema.md
```
: Linear MCP field-name gotchas and response shapes. Read before scripting MCP calls or on a
```
-32602 unrecognized_keys
```
error.
```
scripts/linear-mcp-client.ts
```
: minimal Linear MCP client over HTTP+JSON-RPC.
```
scripts/linear-open.ts
```
: "what's open for me to pick up?" board reader.

```
references/linear-mcp-schema.md
```
：Linear MCP字段名称陷阱和响应格式。在编写MCP调用脚本或遇到
```
-32602 unrecognized_keys
```
错误前阅读。
```
scripts/linear-mcp-client.ts
```
：基于HTTP+JSON-RPC的轻量Linear MCP客户端。
```
scripts/linear-open.ts
```
：“我可以处理哪些工单？”看板阅读器。",