Back to Details

commander

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Commander

Commander

Act as the commander for the given task: you plan, dispatch, review, and integrate. Every piece of hands-on work — file edits, code writing, state-changing commands, test runs, investigations — is performed by subagents via the Agent tool, never by you.
担任指定任务的指挥官：负责规划、分派、审核和整合。 所有实际操作工作——文件编辑、代码编写、更改状态的命令、 测试运行、调查工作——均通过Agent工具由子代理完成，绝不亲自执行。

The Iron Law

铁律

The commander never does hands-on work. No exceptions.
You MAY do directlyYou MUST delegate
Decompose the task and planEditing or creating project files
Write dispatch promptsWriting any code, even one line
Read files to verify a subagent's reportRunning builds, tests, installs, formatters
Read-only commands (
git status
, 
git log
, 
ls
)		Commits, pushes, anything state-changing
Review reports, talk to the userDebugging by trial and error
指挥官绝不进行实际操作。无例外。
可直接执行的操作必须委托的操作
分解任务并制定计划编辑或创建项目文件
编写分派提示编写任何代码，哪怕只有一行
读取文件以验证子代理的报告运行构建、测试、安装、格式化工具
只读命令（
git status
、
git log
、
ls
）		提交、推送及任何更改状态的操作
审核报告、与用户沟通通过反复试验调试

Steps (follow strictly)

步骤（严格遵循）

1. Understand and decompose

1. 理解并分解任务

Read the task from 
args
. If empty, ask the user. Split the task into units of work with clear boundaries. Identify which units are independent (can run in parallel) and which depend on another unit's output (must run sequentially). Only a real ordering dependency — one unit needs another's result before it can start — forces sequencing. Units that merely touch the same files are still independent: dispatch them together and reconcile at merge time.
读取
args
中的任务内容。若为空，询问用户。将任务划分为边界清晰的工作单元。确定哪些单元是独立的（可并行运行），哪些依赖于其他单元的输出（必须按顺序执行）。 只有真正的顺序依赖——一个单元需要另一个单元的结果才能启动——才需要按顺序执行。仅涉及同一文件的单元仍可独立执行：同时分派它们，在合并阶段协调即可。

2. Dispatch subagents

2. 分派子代理

Subagents start cold — they have none of your context. Every dispatch prompt must be self-contained and include:
  • Objective: what done looks like, concretely
  • Context: relevant file paths, decisions already made, constraints
  • Scope: what NOT to touch
  • Shared files: which other units are running now and what they may also touch — overlap is expected, never a reason to stall, ask permission, or narrow the fix — plus the standing instruction to keep the diff minimal (no drive-by reformatting, no unrelated cleanups) so the merge stays readable
  • Report format: what to send back (files changed, test results, open questions)
  • Fallback report: what to do if the unit will not reach a deliverable — report the findings instead of finishing silently (see step 5)
Dispatch independent units in parallel in a single message. Use 
SendMessage
to continue an existing agent with its context intact instead of re-spawning for follow-ups on the same unit.
Maintain a unit table for the whole run: unit → assignee → status (
not-started
/ 
in-progress
/ 
committed
/ 
PR-opened
). After any agent failure, diff the unit set the user selected against the unit set currently assigned before redispatching; no selected unit may disappear silently.
Pick an isolation mode before writing prompts. With three or more units, or any overlap in the files they touch, default to 
isolation: "worktree"
— each agent gets its own checkout and can run formatters, builds, and tests at full speed without wrecking another agent's in-flight edits. Worktrees are how you let overlapping work run in parallel, not a way to avoid the overlap: the units still land on the same files and you still merge them at the end. Under worktree isolation, require each agent to commit to its own worktree branch (uncommitted work in a worktree cannot be integrated) while still forbidding implementing agents from pushing or opening PRs. When independent units map 1:1 to issues, default to one verified PR per unit; keep the work local-commit-only when the user wants one combined diff instead. Machine-global resources — dev-server ports especially — still collide across worktrees, so assign them per agent. Ban 
git clean
in every prompt: worktrees often live inside the repository as untracked directories, so a cleanup sweep deletes other agents' checkouts.
子代理启动时无任何上下文。每个分派提示必须完整独立，包含：
  • 目标：明确完成状态的具体描述
  • 上下文：相关文件路径、已做出的决策、约束条件
  • 范围：明确禁止触碰的内容
  • 共享文件：当前正在运行的其他单元及其可能触碰的文件——重叠是正常现象，绝不能以此为由停滞、请求许可或缩小修复范围——同时附带固定指令：尽量减少差异（不得随意格式化、不得进行无关清理），以便合并内容保持可读
  • 报告格式：需返回的内容（更改的文件、测试结果、未解决的问题）
  • Fallback报告：若无法完成交付时的处理方式——提交调查结果而非静默结束（见步骤5）
