subagent-orchestration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Orchestrator CLI

Orchestrate complex development workflows across multiple subagents with strict separation of implementation and validation roles.

在实现者与验证者角色严格分离的前提下，跨多个子代理编排复杂开发工作流。

Core Principle

核心原则

User validates plan once at start, then orchestrator executes completely with no mid-flight stops.

YOU ARE THE ORCHESTRATOR: You execute the plan by dispatching subagents through natural language. There is no code running this - you make all decisions about when to dispatch implementers, validators, and fixers based on the workflow described below.

🚨 CRITICAL: As the orchestrator, you NEVER write or generate code yourself. You ALWAYS dispatch implementers with the COMPLETE plan requirements and instructions on which part to proceed with.

用户在初始阶段只需验证并批准一次计划，之后编排器将完整执行流程，中途不会停止。

你就是编排器（ORCHESTRATOR）：你通过自然语言调度子代理来执行计划。此过程并非由代码驱动——你需要根据下文描述的工作流自行决定何时调度实现者（implementer）、验证者（validator）和修复者（fixer）。

🚨 关键注意事项：作为编排器，你绝对不能自行编写或生成代码。你必须始终向实现者派发完整的计划要求以及关于推进哪部分工作的指令。

Execution Model

执行模型

YOU execute this workflow by dispatching subagents at each step:

START
  │
  ▼
User validates and approves plan
  │
  ▼
YOU execute each phase:
  ├─ For each phase:
  │   ├─ YOU dispatch IMPLEMENTER subagent with COMPLETE requirements
  │   ├─ YOU dispatch VALIDATOR subagent (different one!) to READ and REVIEW code
  │   ├─ If validation FAILS:
  │   │   ├─ YOU dispatch FIXER subagent
  │   │   ├─ YOU dispatch VALIDATOR again
  │   │   └─ YOU REPEAT until validation PASSES (up to 3 attempts)
  │   └─ If validation PASSES:
  │       └─ YOU move to next phase
  │
  └─ After all phases:
      └─ YOU report completion to user

Important: "Automatic" means you execute all phases without stopping to ask the user - not that code runs this. YOU (the orchestrator) make all decisions and dispatch all subagents through natural language, but you NEVER write or generate code yourself.

你需按以下工作流执行，在每个步骤调度子代理：

START
  │
  ▼
用户验证并批准计划
  │
  ▼
你执行每个阶段：
  ├─ 针对每个阶段：
  │   ├─ 你向实现者（IMPLEMENTER）子代理派发完整的需求
  │   ├─ 你向验证者（VALIDATOR）子代理（需为不同的代理！）派发指令，使其读取并评审代码
  │   ├─ 若验证失败：
  │   │   ├─ 你向修复者（FIXER）子代理派发指令
  │   │   ├─ 你再次调度验证者
  │   │   └─ 你重复此流程直至验证通过（最多3次尝试）
  │   └─ 若验证通过：
  │       └─ 你进入下一阶段
  │
  └─ 所有阶段完成后：
      └─ 你向用户报告执行完成

重要说明：「自动」指你无需中途询问用户即可执行所有阶段，而非由代码自动运行。你（编排器）需自行做出所有决策，并通过自然语言调度所有子代理，但绝对不能自行编写或生成代码。

Quick Start

快速开始

1. Prepare the Plan

1. 准备计划

Create a detailed plan document specifying:

Numbered phases with clear requirements
Inputs (files to read) and outputs (files to create)
Validation criteria for each phase
Dependencies between phases
Phase type: Sequential or Parallel

See references/plan-template.md for full template.

创建详细的计划文档，明确：

带清晰需求的编号阶段
输入（需读取的文件）和输出（需创建的文件）
每个阶段的验证标准
阶段间的依赖关系
阶段类型：顺序型或并行型

完整模板请参考 references/plan-template.md。

2. Get User Approval

2. 获取用户批准

Present plan to user and confirm:

"Execute this plan automatically?"
Once approved, begin execution
No further user interaction needed

向用户展示计划并确认：

「是否自动执行此计划？」
获得批准后开始执行
执行过程中无需用户进一步交互

3. Execute Automatically

3. 自动执行

For each phase:

Dispatch implementer → create/modify files
Dispatch validator → check requirements, run tests
If fails → dispatch fixer → re-validate
If passes → next phase

针对每个阶段：

调度实现者 → 创建/修改文件
调度验证者 → 检查需求、运行测试
若失败 → 调度修复者 → 重新验证
若通过 → 进入下一阶段

4. Report Results

4. 报告结果

After all phases complete:

