orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Orchestration: Subagents, Agent Teams & Parallel Execution

编排指南：Subagents、Agent团队与并行执行

These rules govern ALL parallelization decisions. Apply them on every task.

Not for single-action requests, simple file edits, or sequential-only workflows.

以下规则适用于所有并行化决策，执行每一项任务时都需遵守。

不适用于单动作请求、简单文件编辑或仅支持串行的工作流。

Dispatch

调度说明

$ARGUMENTS	Action
(empty)	Load full orchestration guide; apply Decomposition Gate to current request
`pattern <A-F>`	Show the named pattern from `references/patterns.md`
`tier`	Display Tier Selection table and model guidance
`recovery`	Show the Accounting Rule and Recovery Ladder

$ARGUMENTS	对应操作
(空)	加载完整编排指南，对当前请求应用Decomposition Gate校验
`pattern <A-F>`	展示 `references/patterns.md` 中指定名称的模式
`tier`	展示层级选择表格和模型使用指引
`recovery`	展示计数规则（Accounting Rule）和故障恢复阶梯

Canonical Vocabulary

规范术语表

Canonical Term	Meaning
subagent	A Task-tool-spawned agent running in parallel within a session
wave	A batch of parallel subagents dispatched in a single message
team	A TeamCreate-spawned group of teammates coordinated by a lead
teammate	A member of an agent team with assigned file ownership
lead	The orchestrating agent in a team; never implements directly
dispatch	Send one or more subagents/teammates to execute in parallel
gate	A mandatory checkpoint that must pass before proceeding
accounting rule	N dispatched = N resolved; no agent silently dropped

规范术语	含义
subagent	由Task工具生成的、在同一会话内并行运行的agent
wave	在单条消息中派发的一批并行subagent
team	由TeamCreate生成、由负责人统一协调的队友组
teammate	Agent团队中的成员，拥有分配的文件所有权
lead	团队中负责编排的agent，不直接执行实现工作
dispatch	派发一个或多个subagent/teammate并行执行任务
gate	必须通过才能推进后续流程的强制检查点
accounting rule	派发N个agent必须回收N个结果，不允许静默丢弃任何agent

0. Decomposition Gate (MANDATORY before any work)

0. Decomposition Gate（所有工作前的强制步骤）

Before executing any request that involves tool-mediated work:

DECOMPOSE: List the actions needed (file reads, edits, searches, commands, analyses).
CLASSIFY: Which actions are independent (no data dependency)? Which are dependent?
MAXIMIZE: Actively split actions further — find every opportunity to parallelize. Each independent action = its own subagent. Challenge: can any action be split into two?
CONFLICT CHECK: Two independent actions editing the same file → make those sequential; all others remain parallel.
DISPATCH: Default is Pattern E — TeamCreate with nested subagent waves per teammate. Pre-approve permissions before spawning. Use bare subagent waves only when single domain, no coordination, no context pressure. Single session only when there is literally 1 action.
TRACK: For orchestrated work, create TaskCreate entries before dispatch (see Section 7).

Fast path: Single-action requests skip directly to single session.

Explore-first path: Cannot decompose without exploration → spawn parallel exploration team first (Pattern F Wave 1), then re-enter this gate.

Transition heuristic: Subagent waves hitting context limits or agents need to share findings → upgrade to Pattern E (teams + nested waves).

User override: Explicit user requests for a specific execution approach take precedence.

在执行任何涉及工具调用的请求前：

拆解任务：列出所有需要执行的动作（文件读取、编辑、搜索、命令执行、分析等）。
分类梳理：区分哪些动作是独立的（无数据依赖），哪些是有依赖的。
最大化并行：主动进一步拆分动作，寻找所有可以并行的机会。每个独立动作对应一个专属subagent。可以挑战：是否能将单个动作拆分为两个？
冲突检查：如果两个独立动作需要编辑同一个文件，将其调整为串行执行，其余动作保持并行。
派发执行：默认使用模式E——通过TeamCreate创建团队，为每个队友配置嵌套的subagent波次。生成实例前预先审批权限。仅当任务属于单一领域、无需协调、无上下文压力时，使用纯subagent波次。仅当确实只有1个动作时使用单会话执行。
进度跟踪：对于编排类工作，在派发前创建TaskCreate条目（见第7节）。

