orchestrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Run a pre-specced feature across parallel

/implement

subagents on worktrees.

在worktree上通过并行的

/implement

子Agent运行预先定义好的功能。

Rule Zero

规则零

Never slice or map the work yourself. The parent issue's sub-issues ARE the work packages: fetch them, hand each verbatim to one

/implement

agent. Sub-issues missing or unclear → stop and ask the owner; do not invent packages. Process fidelity is a requirement — a correct deliverable produced off the pre-specced path gets rejected.

请勿自行拆分或规划工作内容。父议题的子议题即为工作包：获取这些子议题，将每个议题原封不动地交给一个

/implement

Agent。若子议题缺失或表述模糊，请停止操作并询问所有者；不得自行创建工作包。流程一致性是硬性要求——若交付成果符合要求但偏离了预先定义的流程，仍会被驳回。

Roles

角色

Orchestrator (you): read-only +
```
gh
```
+ spawning. Never edit
```
src/
```
. Your job: sequencing, relay, verification between phases, merges, cleanup, ops sidecar (see
```
ops.md
```
).
Agents: full
```
/implement
```
flow — native claim, own worktree, TDD, /code-review, own PR. Duplicate none of it here.
Mechanical tail (merge order, CI watch, branch/worktree cleanup) belongs to the orchestrator. Agents end at "PR open + report".

编排器（你）：仅具备只读权限 + 可使用
```
gh
```
工具 + 可生成Agent。不得编辑
```
src/
```
目录。你的职责：任务排序、信息传递、阶段间验证、合并操作、清理工作，以及运维辅助（详见
```
ops.md
```
）。
Agent：负责完整的
```
/implement
```
流程——自主认领任务、管理专属worktree、TDD测试、/code-review代码评审、创建专属PR。此处无需重复该流程的细节。
机械收尾工作（合并顺序、CI监控、分支/worktree清理）由编排器负责。Agent的工作截止到「PR已创建 + 提交报告」阶段。

Ledger

记录台账

The GitHub issue is the ledger. Whenever anything relevant happens or a decision is made without the owner, post a condensed comment — orchestrator on the parent issue, each agent on its sub-issue:

🤖 decision (bot): <one line>
<2–4 lines: why, link>

Types:

decision

question

blocker

progress

. Always the 🤖 prefix; decisions explicitly marked

(bot)

. Post via

gh issue comment N --body-file .temp/<f>.md

(heredocs are blocked). Questions go on the issue and the run proceeds where a tolerant default exists — don't block.

GitHub议题作为记录台账。每当发生相关事件或在未征得所有者同意的情况下做出决策时，请发布精简评论——编排器在父议题下评论，每个Agent在对应的子议题下评论：

🤖 decision (bot): <one line>
<2–4 lines: why, link>

类型：

decision

（决策）|

question

（疑问）|

blocker

（阻塞）|

progress

（进度）。评论必须以🤖前缀开头；决策类评论需明确标记

(bot)

。请通过

gh issue comment N --body-file .temp/<f>.md

命令发布评论（here文档被禁用）。若存在容错默认方案，发布疑问后可继续执行流程——无需暂停。

Run sequence

执行流程

Sync + fetch sub-issues.
```
git fetch && git pull --ff-only
```
(the main checkout's branch drifts — verify
```
git branch --show-current
```
; always branch from
```
origin/main
```
). Then fetch sub-issues — GraphQL only,
```
gh issue view
```
does not render them:
```
gh api graphql -f query='query{ repository(owner:"$OWNER",name:"$REPO"){ issue(number:$N){ subIssues(first:50){ nodes{ number title state } } } } }'
```
Never claim a GitHub feature is absent from CLI output alone. Done when: every sub-issue is listed with its "Blocked by" edges, or the owner has been asked.
Recon + feasibility. Read the seam files yourself — agent summaries miss API gaps. Diff the spec against current behavior before spawning the affected package. Specs may be AI-written: any one-time external setup step (webhook, OAuth app, DNS, third-party config) gets verified against current provider docs before an agent bakes it into docs — e.g. webhooks need a SECRET, not a token;
```
projects_v2_item
```
events are org-webhook-only. Gaps → ledger
```
question
```
. Done when: every external-world assumption is verified or ledgered.
Sequence + hotspots. Order from each ticket's "Blocked by". Flag shared-file hotspots (e.g. one ADR taking amendments from several tickets): serialize them, or pre-agree the conflict posture in the prompts ("keep shared-file changes additive; second-to-merge rebases"). "New files only" = parallelizable; "touches shared files" = single writer.
Spawn. One
```
/implement
```
agent per sub-issue, prompt built from
```
package-prompt.md
```
. Sequence-sensitive rules (rebase-before-PR, conflict posture, merge order) go in the original prompt — a mid-flight message crosses with the agent's push and arrives too late.
Relay + verify. An agent's /code-review children report to YOU, not to it — relay verdicts and fix lists promptly; the relay doubles as your QA checkpoint. Idle ≠ done: before acting on any "finished" signal, verify observable state — branch on origin,
```
git diff --stat
```
, the fix present in the diff (not just the ack). After any relay, expect one more round-trip. Nudge with "finish your remaining steps", never "push now" — a hurried agent skips its own QA.
Merge. On green CI only:
```
gh run watch <id> --exit-status && gh pr merge <n> --squash --delete-branch && <cleanup>
```
chained in one background call. You own merge order; second-to-merge rebases. Done when: every sub-issue has exactly one merged PR carrying
```
Closes #<sub>
```
.
Wrap-up. One final docs PR for shared-line docs (CLAUDE.md current focus) — never per-ticket. Infra blockers you cannot reach (Neon/Vercel consoles are owner-only) are a legitimate terminal state: ledger a
```
blocker
```
on the PR with evidence + the owner action needed. Post the final 🤖 tally on the parent issue.

