agent-rig/rig

rig-epic — 整合分支工作流程

對於包含多個項目、且若直接將每個項目合入主幹會暫時破壞執行時期合約的大型任務，將子 PR 堆疊在一個共用的整合分支上，並在最後將該分支以單一 PR 的方式壓縮合併回主幹。每個子 PR 都會根據其實際步驟進行審查；最終合入主幹的交付則是一次壓縮的變基操作。

設定

讀取 .rig/config.json（預設值顯示在括號中）：

• tracker.provider — linear | github | none（預設 none）。定義父子項目的儲存方式。none 表示項目僅存在於史詩級任務的狀態檔案中（詳見下方），不會呼叫追蹤器。
• tracker.team / tracker.project / tracker.ticketPrefix / tracker.githubIntegration。
• vcs.baseRef（預設 origin/main）、vcs.defaultBranch（預設 main）、vcs.protectedBranchMergeQueue（預設 false）。
• sourceScope[0] — 在 plan 階段探索的範圍。
• agents.architect / agents.reviewer（預設 rig-<role>）— 用於全新上下文的 review 面板。

委派給 /rig-task（每個子項）、/rig-worktree（檢出）、/rig-review + /rig-review fix（合併差異審查）以及 /rig-tidy（可選）。

史詩級任務狀態檔案（取代任何外部記憶體）

每個進行中的史詩級任務都記錄在儲存庫本機的 JSON 檔案中，位於 .rig/epics/<integration-branch>.json：

{
  "parent": "ABC-42 或 tracker=none 時的 slug",
  "parentTitle": "…",
  "integrationBranch": "abc-42-<slug>",
  "whyEpic": "哪些子項互相交錯及其原因",
  "children": [
    { "id": "ABC-43", "title": "…", "blockedBy": [], "branch": null, "status": "todo|merged" }
  ]
}

