g-ki/agent-skills

交付專案

執行待辦事項，直到所有項目都合併到 main 分支。每個票證（ticket）變成一個 PR，由儲存庫的 GitHub 審查自動化機制和人類審查。你的工作是保持工作流暢：一有可能就啟動票證、保持每個 PR 健康、處理值得處理的審查反饋、在父分支合併時重新調整堆疊分支的基底，並保持票證狀態準確。

你是協調者。你讀取狀態、做出決定、委派任務，並記錄所有事項。代理（Agents）撰寫所有程式碼、解決衝突並推送。你不會在此工作目錄中編輯程式碼或執行變基操作，因此主要專案資料夾保持整潔，並且每個變更都可追溯。

輸入

$ARGUMENTS

• 任務檔案：來自 /task-breakdown 的本地 *.tasks.md 檔案（未追蹤，通常位於 git-ignored 的資料夾中，例如 .rfcs/）。如果未指定，請在該處和 docs/rfcs/ 中尋找；如果存在多個，則詢問。
• --parallel N：同時工作的最大代理數量（所有類型）。預設值為 3。
• --max-stack N：PR 堆疊的最大深度。預設值為 3。更深的堆疊可以解除更多工作的阻塞，但會在父分支變更時增加變基的次數。
• --auto-merge：當 main 分支上的 PR 狀態為 pr-ready 時，啟用 GitHub 自動合併（使用 gh pr merge --auto 並採用儲存庫常用的合併方法）。GitHub 仍會強制執行分支保護和必要的核准。預設為關閉：由人類手動合併。
• --once：僅執行一次傳遞（pass），然後退出。使用此選項可以按排程執行交付，例如 /loop 15m /deliver-project <tasks-file> --once，而不是保持一個長時間的會話開啟。

狀態存放位置

• 追蹤器（Linear、Jira、GitHub Issues 等），用於已發布的票證（它們在任務檔案中有 Tracker: 金鑰）。它是判斷票證是否存在以及是否被需要的唯一真實來源：在追蹤器中被取消、刪除或重新分配的票證將被跳過。在票證進展時，將追蹤器問題移動到相應的狀態，除非追蹤器的 GitHub 整合已經自動完成（在第一個 PR 開啟後檢查，並且不要與之衝突）。
• 本地任務檔案，位於主要專案資料夾中。它是交付狀態的唯一真實來源，並且在執行期間你是其唯一的寫入者：代理可以讀取但從不編輯。狀態：open → in progress → pr-draft → pr-open → pr-ready → pr-merged → done，加上 blocked 和 canceled（附帶原因）。Spike 的狀態為 open → in progress → decision-proposed → decided → done。保持 Branch / PR:（或 spike 的 Decision:）欄位已填寫。
• GitHub，用於 PR 狀態：開啟、合併、檢查、審查、可合併性。依賴項在其 PR 合併時即被視為已合併，無論任何檔案說什麼。
• 分支標識這次執行的 PR：每個分支都是 <username>/<project-slug>/<task-branch>，因此這次執行的 PR 就是該使用者的 PR，其頭部分支以 <username>/<project-slug>/ 開頭。這就是重新啟動的執行如何再次找到所有內容的方式。
• 執行日誌，位於任務檔案旁邊的 <rfc-name>.run.md（本地，未追蹤），用於記錄非票證狀態的資訊：正在運行的代理、每個堆疊分支的父分支頭部 SHA、已處理的評論 ID、反饋回合、CI 修復嘗試、升級問題、跟進事項。請使用 templates/run-log.md 模板。如果日誌遺失，請從 GitHub 重建。

references/github.md 包含用於讀取 PR 狀態、審查執行緒和檢查的 gh 命令。

1. 預檢（僅第一次傳遞）

如果以下任何一項失敗，請停止並顯示清晰的訊息：

1. 任務檔案結構正確：ID、狀態、現有依賴項、驗收標準、Project slug:，無依賴循環。
2. 追蹤器可達：如果任何票證有追蹤器金鑰，則追蹤器的連接器必須可用，因為你需要它來檢查取消和更新狀態。如果不可用，請說明需要啟用哪個連接器，並提議僅使用本地檔案繼續。
3. 儲存庫已就緒：乾淨的工作樹、有遠端、gh 已通過推送到 PR 權限驗證，且 main 分支可以構建並通過測試。確定 <username>（使用者現有分支的前綴，否則使用 gh api user --jq .login）和分支前綴。
4. 代理可以無人值守工作：後台代理會在此會話中顯示每個權限提示，因此一個提示就會使整個團隊停滯。建議啟用自動模式，或為 git（包括 push --force-with-lease）、gh、儲存庫的測試、lint 和構建命令以及追蹤器連接器設定允許規則。
5. 技能可用：implement-task 和 spike-task 已安裝在代理可以載入的位置，並且 task-breakdown 可供你用於在做出決策後進行細化。
6. 審查自動化：找到審查 PR 的 GitHub 工作流程，並記下其檢查名稱和機器人登入名稱，以便你知道其審查何時完成以及哪些評論是其自己的。

然後顯示計劃並獲得一次確認：票證數量、現在可以開始的內容以及將要堆疊的內容、並行度、最大堆疊深度、是否啟用自動合併，以及一則誠實的說明，說明每個代理都是一個完整的會話，並且執行會消耗大量使用量。之後，即可無人值守運行。

2. 每次傳遞