快速路径：单动作请求可以直接跳过校验进入单会话执行。

探索优先路径：不经过探索无法拆解任务 → 先生成并行探索团队（模式F第一波），再重新进入本校验环节。

转换规则：当subagent波次触及上下文限制，或agent需要共享发现结果时 → 升级为模式E（团队+嵌套波次）。

用户优先级：用户明确指定的执行方式优先级最高。

Common rationalizations (all invalid)

常见错误理由（全部无效）

"It's faster to do it myself" — Parallel subagents complete N tasks in time of the slowest 1.
"The task is too simple" — If it has 2+ independent actions, parallelize them.
"I'll just do this one thing first" — Decompose BEFORE doing anything.

"我自己做更快" —— 并行subagent完成N个任务的时间等于最慢的1个任务的执行时间。
"任务太简单" —— 如果包含2个及以上独立动作，就应该并行执行。
"我先做完这一件事再说" —— 做任何事之前必须先拆解任务。

Mode constraints

模式限制

Plan mode: Read-only subagents only. No teams, no write-capable agents.
Implementation mode: All tiers available. Default to highest applicable tier.
Delegate mode: Lead orchestrates only. All implementation via teammates/subagents.

计划模式：仅允许只读subagent，不允许创建团队，不允许拥有写入权限的agent。
实现模式：所有层级均可用，默认使用符合条件的最高层级。
委派模式：负责人仅负责编排，所有实现工作由teammate/subagent完成。

Skill integration

技能集成

When a superpowers skill is active, the gate operates WITHIN the skill's execution structure:

Phase-gated skills: Parallelize within each phase. Do not parallelize across phase boundaries.
Per-task review loop skills: The skill's sequential structure takes precedence. Parallelize exploration within each task, not across tasks.
Dispatch-precondition skills: The skill's "Don't use when" conditions remain valid. The gate does not override skill-level safety guards.

当激活超能力技能时，校验需在技能的执行结构内运行：

阶段门控技能：仅在每个阶段内部并行，不允许跨阶段边界并行。
单任务 review 循环技能：技能的串行结构优先级更高，仅在每个任务内部并行探索，不允许跨任务并行。
带前置调度条件的技能：技能的「禁止使用场景」条件仍然有效，校验不会覆盖技能层面的安全防护。

1. Tier Selection (mandatory — highest applicable tier wins)

1. 层级选择（强制要求——优先选择符合条件的最高层级）

Tier	Mechanism	Use when	Model
Team + nested waves (Pattern E)	TeamCreate + subagent waves per teammate — up to ~50 agents total	2+ independent streams — THE DEFAULT	opus (default) / gpt-5.3-codex xhigh (GitHub Copilot CLI)
Subagent wave	Task tool, parallel calls	2+ actions, single domain, no coordination, no context pressure	opus (default) / gpt-5.3-codex xhigh (GitHub Copilot CLI)
Single session	Direct execution	Exactly 1 action	N/A

Select the highest tier whose criteria are met. Never select a lower tier to reduce cost.

层级	实现机制	适用场景	模型
团队+嵌套波次（模式E）	TeamCreate + 每个队友对应subagent波次 —— 总计最多约50个agent	2个及以上独立工作流 —— 默认选项	opus（默认）/ gpt-5.3-codex xhigh（GitHub Copilot CLI）
Subagent波次	Task工具，并行调用	2个及以上动作、单一领域、无需协调、无上下文压力	opus（默认）/ gpt-5.3-codex xhigh（GitHub Copilot CLI）
单会话	直接执行	恰好1个动作	无

选择符合条件的最高层级，禁止为了降低成本选择更低层级。

2. Subagent Best Practices

2. Subagent最佳实践

Spawning

生成规则

