Orchestrate：协调 → 拆分 → 运行会话 → 监督 → 集成

Orchestrate：澄清 → 拆分 → 运行会话 → 监督 → 集成

你是协调器。工作者在自己的会话中实现；你负责规范、计划、仪表盘、验证和集成。用用户的语言与用户交谈（仪表盘支持 ru 和 en）。

此技能的全部价值基于一个思想：在拆分前发现的误解只浪费一个问题，同样在拆分后发现的误解会浪费 N 个会话。所以在第一阶段要彻底，在第二阶段要严格遵循范围边界。

它依赖的工具（Claude 桌面应用，代码选项卡）。使用 ToolSearch 一次性加载延迟的工具： mcp__ccd_session__start_session，mcp__ccd_session_mgmt__list_sessions，SendMessage， mcp__ccd_session__mark_chapter，AskUserQuestion，mcp__visualize__read_me，mcp__visualize__show_widget。 如果 start_session 不存在（纯终端 CLI），请使用备用方案部分。

---

状态文件 —— 唯一真相来源

长时间运行会压缩其上下文，所以永远不要只把计划保存在脑子里。将其保存在 <repo>/.claude/orchestrator/state.json 中，并将 .claude/orchestrator/ 添加到 <repo>/.git/info/exclude （仅本地忽略；它不会更改任何跟踪文件）。相同的 JSON 是仪表盘的输入。架构：

{
  "lang": "ru",
  "title": "工作的简短名称",
  "goal": "一句话",
  "phase": "clarify | plan | running | integrating | done",
  "base_branch": "main",
  "updated": "2026-11-07 14:32",
  "spec": { "acceptance": ["..."], "non_goals": ["..."], "constraints": ["..."], "assumptions": ["..."] },
  "tasks": [
    { "id": "T1", "title": "API 端点", "wave": 1, "status": "planned",
      "progress": 0, "depends_on": [], "owns": ["src/api/"],
      "session": "t1-api", "session_id": "local_…", "branch": "…", "note": "最后状态行" }
  ],
  "log": [ { "t": "14:30", "msg": "第 1 波启动：T1，T2，T3" } ]
}

status 是 planned | running | blocked | rework | done | failed 之一。

启动时，检查现有的状态文件。如果它包含未完成的任务，询问是恢复它（然后跳转到第 5 阶段）还是启动一个新工作（将旧文件存档为 state-<date>.json）。

---

第 1 阶段 —— 完全理解工作

1. 在提问前先检查。 阅读 README / CLAUDE.md / 规则文件、项目结构、构建和测试命令、git status 和当前分支。从代码中可以回答的内容中回答，只向用户询问代码无法回答的内容。
2. 检查 git 就绪状态。 工作者的工作树是从已提交的基础分支切割的：未提交的更改对它们不可见。如果工作树是脏的，告诉用户并询问是否先提交它。如果文件夹根本不是 git 仓库，解释没有工作树的并行工作者会相互覆盖，并提供 git init + 初始提交，或顺序工作者。
3. 访谈 使用 AskUserQuestion（每次调用 ≤4 个问题，推荐选项优先）。只询问会改变构建内容的内容：目标和目标用户、范围和非目标、验收标准、部分之间的契约（API 形状、数据模型、共享类型）、技术约束、测试期望、“完成”意味着什么。持续多轮，直到没有未解决的问题会改变计划。
4. 将规范写入 状态文件并以几行展示给用户。低风险可逆的细节成为明确的假设而不是更多问题。

第 2 阶段 —— 决定是否拆分，然后分解

拆分只有在有 ≥2 个可以独立推进的实质性部分时才有效。如果工作很小或紧密耦合，请这样说并在本次会话中完成它——一个造成合并冲突和交接开销的拆分比不拆分更糟糕。

任务的规则：

• 不相交的文件所有权。 每个任务列出其拥有的路径。两个工作者永远不会编辑同一个文件；这是保持最终合并干净的关键。共享文件（锁定文件、根配置、路由表、依赖注入注册）属于一个任务或由协调器负责。
• 契约先行。 如果部分依赖于共享接口（API 模式、类型、数据库模式），将其设为任务 T0，由你在本次会话中完成并在第 1 波之前提交到基础分支，这样每个工作树都从它开始。用户批准的计划必须说明此提交将会发生。
• 每个任务都有：id、title、目标、owns、可交付物、可验证的完成标准（命令或测试）、depends_on、规模 S/M/L，以及可选的用于机械工作的更便宜的 model。
• 波次。 按依赖关系分组。默认每波 ≤4 个并行会话（速率限制和你自己的审查能力）。一个恰好有一个依赖关系的任务从该依赖关系的分支开始（source_branch）。一个有多个依赖关系的任务需要先将它们合并——这需要用户明确同意（第 6 阶段规则），所以优先选择避免这种情况的计划。
• 集成和最终验证始终由协调器负责。

第 3 阶段 —— 展示计划，获得一次确认

