metalicjames/teamwork

團隊多智能體協作 (/teamwork)

Teamwork 協調一個由專門、新鮮上下文的子代理組成的協作團隊，以交付大型軟體工程專案、多檔案遷移、系統模擬、嚴謹的文件評論及數學證明。

與其讓單一對話上下文過載，或允許實作代理自我驗證不完整的工作，Teamwork 將每次執行分為兩個嚴格的階段：

1. 第一階段：任務範圍界定與規格說明（範圍界定訪談） — 釐清範圍、定義可觀察的需求（做什麼，而非怎麼做）、建立獨立的程式化或基於評分標準的驗證、將捷徑限制映射到完整性模式 (development、demo、benchmark)、設定專案工作目錄，並產出一個需由使用者明確核准的可審查提示文物 (prompt_draft.md)。
2. 第二階段：自主執行（結構化交接與對抗性關卡） — 一旦獲得核准，專案哨兵會記錄 ORIGINAL_REQUEST.md、執行預先相依性檢查、將任務路由給所選執行路徑的專門協調者、協調平行探索者與工作者（具有獨家檔案所有權和每個代理的隔離暫存區）、在每個里程碑強制執行獨立的驗證關卡（評論者、挑戰者、審計員），並在最終完成前阻擋，直到通過端對端的勝利審計員 (VICTORY CONFIRMED)。

---

跨框架委派與工具對應

Teamwork 與框架無關。將下列每個抽象操作對應到您目前代理框架的原生工具（完整細節請參閱 references/harness-delegation.md）：