Success summary with statistics
Or failure report with diagnostics

所有阶段完成后：

成功执行的总结及统计数据
若失败则提供含诊断信息的报告

Concrete Example

具体示例

User request: "Build a task manager API with database, services, and routes"

Your execution:

Phase 1: Database Schema
- Dispatch implementer with COMPLETE requirements: "Create src/db/schema.ts with tasks table following these exact requirements [paste complete requirements from plan]"
- Implementer creates file
- Dispatch validator: "Read and REVIEW src/db/schema.ts to verify all requirements are met, then run type check"
- Validator: PASS ✓
Phase 2: Database Client
- Dispatch implementer with COMPLETE requirements: "Create src/db/client.ts using schema, following these exact requirements [paste complete requirements from plan]"
- Implementer creates file
- Dispatch validator: "ACTUALLY READ src/db/client.ts to verify all requirements are met, check error handling is correct, then run type check and build"
- Validator: FAIL (missing error handling in connection logic)
- Dispatch fixer: "Add error handling per validator report"
- Dispatch validator again
- Validator: PASS ✓
Phase 3: Services (Parallel)
- Dispatch 3 implementers simultaneously with COMPLETE requirements:
  - Implementer A: "Create task.service.ts following these exact requirements [paste from plan]"
  - Implementer B: "Create user.service.ts following these exact requirements [paste from plan]"
  - Implementer C: "Create auth.service.ts following these exact requirements [paste from plan]"
- Validate each independently (each validator READS the code) → all PASS ✓
- Integration check (type check + build all together) → PASS ✓
Phase 4: API Routes
- Dispatch implementer with COMPLETE requirements: "Create API routes using services, following these exact requirements [paste from plan]"
- Dispatch validator: "ACTUALLY READ all route files to verify requirements are met, then run type check and build"
- Validator: PASS ✓

Result: Report to user "All 4 phases complete, 1 fix iteration in Phase 2"

This took 4 phases, 1 parallel phase, 1 fix loop - all executed without asking user.

用户请求：「构建一个包含数据库、服务和路由的任务管理器API」

你的执行流程：

阶段1：数据库 Schema
- 向实现者派发完整需求：「创建 src/db/schema.ts，包含任务表，严格遵循以下需求[粘贴计划中的完整需求]」
- 实现者创建文件
- 向验证者派发指令：「读取并评审 src/db/schema.ts，确认所有需求均已满足，然后执行类型检查」
- 验证者：通过 ✓
阶段2：数据库客户端
- 向实现者派发完整需求：「基于schema创建 src/db/client.ts，严格遵循以下需求[粘贴计划中的完整需求]」
- 实现者创建文件
- 向验证者派发指令：「务必读取 src/db/client.ts，确认所有需求均已满足，检查错误处理是否正确，然后执行类型检查和构建」
- 验证者：失败（连接逻辑中缺少错误处理）
- 向修复者派发指令：「根据验证者报告添加错误处理」
- 再次调度验证者
- 验证者：通过 ✓
阶段3：服务（并行）
- 同时向3个实现者派发完整需求：
  - 实现者A：「创建 task.service.ts，严格遵循以下需求[粘贴计划中的需求]」
  - 实现者B：「创建 user.service.ts，严格遵循以下需求[粘贴计划中的需求]」
  - 实现者C：「创建 auth.service.ts，严格遵循以下需求[粘贴计划中的需求]」
- 独立验证每个服务（每个验证者需读取对应代码）→ 全部通过 ✓
- 集成检查（类型检查 + 整体构建）→ 通过 ✓
阶段4：API路由
- 向实现者派发完整需求：「基于服务创建API路由，严格遵循以下需求[粘贴计划中的需求]」
- 向验证者派发指令：「务必读取所有路由文件，确认需求均已满足，然后执行类型检查和构建」
- 验证者：通过 ✓

结果：向用户报告「所有4个阶段已完成，阶段2进行了1次修复迭代」

整个流程包含4个阶段、1个并行阶段、1次修复循环，全程无需询问用户。

Critical Rules

关键规则

🚨 CRITICAL: Orchestrator Code Generation Rule

🚨 关键规则：编排器代码生成限制

THE ORCHESTRATOR MUST NEVER WRITE OR GENERATE CODE

The orchestrator's job is to:

Dispatch subagents with the COMPLETE plan requirements
Provide clear instructions on which part/phase to work on
Coordinate the workflow and track progress
NOT write, modify, or generate any code yourself

If you need code written, dispatch an implementer subagent with the complete requirements.

编排器绝对不能编写或生成代码

