orchestrate

# Multi-Agent Orchestrate v3.4.0 ## 路徑解析（必讀） 此 Skill 使用共用工具。執行時必須先解析資源根目錄，再使用完整路徑。 **從 command-message header 取得 Base directory**，例如： ``` Base directory for this skill: /path/to/.../skills/orchestrate ``` 支援兩種安裝形態： - Plugin install：repo-level `shared/` 位於 plugin root。 - `npx skills add`：generated `_shared/`、`_scripts/` 位於本 skill 目錄內。 ```bash if [ -d "$BASE_DIR/_shared" ]; then SHARED_DIR="$BASE_DIR/_shared" SCRIPTS_DIR="$BASE_DIR/_scripts" else PLUGIN_ROOT="${BASE_DIR%/skills/orchestrate}" SHARED_DIR="$PLUGIN_ROOT/shared" SCRIPTS_DIR="$PLUGIN_ROOT/scripts" fi "$SHARED_DIR/tools/workflow-init.sh" init "$WORKFLOW_ID" orchestrate "需求摘要" ``` **重要**：不要使用 `./shared/tools/...`，因為工作目錄是用戶專案，不是 skill/plugin 目錄。 --- ## 前置檢查（重要） 在開始工作流之前，檢查專案是否已配置規範執行機制： ```bash # 檢查 settings.local.json 是否包含必要的 hooks cat .claude/settings.local.json 2>/dev/null | grep -q "PostToolUse" && echo "✓ Hooks configured" || echo "✗ Hooks not configured" ``` **如果 Hooks 未配置**，顯示以下提示： ``` ⚠️ 專案尚未配置 workflow 規範執行機制。 建議執行 `/setup-workflow` 啟用以下功能： • Task 完成後自動 commit（保存進度） • 自動運行測試驗證 • Memory 變更追蹤 執行 `/setup-workflow` 一鍵完成配置。 ``` **如果用戶選擇繼續**：可以繼續執行，但不會有自動 commit 和驗證功能。 --- > 需求輸入 → 6 階段串聯 → 品質閘門 → 智慧回退 → 完成交付 ## 使用方式 ```bash /orchestrate [需求描述] /orchestrate 建立用戶認證系統，支援 JWT 和 OAuth2 ``` **Flags**: - `--profile <mode>` - 執行模式：`default`（預設）| `express`（快速）| `quality`（最高品質） - `--start-from STAGE` - 從指定階段開始 - `--skip STAGE` - 跳過指定階段 - `--quick` - 快速模式（等同 `--profile express`） - `--deep` - 深度模式（等同 `--profile quality`） ## 工作流階段 ``` RESEARCH → PLAN → TASKS → IMPLEMENT → REVIEW → VERIFY ↑__________↓ 智慧回退機制 ``` | 階段 | 輸入 | 輸出 | 閘門分數 | |------|------|------|----------| | RESEARCH | 需求 | synthesis.md | ≥70 | | PLAN | 研究報告 | implementation-plan.md | ≥75 | | TASKS | 實作計劃 | tasks.yaml | ≥80 | | IMPLEMENT | 任務清單 | 程式碼 | ≥80 | | REVIEW | 程式碼 | review-summary.md | ≥75 | | VERIFY | 審查報告 | 驗證結果 | ≥85 | ## 執行流程 ``` Phase 0: 初始化工作流 ├── 生成 workflow-id ├── **【必要】執行 workflow-init.sh 初始化通訊環境** │ └── Bash: "$SHARED_DIR/tools/workflow-init.sh" init <workflow-id> orchestrate "<需求摘要>" │ └── 這會創建 .claude/workflow/current.json（Hooks 依賴此檔案） ├── 載入執行模式配置 │ └── 讀取 $SHARED_DIR/config/execution-profiles.yaml │ └── 套用視角數和模型配置 ├── 建立報告目錄 └── 記錄開始時間 ↓ For each stage in [RESEARCH, PLAN, TASKS, IMPLEMENT, REVIEW, VERIFY]: ↓ Phase 1: 執行階段 ├── 呼叫對應 skill └── 等待完成 ↓ Phase 2: 早期終止檢查 ├── 滿足條件？→ 可跳過後續步驟 └── 不滿足 → 繼續 ↓ Phase 3: 品質閘門 ├── 通過 → 下一階段 └── 失敗 → 智慧回退 ↓ End for ↓ Phase 4: 完成 ├── 生成報告 ├── CT 閉環檢查（Self-Dogfood） │ ├── 檢查各階段 ct_detection / quality gate / action log │ ├── 產生 ct-retrospective.md │ ├── 必要時產生 self-upgrade-proposal.md │ └── 安全時執行 autonomous upgrade decision ├── 產生 closed-loop-summary.md 收斂成果 ├── 更新 Memory └── 驗證變更已 commit（見下方 Fallback） ``` ## CT 閉環（Self-Dogfood） `/orchestrate` 完成 VERIFY 後必須吃自己的狗食，檢查工作流本身是否需要升級。 輸出位置： ```text .claude/memory/workflows/{workflow-id}/ct-retrospective.md .claude/memory/workflows/{workflow-id}/self-upgrade-proposal.md # 有改善建議時 .claude/memory/workflows/{workflow-id}/upgrade-decision.yaml .claude/memory/workflows/{workflow-id}/upgrade-report.md # 有實際 patch 時 .claude/memory/workflows/{workflow-id}/closed-loop-summary.md ``` 檢查項目： - `ct_mode` 是否選對：是否過度升級或低估風險 - 必要 artifact 是否存在：strict / experiment 的 CT 產物是否齊全 - quality gates 是否有 false positive / false negative - workflow tools 是否失敗：health、status、DAG、metrics、action log - failure 是否應回寫為 regression case - 最終成果是否已收斂成單一 summary，包含結論、升級決策與驗證結果 自動化等級： | Level | 行為 | |---|---| | L1 | 只記錄 `ct-retrospective.md` | | L2 | 產生 `self-upgrade-proposal.md` | | L3 | 低風險 docs / templates / CT examples 可自動 patch | | L4 | router / gates / scripts 可 patch，但必須附測試 | | L5 | 架構級變更只提出 proposal，需人工批准 | → 規範：[shared/ct/retrospective.md](_shared/ct/retrospective.md) → 自主升級：[shared/ct/autonomous-upgrade.md](_shared/ct/autonomous-upgrade.md) → Policy：[shared/ct/self-upgrade-policy.yaml](_shared/ct/self-upgrade-policy.yaml) ### Phase 4 Fallback：手動 Commit 如果自動 checkpoint commit 沒有觸發（例如 hooks 未配置），手動執行： ```bash # 檢查是否有未 commit 的變更 git status # 如果有變更，手動 commit git add -A git commit -m "chore(workflow): complete {workflow-id}" ``` **自動 Commit 觸發時機**： - 寫入 `synthesis.md` → RESEARCH 完成 - 寫入 `implementation-plan.md` → PLAN 完成 - 寫入 `tasks.yaml` → TASKS 完成 - 寫入 `summary.md` → IMPLEMENT 完成 - 寫入 `review-summary.md` → REVIEW 完成 - 寫入 `verify-summary.md` → VERIFY 完成 ## 智慧回退機制 根據迭代次數決定回退目標： | 迭代 | 回退目標 | 原因 | |------|----------|------| | 1-2 | IMPLEMENT | 可能是實作問題 | | 3 | TASKS | 可能是任務分解問題 | | 4 | PLAN | 可能是設計問題 | | 5+ | HUMAN | 超過自動修復能力 | **循環偵測**： - 相同錯誤兩次 → 升級回退層級 - 階段間振盪 → 暫停分析根因 - 總迭代 > 10 → 強制停止 → 配置：[shared/quality/rollback-strategy.yaml](_shared/quality/rollback-strategy.yaml) ## 部分完成處理（Partial Completion） 當工作流中斷或某階段失敗時，自動保存進度以便恢復。 ### 自動保存進度 每個階段完成後立即保存進度到 `.claude/workflow/{id}/recovery/progress.yaml`： ```yaml workflow_id: "orchestrate_20260206_123456_abc123" status: "interrupted" # completed | interrupted | failed current_stage: "IMPLEMENT" completed_stages: - stage: RESEARCH output: ".claude/memory/research/{topic-id}/synthesis.md" score: 82 timestamp: "2026-02-06T12:35:00Z" - stage: PLAN output: ".claude/memory/plans/{feature-id}/implementation-plan.md" score: 78 timestamp: "2026-02-06T12:40:00Z" - stage: TASKS output: ".claude/memory/tasks/{plan-id}/tasks.yaml" score: 85 timestamp: "2026-02-06T12:45:00Z" failed_stage: stage: IMPLEMENT error: "Tests failed after 3 retries" last_checkpoint: "task-3-of-8" timestamp: "2026-02-06T13:00:00Z" ``` ### 恢復執行 ```bash /orchestrate --resume {workflow-id} # 或 /orchestrate --resume # 自動找到最近中斷的工作流 ``` 恢復流程： 1. 讀取 `progress.yaml` 確認中斷點 2. 驗證已完成階段的輸出仍然有效（檔案存在 + git status 乾淨） 3. 從中斷的階段/任務繼續執行 4. 如果已完成階段的輸出被破壞，回退到該階段重新執行 ### 部分完成的通知 中斷時輸出： ``` ⚠️ 工作流部分完成 (3/6 階段) ✅ RESEARCH → PLAN → TASKS ❌ IMPLEMENT（失敗：Tests failed after 3 retries） ⏸️ REVIEW → VERIFY（未執行） 進度已保存至：.claude/workflow/{id}/recovery/progress.yaml 恢復命令：/orchestrate --resume {id} ``` ### 與智慧回退的區別 | 情境 | 機制 | 說明 | |------|------|------| | 品質閘門失敗 | 智慧回退 | 自動回退到適當階段重試（最多 5 次） | | 回退次數超限 | 部分完成 | 保存進度，等待人工介入後 `--resume` | | Context Limit | 部分完成 | 保存進度，新 session 中 `--resume` | | 外部錯誤（網路/權限） | 部分完成 | 保存進度，修復問題後 `--resume` | | Session 崩潰 | 部分完成 | 依賴 git checkpoint，`--resume` 從最後 commit 恢復 | ## 早期終止 | 階段 | 條件 | 動作 | |------|------|------| | RESEARCH | consensus ≥ 0.9 | 跳過衝突解決 | | PLAN | risk < 0.2 | 快速模式 | | REVIEW | 無 BLOCKER/HIGH | 直接通過 | | VERIFY | pass_rate ≥ 0.98 | 可發布 | → 配置：[shared/config/early-termination.yaml](_shared/config/early-termination.yaml) ## 報告生成 完成後自動生成： - `dashboard.md` - 總覽 - `timeline.md` - 時間線 - `quality-report.md` - 品質報告 - `decisions.md` - 決策記錄 → 工具：[shared/tools/generate-report.sh](_shared/tools/generate-report.sh) ## 輸出結構 ``` .claude/memory/workflows/[workflow-id]/ ├── dashboard.md # 總覽報告 ├── timeline.md # 時間線 ├── decisions.md # 決策記錄 ├── quality-report.md # 品質報告 ├── ct-retrospective.md # CT 閉環檢查 ├── self-upgrade-proposal.md # 必要時產生 ├── upgrade-decision.yaml # 自主升級決策 ├── upgrade-report.md # 有實際 patch 時產生 ├── closed-loop-summary.md # 最終成果收斂報告 ├── stages/ # 各階段報告 ├── agents/ # Agent 記錄 └── exports/ # 匯出格式 ``` ## 共用模組 | 模組 | 用途 | |------|------| | [quality/gates.yaml](_shared/quality/gates.yaml) | 品質閘門 | | [quality/rollback-strategy.yaml](_shared/quality/rollback-strategy.yaml) | 智慧回退 | | [config/early-termination.yaml](_shared/config/early-termination.yaml) | 早期終止 | | [config/execution-profiles.yaml](_shared/config/execution-profiles.yaml) | 執行模式 | | [config/context-freshness.yaml](_shared/config/context-freshness.yaml) | 上下文新鮮 | | [tools/generate-report.sh](_shared/tools/generate-report.sh) | 報告生成 | | [tools/workflow-init.sh](_shared/tools/workflow-init.sh) | 工作流初始化 | ## 【重要】初始化步驟 在執行任何階段之前，**必須**先初始化工作流環境： ```bash # 0. 從 command-message header 取得 Base directory，計算 Plugin Root # 例如：Base directory: /path/.../2.4.2/skills/orchestrate # SHARED_DIR 是 repo-level shared 或本 skill 內 generated _shared # 1. 生成 workflow ID（格式：orchestrate_YYYYMMDD_HHMMSS_xxxx） WORKFLOW_ID="orchestrate_$(date +%Y%m%d_%H%M%S)_$(openssl rand -hex 4)" # 2. 執行初始化（創建 current.json，讓 Hooks 能記錄活動） # 使用完整路徑，不要用 ./shared/... "$SHARED_DIR/tools/workflow-init.sh" init "$WORKFLOW_ID" orchestrate "需求摘要" ``` **為什麼這很重要？** - Hooks（log-tool-pre.sh、log-tool-post.sh、log-agent-lifecycle.sh）依賴 `.claude/workflow/current.json` - 如果沒有這個檔案，所有 Agent 活動都不會被記錄 - 這會導致 `/status` 和 statusline 無法顯示正確的工作流狀態 ## File-Based Handoff Protocol（v3.3 核心機制） **解決 Context Limit 的根本方案**：使用檔案系統作為 Agent 間的「外部記憶體」。 → 完整說明：[shared/coordination/file-based-handoff.md](_shared/coordination/file-based-handoff.md) ### 為什麼會 Context Limit？ ``` 傳統方式： Agent A 完成 → 15K tokens 回傳 Orchestrator Agent B 完成 → 15K tokens 回傳 Agent C 完成 → 15K tokens 回傳 Agent D 完成 → 15K tokens 回傳 ───────────────────────────────── 總計：60K+ tokens → 爆炸 💥 ``` ### 新方式 ``` File-Based Handoff： Agent A 完成 → 寫入檔案 → 回傳 "完成，見 path/a.md" (~100 tokens) Agent B 完成 → 寫入檔案 → 回傳 "完成，見 path/b.md" (~100 tokens) ... ───────────────────────────────── Orchestrator 只累積：~400 tokens ✅ 完整結果在：檔案系統 + Git ``` ### 執行規則 1. **大型任務使用背景執行**： ```javascript Task({ description: "複雜任務", prompt: "...結果寫入 {path}，只回覆確認", run_in_background: true // 關鍵！ }) ``` 2. **Agent 輸出到檔案**： - 完整報告 → `.claude/memory/{type}/{id}/result.md` - 回傳給 Orchestrator → 只說「完成，結果在 {path}」 3. **Git Checkpoint**： - 每批任務完成 → `git commit` - 即使 session 崩潰，結果保留 4. **下一階段讀取檔案**： - Orchestrator 告訴下一個 Agent 檔案路徑 - Agent 自己用 Read 讀取 ### Context 使用量對比 | 方式 | 4 個大型 Agent | Orchestrator Context | |------|---------------|---------------------| | 傳統 | 全部回傳 | ~60K tokens（危險）| | File-Based | 只回傳路徑 | ~10K tokens（安全）| ## 智能並行決策（v3.2 新增） 當用戶要求同時執行多個任務時，Orchestrator 會智能決定執行策略。 → 配置：[shared/config/parallel-execution.yaml](_shared/config/parallel-execution.yaml) ### 並行度控制 | 任務複雜度 | 最大並行數 | 判斷依據 | |-----------|-----------|----------| | 簡單 | 4 | 單一模組、< 3 檔案、測試已存在 |