plan-orchestrate

Plan Orchestrate

將計畫文件銜接到 /orchestrate custom，為每個步驟輸出一個可直接複製貼上的調用指令。本 Skill 僅負責生成，絕不自行執行 /orchestrate。使用者可以在準備就緒後逐行貼上。

啟用時機

• 使用者擁有多步驟計畫文件（PRD、RFC、實作計畫），並希望透過 /orchestrate 來推動執行。
• 使用者提出「orchestrate this plan」、「give me orchestrate prompts for each step」、「compose chains for this plan」（編排此計畫、為每個步驟提供 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 為順序鏈（sequential chain）；每個 Agent 的 HANDOFF 輸出會傳遞給下一個。
• 以逗號分隔的 Agent 列表。建議不要包含空格，但也允許一個空格。
• 不存在 --mode / --gate / --agents=... 等旗標 (flags) — 切勿自行發明。
• Agent 名稱必須來自本 Skill 中的目錄。任務描述中內嵌的雙引號應轉義為 \"。

ECC 安裝形式與命名空間

兩種安裝形式決定了斜線命令（slash command）與每個 Agent 名稱的前綴。兩者必須保持同步 — 每次輸出僅使用一種形式，絕不混用：

假設 <claude-home> 代表 Claude Code 的家目錄：macOS/Linux 上為 ~/.claude，Windows 上為 %USERPROFILE%\.claude。請依照宿主平台解析使用者家目錄的方式進行解析（請勿寫死 ~）。

形式	偵測方式	{ORCH_CMD}	Agent 名稱格式
Plugin 安裝 (2.0.0+)	存在 <claude-home>/plugins/marketplaces/ecc/	/ecc:orchestrate	ecc:<name>
Legacy 獨立安裝	缺少上述目錄；Agent 檔案部位於 <claude-home>/agents/	/orchestrate	<name>

原因說明：在 Plugin 安裝下，Agent 會註冊為 ecc:tdd-guide。使用無前綴名稱會強制進行模糊比對，但在平行調用下偶爾會失敗。在 Legacy 下，前綴形式未被註冊，會直接失敗。

可用 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、資料庫遷移 (migration)、效能優化
• harness-optimizer — 本地 Agent harness 設定
• loop-operator — 長時間執行的自主循環 (autonomous loops)
• chief-of-staff — 多管道分流 (multi-channel triage，極少適用於計畫步驟)

構建錯誤修復類：

• 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 為準 — 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/、自動生成的檔案及明顯的測試測資/fixtures）。若平手或沒有任何語言的原始碼檔案超過 60%，則設定 lang=unknown。
   • 若無標記符合 → 設定 lang=unknown。
   • lang=unknown 是一個哨兵值 (sentinel) — 它不是 Agent 名稱。Phase 2 的規則 4 和 5 會在組合 Agent 鏈時將其轉化為 code-reviewer / build-error-resolver。

4. 偵測 PyTorch 子設定檔 (sub-profile)：當 lang=python 且 pyproject.toml / requirements.txt / uv.lock 中宣告了對 torch 的相依性時，設定 pytorch=true。這僅影響 build 鏈的選擇（參見下方的 Phase 2 規則）；審查者仍為 python-reviewer。

5. 正規化計畫中宣告的任何 Agent 名稱：若計畫內文使用了帶有 Plugin 前綴的形式引用 Agent（例如 ecc:tdd-guide），在驗證或組合鏈之前請剝離前綴以取得純目錄名稱。重新加前綴僅會在輸出階段根據 ECC_MODE 進行（Phase 4）。切勿讓已帶前綴的名稱流入鏈組合程序中 — 否則在 plugin 模式下會導致雙重前綴。

Phase 1 — 拆解步驟

依優先順序識別「步驟單元 (step units)」：

1. 明確編號：## Step N / ### Phase N / ## N. ... / 頂層有序列表。
2. 表格中的「Step」欄位。
3. 由 --- 分隔且標題以動詞開頭的區塊。
4. 否則將每個 H2 視為一個步驟。

每個步驟需擷取 id（從 1 開始）、title（≤ 80 字元）、intent（1–3 句話）、tags。

Phase 2 — 標記標籤並選擇 Agent 鏈

按意圖 (intent) 加上標籤（允許多個標籤；Agent 鏈由主要標籤 + 堆疊的次要標籤建構）：

下方的觸發詞 (Trigger words) 比對不分大小寫。只要語義與列出的英文觸發詞一致，支援比對任何語言中對應的詞幹。

標籤 (Tag)	觸發詞 (Trigger words)	預設 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 會顯式處理特定的多標籤組合；其餘情況則按標籤表格順序追加次要標籤的鏈。
2. impl + security → tdd-guide,<lang>-reviewer,security-reviewer。
3. impl + db → tdd-guide,database-reviewer,<lang>-reviewer。
4. 對生成的 Agent 鏈進行去重（保留首次出現）。例如 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 的步驟需以 reviewer 類別 的 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 和 build resolver）把關，不需要額外的審查者。

Phase 3 — 壓縮任務描述

產出的每個 <task description> 必須：

• 自包含（第一個 Agent 不需要開啟計畫文件）。
• 以 [Plan: <path>#step-<id>] 開頭。
• 包含 1–3 條可驗證的驗收標準 (Acceptance criteria)。
• 僅在計畫為該步驟宣告了範圍防護時包含範圍防護 (Out of scope: ...)。原樣繼承。若計畫中沒有範圍外聲明，完全省略該子句 — 切勿自行編造。
• 長度為 200–600 個字元；單行；內嵌的 " 轉義為 \"；無字面換行符。

Phase 4 — 輸出

使用 ECC_MODE 所決定的格式 輸出 Markdown。輸出全文自始至終使用單一格式 — 每個 {ORCH_CMD} 與每個 Agent 名稱均帶有 Phase 0 所比對出的前綴。請勿同時輸出兩種格式；請勿在渲染出的輸出中包含「這是 plugin 格式」/「請剝離前綴」等說明。

具體渲染規則：

• 在 plugin 模式下，{ORCH_CMD} = /ecc:orchestrate；在 legacy 模式下為 /orchestrate。
• 在 plugin 模式下，{AGENT(name)} = ecc:<name>；在 legacy 模式下為 <name>。
• 總覽表格中的「Chain」欄位使用對應前綴。