按順序執行以下步驟。優先處理堆疊底部的項目很重要：父分支的修復或合併會影響其子分支必須執行的操作。

a. 同步

擷取（Fetch）。列出本次執行的 PR（按分支前綴），包括狀態、基底分支、頭部 SHA、檢查、審查決策和可合併性。從追蹤器重新整理已發布的票證，並跳過任何已被取消的票證。收集自上次傳遞以來已完成代理的報告（每個報告以 RESULT 區塊結尾）。協調：如果 GitHub 和任務檔案不一致，PR 狀態以 GitHub 為準；修復檔案。

b. 處理合併

對於自上次傳遞以來已合併的每個 PR：將其票證狀態設為 pr-merged，並將追蹤器問題移動到「完成」狀態，除非整合已自動完成。一旦追蹤器顯示問題已關閉並且票證中的任何部署步驟已完成，則將其狀態設為 done。每個直接堆疊在已合併 PR 之上的 PR 都需要重新設定基底到 main 並將其基底分支更改為 main：為每個受影響的堆疊啟動一個重新設定基底代理（請參閱 references/stacks.md；將代理的絕對路徑 ${CLAUDE_SKILL_DIR}/references/stacks.md 提供給代理）。

c. 推進決策

Spike 會阻塞其後面的票證，並且只有使用者可以批准決策，因為決策會改變計劃。

• 對於每個處於 decision-proposed 狀態的 spike，確保使用者已看到它：將其放在更新資訊的頂部，並附上問題、建議和信心水準、一行總結的待辦事項變更，以及決策記錄的路徑。請他們批准、選擇另一個選項，或延長 spike。與此同時，讓其他所有事情繼續進行。
• 使用者可以透過在此會話中告知您，或在 --once 傳遞之間透過在任務檔案中將 spike 狀態設為 decided（並在記錄中註明所選選項）來批准。當 spike 變成 decided 時：在決策記錄的 Status: 行中記錄批准，然後使用 task-breakdown 技能的「Spike 後細化」步驟來細化待辦事項（使用者的批准涵蓋追蹤器同步），並將 spike 狀態設為 done。其依賴項將在下一步驟中變為可啟動。
• 如果使用者選擇延長 spike，則將其狀態設回 open，並在其 Question: 欄位中填入更精確的問題。

d. 保持開啟的 PR 健康

逐一處理開啟的 PR，優先處理每個堆疊底部的 PR。一次最多為每個分支或堆疊保留一個代理，這樣就不會有人同時重新設定基底和修復分支。當 PR 上有任何未完成的工作時，其票證狀態保持為 pr-open。

1. 父分支已移動。 如果堆疊 PR 的父分支有了新的提交（其頭部 SHA 與為子分支記錄的不同），則將子分支重新設定基底到父分支的新頭部。
2. 與基底分支衝突。 如果 GitHub 報告 PR 有衝突，或者由於分支保護要求而需要更新，則對其進行變基。不要僅僅因為 main 分支移動就進行變基；這會無謂地重新觸發 CI 和審查。
3. CI 失敗。 讀取失敗的日誌。如果看起來是不穩定的或與 PR 無關（基礎設施問題、PR 未觸及的測試在 main 分支上也失敗），則重新執行失敗的作業一次。如果是 PR 造成的，則啟動一個反饋代理，將失敗作為要處理的項目。在兩次修復嘗試失敗後，將票證狀態設為 blocked 並升級。
4. 審查反饋。 等到審查自動化的檢查完成。然後分類每個尚未解決的審查執行緒和你尚未處理的評論（第 3 節），並為每個 PR 啟動一個反饋代理，處理要解決的項目和要張貼的回覆。
5. 就緒。 檢查全部通過、審查自動化完成、沒有未處理的反饋：將票證狀態設為 pr-ready。如果其基底分支是 main 並且啟用了 --auto-merge，則啟用自動合併；否則，在你的更新中將其列為待人類合併的 PR。

e. 啟動新票證

用可啟動的票證填滿空閒的代理插槽。優先處理 Spike，因為它們會阻塞其他工作；然後是關鍵路徑上的票證。

• Spike 可在其狀態為 open 且其依賴項已完成時啟動。使用 references/agent-prompts.md 中的 spike 提示啟動一個 spike 代理，並將票證狀態設為 in progress。Spike 永遠不會有 PR，並且也沒有任何東西會堆疊在它們之上。
• 一個票證可在以下條件下啟動：其狀態為 open、在追蹤器中未被取消、它所依賴的每個 spike 都處於 done 狀態，並且所有其他依賴項要麼已合併，要麼有一個開啟的 PR，其檢查全部通過且沒有要求修改，並且所有未合併的依賴項都在一條堆疊線上。以最頂層未合併依賴項的分支為基底，如果所有依賴項都已合併，則以 main 分支為基底。不要超過 --max-stack。
• 如果兩個未合併的依賴項位於不同的堆疊中，請等待其中一個合併。
• 不要同時運行其 Files: 有重疊的兩個票證。

決定分支名稱（<username>/<project-slug>/<task-branch>，已發布的票證將追蹤器金鑰包含在 task-branch 中），將票證狀態設為 in progress（並且也更新追蹤器問題，除非整合已自動完成），然後使用 references/agent-prompts.md 中的提示啟動實作代理：一個通用的代理，在背景運行，並在Agent 呼叫上設定 `isolation: