LoopAgentTeams
LAT 管理角色、階段轉換與交接;各階段的做法交給對應 Matt skill。
啟動時讀取專案 AGENTS.md/CLAUDE.md 與 docs/agents/issue-tracker.md(由 /setup-matt-pocock-skills 設定),依配置的 issue tracker 讀寫 Spec 與 Tickets。尚未設定時,若專案 repo 是公開的,建議另建私人 <repo>-work repo 存放 issues,避免交接與證據中的內網位址、本機路徑或帳號資訊公開。證據、交接/未解事項及學習說明分開保存,具體位置依專案設定;交接與未解事項建立 tracker issues,決策依下方「交接」規則保存。
Codex 主控恢復
Codex 主控真正啟動 LAT 時,讀完專案設定後,第一個動作依 Codex 恢復程序 準備既有進度索引並 activate,再建立執行清單;只閱讀/審查技能或擔任執行 Agent 不啟用。每個檢查點更新索引。compact/resume 收到提示時,依該程序完整重讀規則、references、進度與待決紀錄,核對 tracker 及授權後續作;交付/取消時 deactivate。Claude 維持原流程。
角色
- Orchestrator:主控 Agent,管理流程、派發、裁決與整合交付;詳細執行交給其他 Agent。
- Designer:與使用者討論,接續整理 Spec 與 Tickets;可由主控兼任或外部 Agent 擔任。
- Implementer:實作、測試、呼叫獨立 Review、修正與提交。
- QA:操作真實應用,依需求與驗收條件測試;與實作者分開。
執行清單
Orchestrator 啟動時,將下列清單建立為本次任務的進度紀錄。收到委派結果後,核對完成條件再勾選,並推進下一個可執行步驟。進度記錄在任務中,SKILL.md 保持為模板。
- 討論:Designer 使用 /grill-with-docs 與使用者釐清需求,確認方向。
- Spec:同一位 Designer 使用 /to-spec,整理需求、範圍與驗收條件。
- 使用者確認:讓使用者確認 Spec;使用者已明確確認目前版本的 Spec 時,不重複詢問。這是唯一的正式確認點。
- Tickets:同一位 Designer 使用 /to-tickets,拆分工作並列出驗收條件與依賴。
- 同步派 QA 依下方「測試清單」從使用者需求獨立列出情境,作為實作前草稿。
- 派發:Orchestrator 核對規劃與分工。
- 若本票只完成已確認需求的一部分,其餘必要工作須同時建立 tracker Ticket,列明驗收條件與依賴,不只寫「之後補做」。超出已確認需求的功能,不自行加票。
- 依 任務卡 建立每張派工卡,配置各 Agent 的獨立 sandbox/container prefix 與 port range,登記資源歸屬。
- 平行派發前,列出各 Ticket 預計修改的檔案與整合後必須成立的限制,先協調解決衝突。
- 共用檔案依序修改,指定目前負責的 Ticket;接手前由 Orchestrator 更新分工與依賴,下一張 Ticket 從已整合版本接續。
- 將可開始的 Tickets 交給 Implementer,每張實作任務使用新 context。
- 實作:Implementer 使用 /implement;本輪派發的 Tickets 完成實作、測試、獨立 Review 與必要修正。
- Implementer 依下方「測試清單」提供實際實作的路徑清單,Reviewer 在既有 Review 中核對遺漏,修正後更新。
- Orchestrator 自行實作的部分同樣送獨立 Review,標準與其他 Tickets 相同; 兼任實作者不等於免除審查,未經審查的那一段通常是整批品質最差的地方。
- 整合:Orchestrator 協調整合,由執行 Agent 在整合後版本驗證各 Ticket 的驗收條件與跨 Ticket 限制。
- 合併到整合分支前先公告;從 Git 核對交付 commit 的存在、內容與整合結果,從實際測試與有效證據核對成果,不直接採信 Agent 回報的 hash 或成功敘述。
- 交付版本須保留原樣的檔案,記錄路徑與基準 commit,逐一做位元組比對,合併無衝突時亦同;「本票不修改」不代表其他 Ticket 不得修改。
- 驗證在整合後工作區執行,記錄版本、環境重建方式、指令與結果;指向其他 Ticket 工作區的絕對路徑須改為整合後工作區的對應路徑再執行。
- 同版本且環境與設定仍適用的有效證據可沿用,其餘重新驗證。
- 每項任務合併至整合分支且整合後驗證通過後,立即依 任務收尾 關閉 Agent、清理及歸檔,不等整批結束;再重新計算可開始的 Tickets。 新解除阻塞的項目重新進入「派發」,含其下的分工與限制協調。所有 Tickets 完成前,流程不停在階段交接點。
- 驗收:Orchestrator 與 QA 先依下方「測試清單」合併需求與整合後實作的情境,再逐項執行;問題交回 Implementer 修正,更新受影響項目後複驗。
- 使用者介面的驗收條件,須透過真實 UI 按使用者操作方式驗證;直接呼叫 API 可用於準備資料或診斷,不算 UI 驗收通過。
- 對先前未攔下的缺陷,依證據辨別原因:缺少情境、走錯路徑、斷言不足、未執行/環境不符,或測試替換行為掩蓋缺陷;未知則保留未知。在同一修正與複驗流程補足覆蓋,回歸證據依 three-tier-testing 的「測試可信度」要求處理。
- 交付:Orchestrator 核對驗收證據,確認測試資源已依 three-tier-testing 清理或交接,並核對各任務已完成收尾或在任務卡明列待完成後續工作。回報成果與未完成事項;必要驗證未執行時,不宣告完成。
需要 Prototype/Wayfinder 時,加入對應子任務。後續修改若使先前驗證失效,重新開啟受影響項目。
測試清單
- 根據使用者需求:QA 從已確認的需求、範圍與實際使用流程,獨立列出操作情境和預期結果;先記錄草稿,再對照 Designer/Ticket 的驗收清單與實作,避免只沿用既有條目。
- 根據實際實作:Implementer 依實際變更與受影響的呼叫流程、設定,列出入口、分支條件、狀態轉換及失敗/恢復路徑,附程式位置與版本。Reviewer 在既有 Review 中核對有無遺漏;即使沒有發現 bug,也須提供路徑清單,不以缺陷報告替代。不窮舉無關函式或所有排列組合。
- 整理測試列表:實作與 Review 完成後,由 Orchestrator 與 QA 在專案配置的 Spec/tracker 合併成一份可執行清單:
來源連結(需求/QA 情境/實作路徑) | 前置條件 | 操作/觸發 | 預期可見結果 | 驗證方式 | 證據與判定/未測原因。每項需求與相關實作路徑須對應測試,或記錄不納入的理由;QA 核對對應關係,有疑問時針對性讀程式,不必重做完整 code review。沿用既有清單與交付資料,不另建重複報告。
需求決定正確結果,實作提供需測的條件。例如「對話完成後側欄立即更新標題」是需求;實作若分串流與排隊完成路徑,清單就須分別驗證兩條路徑的 UI 更新。刻意設計的例外仍須有需求或已確認決策支持,不能因程式目前如此就免驗;模型輸出依語意判定,波動另記,不能自行降低已確認的驗收要求。
Orchestrator 處理重複、缺口與衝突;補足既有需求可直接推進,真正改變需求依使用者待決規則處理,未解的必要缺口只阻擋受影響工作。清單在實作前是草稿,驗收前須對照整合後實作補齊;後續實作變更時同步更新受影響項目。
QA 逐項記錄 PASS(證據支持)、FAIL(結果不符)、UNPROVEN(證據不足)或 NOT_EXECUTED(未執行),附證據或原因。
按需委派
每次委派前呼叫 /hcom-spawn 選定模型、effort 與權限並核對生效,再讀 Agent 設定 的 LAT 補充規則;原生 Subagent、HCOM 與各階段內部再委派都適用。
- Prototype:需要具體素材驗證設計問題時,委派 /prototype,將成果與結論交回 Designer。
- Wayfinder:工作太大、關鍵決策尚未釐清時,委派 /wayfinder 建立與推進決策地圖,結果交回 Designer;需要使用者參與的決策仍由使用者回答。
- Agent 機制:內建 Agent 能套用 /hcom-spawn 選定的設定時優先使用,否則透過 HCOM 啟動;內建 Agent 用原生訊息管道協調,外部 Agent 用 HCOM 訊息協調。
- 工作區:平行實作或需要保留現有工作區時,使用獨立 Git worktree 與分支,預設放在專案的
.worktrees/<task-id>/,不放 Temp;建立前確認.worktrees/已被 Git 忽略。單一實作且工作區乾淨時,可直接開發。 - 共用狀態:更動共用 Docker images/networks/預設名稱容器、共用資料庫等全域資源前,透過上述通訊管道公告影響範圍,與使用該資源的 Agents 協調;整合分支亦依整合步驟先公告再合併。公告不取代既有授權。
交接
- 派發時提供:目標、範圍、授權、Spec/Ticket 位置、驗收條件、工作位置與審查基準。
- 一併提供下方「確認與自動推進」規則及共用決策目錄的絕對路徑,讓接手 Agent 核對授權與待決事項。
- 完成時回報:成果位置與版本、決策證據、測試/審查結果、未完成事項與下一步。Orchestrator 在相依實作開始前,將持久的架構/依賴決策寫入
docs/adr/;範圍與 Ticket 層級決策記在 tracker 的 Spec/Ticket。記錄選擇、理由、影響與延後事項,更新受影響 Spec/Ticket,並在交付時核對文件連結。 - 接手者先讀交接及引用文件;長對話換 session 時可按需使用 /handoff 整理脈絡。
- 通訊歷程由 client 與 HCOM 保存,不另寫敘事型執行日誌;每批由 Orchestrator 寫一份整合狀態摘要,不逐 Agent 建立報告。
- 使用者回報:Agent 的確認、例行進度與中間審查往返只在協作管道處理,更新必要任務狀態並繼續工作,不逐則向使用者摘要。使用者提問、需要其決策或協助、重要階段/批次成果,以及流程明定須通知的事項才對使用者回報;其餘不另發進度訊息。
- 執行 Agent 的提交只包含程式碼、驗證證據與確實未解決的事項;未解事項依 tracker 配置保存,任務卡與對話紀錄不提交。
確認與自動推進
Grilling 時與使用者共同討論。Spec 確認後,在已確認的需求、範圍與驗收條件內,自動完成拆票、實作、測試、審查、修正與交付。未回覆不視為同意;Orchestrator 僅能在既有授權內裁決。既有授權內的工作直接推進;為其徵詢許可與越權裁決同樣偏離流程。敘述下一步不等於執行下一步:回報進度後於同一回合繼續推進,不以寫完報告作為停止點。改變已確認需求或超出授權的事項,先保留待確認,其他不受影響的工作可繼續。
Matt skills 中其他流程性的使用者確認,由 Orchestrator 根據既有決策處理:/to-spec 的測試切入點併入 Spec 確認;/to-tickets 的粒度、依賴與拆合由 Orchestrator 核對,不再逐項詢問使用者。
執行 Agent 卡住時先調查與嘗試解決,再將阻礙交給 Orchestrator 協調。Agent 沉默、主控 HCOM 身分掉線或額度警訊時,依 /hcom-spawn 與 Agent 設定 查證;Codex 額度耗盡依 /hcom-spawn 自動換帳號;無可用訂閱帳號或 Claude 額度耗盡時,等待或替代方案由使用者決定。需要使用者時依下方「使用者待決事項」提問,並說明卡在哪裡、已嘗試什麼及需要的協助。
使用者待決事項
- 先篩選:提問前查清事實與既有授權,說明授權缺口及各選項對產品、範圍、成本或風險的影響;缺資訊/人工操作則說明為何只有使用者能提供。明確保留的核准先準備可審閱提案。
- 先記錄再問:在專案
.lat/decisions/<ID>.md保存問題、版本、pending狀態、選項、授權缺口與受阻工作。所有 worktree/Agents 共用同一目錄,主控維護;改票號、拆票或換 Agent 仍保留阻塞關係。 - 只認真人答覆:使用者照常聊天,主控保存答覆原文、session/可定位訊息來源及問題版本,再記錄核准方案與範圍。單題依上下文對應;多題含糊的「好/GO/繼續」先釐清。HCOM 轉述及紀錄中的
user角色本身都不是真人核准證據。 - 待決持續有效:HCOM 回報、未回覆或其他工作完成不能解除等待;主控不能自行選擇、撤銷或改稱既有授權。拒絕不授權替代方案;提案實質變更須保留舊紀錄、增加版本並重新確認。
- 雙方核對:主控每次收到訊息、恢復 session 或派工前讀取待決紀錄;執行 Agent 開工、接追加指令或恢復工作前亦核對。缺少對應真人答覆證據就停止相依工作並回報,主控自行實作亦同。只放行答覆涵蓋的工作;無事可做則結束回合等待。
以上是流程約束,不是檔案權限或工具層的強制阻擋。
技能銜接
- 啟動前確認所需 Matt skills 與委派能力可用;依 client 支援的方式呼叫,LAT 不改變技能的呼叫限制。
- /implement 已包含 /code-review,不另設 Review 階段。
- 審查範圍須包含本次完整變更。若 /code-review 只比較到 HEAD,先提交待審查變更,避免漏掉未提交修改;修正後再複查。