netheremp/baton-pass-netheremp

Baton Pass

目的：以最少必要的文字量，在多個代理之間維持連續性。

這是一個低 Token 的工作流程實用工具，並非文檔儀式。

快速設定

在每個代理上安裝（每台機器一次）

npx github:netheremp/baton-pass-netheremp install

將此技能安裝至 ~/.claude 以及每個 ~/.codex* 家目錄。接著：

• Claude Code (CLI + IDE) — 技能自動載入；可使用 /new-game、/save-state、/baton-pass、/foresight、/dragon-dance、/party-check、/hindsight
• Codex CLI — 技能自動載入；使用 $baton-pass 明確執行
• Codex 桌面應用程式 — 技能自動載入；在編寫器中輸入 /prompts:baton-pass

替代方案：/plugin marketplace add netheremp/baton-pass-netheremp（Claude Code）或 /plugins → 安裝（Codex）。

為多代理工作初始化儲存庫

npx github:netheremp/baton-pass-netheremp init

加入 --track-state 可將交接狀態提交至 git（適合需要共享歷史的團隊）。預設為僅限本機（已加入 .gitignore）。

此指令會建立：

• baton-pass.config.json — 工作流程用來找到您的記憶檔案
• baton-pass.state.json — 輕量級的共享所有權狀態
• docs/agent-handoff.md — 所有代理適用的儲存庫特定規則
• docs/current-state.md — 當下正在發生的事
• docs/next-task.md — 誰擁有這項工作以及接下來要做什麼
• docs/progress.md — 執行中的工作階段記錄（僅附加）

init 也會將 /move 斜線指令放入儲存庫的 .claude/commands/ 目錄中。

招式集

• new-game = 在全新的儲存庫中初始化工作流程
• save-state = 安全地暫停，但不交接
• baton-pass = 當 Token 不足或所有權變更時轉移工作
• foresight = 接收或恢復工作，驗證一致性，然後繼續
• dragon-dance = 只有在學到真正教訓時才改進工作流程
• party-check = 檢視最後行動者、應行動者以及目前的儲存庫狀態
• hindsight = 稽核完整的交接鏈 — 已聲稱的里程碑、已進行的驗證、未解決的風險以及從未完成的項目

核心規則

預設傳遞差異，而非重新總結。

除非接收方在沒有這些資訊的情況下無法安全繼續，否則不要重述穩定的專案歷史。

何時使用每個招式

new-game

在儲存庫啟動時，或將此工作流程引入一個尚無共享記憶檔案的儲存庫時使用一次。

save-state

在以下情況使用：

• 您必須突然停止
• 您要暫停工作，稍後再繼續
• 所有權尚未變更

save-state 是本機檢查點，不是轉移。

baton-pass

在以下情況使用：

• Token 不足
• 另一個代理即將接手
• 您需要一個可轉移的連續性套件

baton-pass 是轉移檢查點。

foresight

在以下情況使用：

• 接收交接棒時
• 從 save-state 返回後
• 對於所記錄的狀態是否仍與儲存庫相符有任何疑問時

dragon-dance

僅在以下情況使用：

• 工作流程本身學到了什麼
• 接收方發現了偏移
• 交接棒遺漏了重要事項
• 一個新規則顯然可以防止重複浪費

不要反射性地觸發 dragon-dance。 預設情況下，不要將它包含在每個工作階段或 baton-pass 中。

party-check

在以下情況使用：

• 您忘記輪到誰了
• 多個代理共享同一儲存庫
• 您想了解目前狀態，但不想支付完整 foresight 的費用

party-check 是工作階段內的招式。從純文字終端機（無代理、無 Token）執行 baton-pass status — 它會輸出相同的所有權讀取資訊加上最近的交接鏈，而 baton-pass status --json 則提供機器可讀的輸出，供腳本和鉤子使用。

hindsight

在以下情況使用：

• 里程碑或主要功能已完成，您想要一個乾淨的記錄
• 感覺有什麼不對勁，您需要追溯實際聲稱與完成的事項
• 新代理即將加入，需要完整的歷史脈絡，而不只是最後一次交接
• foresight 發現了嚴重的偏移，您需要了解它從多遠之前開始
• 專案正在接受審查、移交給人類或歸檔

不要在每次交接後都執行 hindsight。 這是一項稽核，不是例行檢查點。

每個招式應記錄的內容

save-state

最少輸出：

• 當前任務
• 停止於
• 觸及的檔案
• 下一個立即行動
• 阻礙或風險

baton-pass

最少輸出：

• 目標
• 已完成
• 任務（若使用任務計畫 — 列出每個任務及其狀態：已完成 / 進行中 / 待處理）
• 檔案
• 工作目錄（若使用 git worktree，請提供分支名稱和工作目錄路徑）
• 已驗證
• 偏差（工作階段中做出的、與原始計畫不同的決定）
• 環境（下一個代理必須確認的先決條件：執行的服務、設定的 .env 變數、測試資料庫等）
• 下一步
• 風險
• 下一個代理

提交紀律：

• 在交接前提交，或說明未提交的原因。
• 絕不在未明確命名未提交狀態的情況下交接骯髒的工作目錄。
• 若未執行驗證，請如實說明 — 不要暗示它通過了。

為什麼任務、工作目錄、偏差和環境很重要： 工作階段記憶在交接時會遺失。如果您正處於一個 20 項任務計畫的中途，下一個代理無法僅從 git 記錄重建哪些任務已完成 — 請明確記錄狀態。如果您在 worktree 內工作，下一個代理需要確切的路徑。如果您以與計畫不同的方式修正了某些問題，請記錄下來 — 否則下一個代理會重新閱讀計畫並以錯誤的方式重做。如果環境必須處於特定狀態（資料庫正在執行、.env 已填入），請明確指出 — 否則新代理會遇到相同的阻礙。

foresight

最少輸出：

• 一致或否
• 如果不一致，哪些資訊是過時或遺失的
• 僅在必要時修正下一步

如果偏移很嚴重（交接棒聲稱工作已完成，但儲存庫顯示並非如此），請在繼續之前撰寫結構化的偏移報告：

• 聲稱了什麼
• 儲存庫實際顯示了什麼
• 必須重做什麼
• 此偏移是否值得觸發 dragon-dance

dragon-dance

最少輸出：

• 問題
• 影響
• 改進
• 新慣例

party-check

最少輸出：

• 狀態
• 上一次招式
• 上一個代理
• 下一個代理
• 更新時間
• 簡短摘要

hindsight

最少輸出：

• 稽核範圍（完整鏈或限定範圍）
• 交接鏈表格（從 → 到、日期、目標摘要）
• 每個代理聲稱的里程碑及其驗證狀態
• 驗證缺口（無證據的聲稱）
• 跨交接棒傳遞的風險
• 跨交接棒發現的偏移
• 從未解決的開放項目
• 稽核裁定：clean（乾淨）、gaps found（發現缺口）、risks unresolved（風險未解決）或 action required（需要行動）

要檢查的來源：

• docs/progress.md — 完整的工作階段記錄
• docs/next-task.md — 回合狀態歷史
• baton-pass.state.json — 程式化狀態
• git log — 提交訊息和日期
• progress 中引用的任何已儲存交接棒或 save-state 檔案

foresight 的接收流程

僅檢查避免失誤所需的最低限度：

• 當前使用者目標
• 工作目錄狀態
• 最新提交
• current-state（當前狀態）
• next-task（下一個任務）
• progress 的最新條目
• 已儲存狀態或交接棒中提到的檔案
• 若有計畫正在進行，任務列表狀態

然後決定：

• 如果一致，繼續
• 如果不一致，修正交接棒後繼續
• 如果不一致顯示出可重複使用的教訓，執行 dragon-dance

跨代理的技能發現

當技能以專案本機方式安裝（安裝到 .claude/commands/ 或透過外掛安裝到儲存庫）時，接手該儲存庫的 Codex 和其他代理會找到相同的技能定義。技能檔案會隨儲存庫一起移動。

哪些技能不會跨工作階段邊界攜帶：

• 記憶體中任務管理器的任務狀態（TaskCreate 列表在工作階段結束時會遺失）
• 子代理執行狀態（哪些審查循環已完成、哪些代理已執行）
• 環境狀態（哪些服務正在執行、哪些 .env 變數已設定）

baton-pass 必須明確記錄所有這些資訊。技能告訴代理如何工作；交接棒告訴代理目前的情況。

狀態模型

使用共享狀態檔案追蹤：

• 當前狀態
• 上一次招式
• 上一個代理
• 下一個代理
• 更新時間
• 摘要

建議的狀態：

• active（作用中）
• paused（暫停）
• handed-off（已交接）
• claimed（已認領）
• blocked（受阻）

驗證詞彙

使用一致的語言，讓接收方確切知道檢查了什麼。

• passed（通過） — 在本機執行，輸出確認乾淨
• passed outside sandbox（在沙箱外通過） — 在本機執行，但未在 CI/建置環境中執行
• not run — [reason]（未執行 — [原因]） — 跳過，請說明原因
• expected to pass, unverified（預期通過，未驗證） — 未執行，但確信正確

切勿在您意指 expected to pass, unverified 時寫下 passed。 光是這個模糊性就會導致最多的交接返工。

回合狀態

next-task 中的「回合狀態」區塊是主要的人類可讀所有權訊號。 baton-pass.state.json 會鏡像它以供程式化使用。

更新其中一個時，兩個都要更新。如果兩者不一致，以 next-task 為準。

兩者中建議的 state 值：

• active — 有人正在工作
• paused — 安全停止，同一代理將恢復
• handed-off — 已轉移，等待接收方認領
• claimed — 接收方已執行 foresight 並正在繼續
• blocked — 無法繼續，原因應記錄在 next-task 中

反模式

避免：

• 對每一個微小檢查點使用 baton-pass
• 在沒有學到任何東西時使用 dragon-dance
• 為微不足道的工作改寫所有記憶檔案
• 每次 foresight 都變成完整的儲存庫稽核
• 每次交接後都執行 hindsight — 它是稽核，不是例行步驟
• 重述整個專案而非差異
• 寫下 passed 但其實意指 expected to pass, unverified
• 在骯髒的工作目錄中交接，卻未命名未提交的狀態
• 在執行編號計畫中途遺漏任務狀態
• 當工作在 git worktree 內時遺漏 worktree 路徑
• 遺漏新代理不會知道的環境先決條件

最佳實務流程

暫停：

• save-state
• 稍後 foresight

轉移：

• baton-pass
• 接收方執行 foresight

改進：

• 只有在 foresight 暴露出有意義的工作流程問題時才執行 dragon-dance

檢查所有權：

• party-check

稽核完整鏈：

• hindsight
• 如果發現缺口或未解決的風險，執行 dragon-dance