Orchestrate Skill（v1 report-only）

宣告式意圖 → planner agent 推導隨 repo 狀態變動的 workflow 計畫 → 預覽人核 → read-only fanout → pre/post 無變更驗證 → 報告走既有 doc review loop。Control plane（.claude_workflows/）是 orchestrator 唯一的狀態面；review 提醒狀態自 hook-lightweighting § 3.2 起存於 repo 外（~/.cache/sd0x-dev-flow/），orchestrator 不讀不寫。

Trigger

• Keywords: orchestrate, workflow orchestration, 編排, plan this workflow, audit the repo for, 自動編排

When NOT to Use

• 執行會改檔的步驟（v1 一律輸出為 proposed-manual，交人走正常流程）
• 單一 skill 就能完成的任務（直接呼叫該 skill）
• Code review（/codex-review-fast）、doc review（/codex-review-doc）
• 既有固定形狀的深度探索（/deep-explore）或研究（/deep-research）——orchestrate 是跨 skill 的編排層，不取代它們

Flags

Flag	行為
（無）/ --dry-run	規劃 + 預覽即止（plan preview = 預設交付物）
--execute	預覽 + AskUserQuestion 核可後執行 read-only fanout → verify → 報告
--budget S|M|L	Budget tier（default M）；超量 fail-closed，見 scripts/plan-context.js
（內部）plan-context.js --out	封包一律寫檔、只回摘要（含 sha256）；主 session 不得持有完整封包（~81 KB × 2 → ~0.5 KB），見 references/planner-prompt.md
--resume <run-id>	以原 baseline compare：無 drift → 續跑 pending 步驟；有 drift → run 標 needs_human 並停（不得重拍 baseline 洗白；要繼續只能開新 run = 新 baseline + 新核可）。baseline 本體留在 .claude_workflows/<run-id>/baseline.json，跨 session 仍在；但 baseline_sha256 只活在主 session 的 context，run-state 刻意不存它（存在 baseline 旁邊等於沒綁定）。因此 resume 的實際限制是 digest 而非檔案：脈絡遺失／換 session → 不可 resume，開新 run
--backend dw|agent	強制 fanout 後端；預設 auto（Workflow 工具可用則用，否則 background Agent ≤3 並行）——admission 同一套

Workflow

sequenceDiagram
    participant U as User
    participant C as Claude（主 session）
    participant S as scripts
    participant P as Planner（Explore，admission 約束）
    participant W as Fanout workers（read-only）
    U->>C: /orchestrate "意圖" --execute
    C->>S: plan-context.js --out（封包寫檔，主 session 只收摘要）
    C->>S: run-verify.js snapshot > .claude_workflows/<run-id>/baseline.json（digest 由 stderr 收進 session）
    C->>P: 背景派發 planner（傳封包路徑，非內容）
    P->>P: Read 封包
    P-->>C: plan JSON
    C->>S: run-verify.js compare --baseline-sha256（planning 後立即驗）
    C->>S: validate-plan.js --context-sha256 <摘要 sha256>（admission + gate lint + 封包完整性）
    C->>U: Plan preview + AskUserQuestion
    U-->>C: 核可
    C->>C: Write run-state（redact 先行）
    loop 每個 parallel_group（≤ max_waves）
        C->>W: 平行派發（單訊息）
        W-->>C: findings（context packet）
    end
    C->>S: run-verify.js compare --baseline-sha256（同一 baseline，同一 digest）
    alt drift
        C->>U: ⚠️ Need Human（run 標 failed，不寫報告）
    else 無變更
        C->>C: Write 報告 → /codex-review-doc 接手
    end

Baseline 時序不變量（hard rule）

run-verify.js snapshot 必須先於任何 agent 派發（含 planner）——否則 planner 期間的 mutation 會被併入 baseline，report-only 證明失效。snapshot 的 stdout（baseline 本體）一律導向 .claude_workflows/<run-id>/baseline.json，兩次 compare 都以 --baseline <該路徑> 讀取；主 session 不留 baseline 內容（它含全樹 content hash，逐字帶在 context 裡既昂貴又會被 compact 丟掉）。digest 走另一條路：只存在主 session 的 context，絕不寫進 .claude_workflows/。這個「本體落在磁碟、digest 留在 session」的拆法正是綁定本身——baseline 檔案對 worker 沒有價值，因為它偽造不出主 session 手上的 digest；把 digest 存到 baseline 旁邊則等於沒綁定。planner 與 fanout worker 受同一 admission allowlist 約束（planner = Explore，名單內唯一具研究能力者）。planning 結束、preview 之前先 compare 一次（早期攔截）；execute 結束後以同一 baseline 再 compare 一次（最終攔截）。