One response, multiple Task calls. All independent subagents MUST be dispatched in the same message.
Use
```
run_in_background: true
```
for subagents whose results are not needed immediately.
N independent actions = N parallel subagents. Merge only when they share file/directory scope.

一条响应，多次Task调用：所有独立subagent必须在同一条消息中派发。
对于不需要立即获取结果的subagent，设置
```
run_in_background: true
```
。
N个独立动作 = N个并行subagent，仅当它们共享文件/目录范围时才合并。

Prompt-tuning

Prompt调优

Give every subagent a detailed, self-contained prompt with exact file paths, expected output format, and domain context.
Do NOT rely on the subagent inheriting conversation history — it does not.

为每个subagent提供详细、自包含的prompt，包含准确的文件路径、预期输出格式和领域上下文。
不要依赖subagent继承对话历史——它无法继承。

Model selection

模型选择

Default policy:
```
opus
```
for every subagent, teammate, and wave.
GitHub Copilot CLI override:
```
gpt-5.3-codex
```
with
```
xhigh
```
effort for every subagent, teammate, wave, and
```
/fleet
```
member.
When both policies are present, apply the environment-specific override for the active runtime.

默认策略：所有subagent、teammate、波次均使用
```
opus
```
。
GitHub Copilot CLI 覆盖规则：所有subagent、teammate、波次、/fleet 成员均使用
```
gpt-5.3-codex
```
与
```
xhigh
```
effort配置。
当两个策略同时存在时，为当前运行环境应用对应的环境专属覆盖规则。

Context management

上下文管理

Delegate verbose operations (test suites, log parsing, doc fetching) to subagents.
Use subagent resumption (agent ID) for multi-phase work rather than spawning fresh.
After a wave completes, apply the Accounting Rule (Section 4) before synthesizing.

将冗余操作（测试套件执行、日志解析、文档拉取）委派给subagent。
多阶段工作使用subagent恢复功能（agent ID），而非重新生成新实例。
一波次执行完成后，先应用计数规则（第4节）再进行结果合成。

3. Agent Team Best Practices

3. Agent团队最佳实践

Scale teammates to match the work — no artificial cap. Use as many as needed for maximum parallelism (up to ~50 agents total including nested subagents). Token budget is not a constraint.
Pre-approve common permissions before spawning teammates to reduce friction.
Assign each teammate a distinct domain and non-overlapping file ownership.
Assign as many tasks per teammate as the domain requires — no artificial limit.
Include all task-specific context in spawn prompts: file paths, architecture decisions, acceptance criteria. Teammates do not inherit conversation history.
Use delegate mode to prevent the lead from implementing work itself.
Task claiming uses file locking — no race conditions when multiple teammates claim simultaneously.
Never assign two teammates overlapping file ownership.
The lead must not proceed to synthesis until all teammate tasks are accounted for (Section 4).

根据工作量匹配队友数量，无人工上限。为了最大化并行度可以按需使用任意数量（包含嵌套subagent总计最多约50个agent），Token预算不是限制条件。
生成队友前预先审批常用权限，减少流程摩擦。
为每个队友分配不同的领域和无重叠的文件所有权。
每个队友的任务数量根据领域需求分配，无人工限制。
在生成prompt中包含所有任务专属上下文：文件路径、架构决策、验收标准。队友无法继承对话历史。
使用委派模式避免负责人自行执行实现工作。
任务认领使用文件锁机制——多个队友同时认领时不会出现竞态条件。
永远不要为两个队友分配重叠的文件所有权。
所有队友的任务都完成计数校验前，负责人不能进入结果合成阶段（第4节）。

4. Quality Gates & Failure Recovery

4. 质量门控与故障恢复

The Accounting Rule (MANDATORY after every parallel dispatch)

计数规则（每次并行派发后的强制步骤）

When N agents are dispatched, all N must be accounted for before proceeding:

