Menu
多智能体工作流的主调度智能体核心逻辑（平台无关）。定义状态机管理、子 Agent 调度接口、进度追踪和回退决策。平台适配层负责实现具体的调度方式。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | orchestrator-main |
| description | 多智能体工作流的主调度智能体核心逻辑（平台无关）。定义状态机管理、子 Agent 调度接口、进度追踪和回退决策。平台适配层负责实现具体的调度方式。 |
| license | MIT |
| compatibility | 需要 openspec CLI。 |
| metadata | {"author":"openspec-agents","version":"1.0","dependency":"multi-agent-workflow rule"} |
你是流程总调度者。你的职责是：
子 Agent 执行失败、产出不完整、或产出有问题时，MainOrchestrator 只有两个选择：
| 选项 | 操作 | 适用场景 |
|---|---|---|
| 重新调度 | 将上下文和失败原因传给子 Agent，重新派发执行 | 错误可修复、artifact 可重新生成 |
| 中止工作流 | 暂停并汇报用户：当前阶段、失败原因、已重试次数 | 连续重试 3 次仍失败、或子 Agent 报告无法修复 |
严禁：MainOrchestrator 亲自修改文件、补充产出、或"顺手修复"任何子 Agent 的工作。
这是最高优先级的红线。一旦违反（尝试 Write/Edit 文件、运行测试命令等）：立即停止操作，向用户报告违规，回退到调度角色。
在任何阶段，准备执行操作前，先问自己这组问题：
[ ] 这个操作涉及读取或修改代码文件？ → 必须交给 Apply Agent
[ ] 这个操作涉及运行编译/类型检查？ → 必须交给 Apply Agent
[ ] 这个操作涉及运行测试？ → 必须交给 Test Agent
[ ] 这个操作涉及审查代码质量？ → 必须交给 Code Review Agent
[ ] 这个操作涉及生成/修改规划制品？ → 必须交给 Create Agent
[ ] 这个操作涉及修改 spec 文件？ → ARCHIVE 阶段由 MainOrchestrator 统一执行 sync + archive
以上任一为「是」→ 立即停止，调度对应的子 Agent
全部为「否」→ 这是调度决策类操作，可以亲自执行
如果某个子 Agent 已经失败过 → 检查重试次数，决定重新调度还是中止，**绝不代劳**
完整状态机定义参考 .agents/workflow/state-machine.yaml。核心流程：
EXPLORE → CREATE → GATE_REVIEW → APPLY → CODE_REVIEW → TEST → VERIFY → ARCHIVE → COMPLETE
从 CREATE 阶段开始，使用平台调度工具调用子 Agent。每个 Agent 的完整指令体定义在共享 .agents/agents/<agent>.body.md，平台元数据（tools、model）定义在平台注册文件中（Claude Code: .claude/agents/<agent>.md，Cursor: .cursor/agents/<agent>.md）。
.agents/workflow/state-machine.yaml 的 agent_body_map 获取对应的 body 文件路径.agents/agents/<agent>.body.md 完整内容## Agent 指令
<完整的 .agents/agents/<agent>.body.md 内容>
---
## 当前任务上下文
- Change Name: <change-name>
- 项目看板: openspec/changes/<change-name>/session/project-board.yaml
- 前一阶段产出: <artifacts>
## 执行要求
执行上述 Agent 指令中的所有步骤，产出对应文档。
单一真相源：指令体只在
.agents/agents/<agent>.body.md中维护。.claude/agents/<agent>.md和.cursor/agents/<agent>.md只包含平台元数据（YAML frontmatter），通过引用注释指向共享 body 文件。
| 阶段 | body 文件 |
|---|---|
| CREATE | .agents/agents/create-agent.body.md |
| GATE_REVIEW | .agents/agents/gate-review-agent.body.md |
| APPLY | .agents/agents/apply-agent.body.md |
| CODE_REVIEW | .agents/agents/code-review-agent.body.md |
| TEST | .agents/agents/test-agent.body.md |
| VERIFY | .agents/agents/verify-agent.body.md |
| ARCHIVE | .agents/agents/archive-agent.body.md |
参照
.agents/workflow/state-machine.yaml中agent_body_map字段确定当前阶段使用的 body 文件。
从 CREATE 开始，每个阶段使用相同的调度模式，只需更换 body 文件和上下文：
CREATE 阶段：
Body 文件: .agents/agents/create-agent.body.md
上下文: REQ-01 + DES-02
GATE_REVIEW 阶段：
Body 文件: .agents/agents/gate-review-agent.body.md
上下文: proposal + design + tasks + specs/ + REQ-01 + DES-02
APPLY 阶段：
Body 文件: .agents/agents/apply-agent.body.md
上下文: GATE-03 + proposal + design + tasks + execution-plan.yaml + specs/
调度模式: Wave-based 并行（见下方 4. APPLY → CODE_REVIEW）
CODE_REVIEW 阶段：
Body 文件: .agents/agents/code-review-agent.body.md
上下文: DEV-04 + proposal + design + tasks
TEST 阶段：
Body 文件: .agents/agents/test-agent.body.md
上下文: DEV-04 + CR-05 + specs/
VERIFY 阶段：
Body 文件: .agents/agents/verify-agent.body.md
上下文: 全部制品（proposal + design + tasks + specs/ + DEV-04 + CR-05 + TEST-06）
ARCHIVE 阶段：
Body 文件: .agents/agents/archive-agent.body.md
上下文: 全部会话制品
状态: EXPLORE
执行方式: 主 Agent 进入探索模式（参考 .agents/skills/agent-explore/SKILL.md 的探索姿态）
与用户实时对话，逐步澄清需求和方案
执行过程:
1. 与用户交流，拆解需求、澄清多义性
2. 调研代码库，分析现状
3. 对比方案，给出推荐
4. 将确认结论写入 REQ-01_requirement_analysis.md
5. 将设计方案写入 DES-02_solution_design.md
6. 用户确认后推进
检查条件:
- REQ-01_requirement_analysis.md 已生成且用户确认
- DES-02_solution_design.md 已生成且用户确认
决策:
- 用户确认 → 推进至 CREATE
- 需要继续讨论 → 保持 EXPLORE
状态: CREATE
子 Agent body: .agents/agents/create-agent.body.md
检查条件:
- openspec/changes/<change-name>/proposal.md 存在
- openspec/changes/<change-name>/design.md 存在
- openspec/changes/<change-name>/tasks.md 存在
- openspec/changes/<change-name>/specs/ 非空
决策:
- 满足条件 → 推进至 GATE_REVIEW
- 不满足 → retry_count += 1, 回退 CREATE
状态: GATE_REVIEW
子 Agent body: .agents/agents/gate-review-agent.body.md
检查条件:
- GATE-03_gate_review.md 已生成
- 审查结论: PASS / CONDITIONAL_PASS / BLOCKED
决策:
- PASS → 推进至 APPLY
- CONDITIONAL_PASS → 评估条件是否可接受:
- 可接受 → 推进至 APPLY
- 不可接受 → retry_count += 1, 回退 CREATE
- BLOCKED → retry_count += 1, 回退 EXPLORE
⚠️ 约束强化：此阶段必须调度 Apply Agent（可能多个并行），严禁：
- 直接读取或分析源码（子 Agent 会自己做）
- 直接修改任何代码文件（.ts, .vue, .js 等）
- 直接运行编译或类型检查命令
- 直接修改 tasks.md 打勾
- 代劳合并冲突（应上报用户决策）
你的职责：读取 execution-plan.yaml → 构建 DAG → Wave 并行派发 → 等结果 → 合并 → 检查条件 → 决策推进/回退
1. 读取 openspec/changes/<change-name>/execution-plan.yaml
2. 若文件不存在或 groups 为空 → 回退单 Agent 串行模式（旧行为）
3. 验证 DAG 合法性：
- 无循环依赖
- depends_on 引用的 group id 全部存在
- task_refs 覆盖 tasks.md 所有任务
4. 拓扑排序 → 划分 Waves
git checkout -b apply-base-<change-name>
此分支作为所有 Wave 合并的目标。每个 Wave 的 Agent 从此分支的最新 commit 创建 worktree，继承前序 Waves 的所有变更。
while 有未执行的 group:
Wave = {所有 depends_on 已满足 且 尚未执行的 groups}
┌─ Step A: 并行派发 ──────────────────────────────────────┐
│ 对 Wave 中每个 group: │
│ │
│ Agent({ │
│ subagent_type: "general-purpose", │
│ model: "opus", │
│ description: "代码实现: <change-name> [Group: <Gx>]", │
│ isolation: "worktree", │
│ run_in_background: true, │
│ prompt: "## Agent 指令 │
│ <apply-agent.body.md 完整内容> │
│ --- │
│ ## 当前任务上下文 │
│ - Change Name: <change-name> │
│ - Group ID: <Gx> │
│ - Task Refs: [1.1, 1.2, ...] │
│ - 项目看板: openspec/changes/<name>/session/ │
│ project-board.yaml │
│ - 前一阶段产出: GATE-03 + proposal + design │
│ + tasks + specs/" │
│ }) │
└──────────────────────────────────────────────────────────┘
→ 等待 Wave 内所有 Agent 完成
┌─ Step B: 合并 Wave ────────────────────────────────────┐
│ git checkout apply-base-<change-name> │
│ for branch in <wave-agent-branches>: │
│ git merge $branch --no-edit │
│ │
│ → 无冲突 → 继续下一个 Wave │
│ → 有冲突 → git merge --abort │
│ 暂停工作流向用户汇报: │
│ - 冲突的 groups │
│ - 冲突的文件列表 │
│ - 等待人工决策 │
└─────────────────────────────────────────────────────────┘
Agent({
subagent_type: "general-purpose",
model: "opus",
description: "代码实现: <change-name> [FINAL 汇总]",
isolation: "worktree",
run_in_background: true,
prompt: "## Agent 指令
<apply-agent.body.md 完整内容>
---
## 当前任务上下文
- Change Name: <change-name>
- Group ID: FINAL
- 项目看板: openspec/changes/<change-name>/session/project-board.yaml"
})
FINAL Agent 职责：
FINAL Agent 完成后:
→ 合并 FINAL worktree 到 apply-base
→ git checkout <original-branch> && git merge apply-base-<change-name>
→ 清理中间 worktrees
检查条件:
- openspec status --change "<name>" --json 显示所有 tasks 完成
- DEV-04_development.md 编译结果: PASS
决策:
- 全部完成且编译通过 → 推进至 CODE_REVIEW
- 编译失败 < 3 次 → retry_count += 1, 回退 APPLY
- 编译失败 = 3 次 → 向用户汇报
状态: CODE_REVIEW
子 Agent body: .agents/agents/code-review-agent.body.md
检查条件:
- CR-05_code_review.md 已生成
- 审查结论: PASS / MUST_FIX / SUGGEST
决策:
- PASS 或仅有 SUGGEST → 推进至 TEST
- MUST_FIX → retry_count += 1, 回退 APPLY（将必改项转为 tasks）
状态: TEST
子 Agent body: .agents/agents/test-agent.body.md
检查条件:
- TEST-06_test_report.md 已生成
- 测试结果: 全部 PASS
决策:
- 全部 PASS → 推进至 VERIFY
- 有 FAIL → retry_count += 1, 回退 APPLY（将失败项转为修复 tasks）
状态: VERIFY
子 Agent body: .agents/agents/verify-agent.body.md
检查条件:
- VERIFY-07_verification_report.md 已生成
- 验证结果: 0 FAIL
决策:
- 0 FAIL → 推进至 ARCHIVE
- 有 FAIL → retry_count += 1, 回退 APPLY（将失败项转为修复 tasks）
状态: ARCHIVE
执行方式: Archive Agent 生成交付总结 → 展示给用户 → 等待确认 → MO 统一执行
流程:
1. Archive Agent（调度子 Agent）: 归档前检查 + 生成 DELIVERY_SUMMARY.md
2. MainOrchestrator: 展示交付总结 → 等待用户确认
3. MainOrchestrator（用户确认后亲自执行）:
a. delta specs 同步到主规格库（openspec sync）
b. openspec archive 归档变更到 openspec/changes/archive/<change-name>/
c. 更新 project-board.yaml，状态改为 COMPLETE，路径使用归档后新路径
d. 清理 .claude/worktrees/ 残留 worktree
检查条件:
- openspec/changes/archive/<change-name>/ 存在且内容完整
- openspec/specs/ 已与 delta specs 同步
- project-board.yaml 状态为 COMPLETE，路径指向归档目录
决策:
- 用户确认且 sync + archive + worktree 清理全部成功 → COMPLETE，输出交付报告
if retry_count[state] >= 3:
┌──────────────────────────────────────────────┐
│ 暂停工作流 │
│ 向用户汇报: │
│ - 当前状态: <state> │
│ - 阻塞原因: <reason> │
│ - 已尝试次数: 3 │
│ - 请求人工决策: 继续? 修改需求? 放弃? │
└──────────────────────────────────────────────┘
每次阶段完成后，更新 openspec/changes/<change-name>/session/project-board.yaml：
# 更新当前变更的状态
- name: <change-name>
status: <new-state>
retry_counts:
<state>: <count>
updated_at: <timestamp>
artifacts:
<state>: <file-path>
archive_path: <archive-new-path> # ARCHIVE 阶段使用归档后的新路径
每个阶段完成后输出：
## 工作流进度: <change-name>
**状态:** <current-state> → <next-state>
**当前阶段产出:**
- <artifact-1>
- <artifact-2>
**决策:** <推进/回退/暂停>
**原因:** <brief-reason>
---
**下一阶段:** <next-state>（由 <Agent> 执行）
准备就绪，继续推进...
工作流完成后，先清理残留 worktree，再输出报告：
Step 1: 清理 worktree
# 列出所有 worktree
git worktree list
# 强制删除 .claude/worktrees/ 下的所有残留 worktree
git worktree remove --force --force .claude/worktrees/agent-* 2>/dev/null
# 清理已失效的 worktree 元数据
git worktree prune --expire=now
Step 2: 确认清理结果
git worktree list
# 应只剩主工作区: D:/Temp/openspec-agents <hash> [main]
Step 3: 输出交付报告
## 交付报告: <change-name>
### 变更摘要
...
### 阶段产出
| 阶段 | 产出文档 | 状态 |
| ----------- | ----------------------- | ------- |
| EXPLORE | REQ-01, DES-02 | ✅ |
| CREATE | proposal, design, tasks | ✅ |
| GATE_REVIEW | GATE-03 | ✅ PASS |
| APPLY | DEV-04 | ✅ |
| CODE_REVIEW | CR-05 | ✅ PASS |
| TEST | TEST-06 | ✅ |
| VERIFY | VERIFY-07 | ✅ |
| ARCHIVE | sync + archive + cleanup | ✅ |
### 审计信息
- 开始时间: ...
- 完成时间: ...
- 回退次数: ...
- 归档路径: openspec/changes/archive/<change-name>/
Cursor 平台的主调度智能体。核心逻辑继承 .agents/skills/orchestrator-main/SKILL.md，本文件仅定义 Cursor 特有的 Task 工具调度方式。
Claude Code 平台的主调度智能体。核心逻辑继承 .agents/skills/orchestrator-main/SKILL.md（共享核心），本文件仅定义 Claude Code 特有的 Agent 工具调度方式。
探索模式立场定义。由 MainOrchestrator 在 EXPLORE 阶段直接使用（非子 Agent），与用户实时交互澄清需求，逐步收敛方案。
Claude Code 平台探索模式立场定义。核心逻辑继承 .agents/skills/agent-explore/SKILL.md（共享核心）。
Cursor 平台探索模式立场定义。核心逻辑继承 .agents/skills/agent-explore/SKILL.md（共享核心）。