flock-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

flock-agents - Run through a backlog autonomously

flock-agents - 自主处理工单积压

Implement a whole backlog of tickets overnight, unattended. Give it the spec (or parent issue) whose build tickets you want built; it pulls the linked tickets from the configured issue tracker, reads the spec and already-completed tickets for context, orders the open tickets by dependency, then runs one agent per ticket — each using the

/implement

skill in its own git worktree, on a model matched to the ticket's difficulty (see the model matrix below) at high reasoning effort — and leaves you your chosen deliverable in the morning: a stack of reviewed branches, one integration branch, or a ready-to-review PR.

Use when you have a pile of well-formed, session-sized build tickets and want them built AFK. These are the tracer-bullet tickets

/to-tickets

produced from a spec — not wayfinder's decision tickets. So on a wayfinder-originated effort, point flock at the spec

/to-spec

produced from the map, never the map itself: the map's children are HITL decisions, and any ticket that still needs a decision belongs in a grilling or prototype session first, not here.

可在无人值守的情况下，一夜之间完成整个工单积压任务。提供你想要构建的工单对应的规格说明（或父级问题）；它会从已配置的问题追踪器中提取关联工单，读取规格说明和已完成工单以获取上下文信息，按依赖关系对未结工单排序，然后为每个工单分配一个Agent——每个Agent在独立的git worktree中使用/implement技能，匹配工单难度选择对应模型（见下方模型矩阵）并以高推理强度运行——次日早上即可为你交付指定成果：一系列已审核分支、一个集成分支，或一个可直接审核的PR。

当你有一堆格式规范、适合单次处理的构建工单，且希望在AFK状态下完成它们时，可使用本工具。这些工单是由规格说明通过/to-tickets生成的“追踪工单”——而非wayfinder的决策工单。因此，对于wayfinder发起的任务，请将flock指向由图谱生成的/to-spec规格说明，而非图谱本身：图谱的子项是需人机协作（HITL）的决策项，任何仍需决策的工单应先放入研讨或原型阶段，而非直接使用本工具。

Input

输入

Ask for this first if it wasn't given:

SOURCE — the spec or parent issue whose build tickets you'll implement, as an issue number or URL. On a local-markdown tracker, SOURCE is instead the
```
.scratch/<feature>/issues/
```
backlog folder.

Also settle these three at launch — from the invocation if the user already said so, otherwise ask ONCE up front (never mid-run; nobody is awake then):

MODEL POLICY — automatic (matrix below) or user-specified per ticket or tier. Default: automatic.
DELIVERABLE — how finished work lands: (a) a stack of per-ticket branches (default), (b) one integration branch built by serialized cherry-picks in dependency order — the best format for a one-sitting morning review, or (c) pushed branch + one PR mapping commits → tickets.
EXTERNAL WRITES — exactly which outward-facing actions are authorized: close finished tickets? comment on SOURCE? push? open a PR? Default: none (tracker read-only). Bake the answers into every agent prompt.

How to turn SOURCE into its ticket set is tracker-specific: read

docs/agents/issue-tracker.md

for how this repo lists a spec's child / linked issues, reads their bodies, and exposes blocking edges. Run

/setup-matt-pocock-skills

if that file is missing.

若未提供以下信息，请先询问用户：

SOURCE — 你要实现的构建工单对应的规格说明或父级问题，以问题编号或URL形式提供。对于本地Markdown追踪器，SOURCE则为
```
.scratch/<feature>/issues/
```
积压文件夹。

此外，在启动时需确认以下三项——若用户已在调用时说明则直接使用，否则提前一次性询问（切勿在运行中途询问，因为无人值守）：

MODEL POLICY — 自动选择（见下方矩阵）或用户指定每个工单或层级的模型。默认值：自动。
DELIVERABLE — 已完成工作的交付形式：(a) 每个工单对应一个分支（默认），(b) 一个按依赖顺序通过序列化樱桃拣选构建的集成分支——最适合晨间一次性审核的格式，或(c) 推送分支并创建一个关联提交与工单的PR。
EXTERNAL WRITES — 授权的对外操作：关闭已完成工单？在SOURCE上添加评论？推送代码？创建PR？默认值：无（仅读取追踪器）。需将答案纳入每个Agent的提示词中。

如何将SOURCE转换为工单集合取决于追踪器类型：阅读

docs/agents/issue-tracker.md

了解本仓库如何列出规格说明的子工单/关联工单、读取工单内容并暴露阻塞依赖。若该文件缺失，请运行

/setup-matt-pocock-skills

。

Steps