Salvage from an archived earlier run, deploy diagnosis, Projects v2 limits, destructive-script rules:

ops.md

同步 + 获取子议题。执行
```
git fetch && git pull --ff-only
```
（主检出分支可能会偏离，请通过
```
git branch --show-current
```
验证；始终从
```
origin/main
```
分支创建新分支）。然后获取子议题——仅支持GraphQL方式，
```
gh issue view
```
无法显示子议题：
```
gh api graphql -f query='query{ repository(owner:"$OWNER",name:"$REPO"){ issue(number:$N){ subIssues(first:50){ nodes{ number title state } } } } }'
```
请勿仅根据CLI输出就断言GitHub不具备某项功能。完成标志：所有子议题及其「被阻塞于」关联关系均已列出，或已询问所有者。
调研 + 可行性分析。请自行阅读衔接文件——Agent的总结可能会遗漏API缺口。在生成受影响的工作包之前，将规格文档与当前行为进行对比。规格文档可能由AI生成：任何一次性外部设置步骤（webhook、OAuth应用、DNS、第三方配置）在Agent将其写入文档之前，需对照服务商当前文档进行验证——例如，webhook需要SECRET而非token；
```
projects_v2_item
```
事件仅支持组织级webhook。若发现缺口，请在记录台账中发布
```
question
```
。完成标志：所有外部环境假设均已验证或已记录在台账中。
排序 + 热点处理。根据每个工单的「被阻塞于」关系确定执行顺序。标记共享文件热点（例如，一个ADR需要接收多个工单的修改）：要么串行处理这些工单，要么在提示中预先约定冲突处理方式（「共享文件修改仅允许增量添加；第二个合并的工单需执行rebase」）。「仅创建新文件」的工单可并行处理；「修改共享文件」的工单需串行处理，同一时间仅允许一个处理者。
生成Agent。每个子议题对应一个
```
/implement
```
Agent，提示语基于
```
package-prompt.md
```
构建。对顺序敏感的规则（PR前需rebase、冲突处理方式、合并顺序）需包含在初始提示语中——中途发送的消息可能与Agent的推送操作冲突，导致无法及时生效。
传递 + 验证。Agent的/code-review子任务需向你汇报，而非向该Agent汇报——请及时传递评审结论和修复清单；传递过程同时作为你的QA检查点。Agent处于空闲状态≠任务完成：在响应任何「已完成」信号之前，需验证可观测状态——origin上的分支、
```
git diff --stat
```
输出、修复内容是否存在于diff中（而非仅确认收到回复）。每次传递信息后，需等待至少一轮往返沟通。请用「完成剩余步骤」提醒Agent，切勿使用「立即推送」——仓促的Agent会跳过自身的QA步骤。
合并。仅当CI通过时执行：将
```
gh run watch <id> --exit-status && gh pr merge <n> --squash --delete-branch && <cleanup>
```
作为一条后台命令链式执行。你负责确定合并顺序；第二个合并的工单需执行rebase。完成标志：每个子议题对应恰好一个已合并的PR，且PR中包含
```
Closes #<sub>
```
标记。
收尾。针对共享文档（当前重点为CLAUDE.md）提交一个最终的文档PR——切勿为每个工单单独提交PR。若遇到你无法解决的基础设施阻塞问题（例如Neon/Vercel控制台仅对所有者开放），属于合法的终止状态：在PR的记录台账中发布
```
blocker
```
，附上证据及所有者需要执行的操作。在父议题下发布最终的🤖总结。

从已归档的早期执行中恢复数据、部署诊断、Projects v2限制、破坏性脚本规则：详见

ops.md

。