ce-compound

/ce-compound

協調多個子 Agent (subagent) 並行工作，將最近解決的問題記錄成完整的說明文件。

Setup

在本次呼叫開始時、派發任何子 Agent 之前執行此腳本一次，並遵循其輸出的指令——除非該指令與本 Skill 自身關於「向使用者提問」的規則相衝突（無論該規則是僅限於非互動模式或適用於所有模式），此時本 Skill 的規則優先，且不會提出阻斷性的問題。請勿在同一次呼叫中重複執行；若後續呼叫本 Skill 或其他 Skill，將會執行各自的 Setup。若系統未安裝 Node 執行環境，本 Skill 將依原本流程繼續執行。

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
NODE="$(for c in node nodejs; do command -v "$c" >/dev/null 2>&1 && "$c" -e '' >/dev/null 2>&1 && { echo "$c"; break; }; done)";
if [ -n "$NODE" ]; then
"$NODE" "$SKILL_DIR/scripts/context.mjs" || echo "context script failed; continue with the skill's normal behavior";
else
echo "no Node runtime; continue with the skill's normal behavior";
fi

Purpose

趁著記憶與上下文尚新時捕捉問題的解決方案，在 <root>/solutions/ 中建立結構化文件，並附加 YAML frontmatter 以利搜尋與未來參考。本流程會使用多個並行的子 Agent。

為什麼稱為「compound」（複利）？ 每份記錄下來的解決方案都能為你的團隊知識帶來「複利效應」。第一次解決問題需要投入研究；一旦將其記錄下來，下次再遇到就只需要幾分鐘。知識是可以不斷沉澱與複利的。

Usage

/ce-compound                            # 記錄最近一次修復的問題
/ce-compound [brief context]            # 提供額外的背景上下文提示
/ce-compound mode:headless              # 供自動化腳本使用的非互動式執行
/ce-compound mode:headless [context]    # 附帶背景上下文提示的非互動式執行
/ce-compound mode:headless depth:lightweight [context] # 低開銷的非互動式執行
/ce-compound mode:headless depth:full [context]        # 完整的非互動式執行

每次執行僅處理一項經驗學習（One learning per run）。 工作流程中的背景定位（grounding）、重疊檢測以及交叉引用，均建立在「單一已解決問題」的假設之上。當同一個 Session 產生了多個不同的經驗學習時，請針對每項學習依序單獨執行本 Skill——每次執行都會重新對照程式碼樹進行背景定位。切勿將多項學習合併在一次執行中處理，事後再手動串接草稿之間的交叉引用；否則草稿上下文中的編號（例如「Learning 3」）容易洩漏到最終撰寫的文件中，而這正是本規則所要防止的錯誤。

CONCEPTS.md bootstrap requests

如果呼叫本 Skill 的具體目的是為了從零開始建立或引導建立（bootstrap）CONCEPTS.md，而非記錄某個已解決的問題，請勿執行正常的階段（Phase）——ce-compound 填入 CONCEPTS.md 僅作為記錄真實學習時的副產品（它只會建立該學習領域的詞彙種子，而非整個儲存庫；詳見 Phase 2.4）。建立全儲存庫級別的概念地圖是 ce-compound-refresh 的職責。遇到獨立的 bootstrap 需求時，請重定向至 ce-compound-refresh（它會詢問要建立概念地圖還是執行重新整理週期），然後結束執行。

Mode Detection

當滿足以下任一條件時，即進入 Headless 模式：呼叫時傳入的引數包含 mode:headless token，或是呼叫方式明確表達了非互動意圖——例如呼叫端或常駐指令要求「headless」、「non-interactively」、「unattended」或「without prompts/questions」執行 ce-compound。該 token 是顯式形式；而清晰的自然語言非互動要求具備同等效力。僅提及「automatically」或「auto-run」本身不構成 Headless 訊號——這僅代表觸發該 Skill，而非抑制其提問提示——因此在訊號模糊或未提供時，預設為互動模式（interactive）。以 mode: 或 depth: 開頭的 token 為 Flag 標籤而非背景資訊——在將剩餘內容作為簡短背景提示處理之前，請先將這些 token 裁切移除。