兩次 compare 都必須帶 --baseline-sha256，值取自 snapshot 印在 stderr 的 baseline_sha256=…。沒有這個綁定，compare 證明的只是「我拿到的這份檔案與 repo 相符」——而 worker 在改動後重跑一次 snapshot 就能造出這樣一份檔案，drift 於是讀成 ok: true。digest 由主 session 在任何派發之前取得、也由主 session 傳回，worker 全程碰不到，因此能擋住 worker 平面的替換；它擋不住已被接管的主 session——該層沒有任何機制能擋，因為兩個參數都由它決定。與 validate-plan.js --context-sha256 同一條信任鏈。

Admission（deny-by-default）

Fanout 候選一律比對 references/admission-allowlist.json（v1 僅 Explore + performance-optimizer；coverage-analyst / git-investigator 為明確排除，理由見檔內）。不在名單 = 拒絕，不論其 allowed-tools 宣告——allowed-tools 不可信任為 read-only 判據。名單變更必過 review + 重審 run-verify.js 驗證面涵蓋性。

Report-only 強制機制（非能力層阻擋，盡力而為的 fail-closed 縱深）：report-only 不依賴能力層阻擋 Skill 工具——兩條看似可行的能力路徑都不適用。v1 的 report-only 是 admission allowlist（只收 curated 唯讀導向 worker）、驗證層 drift 偵測、行為層契約 三者的盡力而為 fail-closed 組合，非對抗 admitted Bash-capable worker 的絕對保證——admitted Explore 具 Bash，可觸發下表驗證層列所載的殘餘 bypass（如 assume-unchanged index 隱藏），故 v1 report-only 的強度實際倚賴 admission 名單的 curation，殘餘 bypass 明確 defer v2（見下表與段末）：

層	機制	保證	限制／原因
能力層	省略 allowed-tools 中的 Skill	無硬阻擋	依 Claude Code，allowed-tools 僅為預先核可清單；未列的工具仍可在使用者一般權限下被呼叫
能力層	disallowed-tools: Skill	硬阻擋，但刻意不用	依 Claude Code 現行行為，持續到下一則使用者訊息才解除；會連帶封殺同一輪的 /codex-review-doc 交接（同走 Skill 工具），令 run 永遠無法抵達 Mergeable/done
驗證層	run-verify.js 的 snapshot／compare 原語（SC-2）	對 git 監測面（porcelain + tracked／untracked／ignored 內容 hash + tracked mode + untracked／ignored 目錄節點 + refs／config／worktree／stash）的 repo 狀態變更提供 fail-closed drift 證據（drift → exit 1）	非 hard sequencing guarantee：呼叫順序、run-state 轉移、報告抑制由 SKILL.md 派發流程與 references/execution-policy.md 行為契約負責；且有殘餘風險（node_modules/、.venv/、build/、dist/、repo 外寫入、assume-unchanged／skip-worktree index 隱藏等，見 admission-allowlist.json 的 residual_risk）；.claude_workflows/ 控制面為 by-design 排除（orchestrator 自身寫 run-state，非監測面）
行為層	planner／executor 契約	v1 不執行 main-skill	mutating 構想一律轉 kind: proposed-manual（mutating: true）；非 mutating main-skill 仍為 kind: main-skill 受 validate-plan.js A4 target 驗證，但 v1 executor 不派發

派發順序上，run-verify.js snapshot 於任何 agent 派發之前取 baseline，execute 後以同一 baseline compare；落在受監測 git-scoped 面的任何 drift → run 標 failed、不寫報告（見 references/execution-policy.md fail-closed 矩陣）。v2 若要開放 main-skill 執行，前提是 skill_candidates 帶 mutation flag 讓 mutating 目標在 A4 先被拒 + reviewed read-only allowlist（見 validate-plan.js A4 註解），而非解除任何 Skill 能力阻擋。

Run-state 管理