COLLECT: Wait for all N agents to return. Poll with
```
TaskOutput
```
block=false for timeout detection.
TALLY: Results received vs dispatched. Missing = unresolved.
RESOLVE all non-successes via the Recovery Ladder (see
```
references/patterns.md
```
).
GATE: Do NOT advance until every agent has SUCCESS or explicit SKIP.
REPORT: Summarize all agent outcomes via TaskUpdate before proceeding.

派发N个agent后，推进后续流程前必须完成所有N个agent的结果统计：

收集结果：等待所有N个agent返回结果，使用
```
TaskOutput
```
block=false轮询检测超时。
核对计数：对比收到的结果和派发数量，缺失的视为未解决。
解决问题：通过故障恢复阶梯（见
```
references/patterns.md
```
）处理所有非成功结果。
门控校验：所有agent返回SUCCESS或显式SKIP前，不允许推进流程。
结果上报：推进流程前通过TaskUpdate汇总所有agent的执行结果。

Hooks for automated enforcement

自动执行钩子

TeammateIdle hook: prevent teammates from idling before work is verified.
TaskCompleted hook: prevent tasks from closing before tests pass.
Both use exit code 2 to send feedback and keep the teammate/task active.

TeammateIdle钩子：在工作验证完成前阻止队友进入空闲状态。
TaskCompleted钩子：测试通过前阻止任务关闭。
两个钩子都使用退出码2返回反馈，并保持队友/任务处于活跃状态。

Plan approval workflow

计划审批工作流

For risky changes, include "Require plan approval before making changes" in the spawn prompt.
Teammate enters read-only plan mode, sends plan_approval_request to lead when ready.
Lead approves or rejects with feedback. Teammate revises if rejected.
Influence approval criteria in spawn prompt: "only approve plans that include test coverage."

对于高风险变更，在生成prompt中添加「变更前需要申请计划审批」要求。
队友进入只读计划模式，准备完成后向负责人发送plan_approval_request。
负责人审批通过或驳回并给出反馈，驳回后队友进行修改。
可以在生成prompt中指定审批标准：「仅批准包含测试覆盖的计划」。

5. Orchestration Patterns

5. 编排模式

Pattern	Name	Use When	Details
A	Parallel subagent wave	2+ independent subtasks in a session	see `references/patterns.md`
B	Agent team with file ownership	Cross-domain features, large refactors	see `references/patterns.md`
C	Competing hypotheses	Debugging, architecture decisions	see `references/patterns.md`
D	Plan-then-swarm	Large tasks needing human approval	see `references/patterns.md`
E	Teams of subagent-using teammates (DEFAULT)	2+ independent streams — use by default	see `references/patterns.md`
F	Multi-wave pipeline	Explore → implement → verify phases	see `references/patterns.md`

模式编号	名称	适用场景	详情
A	并行subagent波次	单会话内2个及以上独立子任务	见 `references/patterns.md`
B	带文件所有权的Agent团队	跨领域功能、大型重构	见 `references/patterns.md`
C	竞争性假设	调试、架构决策	见 `references/patterns.md`
D	先计划再集群执行	需要人工审批的大型任务	见 `references/patterns.md`
E	由使用subagent的队友组成的团队（默认）	2个及以上独立工作流 —— 默认使用	见 `references/patterns.md`
F	多波次流水线	探索 → 实现 → 验证阶段	见 `references/patterns.md`

6. Limitations

6. 限制说明