步骤

Gather context. Read the SOURCE spec / parent issue and the already-completed (closed) tickets linked to it. Learn the established patterns and conventions, and note what is already done — so agents match existing work and never redo a closed ticket.
Enumerate the work. Pull the open tickets linked to SOURCE from the tracker — its child / sub-issues or issues referencing it, filtered to the
```
ready-for-agent
```
label (per
```
docs/agents/issue-tracker.md
```
); on a local tracker, the open ticket files in the backlog folder. Skip anything closed, merged, or still flagged as needing a decision. For each, capture its acceptance criteria and the files it is likely to touch. Gate on quality: a ticket without testable acceptance criteria, or one still hiding a design decision, is not agent-ready — set it aside for the morning report rather than letting an agent guess at it overnight.
Order into phases. Group tickets by dependency — use the tracker's native blocking edges as the primary signal (a ticket is takeable only once its blockers are closed), plus file overlap. Tickets that share files or depend on another's output must not run in the same parallel batch. Independent tickets run together; dependents run in later phases.
Preflight one worktree. Everything gitignored is missing in a fresh worktree — node_modules, generated files, env, symlink chains. Before launching anything: create one worktree, provision it, and prove the checks the tickets rely on actually pass there (typecheck at minimum). Keep the result as an idempotent setup script every lane reuses. Skipping this is the #1 way an overnight run dies: every agent stalls on the same broken toolchain — or worse, "fixes" the phantom errors it causes.

Decide how models are chosen — from the MODEL POLICY input (asking mid-flight blocks a fire-and-forget launch):

Automatic (recommended) — you, the orchestrator, pick a model tier per ticket from the matrix below, judging each by its acceptance criteria and likely blast radius (captured in step 2).
User-specified — the user names the model(s): one model for every ticket, or a per-tier / per-ticket mapping. Honour it exactly for the implementation agents and skip the matrix.

Matrix (automatic path). Match capability tiers, not specific model names — this works on whatever runtime you use (Claude Code, OpenAI Codex, etc.); map each tier to the best-fitting model your runtime offers. Use the smartest, most capable model available for the hardest tickets, and drop to faster, cheaper tiers as the work gets more mechanical. When in doubt between two tiers, pick the stronger one; a failed overnight run costs more than the token difference.

Ticket profile	Model tier	Signals
Hardest: UI/UX work, cross-cutting or architectural changes, ambiguous specs, many files touched	Smartest / most capable model available	"redesign", "refactor across", visual/layout acceptance criteria, touches shared frameworks or 5+ files
Normal implementation ticket (the default)	Balanced mid-tier model	one feature or fix, clear acceptance criteria, a handful of files, established patterns to copy
Trivial: formatting, renames, config/doc tweaks, mechanical one-file changes	Fast / cheap model	no design decisions, diff is predictable from the ticket text alone

Verifier agents check a diff against acceptance criteria — catching a subtle miss is worth the strongest judgment, so run them on the smartest / most capable model available regardless of the implementation model, unless the user's specification says otherwise.

Launch the flock as a background dynamic workflow, so it survives overnight and resumes if interrupted. First check for leftovers of an interrupted earlier run (existing flock worktrees/branches, tickets with unverified commits): adopt that work — rebase, audit against the acceptance criteria, review, fix — instead of redoing it. For each ticket spawn one agent:
- in its own git worktree (isolated branch — no collisions),
- on the model chosen in step 5 at high reasoning effort,
- with the per-agent instructions below. Run phases in order; within a phase, run agents in parallel. Write every branch-prep step idempotently: a killed agent leaves a dirty worktree and a half-created branch, and a naive
```
checkout -b
```
  on re-run just dies — stash leftovers, reuse existing branches, reset only when safe.
Verify each result. After an agent commits, a separate verifier agent judges the diff against that ticket's acceptance criteria — adversarially, evidence over claims: it re-runs the checks itself rather than trusting the implementer's report, confirms the new tests actually pin the required behavior (a suite that passes without the change is vacuous), and checks commit hygiene. On failure, return the ticket to its agent ONCE with the failure notes; if it still fails, stop and flag it. Never loop unbounded overnight.
Land per the DELIVERABLE. Branch-stack mode: leave the verified branches. Integration-branch mode: one merge agent at a time — strictly serialized — cherry-picks each verified ticket in dependency order onto the integration branch; conflicted generated artifacts (declaration rollups, API reports, generated clients) are regenerated from source, never hand-merged. Then run a final cross-ticket integration gate (repo typecheck + full checks of every touched package/app): per-ticket green does not compose into collectively green. PR mode: after the gate, push and open one PR whose description maps commits → tickets → spec criteria. In every mode: no force-pushes, nothing merges to the default branch.
Report. Write a run log the user reads with coffee — a file next to the worktrees (on a local tracker, in the backlog folder): each ticket's status (done / failed / needs-decision), its branch or PR, commit shas, verifier evidence, and anything a human must resolve. Comment on SOURCE or close finished tickets only if EXTERNAL WRITES authorized it. Leave the rest for morning review — do not auto-merge.