規則	內容
路徑	.claude_workflows/<run-id>.json（gitignored；run-id = <UTC yyyymmdd-HHMMSS>-<intent-slug>）
寫入工具	主 session Write（gitignored 路徑，不進 review 平面）
Redaction	寫入磁碟前過 scripts/security-redact.js 完整 contract：scanHighConfidence truthy → abort fail-closed（不寫檔、run 標 needs_human、提示改寫意圖）；medium → mask 後寫入
FIFO	保留最近 10 個 run，超過刪最舊。兩者一起算、一起刪：<run-id>.json（run-state）與同名的 <run-id>/ 目錄（封包 + plan + baseline）。只清 .json 會讓 plan-context.json（~81 KB／run）無限累積在 gitignored 目錄裡；封包已含完整 catalog 與 repo signals，過期後留著只是垃圾與洩漏面。執行方式（規範路徑，非能力邊界：本 skill 未預先核可 Bash(rm:*)，但預先核可的 Bash(node:*) 同樣涵蓋 node -e 'fs.rmSync(…)'，沒有機制強制刪除走這支腳本；containment 只在走這條路時成立）：node "${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/scripts/prune-runs.js"（先跑 --dry-run 看清單）。路徑必須是 plugin root 絕對路徑，與本 skill 呼叫 plan-context.js／validate-plan.js 的形式一致：skill 執行時的 cwd 是目標 repo，不是 plugin 目錄，所以 repo 相對路徑只在本 repo 內開發時碰巧可用，部署到任何其他專案都是 MODULE_NOT_FOUND——retention 於是從未執行，而 .claude_workflows/ 以每 run ~81 KB 持續累積，正好是這支腳本要擋的洩漏。腳本自行從目錄讀取 run-id、拒絕非 .claude_workflows 的 root 與 symlink、認不得的檔名一律保留並回報
封包提前刪除（建議）	validate-plan.js 通過、plan 進入執行後，<run-id>/plan-context.json 已無用途——可立即刪除，只留 <run-id>/plan.json 供事後稽核。digest 已在驗證當下比對完畢，事後保留封包不會增加任何保證
終態	done 的唯一路徑 = 報告之 doc review 回 Mergeable gate；回 blocked / degraded / 無法判定 → needs_human（不得呈現為完成）

輸出隔離契約

/orchestrate 自身輸出禁止出現 gate sentinels（gate 標頭行、bare Ready / Mergeable / Blocked / All-Pass 記號）——這些是行為層信號，模型與 reviewer 讀對話時會把它們當成 gate verdict，orchestrate 的總結不得偽造一個沒有 gate 產出的 verdict。run 總結使用 ## Orchestrate Run Summary + [ORCHESTRATE_RUN] run_id=… status=… 結構行。報告寫入後的 doc gate sentinel 由 /codex-review-doc 自己輸出（合法路徑）。

Verification Checklist

• snapshot 先於任何 agent 派發，且 stdout 導向 .claude_workflows/<run-id>/baseline.json；planning 後 + execute 後各 compare 一次（同一 baseline 檔）
• baseline_sha256 只留在主 session context，未寫入 .claude_workflows/ 任何檔案
• 兩次 compare 都帶 --baseline-sha256（值取自 snapshot stderr 的 baseline_sha256=）；未帶或不符會 exit 1
• 計畫經 validate-plan.js 全規則通過（A1-A4 / G1-G2 / O1 / B1 / S1 / SCHEMA）
• validate-plan.js 帶入 --context-sha256（值取自 plan-context.js --out 摘要的 sha256）；未帶 digest 一律 exit 1，--context -（stdin）也不例外——綁定的是 digest 走過 worker 碰不到的通道，不是 bytes 從哪個 fd 進來
• 執行前經 AskUserQuestion 人核
• run 終態正確：drift → failed；doc gate 未過 → needs_human；Mergeable → done
• 無任何 git 狀態變更操作（add / commit / push / stash / tag / config / checkout / reset 等——allowed-tools 僅開放唯讀 git 指令，mutation 由 run-verify.js compare 兜底）

Bundled References

File	Purpose
planner-prompt.md	Planner 獨立推導契約（不餵 Claude 預擬步驟）
plan-schema.md	Plan JSON schema 正典（含 lint 規則對照）
execution-policy.md	Backend 選擇、波次、fail-closed 矩陣
admission-allowlist.json	Fanout allowlist（curated + 排除記錄）

Examples

Input: /orchestrate "audit 全 repo hook 的 fail-open 路徑" --execute
Action: context → snapshot → planner → lint → preview → 核可 → 3× Explore fanout → compare → 報告 → doc review

Input: /orchestrate "完成 feature X 並確保品質"
Action: 規劃 + 預覽即止——mutating 步驟以 proposed-manual 列出（含 code-review + precommit gate），交人走正常流程