這是 next/run/review/finish/prune 指令讀取的唯一事實來源。將 .rig/epics/ 加入 .gitignore（這是暫時的協調狀態）。父項推斷（當未提供 <PARENT> 時）：如果恰好存在一個 .rig/epics/*.json 檔案，則使用它；如果為零或多個，則詢問使用者。

意圖橫幅： 每次呼叫都必須先輸出一行 — 模式、PR 目標分支、以及不會執行的事項：

rig-epic: <子指令> — <動作>。PR 目標為 <branch>。不會執行 <thing>。

status（預設，僅報告）

讀取史詩級任務狀態檔案。報告：整合分支 + 領先 vcs.baseRef 的提交數；開啟的子 PR（gh pr list --base <integration-branch>）及其狀態；每個子項的追蹤器狀態（如有設定）；剩餘的已合併/已刪除工作目錄（建議執行 /rig-epic prune）；以及一行建議（「開啟子 PR X」、「準備好執行 /rig-epic next」或「準備好執行 /rig-epic finish」）。不修改任何內容；不產生任何子程序。

plan <FEATURE>

將一個功能分解為一個父項和 3–8 個子項，寫入狀態檔案，然後鏈接到 start。

僅在工作確實符合史詩級任務形狀時使用此指令（子項互相交錯 — 至少一個子項的執行時期合約依賴於另一個子項的部分完成）。如果項目彼此獨立且每個都能單獨合入主幹，則停止並告訴使用者改為執行 /rig-sprint plan — 相同的分解方式，但無需整合分支。

程序

1. 讀取上下文。 如果專案有產品/規格文件，則讀取這些文件（如果不確定則詢問）；探索程式碼庫（sourceScope[0]）以了解現有內容。如果已設定追蹤器，請先搜尋是否有近似重複的項目。
2. 確認這確實是一個史詩級任務（根據上述的交錯測試）。如果不是 → 導向 /rig-sprint plan。
3. 建立父項。
   • tracker: linear/github → 建立父項（根據設定中的團隊/專案）；描述涵蓋總覽、為何是史詩級任務以及規劃的子項。
   • tracker: none → 父項僅為記錄在狀態檔案中的 slug 和標題。
4. 建立每個子項並標記其依賴關係。
   • 足夠小以能在單一代理工作階段中完成（1–3 個檔案）；具體、可測試的驗收標準；基礎工作優先。
   • 記錄每個真實依賴的 blockedBy — 這是 next 指令用來挑選下一個未受阻擋的子項的依據。如果沒有這個，選擇會退回到宣告順序，進而導致交錯的史詩級任務處理錯誤。
   • 追蹤器模式：設定追蹤器原生的父子/受阻擋關係，並將其鏡像到狀態檔案中。none 模式：僅限狀態檔案。
5. 顯示摘要表格（ID · 標題 · 依賴於）。
6. 鏈接到 start <PARENT> — plan 是「規劃並開始」；不要停下來詢問。
7. 在 start 之後停止。 報告整合分支、子項以及下一步驟（單一子項執行 /rig-epic next，迴圈執行 /rig-epic run）。絕不自動啟動 run — 執行是一個明確的選擇加入動作。

start <PARENT>

前置檢查：git fetch origin；確認父項和至少一個子項存在（在追蹤器中，或針對 none 模式作為引數提供）。

1. 整合分支名稱： <parent-slug>-<title-slug>（連字號格式，例如 abc-42-agent-as-definition）。
2. 從 vcs.baseRef 建立整合分支，無需在本機檢出：

   git fetch origin
   git push origin <vcs.baseRef>:refs/heads/<integration-branch>
   

   非破壞性操作。如果分支已存在，則保留它（絕不覆蓋 — 可能摧毀正在進行的工作）。
3. 寫入 .rig/epics/<integration-branch>.json（結構如上），包含父項、為何是史詩級任務以及每個子項和其 blockedBy。這是讓每個 /rig-task <child> 以整合分支而非主幹為目標的關鍵。
4. 如果已設定追蹤器，則為每個子項新增一項備註：「整合分支：目標為 <integration-branch>，非主幹」，以便下一個代理不會重新讀取此技能，並確保父項狀態為「進行中」（適應性：僅在未開始時移動；如果已有正在進行的整合則延遲）。子項會在其各自的 /rig-task 步驟 1 中設定為「進行中」。
5. 透過 scripts/set-session-name.sh 將工作階段命名為 "EPIC: <parent title> (<parent>)"（僅限 Claude-Code；其他環境無作用），以便背景工作清單中能顯示為該史詩級任務。子項會使用 --skip-if-prefix "EPIC:" 設定自己的 FEAT:/CHORE: 名稱，因此此史詩級任務標籤會保持在頂端。
6. 報告分支、子項以及下一步驟。

next（單一子項）

1. 解析作用中的整合分支（預期只有一個；如果有多個則詢問）。如果工作階段尚未命名為 EPIC:（即直接呼叫 next，而非透過 start），則將其命名為 "EPIC: <parent title> (<parent>)"（僅限 Claude-Code）。
2. 挑選下一個未受阻擋的子項： 第一個尚未完成的子項，其 blockedBy 中的所有項目都已合併到整合分支中。在橫幅中說明選擇結果及其理由。
3. 確保上一個子項已成功合入。 使用 --auto-merge（步驟 4），每個子項的 PR 會在 CI 通過時自動合併到整合分支，因此整合分支的頂端會自動推進 — 只需執行 git fetch origin 並確認即可。（對於未使用 --auto-merge 執行的子項的備用方案：將分支快轉到其頂端 — git push origin origin/<previous-child-branch>:refs/heads/<integration-branch>，這會自動將該 PR 關閉為「已合併」。可安全地重複執行。）
4. 執行 /rig-task <CHILD> --base <integration-branch> --auto-merge（當 run 的預先規格審查已經確認規格時，加上 --spec-cleared）— --base 使子項的工作目錄分支和其 PR 目標都設定為整合分支；--auto-merge 使子項在其審查通過後，對其自身的 PR 啟用 gh pr merge --squash --auto，因此 CI 會將其合入整合分支（始終使用壓縮合併 — 不要使用變基合併；許多儲存庫禁止此操作。如果整合分支沒有必要的檢查，子項會直接合併）。一次性執行（開始→結束）；它會回傳單一的結果字串，用於合併閘門。
5. 合併閘門 — 僅有 clean 狀態表示合併綠燈：
   • clean → 子項已啟用自動合併，因此其 PR 會在 CI 通過時合入。等待其完成：輪詢 gh pr view <N> --json state（約 60 秒，最多約 30 分鐘）直到狀態為 MERGED，然後執行 git fetch origin 並確認頂端已推進。在狀態檔案中將子項記錄為 merged 並記錄其分支，並確保子項的票證狀態為「已完成」（適應性 — 僅在未完成時移動；如果已有正在進行的整合關閉了它，則延遲）。如果 CI 失敗或從未合併 → 視為非 clean 狀態。
   • 其他任何狀態（actionable/timeout，或追蹤器暫停狀態）→ 子項未啟用自動合併；停止。顯示結果、PR URL 以及任何審查者摘要。等待使用者；不要重試暫停的審查。

next 只處理一個子項。如需迴圈處理，請使用 run。

run [--advisor]

預先規格審查 — 僅執行一次，在迴圈開始之前。 預先一起審查所有子項的規格，而不是在執行過程中逐一發現阻礙。在執行中途暫停於規格問題的子項會拖慢整個史詩級任務（在並行或持久化執行環境下，暫停的子項可能導致整個批次失敗），因此請在任何子項開始編碼之前解決規格問題：

1. 將 agents.architect + agents.qa 分散到每個子項的規格上，針對整合分支進行閱讀；每個子項會回傳其阻礙因素。
2. 將所有阻礙因素合併為一個清單並一次性解決 — 在追蹤器中澄清，或與使用者共同決定。這是史詩級任務的唯一規格決策點。
3. 然後執行每個子項，並將其自身的規格閘門設定為預先清除：/rig-task <CHILD> --base <integration-branch> --auto-merge --spec-cleared，這樣就不會有子項在已經回答過的問題上再次暫停。

這是編碼前的規格檢查；而結合差異的 review（見下文）是合併後的程式碼檢查 — 兩者是不同的閘門。

--advisor（無人值守）。 使用顧問檢查而非人類來決定該預先閘門：委派的 agents.architect 審查會閱讀架構師和 QA 規格，然後要么繼續並提供綜合後的每個子項指導（逐字傳遞給每個子項的編碼者），要么停止並產出一份阻塞報告，指明需要人類決定的事項。無需人類等待，因此史詩級任務可以在無人值守的情況下運行到子 PR 階段；真正的阻礙因素仍然會阻止它，而不是在錯誤的規格上繼續前進。（配對的 Smithers 持久化工作流程使用一個廉價模型來實作此功能 — 「Fable 顧問」— 因此已啟動的史詩級任務永遠不會停留在閘門處。）

然後迴圈執行 next，直到沒有未受阻擋的子項：

while 存在未受阻擋的子項:
  執行 /rig-epic next            # 子項以 --spec-cleared 執行（規格已預先載入）
  如果停止且未合併（結果 ≠ clean）→ 停止，交回控制權
  否則 → 重新評估未受阻擋的子項

當佇列清空時，報告「史詩級任務已準備好執行 /rig-epic finish」。

review [<PARENT>]

在最後一個子項合併到整合分支之後、finish 之前執行。/rig-task 中的每個子 PR 審查（/rig-review）只看到孤立的子項；而這個審查看到的是合併後的整體形狀，以及只有當所有東西都整合在一起時才能看見的簡化機會。全新上下文的子代理（輸入為壓縮後的差異 + 子 PR 標題）無法繼承實作者記住的合理化理由。

在 prune 之前執行 — 審查子代理需要一個可用的檢出目錄；如果仍存在某個子項的工作目錄，請重複使用它（避免重新安裝和重新建立環境符號連結）。

1. 解析整合分支；git fetch origin。
2. 確保存在一個整合分支的工作目錄（$WT）。重複使用一個已合併子項的工作目錄，並將其快轉到整合分支頂端，否則使用 /rig-worktree 建立一個（--base <integration-branch> --reuse）。
3. 同時分散三個子代理（一條訊息，三次 Agent 呼叫），每個都 cd 到 $WT 中，並檢出整合分支頂端：
   • 透鏡 1 — 簡化（agents.architect）： 執行 git diff <vcs.baseRef>...HEAD 取得差異；透過 gh pr list --base <BR> --state merged 取得子 PR 清單。任務：找出可以合併的抽象、某個 PR 加入的輔助函式被另一個 PR 的最終形狀變得冗餘、無人設定的設定按鈕、合併後的差異使得某些程式碼路徑失效、只有一個呼叫者的型別。具體的刪除/合併建議，包含檔案:行號，影響最高的優先。跳過正確性檢查。
   • 透鏡 2 — 跨 PR 正確性（agents.reviewer）： 將專案的審查模式目錄（review.patternsFile）套用到合併後的差異上。逐個 PR 的審查已經執行過；現在要捕捉只有在合併後的形狀中才可見的互動問題（例如 PR-A 的輔助函式與 PR-D 的過時呼叫者；PR-B 移除了一個設定按鈕，但 PR-F 仍在讀取它）。分類為 P0/P1/P2，包含檔案:行號和類別。
   • 透鏡 3 — 無效程式碼與過時引用（agents.reviewer）： 對於差異新增的每個符號，檢查它是否在其他地方被呼叫？對於移除的每個符號，在專案樹（工作流程、清單檔、IaC、腳本、文件）中搜尋殘留的引用。包含檔案:行號的報告。
4. 合併 — 去重，產生一個按透鏡分組的 P0/P1/P2 清單，並顯示計數。
5. 分類處置：
   • 0 個項目 → clean — 準備好執行 /rig-epic finish，停止。
   • 有發現 → 透過 AskUserQuestion 詢問：apply now（立即套用）/ skip and finish anyway（跳過並繼續完成，降級為後續事項）/ pause（暫停）。如果選擇 apply now，在 $WT 中執行 /rig-review fix --source local（啟動 agents.coder，重新審查到 clean，提交）+ git push origin <integration-branch>，再執行一次 review 以確認收斂。
6. 結果字串（供 finish 使用）：clean — … / applied — … / paused — …。

finish [<PARENT>] [--merge]

將整個整合分支壓縮為一個針對主幹的單一 PR。預設：開啟 PR 並停止 — 這是需要仔細檢查的那一個 PR。

review 是一個強制閘門。 finish 總是先執行 review；只有在 clean 或 applied 狀態下才會開啟壓縮 PR。如果狀態為 paused，則停止並等待。

1. 執行 review（閘門） 內嵌；根據其結果進行分支處理（clean/applied → 繼續；paused → 停止並列印待辦發現事項）。
2. 如有必要，更新並變基。 git fetch origin；列出 git log <vcs.baseRef>..origin/<integration-branch> --oneline。如果主幹有移動，先將整合分支變基到其上（在本機副本上執行 git rebase <vcs.baseRef>，然後執行 git push --force-with-lease origin <local>:<integration-branch>）。
3. 開啟最終 PR 到 vcs.defaultBranch，標題引用父項，主體總結所有子項。在設有閉合動詞的追蹤器中（例如 Fixes <PARENT> / Closes #<n>），將其包含在內，以便父項在 PR 合併時自動關閉。