收集上下文。读取SOURCE规格说明/父级问题及其关联的已完成（已关闭）工单。学习已确立的模式和约定，记录已完成的工作——确保Agent匹配现有工作，且不会重复处理已关闭工单。
枚举工作内容。从追踪器中提取SOURCE关联的未结工单——其子工单/子问题或引用它的工单，筛选带有
```
ready-for-agent
```
标签的工单（详见
```
docs/agents/issue-tracker.md
```
）；对于本地追踪器，则为积压文件夹中的未结工单文件。跳过已关闭、已合并或仍标记为需决策的工单。为每个工单记录其验收标准及可能涉及的文件。进行质量校验：无可测试验收标准或仍隐藏设计决策的工单不适合Agent处理——将其留到晨间报告中，而非让Agent在夜间自行猜测。
按阶段排序。按依赖关系对工单分组——以追踪器原生的阻塞依赖为主要依据（仅当阻塞工单关闭后，该工单才可处理），同时考虑文件重叠情况。共享文件或依赖其他工单输出的工单不得并行处理。独立工单可并行处理；依赖工单需在后续阶段处理。
预检查工作树。新工作树中会忽略所有gitignored内容——如node_modules、生成文件、环境变量、符号链接链。在启动任何任务前：创建一个工作树，配置环境，并确保工单依赖的检查能正常通过（至少通过类型检查）。将结果保存为幂等设置脚本，供所有分支复用。跳过此步骤是导致夜间运行失败的首要原因：每个Agent都会因相同的工具链问题停滞——更糟的是，Agent会“修复”这些虚假错误。

确定模型选择方式——根据MODEL POLICY输入（运行中途询问会阻碍一键启动）：

自动（推荐） — 编排器根据下方矩阵为每个工单选择模型层级，依据工单的验收标准和可能影响范围（步骤2中记录）进行判断。
用户指定 — 用户指定模型：为所有工单指定一个模型，或按层级/工单指定映射。严格按照用户指定为实现Agent选择模型，无需使用矩阵。

矩阵（自动模式）。匹配能力层级，而非特定模型名称——此方式适用于任何运行环境（Claude Code、OpenAI Codex等）；将每个层级映射到运行环境中最合适的模型。最难的工单使用可用的最智能、能力最强的模型，工作越机械则使用更快、更便宜的层级。若在两个层级间犹豫，选择更强的层级；夜间运行失败的成本远高于令牌差异。

工单类型	模型层级	判断信号
最难：UI/UX工作、跨模块或架构变更、模糊的规格说明、涉及大量文件	可用的最智能/能力最强模型	包含“重新设计”“跨模块重构”、视觉/布局验收标准、涉及共享框架或5个以上文件
常规实现工单（默认）	平衡型中层级模型	单个功能或修复、清晰的验收标准、涉及少量文件、可参考已确立的模式
简单：格式调整、重命名、配置/文档修改、机械性单文件变更	快速/低成本模型	无设计决策、从工单文本可预测差异内容

验证Agent会根据验收标准检查差异——发现细微错误需要最强的判断能力，因此无论实现模型如何，验证Agent均使用可用的最智能/能力最强模型，除非用户另有指定。

启动Agent集群作为后台动态工作流，确保其可在夜间持续运行，中断后可恢复。首先检查是否有之前中断运行的遗留内容（现有flock工作树/分支、带有未验证提交的工单）：复用这些工作——重新变基、根据验收标准审核、复查、修复——而非重新执行。为每个工单启动一个Agent：
- 在独立的git worktree中（隔离分支——无冲突），
- 使用步骤5中选择的模型并以高推理强度运行，
- 遵循下方的Agent专属指令。按阶段顺序运行；同一阶段内的Agent并行运行。将每个分支准备步骤设置为幂等：被终止的Agent会留下脏工作树和半创建的分支，若重新运行时直接执行
```
checkout -b
```
  会失败——需暂存遗留内容、复用现有分支、仅在安全时重置。