Depth 是僅限在 Headless 模式下使用的顯式選擇器。在 Headless 模式中，最多接受一個 depth token：depth:lightweight 直接路由至 Lightweight Mode（輕量模式），而 depth:full 則路由至 Full Mode（完整模式）並執行自動 Session 歷史紀錄探測。未帶 depth: token 的 mode:headless 保持向下相容並執行 Full Mode。Headless lightweight 不會提出阻斷性提問，也不會啟動任何子 Agent。若呼叫包含未知的 depth: token、多個 depth: token，或是在未具備 Headless 意圖時傳入 depth: token，請勿猜測；請輸出附帶原因的 Headless 失敗報告，並以 Documentation skipped 結束。

Mode	當...時	行為
Interactive (預設)	未傳入 Headless token 且無明確非互動意圖	自動選擇 Full 或 Lightweight 模式並回報選擇結果；將 Session 歷史紀錄作為自動探測執行（僅限 Full 模式）；詢問 Discoverability Check（可發現性檢查）授權；最後輸出純文字摘要（不顯示「What's next?」選單）
Headless	存在 mode:headless token，或呼叫方式帶有明確的非互動意圖	不提出任何阻斷性提問。執行明確要求的 depth，預設為 Full mode 並帶有自動 Session 歷史紀錄探測。若 Discoverability Check 發現缺口，僅進行回報而不修改指令檔案。跳過 Phase 3 專用審查。最後輸出結構化的終端報告——不顯示「What's next?」選單。

Headless 模式專為自動化流程以及 Skill 對 Skill 呼叫所設計，此時無人在場回答問題。一經檢測確認，Headless 模式將套用至整趟執行過程。

Session context

在執行 Phase 1 的 Session 歷史紀錄篩選前，先透過 Shell 工具於執行期解析出兩個數值。將每個項目作為獨立命令執行並讀取其離開狀態碼（exit status）——在此處，非 0 的離開狀態屬於正常狀況，而非需要繞道的錯誤：

• Git branch — 執行 git rev-parse --abbrev-ref HEAD。使用分支名稱在 Phase 1 中篩選 Session 歷史紀錄。若回傳 HEAD（分離頭狀態 / detached）或 exit status 非 0（非 git 儲存庫），則跳過分支篩選。
• Repo root — 執行 git rev-parse --show-toplevel。將其用作 Phase 1 中 Session 歷史紀錄的儲存庫篩選器。若 exit status 非 0（非 git 儲存庫），則退回使用目前的工作目錄（working directory）。

Support Files

這些檔案是本工作流程的持久化規範契約（durable contract）。請在需要時按需讀取（on-demand）——切勿在 Skill 啟動時一次性批次載入。

• references/schema.yaml — 標準 Frontmatter 欄位與 Enum 列舉值（在驗證 YAML 時讀取）
• references/yaml-schema.md — 從 problem_type 到目錄的分類映射表（在進行分類時讀取）
• references/concepts-vocabulary.md — CONCEPTS.md 的格式與收錄規則（在 Phase 2.4 出現領域術語時讀取）
• references/agents/session-historian.md — 本 Skill 專用的合成提示詞，用於可選的 Session 歷史紀錄複利上下文（僅在使用者同意納入 Session 歷史紀錄時讀取）
• references/grounding-validation.md — Grounding 驗證協定：標籤裁決規則與語意驗證器提示詞（在 Phase 2.45 讀取）
• assets/resolution-template.md — 新文件的章節結構範本（在組裝文件時讀取）
• scripts/session-history/ — 內建於本 Skill 中的 Session 發現與提取腳本，使 Session 歷史紀錄支援功能完全獨立自足
• scripts/validate-frontmatter.py — Frontmatter 解析器安全驗證器（在 Phase 2 步驟 8 透過該處記錄的存在檢查進行執行；將 SKILL_DIR 設定為本 Skill 的目錄，若腳本缺失則退回手動檢查清單）
• scripts/validate-doc-claims.py — 機械式主張驗證器：引用的路徑、commit SHA、相對連結、殘留的草稿骨架（在 Phase 2.45 透過 SKILL_DIR 錨點執行）

派發子 Agent 時，請將相關檔案內容直接傳入 Task 提示詞中，以便子 Agent 無需跨 Skill 存取路徑即可取得規範契約。

Artifact Root

本 Skill 會在 <root>/solutions/ 下寫入與讀取經驗學習文件。當你首次構建 <root>/solutions/ 路徑時（依據下方區塊），請先解析出 <root>；在向子 Agent 傳遞搜尋或寫入範圍時，請傳遞解析後的 <root>/solutions/ 路徑，而非原始設定。