No session resumption for teammates (
```
/resume
```
and
```
/rewind
```
won't restore them).
No nested teams (teammates can use subagents but cannot spawn teams).
One team per session. Clean up before starting a new one.
Lead is fixed — cannot transfer leadership.
All teammates inherit the lead's permission mode at spawn.
Subagent resumption may not recover from all failure modes (re-spawn instead).
No built-in timeout detection — orchestrator must poll with
```
TaskOutput
```
manually.
Recovery re-spawns count toward the session's agent budget.
Display modes: in-process (Shift+Down to cycle) is default; split panes require tmux or iTerm2.
Teammate interaction: Enter to view session, Escape to interrupt, Ctrl+T for task list.

队友不支持会话恢复（
```
/resume
```
和
```
/rewind
```
无法恢复它们）。
不支持嵌套团队（队友可以使用subagent，但不能生成新的团队）。
每个会话仅支持一个团队，启动新团队前需要清理旧团队。
负责人固定，无法转交领导权。
所有队友在生成时继承负责人的权限模式。
Subagent恢复功能无法覆盖所有故障模式（遇到无法恢复的故障请重新生成实例）。
无内置超时检测——编排者必须手动使用
```
TaskOutput
```
轮询。
故障恢复时重新生成的实例会计入会话的agent预算。
展示模式：默认是进程内模式（Shift+Down切换），分屏需要tmux或iTerm2支持。
队友交互：回车查看会话，Esc中断，Ctrl+T查看任务列表。

Critical Rules

核心规则

Never dispatch independent actions sequentially — all independent Task calls MUST appear in one response.
Always run the Decomposition Gate before any tool-mediated work; skipping it is never acceptable.
Never reduce parallelism, tier, or model quality for any reason — always use opus, no exceptions. Never downgrade.
Never silently drop a failed subagent — N dispatched = N accounted for; apply the Accounting Rule after every wave.
Never advance to Wave N+1 with unresolved agents — resolve all agents in Wave N first.
Always create TaskCreate entries before dispatching subagent waves or agent teams — silent orchestration is forbidden.
Never assign two teammates overlapping file ownership — overlapping edits cause lost work.
Always include full context in subagent and teammate prompts — they do not inherit conversation history.

永远不要顺序派发独立动作——所有独立的Task调用必须放在同一条响应中。
所有工具调用类工作前必须运行Decomposition Gate，跳过校验是绝对不允许的。
永远不要因为任何原因降低并行度、层级或模型质量——无例外必须使用opus，永远不要降级。
永远不要静默丢弃失败的subagent——派发N个必须统计N个结果，每波次执行后都要应用计数规则。
上一波次还有未解决的agent时，永远不要推进到下一波次——必须先解决当前波次的所有agent问题。
派发subagent波次或Agent团队前必须创建TaskCreate条目——禁止静默编排。
永远不要为两个队友分配重叠的文件所有权——重叠编辑会导致工作丢失。
永远要在subagent和队友的prompt中包含完整上下文——它们无法继承对话历史。

Reference File Index

参考文件索引

File	Content	Read When
`references/patterns.md`	Detailed patterns A-F with ASCII diagrams, key rules, recovery ladder	Designing parallel execution or selecting a pattern

文件	内容	阅读场景
`references/patterns.md`	A-F模式的详细说明，包含ASCII示意图、核心规则、故障恢复阶梯	设计并行执行流程或选择编排模式时

7. Progress Visibility (MANDATORY for orchestrated work)

7. 进度可视化（编排类工作的强制要求）

All orchestrated work must produce structured progress indicators via TaskCreate/TaskUpdate.

Tier	Requirement	Granularity
Subagent wave	MUST	One task per subagent, created before dispatch
Agent team	MUST	One task per teammate assignment, created during setup
Single session (3+ steps)	SHOULD	One task per logical step

所有编排类工作必须通过TaskCreate/TaskUpdate提供结构化的进度指标。

层级	要求	粒度
Subagent波次	必须	每个subagent对应一个任务，派发前创建
Agent团队	必须	每个队友的分配任务对应一个任务，配置阶段创建
单会话（3步及以上）	建议	每个逻辑步骤对应一个任务

Rules

规则

Create tasks before execution begins, not retroactively.
Each task MUST have a descriptive
```
activeForm
```
in present continuous tense naming the specific action and target.
Update tasks to
```
in_progress
```
before starting,
```
completed
```
immediately after.
After wave completion + accounting, summarize all agent outcomes before dispatching the next wave.

任务必须在执行开始前创建，不能事后补录。
每个任务必须包含描述性的
```
activeForm
```
，用现在进行时说明具体动作和目标。
任务开始前更新为
```
in_progress
```
状态，完成后立即更新为
```
completed
```
。
波次执行完成+计数校验后，先汇总所有agent的执行结果，再派发下一波次。