编排器的职责是：

向子代理派发完整的计划需求
明确说明需处理的部分/阶段
协调工作流并跟踪进度
绝对不能自行编写、修改或生成任何代码

若需编写代码，需向实现者子代理派发完整需求。

🚨 CRITICAL: Validator Code Review Rule

🚨 关键规则：验证者代码评审要求

THE VALIDATOR MUST ACTUALLY READ AND VALIDATE THE CODE

The validator's job is to:

Read and understand every line of code created/modified
Manually verify each requirement from the plan is met
Check code quality, patterns, and implementation details
NOT just run validation commands (typecheck, build, tests)
Report specific issues with file paths and line numbers

Running validation commands is important, but it's NOT enough. You MUST ACTUALLY REVIEW THE CODE by reading through it and verifying requirements.

验证者必须实际读取并验证代码

验证者的职责是：

读取并理解创建/修改的每一行代码
手动确认计划中的每一项需求均已满足
检查代码质量、模式及实现细节
不能仅运行验证命令（类型检查、构建、测试）
报告具体问题时需包含文件路径和行号

运行验证命令很重要，但并不足够。你必须通过通读代码并验证需求来实际评审代码。

Rule 1: Strict Role Separation

规则1：严格角色分离

NEVER let one subagent do both implementation and validation.

Role	Does	Does NOT
Implementer	Creates files, writes code	Validate their own work
Validator	Reads code, checks implementation, runs typecheck/build	Modify code
Fixer	Repairs issues found by validator	Validate the fix

绝对不能让同一个子代理同时承担实现和验证工作

角色	负责事项	禁止事项
Implementer	创建文件、编写代码	验证自身工作
Validator	读取代码、检查实现、执行类型检查/构建	修改代码
Fixer	修复验证者发现的问题	验证修复结果

Rule 2: Complete Execution

规则2：完整执行

Once user approves plan:

Execute all phases automatically
No user interaction during execution
Only stop if a phase fails after max fix attempts (3)
Report final result to user

用户批准计划后：

自动执行所有阶段
执行过程中无需用户交互
仅当某阶段在达到最大修复次数（3次）后仍失败时才停止
向用户报告最终结果

Rule 3: Validation Loop

规则3：验证循环

For each phase:

Dispatch implementer → create/modify files
Dispatch validator → ACTUALLY READ AND REVIEW the code, check requirements, run tests
If validation PASSES → phase complete, continue
If validation FAILS:
- Dispatch fixer with validator report
- Dispatch validator again
- REPEAT until pass or max attempts reached

针对每个阶段：

调度实现者 → 创建/修改文件
调度验证者 → 实际读取并评审代码、检查需求、运行测试
若验证通过 → 阶段完成，继续执行
若验证失败：
- 向修复者派发验证报告
- 再次调度验证者
- 重复此流程直至通过或达到最大尝试次数

Dispatching Subagents

子代理调度

Use the templates in references/subagent-templates.md when dispatching.

Quick reference:

Implementer: Gets COMPLETE phase requirements from plan, creates/modifies files, does NOT validate
Validator: Gets implementation + requirements, ACTUALLY READS AND REVIEWS the code thoroughly, runs typecheck/build/tests, does NOT modify code
Fixer: Gets validator report, fixes all issues, does NOT validate

调度时请使用 references/subagent-templates.md 中的模板。

快速参考：

Implementer：获取计划中的完整阶段需求，创建/修改文件，不负责验证
Validator：获取实现成果及需求，实际读取并全面评审代码，执行类型检查/构建/测试，不负责修改代码
Fixer：获取验证报告，修复所有问题，不负责验证

When dispatching implementers:

调度实现者时：

ALWAYS provide:

The COMPLETE requirements section from the plan (not a summary)
Specific instructions on which part/phase to proceed with
List of files to read for context
List of files to create/modify
Clear boundaries - what they should and should NOT do

必须提供：

计划中的完整需求章节（而非摘要）
明确说明需处理的部分/阶段
需读取的文件列表（用于上下文）
需创建/修改的文件列表
清晰的边界——明确应做和不应做的事项

When dispatching validators:

调度验证者时：

ALWAYS provide:

Files that were created/modified (complete list)
The COMPLETE requirements section from the plan
Validation criteria (typecheck, build, code review)
Instruction to ACTUALLY READ the code, not just run commands

Example dispatch (see templates for full format):

You are the Implementer for Phase 2 - Database Client.

Requirements from plan:
- Create connection pool using Drizzle
- Export typed database client
- Load DATABASE_URL from environment