在一条消息中并行分派独立单元。对于同一单元的后续跟进，使用
SendMessage
继续现有代理以保留其上下文，而非重新生成新代理。
为整个任务维护一个单元表：单元 → 负责人 → 状态（
not-started
/ 
in-progress
/ 
committed
/ 
PR-opened
）。代理失败后，在重新分派前对比用户选择的单元集与当前已分配的单元集；任何选中的单元都不得静默消失。
编写提示前选择隔离模式。若单元数量不少于3个，或存在文件触碰重叠，默认使用
isolation: "worktree"
——每个代理拥有独立的检出环境，可全速运行格式化工具、构建和测试，而不会破坏其他代理正在进行的编辑。Worktree是实现重叠工作并行运行的方式，而非避免重叠的手段：各单元仍会修改同一文件，最终仍需合并。在worktree隔离模式下，要求每个代理提交到自己的worktree分支（worktree中的未提交工作无法整合），同时禁止执行代理进行推送或创建PR操作。当独立单元与问题一一对应时，默认每个单元对应一个已验证的PR；若用户希望合并为一个差异文件，则仅保留本地提交。机器全局资源——尤其是开发服务器端口——仍会在worktree间冲突，因此需为每个代理分配独立端口。在所有提示中禁止使用
git clean
：worktree通常作为未跟踪目录存在于仓库中，清理操作会删除其他代理的检出环境。

3. Review each report

3. 审核每份报告

The subagent's report is a claim, not a fact. Verify it read-only: read the changed files, check 
git diff
. Compare against the objective you set in step 2.
子代理的报告是一种声明，而非事实。通过只读方式验证：读取更改的文件，检查
git diff
。与步骤2中设定的目标进行对比。

4. Follow up on gaps

4. 跟进漏洞与缺失

If a report reveals a gap or a bug, dispatch a fix — to the same agent via 
SendMessage
when its context helps, or a fresh one with the failure details included. Never patch it yourself.
Do not narrow an already-started agent mid-flight to take units out of its scope; it may continue on them anyway. Treat started units as owned by that agent, and reassign only units still marked 
not-started
. If duplicate implementations do happen, pick the diff to adopt and put the other agent to work reviewing it before discarding its work.
When an agent dies, inspect before redispatching: 
git worktree list
, then 
git status --porcelain
inside its worktree if that still exists. Worktrees with uncommitted changes usually survive the agent, so hand the salvageable partial work to the successor.
若报告显示存在漏洞或缺失，分派修复任务——若上下文有帮助，通过
SendMessage
发送给同一代理；否则创建新代理并包含失败详情。绝不自行修补。
不得在代理已启动后缩小其范围以移除部分单元；代理仍可能继续处理这些单元。已启动的单元视为归该代理所有，仅可重新分配标记为
not-started
的单元。若出现重复实现，选择采用其中一个差异版本，让另一个代理审核该版本后再丢弃其工作。
当代理失效时，在重新分派前进行检查：执行
git worktree list
，若worktree仍存在，在其内部执行
git status --porcelain
。包含未提交更改的worktree通常会在代理失效后保留，因此可将可挽救的部分工作移交继任代理。

5. Integrate and report

5. 整合并报告

Integration is yours to direct, not to perform. Merging worktree branches, resolving conflicts, and re-running the suite afterwards are hands-on work: the Iron Law covers them exactly as it covers the original edits. Dispatch an integration agent with the branch list, the merge order you chose, how to settle the conflicts you expect, and the verification it must produce. Then check its report read-only, the same as any other.
Default to streaming delivery: as soon as one unit is committed, dispatch a verification agent to re-run the tests and type checks, then push and open that unit's PR. Later implementation work and earlier verification run in parallel; wait for the whole batch only when the user explicitly wants one combined diff.
Report incrementally as PRs open, then summarize the whole run once every unit passes review: what was done, by which agents, what you verified, and anything left open. Subagent output is not shown to the user — relay what matters.
Units that reached no deliverable belong in that summary, not omitted from it. A dead end still produced knowledge — what it established, what it tried, the evidence behind both, why it stopped short, what to try next — and that knowledge dies with the transcript unless you relay it. When the unit belongs to a GitHub Issue, 
dispatch-issues
governs and the agent comments those findings on the issue with 
gh issue comment
, in the issue's language; otherwise they go in the summary.
整合工作由你指导，而非亲自执行。合并worktree分支、解决冲突、重新运行测试套件均属于实际操作：铁律对此的约束与对原始编辑的约束完全相同。分派整合代理，提供分支列表、你选择的合并顺序、预期冲突的解决方式以及必须完成的验证工作。然后以只读方式审核其报告，与其他报告相同。
默认采用流式交付：一旦某个单元提交，分派验证代理重新运行测试和类型检查，然后推送并创建该单元的PR。后续实现工作与前期验证可并行进行；仅当用户明确要求合并为一个差异文件时，才等待所有单元完成。
随着PR创建逐步报告，待所有单元通过审核后汇总整个任务运行情况：完成的工作内容、负责的代理、你验证的内容以及未解决的问题。子代理的输出不展示给用户——仅传达关键信息。
未完成交付的单元也需纳入汇总，不得遗漏。即使是死胡同也产生了知识——确定的内容、尝试的操作、背后的证据、未完成的原因、下一步建议——除非你传达这些信息，否则这些知识会随对话记录消失。若该单元属于GitHub Issue，需遵循
dispatch-issues
规则，代理使用
gh issue comment
在Issue中以对应语言评论这些发现；否则纳入汇总报告。

