DenisSergeevitch/repo-task-proof-loop

倉庫任務證明循環

當使用者想要對一個非平凡的編碼任務（特別是功能、重構、遷移或錯誤修復）執行可重複、可稽核的實作工作流程時，請使用這個技能。此工作流程應在 .agent/tasks/<TASK_ID>/ 下留下倉庫本地的證明。

此工作流程建立的所有任務工件都必須保留在儲存庫內部。

當下面的範例提到 scripts/task_loop.py 時，該路徑是相對於此技能根目錄的。請在您 shell 的工作目錄位於目標儲存庫內時執行它。

這個技能的用途

1. 在 .agent/tasks/<TASK_ID>/ 下初始化一個嚴格的倉庫本地任務資料夾
2. 建立或更新所需的工件檔案
3. 將專案範圍的 Codex 和 Claude 子代理範本安裝到 .codex/agents/ 和 .claude/agents/
4. 使用一個說明工作流程的管理區塊，更新倉庫根目錄的 AGENTS.md Codex 基準以及倉庫的 Claude 指南檔案（CLAUDE.md 或 .claude/CLAUDE.md）
5. 引導代理執行一個嚴格的循環：
   • 規格凍結
   • 建構者實作
   • 證據封裝
   • 全新驗證
   • 最小修復
   • 再次全新驗證，直到通過為止

請參閱：

• references/REFERENCE.md
• references/COMMANDS.md
• references/SUBAGENTS.md
• references/SCHEMAS.md

此技能支援的命令

當使用者呼叫此技能時，請將以下詞彙視為命令：

• init <TASK_ID>：建立 .agent/tasks/<TASK_ID>/，安裝或重新整理子代理範本，並更新 AGENTS.md 以及倉庫的 Claude 指南檔案
• freeze <TASK_ID>：根據使用者任務、任務檔案和倉庫指導建立或完善 spec.md
• build <TASK_ID>：根據凍結的規格實作任務
• evidence <TASK_ID>：建立或重新整理 evidence.md、evidence.json 和原始工件，但不更改生產程式碼
• verify <TASK_ID>：執行一次全新的驗證器傳遞，並寫入 verdict.json，必要時也寫入 problems.md
• fix <TASK_ID>：從 problems.md 應用最小安全修復集，然後重新整理證據套件
• run <TASK_ID>：執行從規格凍結到驗證的完整循環
• status <TASK_ID>：總結目前的工件狀態

如果使用者沒有提供命令，則根據倉庫狀態推斷下一步：

• 如果任務資料夾不存在，則先執行 init。如果使用者明確只想初始化，則在此停止。否則，在 init 成功且 .agent/tasks/<TASK_ID>/spec.md 存在後，在同一輪中繼續重新評估倉庫狀態。不要將 init 與 freeze、build、evidence、verify、fix、validate、status 或子代理工作重疊。
• 如果缺少 spec.md 或僅為佔位符，則執行 freeze
• 如果實作尚未完成，則執行 build
• 如果證據過期或遺失，則執行 evidence
• 如果沒有新的判定結果，則執行 verify
• 如果判定結果不是 PASS，則執行 fix

初始化步驟

從儲存庫根目錄或儲存庫內的工作目錄執行綁定的初始化程式：

scripts/task_loop.py init --task-id <TASK_ID>

選擇性的任務播種：

scripts/task_loop.py init --task-id <TASK_ID> --task-file path/to/task.md
scripts/task_loop.py init --task-id <TASK_ID> --task-text "使用者任務文字"

初始化程式將會：

• 解析儲存庫根目錄
• 建立 .agent/tasks/<TASK_ID>/
• 建立所有必需的工件，包括 raw/ 下的佔位符
• 安裝專案範圍的子代理檔案
• 在 AGENTS.md 和倉庫的 Claude 指南檔案中插入或重新整理管理工作流程區塊