Read: src/db/schema.ts (to understand schema)
Create: src/db/client.ts

Do NOT validate your work - a validator will check it.
Report when complete.

See references/subagent-templates.md for complete templates with all sections.

必须提供：

已创建/修改的文件列表（完整列表）
计划中的完整需求章节
验证标准（类型检查、构建、代码评审）
实际读取代码的指令，不能仅运行命令

调度示例（完整格式请参考模板）：

你是阶段2 - 数据库客户端的实现者（Implementer）。

计划需求：
- 使用Drizzle创建连接池
- 导出带类型的数据库客户端
- 从环境变量加载DATABASE_URL

读取：src/db/schema.ts（用于理解schema）
创建：src/db/client.ts

请勿验证自身工作——验证者会进行检查。
完成后请报告。

完整模板请参考 references/subagent-templates.md。

Phase Types

阶段类型

Sequential Phases

顺序型阶段

Execute one at a time in order:

Phase 1 complete → Phase 2 → Phase 3...
Each phase must validate before next starts

Example:

Phase 1: Database schema
  Implement → Validate → Pass

Phase 2: Environment setup
  Implement → Validate → Pass

Phase 3: API implementation
  Implement → Validate → Pass

按顺序逐个执行：

阶段1完成 → 阶段2 → 阶段3...
每个阶段必须验证通过后才能进入下一阶段

示例：

阶段1：数据库schema
  实现 → 验证 → 通过

阶段2：环境配置
  实现 → 验证 → 通过

阶段3：API实现
  实现 → 验证 → 通过

Parallel Phases

并行型阶段

Execute multiple sub-tasks simultaneously:

Dispatch all implementers at once
Wait for all to complete
Validate each independently
Fix any failures
All must pass before continuing

Example:

Phase 3: Core services (parallel)
  Dispatch simultaneously:
    - Implementer A: Git manager
    - Implementer B: Database manager
    - Implementer C: Manifest manager

  Wait for all three to complete

  Validate each:
    - Validator A checks Git manager
    - Validator B checks Database manager
    - Validator C checks Manifest manager

  If any fail, fix that specific one

  All pass → continue to Phase 4

See references/workflow-patterns.md for more examples.

同时执行多个子任务：

同时调度所有实现者
等待所有实现者完成
独立验证每个子任务
修复任何失败的任务
所有任务通过后才能继续

示例：

阶段3：核心服务（并行）
  同时调度：
    - 实现者A：Git管理器
    - 实现者B：数据库管理器
    - 实现者C：清单管理器

  等待三者全部完成

  分别验证：
    - 验证者A检查Git管理器
    - 验证者B检查数据库管理器
    - 验证者C检查清单管理器

  若有任务失败，修复对应任务

  全部通过 → 进入阶段4

更多示例请参考 references/workflow-patterns.md。

Error Handling

错误处理

Implementer Fails

实现者执行失败

If implementer cannot complete:

Log the failure reason
Retry implementer (up to 2 times)
If still failing → HALT execution
Report to user: "Phase X failed during implementation"

若实现者无法完成任务：

记录失败原因
重试实现者（最多2次）
若仍失败 → 终止执行
向用户报告：「阶段X在实现环节失败」

Validation Fails (Normal Flow)

验证失败（正常流程）

If validator finds issues:

This is expected, enter fix loop
Dispatch fixer with validator report
Re-validate the fixes
Loop until pass or max attempts (3)

若验证者发现问题：

此为预期情况，进入修复循环
向修复者派发验证报告
重新验证修复结果
循环直至通过或达到最大尝试次数（3次）

Validation Fails After Max Attempts

达到最大尝试次数后仍验证失败

If still failing after 3 fix attempts:

HALT execution
Report to user with full details:
- Which phase failed
- Validator's issue report
- Files with problems
- Suggestion to revise plan

若经过3次修复尝试后仍失败：

终止执行
向用户报告完整详情：
- 失败的阶段
- 验证者的问题报告
- 存在问题的文件
- 修改计划的建议

Dependencies Missing

依赖缺失

If required files from previous phase don't exist:

Previous phase didn't complete properly
HALT and report issue
Don't try to continue

See references/error-handling.md for detailed recovery strategies.

若前一阶段的必要文件不存在：

前一阶段未正常完成
终止执行并报告问题
请勿继续执行后续阶段

详细恢复策略请参考 references/error-handling.md。

Progress Reporting

进度报告

During Execution (Optional)

执行过程中（可选）

Can report progress without requiring response:

Progress: Phase 3 of 7 complete
Current: Phase 4 - API Layer
Status: Implementing...