<!-- ce-docs-root:start -->
在構建任何 Artifact 路徑前，請先解析 CE 的 Artifact 根目錄 <root>。

• 讀取 docs_root：優先讀取 <repo-root>/.compound-engineering/config.local.yaml，其次讀取 config.yaml；以第一個非空值為準（<repo-root> = git rev-parse --show-toplevel）。若未設定 -> <root> 預設為 docs，保持與過往完全一致。
• 驗證 已設定的值：必須為相對於儲存庫的目錄，其真實且經 symlink 解析後的路徑需保持在儲存庫內部，且既不能是儲存庫根目錄，也不能位於 .git/ 之下。否則請停止執行並回報包含 docs_root 及該設定值的錯誤——絕不要退回使用 docs。
• 使用 <root> 作為唯一的 Artifact 位置：若不存在則予以建立，將每個路徑構建為 <root>/<subdir>（搭配本 Skill 自己的子目錄），且絕不要同時讀取 docs。
  <!-- ce-docs-root:end -->

Execution Strategy

ce-compound 不會向使用者詢問要執行哪種模式，也不會詢問是否搜尋 Session 歷史紀錄。這兩者都是由 Agent 決定更為合適的決策：模式取決於 Agent 能觀察到的上下文預算（context budget），而 Session 歷史紀錄的價值在事前對雙方來說都是不可知的（其收益往往來自當前 Agent 未曾參與的無關早期 Session），因此這是透過低成本的探測來確認，而非透過提問。整個工作流程中唯一的互動提示是 Discoverability Check 的授權詢問，因為該動作會修改受版本控制的指令檔案。

模式選擇（Full vs Lightweight）— 由 Agent 直接決定，切勿提問。

• 預設為 Full：完整的工作流程（研究、交叉引用、重疊檢測、Grounding 驗證）。對於絕大多數記錄下來的經驗學習而言，這都是正確的選擇——相較於產生該學習的工程投入，其 Token 成本微不足道，且遠低於具備複利效應的文件價值。
• 僅在真實的上下文壓力下選擇 Lightweight（單次處理，不啟動子 Agent — 參見 Lightweight Mode）：例如 Session 已接近上下文上限，或是問題修復極為簡單、交叉引用無法帶來任何價值。這些是 Agent 可以觀察而使用者無法觀察的條件，這正是為什麼這不該成為一個問題。
• 在完成輸出的第一行說明所選模式與一行原因（例如："Ran Full mode." / "Ran Lightweight mode — session context was tight."）。若 Lightweight 的選擇不合使用者胃口，重新執行是一項罕見且低成本的修正——比每次執行都用提問騷擾使用者更劃算。

在 Headless 模式下，跳過自動模式選擇。執行 Mode Detection 階段所選定的 depth：depth:lightweight 進入 Lightweight Mode；depth:full 或未提供 depth token 則進入 Full Mode（包含自動 Session 歷史紀錄探測，即 Phase 1 步驟 4）。

Session 歷史紀錄 — Full 模式下的自動探測，絕不進行提問。 搜尋過往 Session 的目的在於：一個無關的早期 Session 可能包含相關的解題過程；Agent 和使用者事前都無法確知這一點，因此提問是沒有意義的。相反地，Full 模式總是會執行低成本的發現與中繼資料探測（Phase 1 步驟 4）——它與研究子 Agent 並行執行，因此在實際時間（wall-clock）上幾乎零開銷——只有當探測發現真正相關的候選 Session 時，才會提升至高成本的提取與合成階段。Lightweight 模式則完全跳過 Session 歷史紀錄；Headless Full 執行相同的自動探測，因為它不會進行任何提問提示，從而保持 Headless 的非互動特性。這項支援僅存在於複利工作流程內部，並無獨立的 Session 歷史紀錄功能入口。

---

Full Mode

<critical_requirement>
主要交付物為單一檔案 - 最終的說明文件。

Phase 1 的子 Agent 會將其完整的結構化輸出寫入 <run-dir>/ 下的單次執行暫存 Artifact 中，且僅回傳包含 Artifact 路徑的簡短確認訊息。Orchestrator 會在 Phase 2 的組裝階段讀回這些 Artifact。T