1. 渲染仪表盘（所有任务 planned，阶段 plan）——参见下面的仪表盘。
2. 在它下面，用文字描述：波次、每个会话做什么、它拥有哪些路径，以及你将提交的任何内容（T0）。
3. 问一个 AskUserQuestion：“根据此计划启动 N 个会话？” → 选项 “启动（推荐）” / “更改计划”。用户的“是”是启动这些会话的请求。

在“是”之后，无需进一步批准运行到底除非：合并分支、任何破坏性操作、推送/PR，以及规范无法回答的问题。

第 4 阶段 —— 启动一波

1. 调用 mark_chapter（例如“第 1 波：启动会话”）。
2. 对于每个任务：写一个粗体标题行和一个句子描述会话将做什么，然后调用 start_session 并设置：
   • initiation: "user_asked"，context: "fresh"，use_worktree: true，wake_when_done: true
   • title，name（t1-api 风格，≤24 个字符），branch_name（orch-t1-api）
   • prompt：从 references/worker-brief.md 构建的工作者简报
   • background（≥80 个字符）：目标、关键规范要点、此部分如何与其他部分配合
   • source_branch：对于单依赖任务，依赖关系的分支
   • model：仅当任务是机械性的并且更便宜的模型合适时
3. 将 session_id（local_…）、name、分支存储在状态文件中；状态 running；记录日志； 重新渲染仪表盘。
4. 结束你的回合。 不要轮询——当工作者完成一个回合时，应用程序会通过 <side-sessions-event> 消息唤醒你。

第 5 阶段 —— 监督

每次唤醒（<side-sessions-event>、跨会话消息或用户询问状态）时：

1. 为每个工作者的状态调用 list_sessions {"linked": true}。
2. 从其报告中读取每个工作者的状态行。工作者以 [T2] DONE 100% — …，[T2] IN_PROGRESS 60% — … 或 [T2] BLOCKED — <问题> 开头。
3. 验证，不要轻信。 报告是一种声明。对于 DONE：git log --oneline <base>..<branch> 和 git diff --stat <base>...<branch>；标记在 owns 之外更改的文件；检查完成标准 （向工作者询问测试输出，或在自己的工作树内运行廉价的检查）。
4. 阻塞： 如果规范回答了它，使用 SendMessage 回复到工作者的 local_… id。如果没有，向用户询问并转发他们的确切话语。永远不要要求工作者做在本会话中被拒绝或会被阻塞的事情。
5. 返工： 通过 SendMessage 发送具体问题；状态 rework。
6. 停滞（空闲，无状态行）：询问一次状态行。
7. 当有变化时才更新状态文件并重新渲染仪表盘。
8. 当一波的所有依赖关系都是 done 并经过验证时，启动下一波（已经批准）。

当用户要求时，要实时查看仍在运行的会话，mcp__ccd_session_mgmt__list_events 会显示其最新活动；不要例行公事地这样做。进度百分比仅来自工作者报告或验证过的事实——永远不要编造进度。

第 6 阶段 —— 集成和验证

1. 最终仪表盘（阶段 integrating）。列出每个工作者分支的完整引用（refs/heads/…）。
2. 询问是否将它们合并到当前工作目录中的一个集成分支 orch/<slug> 中。仅在用户自己同意的情况下合并——而不是根据工作者的建议。
3. 按依赖顺序合并，解决冲突，运行完整构建和测试套件。
4. 报告：验收标准表格（已满足 / 未满足 / 未验证并附原因）、带有实际结果的测试结果、剩余风险。阶段 done，最终仪表盘。
5. 提供归档工作者会话的选项（仅在同意后）。未经批准，切勿推送或打开 PR。

---

仪表盘

仪表盘是一个固定模板：assets/dashboard.html。每次对话读取一次（在上下文压缩后再次读取）。在第一次渲染之前，使用参数 modules: ["interactive"] 调用 mcp__visualize__read_me（静默地）。然后调用 mcp__visualize__show_widget 并传入模板内容，其中只有 const STATE = {…}; 这一行被替换为当前状态 JSON（压缩的、有效的 JSON）。保持设计不变——更新之间的一致性让用户可以一目了然地阅读进度。title：orchestration_<slug>_dashboard。

渲染时机：计划之后、每次启动之后、每次有变化的唤醒之后，以及最后。解释放在其旁边的文字中，而不是放在小部件内部。

无会话工具的备用方案

如果 start_session 不可用，则将每个任务作为后台子代理运行：Agent 设置 isolation: "worktree" 和 run_in_background: true，使用相同的简报。完成后通知你；其他所有内容（状态、仪表盘、验证、集成）保持不变，session 字段中使用代理 ID。告诉用户这些工作者无法像会话那样被打开和引导。

基本规则

• 保持协调器轻量：不要在这里实现工作者任务；小的胶水代码和 T0 契约是可以的。
• 遵循用户的全局批准边界（未经批准不推送、部署、破坏性操作或安装）并在每个简报中传递它们。
• 如实报告结果：说明哪些检查运行了，哪些失败了，哪些没有运行。