验证每个结果。Agent提交后，由独立的验证Agent根据工单验收标准判断差异——以对抗性方式，基于证据而非声明：验证Agent会自行重新运行检查，而非信任实现Agent的报告，确认新测试确实锁定了所需行为（未修改即可通过的测试套件无意义），并检查提交规范。若验证失败，将工单连同失败反馈返回给Agent一次；若仍失败，则停止并标记该工单。夜间运行切勿无限循环。
按DELIVERABLE交付。分支栈模式：保留已验证的分支。集成分支模式：每次启动一个合并Agent——严格序列化——按依赖顺序将每个已验证工单樱桃拣选到集成分支；冲突的生成工件（声明汇总、API报告、生成客户端）从源代码重新生成，切勿手动合并。然后运行最终的跨工单集成检查（仓库类型检查 + 所有涉及包/应用的完整检查）：单个工单通过检查不代表整体通过。PR模式：检查通过后，推送代码并创建一个PR，其描述关联提交→工单→规格说明标准。所有模式下：禁止强制推送，不得合并到默认分支。
生成报告。生成一份用户晨间查看的运行日志——位于工作树旁的文件（本地追踪器中则在积压文件夹内）：每个工单的状态（完成/失败/需决策）、对应的分支或PR、提交哈希、验证证据，以及需人工解决的问题。仅当EXTERNAL WRITES授权时，才在SOURCE上添加评论或关闭已完成工单。其余内容留待晨间审核——切勿自动合并。

Per-agent instructions

Agent专属指令

Give each implementation agent exactly this shape:

You own ONE ticket:
```
<ticket>
```
— fetch it from the tracker and read it fully.
Reference (read-only) the spec and these completed tickets for conventions:
```
<pointers>
```
. Match existing patterns; do not redo done work.
Invoke the
```
/implement
```
skill on this ticket only: use TDD where possible at pre-agreed seams, type-check and run single test files regularly, one full test sweep at the end.
Then run code review, and commit to your worktree branch.
If you hit a blocker or a real decision, STOP and write why — do not guess.

为每个实现Agent提供以下格式的指令：

你负责处理一个工单：
```
<ticket>
```
——从追踪器中获取并完整阅读该工单。
参考（只读）规格说明及以下已完成工单以遵循约定：
```
<pointers>
```
。匹配现有模式；不得重复已完成工作。
仅对该工单调用/implement技能：尽可能在预先约定的环节使用TDD，定期进行类型检查并运行单个测试文件，最后进行一次完整测试扫描。
然后进行代码审查，并提交到你的工作树分支。
若遇到阻塞或需实际决策，立即停止并说明原因——切勿猜测。

Before you run (unattended safety)

运行前准备（无人值守安全）

Pre-allowlist the shell commands the agents need (test runner, typecheck, git, package manager, and the tracker CLI — e.g.
```
gh
```
— for reading tickets and posting status). Unattended agents auto-approve file edits but will stall on a non-allowlisted command with no one to confirm.
Authorize external writes explicitly (the EXTERNAL WRITES input). Permission classifiers judge intent from what the user asked for: an unattended
```
gh issue close
```
or
```
git push
```
the user never requested gets denied mid-run, with nobody awake to approve it. Collect the authorization at launch and carry it verbatim into the prompts.
Dynamic workflows must be enabled (on by default for Max/Team/Enterprise; Pro users enable them in the Dynamic workflows row of
```
/config
```
).
Worktrees from non-interactive runs are not auto-cleaned; expect to
```
git worktree remove
```
after merging.
Fan-out multiplies token usage and draws down rate limits (workflow caps: 16 agents concurrent, 1000 per run). Size the batch to fit your plan.

预先允许Agent所需的Shell命令（测试运行器、类型检查、git、包管理器，以及追踪器CLI——如
```
gh
```
——用于读取工单和发布状态）。无人值守的Agent会自动批准文件编辑，但遇到未允许的命令时会停滞，无人确认。
明确授权对外操作（EXTERNAL WRITES输入）。权限分类器会根据用户请求判断意图：用户未请求的无人值守
```
gh issue close
```
或
```
git push
```
会在运行中途被拒绝，且无人批准。需在启动时收集授权信息，并将其原封不动纳入提示词。
需启用动态工作流（Max/Team/Enterprise默认启用；Pro用户需在
```
/config
```
的Dynamic workflows行中启用）。
非交互式运行生成的工作树不会自动清理；合并后需手动执行
```
git worktree remove
```
。
并行运行会增加令牌使用量并耗尽速率限制（工作流上限：16个Agent并发，单次运行最多1000个）。请根据计划调整批量大小。