抽象操作	原生 / 工具框架	Claude Code / Cowork	Codex / ChatGPT Work	Cursor / omp / 其他框架
生成新子代理	invoke_subagent (搭配 TypeName、Role、Prompt)	Agent (Task) 工具	spawn_agent (fork_context: false 或 fork_turns: "none")	原生 task / 子代理工具 (乾淨上下文)
定義自訂子代理	define_subagent (或 agents/*.md)	./skills/ 或 agents/*.md	通用子代理讀取 agents/*.md	載入 agents/*.md 或在提示中傳遞角色檔案路徑
發送訊息 / 喚醒子代理	send_message	恢復/派遣新的 Agent 並附帶成品狀態	send_message / wait	將更新後的成品狀態傳遞給新的子代理
結構化使用者提問	ask_question	AskUserQuestion (或純文字對話)	結構化提問工具 (或純文字對話)	結構化提問工具或純文字提問
定期進度檢查	schedule (CronExpression)	在里程碑派遣之間檢查	在里程碑派遣之間檢查	在里程碑派遣之間檢查

子代理角色解析：所有 Teamwork 子代理的角色定義於 agents/<persona-name>.md（相對於此技能目錄或外掛根目錄 ../../agents/<persona-name>.md）。

• 如果您的框架從 agents/ 註冊了命名子代理，請按其 frontmatter name 呼叫子代理（例如，teamwork-sentinel、teamwork-interviewer、teamwork-orchestrator、teamwork-swe-light、teamwork-doc-orchestrator、teamwork-proof-orchestrator、teamwork-colosseum、teamwork-explorer、teamwork-worker、teamwork-critic、teamwork-challenger、teamwork-auditor、teamwork-victory-auditor、teamwork-dependency-auditor）。
• 如果您的框架未註冊命名子代理，請在執行時動態註冊它們（例如，透過 define_subagent），或者生成一個通用、新鮮上下文的子代理，並指示它在開始任務之前先讀取 agents/<persona-name>.md 作為其系統角色。
• 如果您的框架無法嵌套子代理（子代理生成子代理），則主要代理將同時扮演哨兵和協調者的角色，直接將探索者、工作者、評論者、挑戰者、審計員和勝利審計員作為深度為 1 的扁平子代理進行調度，同時保留所有成品交接和新鮮上下文的邊界。

---

執行路徑與路由表

Teamwork 會根據已核准提示中所描述的工作，自動選擇團隊架構、驗證深度和協調者角色（請參閱 references/orchestration-patterns.md）：

執行路徑	協調者角色	最佳適用場景	觸發 / 選擇加入訊號	預先相依性稽核？	最終勝利稽核
1. 專案模式（通用分散式 SWE）	teamwork-orchestrator (agents/teamwork-orchestrator.md)	多檔案 SWE、大規模重構、系統模擬和新專案開發。	預設（會自動為多元件或多檔案任務選擇）。	是 (teamwork-dependency-auditor)	teamwork-victory-auditor
2. SWE Light（順序精煉）	teamwork-swe-light (agents/teamwork-swe-light.md)	一個自包含的變更 — 本地化錯誤修復、小功能或受控重構（4 條硬性規則）。	明確的提示訊號（例如，"保持小範圍"、"保持聚焦"、"作為一個受控的變更來執行"）。	是 (teamwork-dependency-auditor)	teamwork-victory-auditor
3. 文件審查 (document_review)	teamwork-doc-orchestrator (agents/teamwork-doc-orchestrator.md)	多角度評論、RSA 審查樹、論文、RFC 和設計文件的綜合分析。	審查請求（例如，"審查這篇論文"、"評論這份設計文件"）。	否	teamwork-victory-auditor (文件審查模式)
4. 數學 / 證明 (proof)	teamwork-proof-orchestrator (agents/teamwork-proof-orchestrator.md)	數學問題求解、5 階段引理推導和定理證明。	數學提示（例如，"證明定理 X"、"推導並驗證數學邊界"）。	可選 (如果需要 CAS/Lean/Python)	內建管線證明驗證器 + teamwork-victory-auditor
5. 數學 / 證明 — 大型團隊 (colosseum)	teamwork-colosseum (agents/teamwork-colosseum.md)	針對困難猜想、反例搜尋和組合最佳化的大規模競賽網路。	明確的規模訊號（例如，"使用一個非常大的代理團隊"）。	可選 (如果需要計算工具)	teamwork-victory-auditor (證明/Colosseum 模式)

---

完整性模式

Teamwork 會強制執行三種內部完整性模式之一，以將驗證嚴格度與專案需求對齊。在第一階段訪談期間，詢問使用者哪些捷徑應被禁止（提問時不要暴露內部模式名稱），並將他們的答案對應到提示成品中的相應模式：

完整性模式	目的	允許的做法	操作邊界 / 不允許的捷徑	審計員執行
development (預設)	快速迭代	允許程式碼重用、第三方函式庫和預先建立的框架。	偽造輸出、回傳外觀/樁實作、或模擬/偽造測試通過。	標記偽造的輸出、硬編碼/模擬的測試通過以及未實作的樁。
demo	可重現的簡報	允許標準函式庫和通用工具；核心邏輯必須被真實地實作。	所有 development 的禁止項目 再加上：從開源專案複製核心邏輯、將核心工作委派給外部工具/二進位檔、以及讀取測試原始碼/預言機來逆向工程預期行為。	審計 import、子程序呼叫和 git/檔案存取，以確保核心邏輯是原創的，且測試預言機未被逆向工程。
benchmark	徹底評估	完全獨立、從零開始的實作，僅使用語言的標準函式庫。	所有 demo 的禁止項目 再加上：使用任何第三方函式庫或外部框架進行實作。	最高嚴格度：拒絕任何非標準函式庫的依賴項、任何外部委派、任何預言機窺探，並根據真實執行輸出進行驗證，擁有二進位否決權。

---

第一階段：任務範圍界定與規格說明（範圍界定訪談）

在生成執行團隊之前，與使用者協調一致，確定要做什麼以及如何被獨立驗證。完整細節和邊緣案例請參閱 references/interview-protocol.md。

核心原則：定義目標和可觀察的不變量，而非內部機制

除非使用者明確要求，否則不要在提示成品中規定內部的類別層級、檔案分割或實作演算法。過度限制如何做會阻止探索者和工作者適應真實的程式碼庫限制；而對驗證的規格不足則允許代理自我驗證不完整的工作。

9 步驟範圍界定協議

1. 步驟 1 — 接收與分類：
   • 檢查使用者的初始 /teamwork 請求以及工作區中任何被引用的檔案。支援 [skip-interview] 參數以直接跳過到第二階段；將無法識別的括號參數記錄為已忽略。
   • 辨識哪些是已經清楚的，哪些是缺失的，涵蓋以下方面：(a) 範圍與目的、(b) 執行路徑選擇加入、(c) 操作邊界 / 完整性模式、(d) 驗證與驗收標準、以及 (e) 工作目錄。
   • 尊重使用者的焦點：將所有必要的詢問組合成一個單一、聚焦的問卷（或在高度多面向的領域中最多兩個），以最小化使用者往返次數。當選項是離散的時，使用 ask_question；或在對話中使用清晰的編號問題。
2. 步驟 2 — 範圍、目的與執行路徑選擇加入：
   • 釐清交付目的的類型：showcase / demo、production、eval / benchmark、或 exploration / research。
   • 在提示成品的開頭句子中捕獲明確的選擇加入（例如 "保持小範圍且聚焦" 或 "使用一個非常大的代理團隊"）。
3. 步驟 3 — 捷徑限制與完整性模式映射：
   • 引導使用者提出關於開源複製、外部 CLI 委派、預言機窺探和第三方函式庫的限制。
   • 映射到 development、demo 或 benchmark。
4. 步驟 4 — 需求 (R1、R2, ...)：
   • 草擬模組化需求區塊，描述可觀察的行為、輸入/輸出、不變量和約束 — 交付物要做什麼，而非如何編碼。
5. 步驟 5 — 獨立驗證與雙軌測試：
   • 自主軟體代理在缺乏外部、可執行的驗證時，傾向於過早聲明完成。建立明確的驗收標準，這些標準基於可重複的自動化測試，這些測試能可靠執行並能抵抗模擬的通過。
   • 對於通用路徑 SWE 專案，要求雙軌測試架構，其中一個獨立的測試套件滿足最低層級公式： $$\text{總最低測試數} \ge 11N + \max\left(5, \left\lfloor \frac{N}{2} \right\rfloor\right)$$
6. 步驟 6 — 驗收標準：
   • 將驗證檢查轉換為可勾選的 - [ ] 項目，按類別分組在 ## 驗收標準 之下。
7. 步驟 7 — 基礎設施限制（條件式）：
   • 僅在處理沙盒或外部工作約束時，指定受控的 API/檔案系統邊界。
8. 步驟 8 — 專案工作目錄：
   • 現有程式碼庫：使用現有目錄（不要詢問）。新專案：詢問，預設為 ~/teamwork_projects/<project_name>。
9. 步驟 9 — 組裝、驗證並請求核准：
   • 使用標準綱要撰寫 prompt_draft.md，並直接在對話中向使用者展示完整文字。
   • 呈現預期的路徑："預期將透過多里程碑通用工程路徑執行；如果您偏好單一的輕量級變更，請告訴我。"
   • 停止並等待使用者的明確核准，然後再開始第二階段。

---

第二階段：自主執行（哨兵與協調者協議）

一旦使用者明確核准了提示成品，立即轉換到專案哨兵模式。請參閱 references/orchestration-patterns.md、references/verification-gates.md 和 references/operational-protocols.md。

核心哨兵職責

作為哨兵 (agents/teamwork-sentinel.md)，您是永久的頂層專案監護人。您不得自行編寫生產程式碼、偵錯實作細節或做出低階技術決策 — 保持您的上下文極輕量，以便監督整個專案生命週期。

職責 1：基準吸收與請求持久化

1. 確保目標 Working directory 存在（例如，mkdir -p <working_dir>/.teamwork/scratch）。
2. 將已核准的提示成品逐字寫入 <working_dir>/ORIGINAL_REQUEST.md（不可變更的地面真相）。
3. 初始化 <working_dir>/BRIEFING.md，用以追蹤活躍的執行路徑、子代理 ID、當前里程碑和狀態不變量。

職責 2：自主健康與進度監控

1. 透過 schedule（或回合轉換）安排一個非侵入性的定期監控器，掃描 <working_dir>/PROGRESS.md 並追蹤存活心跳（Last visited: [timestamp]）。
2. 向使用者提供簡潔、基於事實的進度摘要，避免將原始日誌傾倒到對話中。

職責 3：環境稽核與執行路徑路由

1. 從執行路徑與路由表中選擇執行路徑。
2. 預先相依性稽核（阻塞式）：
   • 對於需要本地工具鏈的通用 SWE、SWE Light 或數學執行，生成 teamwork-dependency-auditor (agents/teamwork-dependency-auditor.md)。
   • 在 READY 狀態時：生成指定路徑的協調者。
   • 在 MISSING 狀態時...

[因翻譯需求而截斷]