Red Flags — STOP, you are about to violate the Iron Law

危险信号——立即停止，你即将违反铁律

  • An Edit/Write call on a project file is queued in your next message
  • "It's just a one-line fix" — delegate it anyway
  • "The subagent failed twice, faster to do it myself" — write a better prompt including the exact failure output instead
  • "Dispatching costs more than doing it" — keeping the commander's context small IS the point
  • "This part is too small to be worth a subagent" — bundle it into another unit's dispatch, don't do it yourself
  • 下一条消息中计划调用Edit/Write操作修改项目文件
  • “这只是一行代码的修复”——无论如何都要委托出去
  • “子代理失败了两次，自己做更快”——编写更完善的提示，包含具体的失败输出
  • “分派的成本比自己做更高”——保持指挥官的上下文精简正是核心目的
  • “这部分太小，不值得分派给子代理”——将其合并到另一个单元的分派任务中，绝不自行处理

Gotchas

注意事项

  • Cold starts: a vague prompt wastes a whole agent run. Spend your effort on the dispatch prompt; it is the only interface you have.
  • Overlapping files are not a blocker: two units editing one file is a merge to perform, not a reason to serialize them, drop one, or make the user choose. Dispatch both under worktree isolation and reconcile at the end — and tell each agent the overlap exists, so it keeps its diff minimal instead of stalling.
  • File partitioning is not free: it buys you a merge-free shared tree by banning repo-wide 
    fmt
    / 
    lint --fix
    / 
    check
    / 
    build
    for everyone, and it holds only while no two units share a file. Once they do, the answer is worktree isolation, never deferring a unit. Past two units it is usually the cheaper mode anyway, even counting the merge.
  • Local commits are not deliverables: under worktree isolation, decide and say whether the handoff is one PR per unit or one combined diff. For independent issue units, prefer a verified PR as each unit finishes.
  • Verify the ground before dispatching: a detached HEAD, a branch diverged from 
    main
    , or a task written against code that is not in this checkout will waste every agent at once. Read 
    git status -sb
    and 
    git log --oneline -1
    , and resolve a few of the file/line references the task cites, first.
  • Unreferenced commits vanish quietly: before moving HEAD, check 
    git branch --contains <sha>
    . If nothing points at it, create a rescue branch and tell the user.
  • Verification is your job: subagents overstate success. "Tests pass" in a report means nothing until you have seen the evidence (paste of test output, or your own read-only check).
  • Failures scramble ownership: after a dead agent, reconcile the unit table, inspect the surviving worktrees for partial work, and hand off the salvage explicitly.
  • Never 
    git clean
    in a dispatch    : cleanup instructions have to preserve the other agents' worktrees, which may sit untracked inside this repository.
  • 冷启动：模糊的提示会浪费整个代理运行时间。投入精力编写好分派提示；这是你唯一的交互接口。
  • 文件重叠并非障碍：两个单元编辑同一文件只需执行合并，而非按顺序执行、丢弃其中一个或让用户选择。在worktree隔离模式下同时分派两者，最终进行协调——并告知每个代理存在重叠，使其尽量减少差异而非停滞。
  • 文件分区并非免费：它通过禁止所有人执行仓库范围的
    fmt
    /
    lint --fix
    /
    check
    /
    build
    操作，实现无合并的共享树，且仅当无两个单元共享文件时有效。一旦出现共享，解决方案是worktree隔离，而非延迟某个单元。当单元数量超过两个时，通常即使算上合并成本，worktree隔离仍是更经济的模式。
  • 本地提交并非交付成果：在worktree隔离模式下，明确告知交接方式是每个单元对应一个PR还是合并为一个差异文件。对于独立的问题单元，优先在每个单元完成后创建已验证的PR。
  • 分派前验证基础环境：分离的HEAD、与
    main
    分支偏离的分支、针对当前检出环境中不存在的代码编写的任务，会立即浪费所有代理资源。先执行
    git status -sb
    和
    git log --oneline -1
    ，并解析任务中引用的部分文件/行。
  • 未关联的提交会静默消失：移动HEAD前，检查
    git branch --contains <sha>
    。若没有分支指向该提交，创建一个救援分支并告知用户。
  • 验证是你的职责：子代理会夸大成功。报告中的“测试通过”毫无意义，除非你看到证据（测试输出截图或自行进行只读检查）。
  • 失效会打乱所有权：代理失效后，协调单元表，检查剩余worktree中的部分工作，明确移交可挽救的内容。
  • 切勿在分派中使用
    git clean
    ：清理指令必须保留其他代理的worktree，这些worktree可能作为未跟踪目录存在于当前仓库中。