對於 Codex，初始化程式會將其管理工作流程區塊保留在儲存庫根目錄的 AGENTS.md 中。Codex 也支援 AGENTS.override.md 和已設定的備用指南檔案名稱；較接近程式碼的巢狀檔案仍然具有優先權，此技能有意不覆寫它們。 如果 init 在正在執行的 Codex 會話期間建立或重寫了 AGENTS.md，請在依賴更新後的指示之前啟動一個新的 Codex 會話。Codex 在會話開始時會快照專案文件指導。

對於 Claude Code，初始化程式會將其管理工作流程區塊保留在儲存庫根目錄的 CLAUDE.md 中。Claude Code 也支援 .claude/CLAUDE.md、.claude/rules/*.md 和 CLAUDE.local.md，但此技能將根目錄的 CLAUDE.md 視為主要專案指南，因為 Claude 會直接將其展示出來。

在 Claude Code 中，如果 init 在當前會話中剛剛寫入或重新整理了 .claude/agents/*，請不要假設這些更新後的代理在會話中期間就已經可用。

將 init 視為序列化的先決條件。切勿將其與 freeze、build、evidence、verify、fix、validate、status 或子代理生成重疊。

重型任務的預設工作流程

對於大型任務，保持使用者面對的請求簡單。在 Codex 中，除非使用者明確要求委派或平行代理工作，否則繼續序列化進行；在獲得該授權後，當當前產品表面支援委派且任務形狀需要時，此技能可以自動選擇內部的子代理設定。

首選的委派序列

1. 如有必要，執行 init <TASK_ID>。等待其完成，然後在繼續之前確認 .agent/tasks/<TASK_ID>/spec.md 和倉庫本地任務結構存在。
2. 僅在 init 完成後，生成剛好一個規格凍結子代理並等待它
3. 生成剛好一個建構子代理並讓其實作
4. 使用同一個建構子會話繼續進行證據封裝
5. 生成剛好一個全新的驗證子代理並等待它
6. 如果判定結果不是 PASS，則生成剛好一個修復子代理
7. 再次生成一個全新的驗證子代理
8. 重複步驟 6-7，直到驗證者返回 PASS 或使用者停止循環

Codex 適應性扇出

僅在使用者明確授權 Codex 委派且任務範圍足夠廣泛以致於可以從有界平行工作中受益時，才使用此模式。對於狹隘的任務，請使用上面更簡單的序列化序列。

適合的情況：

• 在規格穩定之前，必須先回答多個獨立的程式碼庫問題
• 實作可以分割成不相交的寫入範圍
• 需要對不同表面執行多個獨立的唯讀檢查來進行證明

Codex 模式：

1. init 保持序列化。
2. 如果任務仍然不明確，則平行扇出最多 3 個內建的 explorer 子代理。為每個子代理指定一個單一的問題、子系統或路徑範圍。等待它們，然後凍結規格。
3. 生成一個規格凍結子代理並等待它。
4. 生成一個 task-builder 子代理作為整合擁有者。
5. 如果實作可以乾淨地分割，父代理也可以平行生成有界的內建 worker 子代理。每個 worker 必須有明確的檔案或模組擁有權，且不得寫入 evidence.md、evidence.json、verdict.json 或 problems.md。
6. 使用 send_input 或等效的後續面，讓整合建構者保持活躍以進行證據封裝。建構者仍然是證據套件的唯一擁有者。
7. 如果需要額外的證明，父代理可以扇出一個小型的、有界的唯讀 explorer 子代理集合，以平行重新執行不相關的檢查或檢查不同的證明空白。這些子代理可以報告命令、輸出和發現結果，但他們不寫入 verdict.json。
8. 為每個驗證傳遞執行剛好一個全新的驗證子代理。

平台行為

• 在 Codex 中，保持正常路徑為序列化，並在 init 後優先使用自動模式。除非它們會顯著影響工作，否則避免展示委派的內部細節。
• 在 Codex 中，僅在使用者明確要求子代理、委派或平行代理工作時，才生成有界的子代理。
• 在 Codex 中，一旦委派被授權，技能可以選擇匹配的子角色，並決定是保持一次一個子代理還是有界扇出。使用者不需要指定特定的子角色或斜線命令。
• 在 Codex 中，子代理生成仍然是父代理協調者的顯式操作。如果當前的 Codex 表面封鎖了委派，僅在它會顯著影響工作時簡短說明，然後繼續序列化進行。
• 在 Codex 中，保持任務樹淺層。父會話應直接生成研究、建構、修復和驗證子代理，而不是要求一個自訂任務子代理去協調更多的子代理。
• 在 Codex 中，一旦委派被授權，根據凍結的規格、倉庫形狀和當前的委派表面，在每次一個子代理的委派和有界扇出之間進行選擇。無論哪種方式，都要保持 init、證據擁有權和每個驗證傳遞的序列化。
• 在 Codex 中，保持輔助扇出適度且基於批次。一次最好平行不超過 3 個輔助子代理，等待該批次完成，然後決定下一個階段。
• 在 Codex 中，內建的 explorer 是進行唯讀儲存庫探索和證明探測的首選。當您可以指定明確的擁有權時，內建的 worker 適用於有界的不相交實作或檢查重新執行。
• 在 Codex 中，通過向其發送後續指令來重用活躍的建構子子代理以進行證據封裝。驗證傳遞必須使用全新的子代理或全新的會話；不要透過恢復先前的驗證者來滿足驗證新鮮度要求。當您有意想要建構者和修復子代理的上下文時，可以重用或恢復它們。
• 在 Codex 中，在重用或恢復子代理之前，檢查當前的子線程列表。在 Codex CLI 中使用 /agent，或在當前 Codex 產品表面可用的任何等效子線程清單面進行檢查。
• 在 Codex 中，來自 update_plan 的計劃/待辦事項清單 UI 是可選的會話指導。它對於即時進度顯示很有用，但它不是此工作流程的真實來源。
• 在 Claude Code 中，技能應決定是留在主線程上，還是讓主 Claude 會話在 init 後自動將當前階段委派給匹配的內建或專案子代理。使用者不需要另外請求特定的 Claude 子代理或委派模式。
• 在 Claude Code 中，TodoWrite 或可見的任務/待辦事項 UI 是僅限會話範圍的選擇性進度顯示。它有助於在當前會話中進行即時追蹤，但它不是此工作流程的真實來源。
• 在 Claude Code 中，優先使用來自 .claude/agents/ 的已安裝專案子代理，其描述應作為匹配證明循環階段的積極觸發條件。Claude 的主會話會根據任務請求、子代理描述和當前上下文進行路由，因此請保持每個階段的提示以自然語言清晰表達。預設情況下，對證據步驟重用同一個建構子子代理。僅在原始建構子會話不可用或您有意丟棄它的時候，以僅證據模式運行一個全新的建構子。如果 init 在當前的 Claude 會話期間剛剛重新整理了 .claude/agents/*，則回退到主線程或已可見的代理，而不是假設重新整理後的代理立即可用。
• 在 Claude Code 中，保持協調扁平化：主會話自動委派是可以的，但證明循環工作流程代理本身是葉角色。父會話應擁有證明循環階段的轉換，而不是要求一個自訂任務代理去生成另一個。
• 在 Claude Code 中，規範的持久狀態始終是 .agent/tasks/<TASK_ID>/ 下的倉庫本地工件集，特別是 spec.md、evidence.md、evidence.json、verdict.json 和 problems.md。
• 如果子代理不可用，請在當前會話的不同會話或乾淨的模式切換中保留相同的角色分離。

使用來自 references/COMMANDS.md 的確切角色提示。

規格凍結要求

spec.md 必須至少包含：

• 原始任務陳述
• 標記為 AC1、AC2、... 的顯式接受標準
• 約束條件
• 非目標

它還可以包含：

• 儲存庫指導來源
• 驗證計劃
• 根據使用者請求狹義解決的假設

在規格凍結期間不要編輯生產程式碼。

證據封裝要求

evidence.md 和 evidence.json 必須獨立地對每個接受標準進行以下之一的判斷：

• PASS
• FAIL
• UNKNOWN

證據封裝可以執行缺失的檢查，但它不能持續更改生產程式碼。

每個 PASS 必須引用具體的證明，例如：

• 檔案路徑
• 執行的命令
• 退出碼
• 輸出摘要
• raw/ 下的工件路徑

除非每個接受標準都是 PASS，否則不要在證據套件中聲明整體 PASS。

全新驗證要求

驗證者必須是一個全新的會話或全新的子代理。 在 Codex 中，不要透過恢復先前的驗證子代理來滿足此要求。

驗證者必須判斷當前的儲存庫狀態和當前的重新執行結果，而不是建構者的敘述。

驗證者會寫入：

• .agent/tasks/<TASK_ID>/verdict.json
• 僅當整體判定不是 PASS 時，.agent/tasks/<TASK_ID>/problems.md

對於每個非 PASS 的標準，problems.md 必須包含：

• 標準 ID 和文字
• 狀態
• 為何未被證明
• 最小重現步驟
• 預期結果與實際結果
• 受影響的檔案
• 最小安全修復
• 1-3 句的修正提示

驗證者不得修改生產程式碼或回填證據套件。

修復者要求

修復者僅讀取：

• spec.md
• verdict.json
• problems.md

修復者必須：

• 在編輯之前重新確認程式碼庫中列出的每個問題
• 做出最小安全變更集
• 避免回歸已通過的標準
• 重新生成 evidence.md、evidence.json 和原始工件
• 停止而不寫入最終簽署

驗證

在聲明工作流程已正確初始化或工件集已完成之前，請執行：

scripts/task_loop.py validate --task-id <TASK_ID>

僅在 init 完全完成後執行 validate。如果它報告初始化正在進行中，請等待並重新執行，而不是將該結果視為穩定的任務失敗。

如需快速摘要：

scripts/task_loop.py status --task-id <TASK_ID>

僅在 init 完全完成後，並且您需要穩定的任務狀態時，才執行 status。如果它報告 init_in_progress: true，則將其視為稍後重試的條件。

護欄

• 將 .agent/tasks/<TASK_ID>/ 保留在儲存庫內
• 將 Codex 待辦事項/檢查清單 UI 視為僅是暫時的進度顯示；持久狀態是倉庫本地的工件集
• 在規格凍結期間不要變更生產程式碼
• 驗證者不得修改生產程式碼或回填證據
• 修復者必須從 problems.md 重新確認每個問題，並進行最小安全修復
• 保持任務樹淺層；父會話應直接生成葉角色子代理
• 將 init 視為序列化的先決條件
• 對證據封裝重用建構者會話，除非它不可用
• 對每個驗證傳遞使用全新的會話或全新的子代理
• 如果委派被授權，在每次一個子代理的委派和有界扇出之間進行選擇
• 保持輔助扇出適度且基於批次（一次最多 3 個平行子代理）

疑難排解

• 如果 scripts/task_loop.py 找不到：確保您的 shell 工作目錄是目標儲存庫，並且技能根目錄在路徑上
• 如果 init 報告錯誤：檢查您是否對 .agent/tasks/<TASK_ID>/ 路徑具有寫入權限
• 如果 validate 或 status 報告 init_in_progress：等待並重試
• 若在進行中的 Codex 會話期間 AGENTS.md 被 init 覆寫：啟動一個新的 Codex 會話
• 若在目前會話期間 .claude/agents/* 被重新整理：回退到主線程或已可見的代理
• 如果子代理生成失敗：檢查委派是否在目前的 Codex 或 Claude 產品表面上被阻止，如果被阻止，則序列化地繼續