plan-orchestrate

Plan Orchestrate

通过为每个步骤生成一条可直接复制粘贴的调用指令，将计划文档接入 /orchestrate custom。本 Skill 仅负责生成——绝不主动执行 /orchestrate。用户准备就绪后自行逐行粘贴执行。

触发条件

• 用户有一份多步骤计划文档（PRD、RFC 或实现方案），希望通过 /orchestrate 来推动执行。
• 用户提出类似“编排这份计划”、“给我每个步骤的 orchestrate 提示词”、“为这个计划组合 Agent 链”的需求。
• 已有分步计划，但用户不想手动为每个步骤挑选 Agent。

跳过场景：

• 单个临时步骤的操作 → 直接调用 /orchestrate custom 即可。
• 计划文档无法读取或为空。仅缺少显式编号不属于跳过条件——详见下文“步骤不明确”的边界情况处理。

入参说明

<plan-doc-path> [--lang=python|typescript|go|rust|cpp|java|kotlin|flutter|auto] [--scope=all|step:<n>|range:<a>-<b>] [--dry-run]

• <plan-doc-path> — 必填；相对路径或绝对路径（支持 @docs/... 格式）。
• --lang — 审查器（reviewer）语言变体；默认为 auto（自动从项目中识别）。
• --scope — 限制生成的步骤范围；默认为 all。
• --dry-run — 仅打印步骤拆解与 Agent 链编排逻辑，不生成最终提示词。

/orchestrate 标准格式（严禁擅自修改）

{ORCH_CMD} custom "<agent1>,<agent2>,...,<agentN>" "<task description>"

其中 {ORCH_CMD} 在 Phase 0 中确定（见下文）。生成输出中的命令字符串必须使用唯一的确定形式——绝对不要混用，也不要留占位符。

• custom 表示串行链式调用；前一个 Agent 的 HANDOFF 输出会直接传给下一个。
• Agent 列表用英文逗号分隔。推荐不加空格；允许带一个空格。
• 不存在 --mode / --gate / --agents=... 等任何 Flag——严禁捏造。
• Agent 名称必须来自本 Skill 内置的目录。任务描述（task description）中嵌有双引号时须转义为 \"。

ECC 安装模式与命名空间

共有两种安装模式，决定了斜杠命令与所有 Agent 名称的前缀。两者必须全程保持同步——单次输出中统一采用对应格式，绝不混用：

假设 <claude-home> 代表 Claude Code 的主目录：macOS/Linux 为 ~/.claude，Windows 为 %USERPROFILE%\.claude。使用宿主平台默认的方式解析用户主目录（切勿硬编码 ~）。

模式	检测依据	{ORCH_CMD}	Agent 名称格式
插件安装（Plugin install, 2.0.0+）	存在 <claude-home>/plugins/marketplaces/ecc/	/ecc:orchestrate	ecc:<name>
传统独立安装（Legacy bare install）	无上述目录；Agent 文件位于 <claude-home>/agents/ 下	/orchestrate	<name>

为什么这很重要：在插件安装模式下，Agent 注册为 ecc:tdd-guide。如果传入裸名称会强制触发模糊匹配，在并行调用时偶尔会失效。而在传统安装模式下，带前缀的形式并未注册，会导致直接报错。

可用 Agent 目录（必须从中选择）

通用类：

• planner — 需求重新表述、风险拆解、步骤规划
• architect — 架构设计、系统设计、重构方案
• tdd-guide — 编写测试 → 编写实现 → 达到 80%+ 覆盖率
• code-reviewer — 通用代码审查
• security-reviewer — 安全审计、OWASP 漏洞、密钥泄露排查
• refactor-cleaner — 死代码清理、重复代码清理、knip 级别代码净化
• doc-updater — 文档更新、代码映射图（codemap）、README 维护
• docs-lookup — 第三方库 API 查询（Context7）
• e2e-runner — 端到端（E2E）测试编排
• database-reviewer — PostgreSQL Schema、数据库迁移、性能优化
• harness-optimizer — 本地 Agent 测试 Harness 配置
• loop-operator — 长时间运行的自主循环任务
• chief-of-staff — 多渠道分发与任务分流（极少适用于计划步骤）

构建报错修复类：

• build-error-resolver（通用） / cpp-build-resolver / go-build-resolver / java-build-resolver / kotlin-build-resolver / rust-build-resolver / pytorch-build-resolver

代码审查类：

• python-reviewer / typescript-reviewer / go-reviewer / rust-reviewer / cpp-reviewer / java-reviewer / kotlin-reviewer / flutter-reviewer

拼错 Agent 名称会导致 /orchestrate 执行失败。生成指令前请务必仔细核对本列表。

执行流程

Phase 0 — 检测 ECC 模式与项目语言

1. 读取 <plan-doc-path>。若文件不存在或内容为空，直接报告错误并终止。

2. 检测 ECC 安装模式并冻结到 ECC_MODE 变量中。判定算法（按顺序执行，首次匹配即止）：

   1. 若存在 <claude-home>/plugins/marketplaces/ecc/ → ECC_MODE=plugin。
   2. 否则若存在 <claude-home>/agents/ 且包含至少一个 ECC Agent 文件（例如 tdd-guide.md、code-reviewer.md）→ ECC_MODE=legacy。
   3. 否则 → 默认回退至 ECC_MODE=legacy，并在输出最顶部打印一行警告：> Warning: could not detect ECC install; defaulting to legacy form. If you use the plugin install, edit the prefixes manually.
   4. 若两个标志位同时存在（混合安装），优先判定为 plugin——因为只有插件命名空间才能在无需模糊匹配的情况下准确解析 Agent 名称。

   从此时起，生成的每一行指令在斜杠命令与所有 Agent 名称上均统一使用对应的前缀。绝不要在同一份输出中混用两种格式。

3. 解析 --lang 参数。当为 auto 时，进行多语言感知检测：

   • 特征文件探查：pyproject.toml / uv.lock / requirements.txt → python；package.json → typescript；go.mod → go；Cargo.toml → rust；CMakeLists.txt 或顶层 *.cpp → cpp；pom.xml / build.gradle (Java) → java；build.gradle.kts 或顶层 Kotlin 文件 → kotlin；pubspec.yaml → flutter。
   • 多语言平局裁决（Polyglot tie-break）：若匹配到多个特征文件，选择源码文件数量最多的语言（通过 git ls-files 统计，排除 vendor/、node_modules/、dist/、build/、.venv/、生成文件及明显的测试 Fixture）。若出现平局或没有任何语言的源码占比超过 60%，则将 lang 设为 unknown。
   • 未匹配到任何特征文件 → 将 lang 设为 unknown。
   • lang=unknown 是一个标记值（sentinel）——它不是 Agent 名称。在 Phase 2 的规则 4 和 5 中，它会在组装 Agent 链时转换为 code-reviewer / build-error-resolver。

4. 检测 PyTorch 子配置：当 lang=python 且 pyproject.toml / requirements.txt / uv.lock 中声明了 torch 依赖时，设置 pytorch=true。这仅影响 build 链的选取（见下文 Phase 2 规则）；审查器依然维持 python-reviewer。

5. 规范化计划中声明的 Agent 名称：若计划文本中以插件前缀形式引用了 Agent（如 ecc:tdd-guide），在校验或组装链之前必须先剥离前缀，还原为裸目录名称。重新添加前缀的操作仅在 Phase 4 输出阶段根据 ECC_MODE 统一处理。绝不能让已带前缀的名称直接流向链组装步骤——否则在插件模式下会导致双重前缀（double-prefixing）。

Phase 1 — 拆解步骤

按优先顺序识别“步骤单元”：

1. 显式编号：## Step N / ### Phase N / ## N. ... / 顶层有序列表。
2. 表格中的“Step”或“步骤”列。
3. 由 --- 分割且带有动词开头的标题块。
4. 否则将每个二级标题（H2）视为一个步骤。

为每个步骤提取 id（从 1 开始）、title（≤ 80 字符）、intent（1–3 句话）、tags。

Phase 2 — 打标签与挑选 Agent 链

根据意图打标签（允许打多个标签；Agent 链由主标签 + 堆叠的次要标签共同构建）：

匹配下述触发词时忽略大小写。只要语义与列表中的英文触发词一致，跨语言计划同样支持通过词干匹配。

标签	触发词	默认 Agent 链
design	architecture, design, choose, evaluate, RFC	planner,architect
plan	plan, breakdown, milestone	planner
impl	implement, build, add, create, port	tdd-guide,<lang>-reviewer
test	test, coverage, e2e, integration	tdd-guide,e2e-runner
refactor	refactor, cleanup, dedupe, split	architect,refactor-cleaner,<lang>-reviewer
migration	migrate, upgrade, rewrite, port	architect,tdd-guide,<lang>-reviewer
db	schema, migration, index, SQL, Postgres, alembic, sqlmodel	database-reviewer,<lang>-reviewer
security	encrypt, auth, secret, OWASP, PII	security-reviewer,<lang>-reviewer
build	build, compile, lint failure, CI	<lang>-build-resolver（回退至 build-error-resolver）
docs	docs, readme, codemap, changelog	doc-updater
lookup	lookup, reference, API usage	docs-lookup
review	review, audit, verify	<lang>-reviewer,code-reviewer
loop	loop, autonomous, watchdog	loop-operator

Agent 链组合规则：

1. 主标签选择：当一个步骤匹配多个标签时，表格顺序中排在最前面的标签（表格顶部 = 最高优先级）作为主标签，其余为次要标签。下述规则 2 和 3 明确处理特定的多标签组合；其他情况则按标签表格顺序追加次要 Agent 链。
2. impl + security → tdd-guide,<lang>-reviewer,security-reviewer。
3. impl + db → tdd-guide,database-reviewer,<lang>-reviewer。
4. 对最终生成的链进行去重（保留首次出现的位置）。例如 review + lang=unknown 在规则 5 处理前会产生 code-reviewer,code-reviewer，去重后收拢为 code-reviewer。
5. 当 lang=unknown 时，<lang>-reviewer 解析为 code-reviewer。
6. 当 lang=unknown 时，<lang>-build-resolver 解析为 build-error-resolver。特例情况：若 Phase 0 将 pytorch=true，无论 <lang> 为何值，build 链均使用 pytorch-build-resolver。不存在 python-build-resolver；未设置 pytorch=true 的 --lang=python 会直接解析为 build-error-resolver。
7. 无标签步骤：若未匹配到任何触发词，将 Agent 链设为 code-reviewer，并在“Chain rationale（选链依据）”中注明 no tag matched; default review-only chain（未匹配到标签，默认仅审查）。
8. 去重后的 Agent 链长度必须 ≤ 4。若超长，按优先级舍弃最弱的标签（优先舍弃 lookup 和 docs）。
9. 不要在 impl 链中同时搭配 planner 和 architect（浪费 Token）。仅在 design 步骤中才将两者配对。
10. 打有 impl、refactor 或 migration 标签的步骤，尾部必须以审查类 Agent 结尾——即 <lang>-reviewer、code-reviewer、security-reviewer 或 database-reviewer 中的任意一个。最针对特定领域的审查器占领末位（例如规则 2 的 impl+security 尾部为 security-reviewer；规则 3 的 impl+db 尾部为 <lang>-reviewer，因为 database-reviewer 已经在链的前面卡点了迁移逻辑）。test 和 build 步骤由它们自带的验证器（分别为 e2e-runner 和构建修复器）卡关，不需要额外的审查器。

Phase 3 — 精简任务描述

生成的每个 <task description> 必须满足：

• 具备独立完备性（首个 Agent 无需打开计划文档）。
• 以 [Plan: <path>#step-<id>] 开头。
• 包含 1–3 条可验证的验收标准（Acceptance criteria）。
• 仅在计划明确为该步骤声明了范围边界时，才包含 Scope guard（如 Out of scope: ...）。原样继承计划原文。若计划中没有写排除范围，切勿自行捏造，直接省略该子句。
• 长度控制在 200–600 个字符；单行输出；内嵌的双引号 " 转义为 \"；不得包含硬换行符。

Phase 4 — 输出

根据 ECC_MODE 确定的格式生成 Markdown。整体输出在格式上保持高度一致——每一个 {ORCH_CMD} 和 Agent 名称都带有 Phase 0 计算出的对应前缀。切勿同时输出两种格式；也不要在生成的渲染文本中包含“这是插件格式” / “请自行剥离前缀”等提示说明。

具体渲染规则：

• 在 plugin 模式下 {ORCH_CMD} = /ecc:orchestrate，在 legacy 模式下为 /orchestrate。
• 在 plugin 模式下 {AGENT(name)} = ecc:<name>，在 legacy 模式下为 <name>。
• 概览表格中的“Chain”列使用对应前缀。