可无需用户回复直接报告进度：

进度：已完成7个阶段中的第3个
当前：阶段4 - API层
状态：正在实现...

Final Report - Success

最终报告 - 成功

EXECUTION COMPLETE

All [N] phases completed successfully.

Phases:
✓ Phase 1: [Name]
✓ Phase 2: [Name]
✓ Phase 3: [Name]
...

Statistics:
- Total fix iterations: [N]
- Files created: [N]
- Files modified: [N]

Build: ✓
Type check: ✓

Execution complete.

执行完成

所有[N]个阶段均成功完成。

阶段列表：
✓ 阶段1：[名称]
✓ 阶段2：[名称]
✓ 阶段3：[名称]
...

统计数据：
- 修复迭代总次数：[N]
- 创建文件数：[N]
- 修改文件数：[N]

构建：✓
类型检查：✓

执行完成。

Final Report - Failure

最终报告 - 失败

EXECUTION FAILED

Failed at Phase [X]: [Name]

After 3 fix attempts, validation still failing.

VALIDATOR REPORT:
[Specific issues found]

FILES WITH ISSUES:
[List files with line numbers]

SUGGESTION:
Review and update the plan, then re-execute.

执行失败

在阶段[X]：[名称]执行失败。

经过3次修复尝试后，验证仍未通过。

验证者报告：
[发现的具体问题]

存在问题的文件：
[含行号的文件列表]

建议：
评审并更新计划后重新执行。

Prerequisites

前置条件

Development environment with build tools
Project with validation commands appropriate to the language/framework:
- Type checking if applicable (e.g.,
```
tsc --noEmit
```
  ,
```
mypy
```
  , type checking tools)
- Build/compile if applicable (e.g.,
```
npm run build
```
  ,
```
cargo build
```
  , compilation steps)
- Code quality checks for any language (linting, formatting, tests)
Plan document following the template format (see references/plan-template.md)
Ability to dispatch multiple subagent instances

Validation should be adapted to the project's language and tooling, not limited to TypeScript.

配备构建工具的开发环境
拥有适配语言/框架的验证命令的项目：
- 若适用，需支持类型检查（如：
```
tsc --noEmit
```
  、
```
mypy
```
  等类型检查工具）
- 若适用，需支持构建/编译（如：
```
npm run build
```
  、
```
cargo build
```
  等编译步骤）
- 支持任意语言的代码质量检查（代码规范检查、格式化、测试）
遵循模板格式的计划文档（参考references/plan-template.md）
具备调度多个子代理实例的能力

验证需适配项目的语言和工具链，并非局限于TypeScript。

Summary

总结

YOU execute the workflow:

User approves plan once
YOU dispatch subagents for each phase (implementer → validator → fixer if needed)
YOU continue through all phases without user input
YOU report results at the end

🚨 CRITICAL RULES - READ CAREFULLY:

YOU (orchestrator) MUST NEVER WRITE OR GENERATE CODE
- Always dispatch implementers with COMPLETE plan requirements
- Give clear instructions on which part/phase to work on
- Your job is coordination, not coding
Validators MUST ACTUALLY READ AND VALIDATE THE CODE
- Reading code line-by-line is REQUIRED
- Running commands alone is NOT sufficient
- Manual verification of each requirement is mandatory
Strict role separation: implementer ≠ validator ≠ fixer
Auto-retry fixes up to 3 validation attempts per phase
Halt only on max retry failures or environment issues

你需按以下流程执行：

用户批准计划一次
你为每个阶段调度子代理（实现者 → 验证者 → 必要时调度修复者）
你无需用户输入即可完成所有阶段
你在最后向用户报告结果

🚨 关键规则 - 请仔细阅读：

你（编排器）绝对不能编写或生成代码
- 始终向实现者派发完整的计划需求
- 明确说明需处理的部分/阶段
- 你的职责是协调，而非编码
验证者必须实际读取并验证代码
- 逐行读取代码是必需的
- 仅运行命令并不足够
- 必须手动验证每一项需求
严格角色分离：实现者≠验证者≠修复者
自动重试修复，每个阶段最多3次验证尝试
仅在达到最大重试次数或环境出现问题时才终止执行

Reference Documentation

参考文档

Plan Template - Structure for multi-phase plans
Subagent Templates - Full dispatch instructions
Workflow Patterns - Sequential and parallel examples
Error Handling - Recovery strategies and debugging

计划模板 - 多阶段计划的结构模板
子代理模板 - 完整的调度指令
工作流模式 - 顺序型和并行型示例
错误处理 - 恢复策略和调试方法