lat

Files (6)

• SKILL.md
• agents.md · references/
• codex-recovery.md · references/
• task-cards.md · references/
• codex-lat-session.py · scripts/
• test_codex_lat_session.py · tests/

SKILL.md (first lines)

# 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 恢復程序](references/codex-recovery.md) 準備既有進度索引並 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，列明驗收條件與依賴，不只寫「之後補做」。超出已確認需求的功能，不自行加票。
  - [ ] 依 [任務卡](references/task-cards.md) 建立每張派工卡，配置各 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 工作區的絕對路徑須改為整合後工作區的對應路徑再執行。
  - [ ] 同版本且環境與設定仍適用的有效證據可沿用，其餘重新驗證。
  - [ ] 每項任務合併至整合分支且整合後驗證通過後，立即依 [任務收尾](references/task-cards.md#任務收尾) 關閉 Agent、清理及歸檔，不等整批結束；再重新計算可開始的 Tickets。
        新解除阻塞的項目重新進入「派發」，含其下的分工與限制協調。所有 Tickets 完成前，流程不停在階段交接點。
- [ ] 驗收：Orchestrator 與 QA 先依下方「測試清單」合併需求與整合後實作的情境，再逐項執行；問題交回 Implementer 修正，更新受影響項目後複驗。
  - [ ] 使用者介面的驗收條件，須透過真實 UI 按使用者操作方式驗證；直接呼叫 API 可用於準備資料或診斷，不算 UI 驗收通過。
  - [ ] 對先前未攔下的缺陷，依證據辨別原因：缺少情境、走錯路徑、斷言不足、未執行／環境不符，或測試替換行為掩蓋缺陷；未知則保留未知。在同一修正與複驗流程補足覆蓋，回歸證據依 three-tier-testing 的「測試可信度」要求處理。
- [ ] 交付：Orchestrator 核對驗收證據，確認測試資源已依 three-tier-testing 清理或交接，並核對各任務已完成收尾或在任務卡明列待完成後續工作。回報成果與未完成事項；必要驗證未執行時，不宣告完成。

需要 Prototype／Wayfinder 時，加入對應子任務。後續修改若使先前驗證失效，重新開啟受影響項目。

## 測試清單

1. **根據使用者需求**：QA 從已確認的需求、範圍與實際使用流程，獨立列出操作情境和預期結果；先記錄草稿，再對照 Designer／Ticket 的驗收清單與實作，避免只沿用既有條目。
2. **根據實際實作**：Implementer 依實際變更與受影響的呼叫流程、設定，列出入口、分支條件、狀態轉換及失敗／恢復路徑，附程式位置與版本。Reviewer 在既有 Review 中核對有無遺漏；即使沒有發現 bug，也須提供路徑清單，不以缺陷報告替代。不窮舉無關函式或所有排列組合。
3. **整理測試列表**：實作與 Review 完成後，由 Orchestrator 與 QA 在專案配置的 Spec／tracker 合併成一份可執行清單：`來源連結（需求／QA 情境／實作路徑） | 前置條件 | 操作／觸發 | 預期可見結果 | 驗證方式 | 證據與判定／未測原因`。每項需求與相關實作路徑須對應測試，或記錄不納入的理由；QA 核對對應關係，有疑問時針對性讀程式，不必重做完整 code review。沿用既有清單與交付資料，不另建重複報告。

需求決定正確結果，實作提供需測的條件。例如「對話完成後側欄立即更新標題」是需求；實作若分串流與排隊完成路徑，清單就須分別驗證兩條路徑的 UI 更新。刻意設計的例外仍須有需求或已確認決策支持，不能因程式目前如此就免驗；模型輸出依語意判定，波動另記，不能自行降低已確認的驗收要求。

Orchestrator 處理重複、缺口與衝突；補足既有需求可直接推進，真正改變需求依使用者待決規則處理，未解的必要缺口只阻擋受影響工作。清單在實作前是草稿，驗收前須對照整合後實作補齊；後續實作變更時同步更新受影響項目。

QA 逐項記錄 `PASS`（證據支持）、`FAIL`（結果不符）、`UNPROVEN`（證據不足）或 `NOT_EXECUTED`（未執行），附證據或原因。

## 按需委派

每次委派前呼叫 /hcom-spawn 選定模型、effort 與權限並核對生效，再讀 [Agent 設定](references/agents.md) 的 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 設定](references/agents.md#存活與恢復) 查證；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，先提交待審查變更，避免漏掉未提交修改；修正後再複查。

From ouob-tw/LoopAgentTeams, MIT.

More from ouob-tw/LoopAgentTeams