請遵循執行階段配接器的指引。其執行階段對應關係適用於所有被引用的腳本與腳本集。
Pstack 配對
一個儲存庫，兩個代理，一個 Herdr 或 Rex 工作階段。主導者擁有判斷權，副手則擁有工作樹。代理之間的所有訊息都是配對儲存區中的一個檔案，加上一行命名該檔案的提示。終端機永遠不是記錄，因為在交替螢幕上的代理不會留下可滾動的歷史記錄。
先決條件
- 在 Herdr (
test "${HERDR_ENV:-}" = 1) 或 Rex (REX_BLOCK已設定) 環境內。若不在任何一種環境中，則告知並停止。 - 載入多工器的技能以控制窗格與代理：Herdr 的
~/.agents/skills/herdr/SKILL.md（或當該檔案不存在時使用herdr --skill），或 Rex 的rex skill show。其安全規則貫穿整個過程。在 Rex 中，請閱讀在 Rex 中執行。 - PATH 環境變數中需包含
herdr或rex，以及 Python 3.11 或更新版本 (python3)。scripts/pair.sh help列出所有儲存區與頻道操作；請優先使用此指令，而非手動建構herdr或rex呼叫來進行配對。 - 以自動模式啟動主導者。Devin 預設使用
--permission-mode dangerous繞過權限。其他類型的代理則繼承主導者的模式。pair.sh permission會顯示偵測到的主導者模式。使用--permission <模式>或在--之後使用原生的權限旗標來覆蓋預設值；--permission auto則選擇 Devin 的智慧模式。沒有對應翻譯的代理類型，請在--之後使用其原生旗標。spawn也會跳過每個代理類型的資料夾信任提示（這會導致未在未見過的資料夾中啟動的無人值守代理卡住）：pi 使用--approve，Devin 使用--respect-workspace-trust false。在--之後的信任旗標會覆蓋此設定。Claude 和 Codex 則會詢問是否信任一個它們尚未見過的資料夾；該決定應由人類做出，因此spawn會拒絕對話並停止，同時告知操作：在該儲存庫中開啟該代理一次並信任它。
角色
| 角色 | 主導者 | 副手 |
|---|---|---|
| 擁有 | 計劃、簡報、審查、決策、人類 | 工作樹、測試、診斷、證據 |
| 以 pstack 執行 | poteto 模式框架、how、architect、審查技能 | 每個簡報中命名的腳本集及其待辦清單 |
| 寫入 | 僅限配對儲存區 | 簡報 Scope 內的檔案，加上其進度日誌與報告 |
| 透過...溝通 | 簡報、方向指引、審查、常規命令、關卡 | 進度行、報告 |
進入你的角色。主導者：references/master.md。副手：references/sidekick.md。
配對儲存區
${XDG_STATE_HOME:-$HOME/.local/state}/pstack/pair/<slug>/，由 pair.sh init 建立。每個檔案只有一個寫入者。
| 路徑 | 寫入者 | 內容 |
|---|---|---|
pair.json | 主導者透過 pair.sh | 代理名稱、窗格 ID、當前工作目錄、Git 根目錄、副手的備用與容錯方案、窗格佈局（分割或分頁） |
standing-orders.md | 主導者 | 編號的限制條件，透過路徑貼到每個簡報中 |
plans/NNN-<slug>.md | 主導者 | 一個計劃輪次，來自計劃範本 |
briefs/NNN-<slug>.md | 主導者 | 一個工作單元，來自簡報範本 |
progress/NNN-<slug>.md | 副手透過 pair.sh progress | 每個完成的步驟或方法變更的時間戳記行；簽到只顯示主導者尚未看到的行 |
steers/NNN-<slug>-s<k>.md | 主導者 | 針對單元 NNN 的中間方向指引 k，來自方向指引範本；supersedes: 命名其回應的反對方向指引 |
reports/NNN-<slug>-s<k>.md | 副手 | 對方向指引 k 的反對，來自方向指引回應範本 |
reports/NNN-<slug>.md | 副手 | 簡報 NNN 的證據，來自報告範本，或是對計劃 NNN 的同意/反對回應，來自計劃回應範本 |
reviews/NNN-<slug>.md | 主導者 | 對報告 NNN 的裁決，來自審查範本；對計劃的 agreed 裁決會解鎖其簡報 |
scratch/<id> | 主導者透過 pair.sh scratch | 指向一個臨時工作樹的連結，用於在某個單元的提交處重新執行其檢查，位於儲存庫外的 ${XDG_STATE_HOME:-~/.local/state}/pstack/scratch/（PSTACK_SCRATCH_ROOT 可移動它），Claude 和 Codex 需要在每台主機上信任一次（kitchen.py doctor 會檢查）；審查完成後會移除 |
gates.md | 主導者 | 留待人類解決的開放問題 |
decisions.tsv | 主導者透過 pair.sh log | 展示你工作的軌跡 |
status.md | pair.sh status | 衍生的表格；請勿手動編輯 |
queue | 主導者透過 pair.sh queue 與 dispatch | 下一個簡報的路徑，一個槽位 |
steps/NNN-<slug>.tsv | 副手透過 pair.sh step | 每個已提交步驟一行：編號、提交、時間、它解決的備註、摘要 |
notes/NNN-<slug>-n<k>.md | 主導者透過 pair.sh new-note 與 note | 對單元步驟直到步驟 k 的審查，來自備註範本：阻塞項目與後續行動 |
followups.md | 主導者透過 pair.sh note | 來自每個備註的後續行動，用於後續的簡報或議題 |
session-handoff.md | 主導者 | 精簡的恢復與下一個任務上下文，在啟動時讀取 |
sessions/ | pair.sh spawn / rotate | 先前的就緒報告；保留的工作階段匯出與時間證據 |
events.tsv | 每個 pair.sh 指令 | 每條訊息、報告、喚醒與日誌項目一行，由 pair.sh metrics 讀取 |
NNN 是零填充的序列，由計劃或簡報、報告與審查共享，因此一個單元的檔案會排序在一起。
訊息
| 提示文字 | 方向 | 發送者的輔助工具 | 接收者的行動 |
|---|---|---|---|
| bootstrap (命名技能與儲存區) | 主導者到副手 | pair.sh spawn | 啟動步驟，reports/000-ready.md，回覆 READY |
pstack-pair PLAN <plan-path> | 主導者到副手 | pair.sh discuss | 將計劃落實在程式碼中，撰寫同意或反對回應，結束回合 |
pstack-pair BRIEF <brief-path> | 主導者到副手 | pair.sh dispatch | 執行簡報，撰寫其報告，執行 pair.sh finish，然後以 REPORT 行結束回合 |
pstack-pair BRIEF <brief-path>, 已排隊 | 主導者到正在工作的副手 | pair.sh queue | 主導者在新的工作階段後分派它；pair.sh next 拒絕 |
pstack-pair STEER <steer-path> | 主導者到正在工作的副手，或暫停在反對狀態的副手 | pair.sh steer | 到達時立即讀取，在工具呼叫之間；同意則繼續，或提出證據反對並結束回合 |
pstack-pair REPORT <report-path> | 副手到主導者 | pair.sh finish (或 notify) | 讀取報告，審查 |
pstack-pair STOP <store> | 主導者到副手 | pair.sh stop | 安全暫停，撰寫停止報告 |
主導者的 dispatch 與 wait 會在副手的回覆送達時返回：即自訊息以來已寫入的報告，或一個 blocked 的副手。單獨來自多工器的穩定狀態是不可信的：一個 Devin 副手在提示送達時與步驟之間顯示為空閒，並且在狹窄的窗格中可能會在整個運行完成後顯示為完成，因此會將穩定狀態與窗格中的「按 esc 中斷」行進行比對；如果穩定狀態持續一分鐘而沒有報告，則 wait 會以 report: missing 結束。當簽到間隔已過而副手仍在工作時，它們也會返回，並列印簽到摘要而非報告路徑。wait 也會在分派的簡報報告送達時立即返回，即使副手已經接受了已排隊的簡報；running: 會命名它正在進行的簡報。notify 僅在主導者空閒時提示主導者，因此等待中的主導者永遠不會被中斷。在壓縮後收到的訊息仍會命名此技能和要讀取的檔案，因此請重新載入技能並從該檔案繼續。
先計劃後執行
實作僅在兩位代理都同意的計劃之後開始。主導者驅動實作、架構與系統設計：它起草 plans/NNN-<slug>.md，包含所選設計、權衡的替代方案及其優缺點，然後使用 pair.sh discuss 發送。副手針對這些權衡進行腦力激盪，針對程式碼檢查每個步驟，並以證據表示同意或反對。主導者在新一輪計劃中進行修訂或回應反對意見，直到回應表示同意，且主導者撰寫一個裁決為 agreed 的審查。pair.sh dispatch 拒絕一個功能、錯誤修復、重構、性能問題或 pstack TDD 簡報，如果其 plan: 行沒有命名一個已同意的計劃。唯讀與鑑識簡報不需要計劃；一個錯誤的診斷簡報在其計劃之前執行，因此計劃基於執行階段的證據。三輪未達成一致則成為一個留待人類處理的關卡，gates.md 中會記錄雙方的立場。
簽到與方向指引
主導者以配對中駕駛者的方式驅動：它定期查看，而非持續查看，並且修正方向，而非按鍵。
- 副手透過
pair.sh progress將每個完成的待辦清單步驟與每次方法變更新增一行到progress/NNN-<slug>.md。在它寫入 Scope 外部或偏離計劃之前，它會先寫下這一行，以便簽到可以捕捉到它。 dispatch與wait會在簽到間隔（--every MIN，預設九分鐘）過去且副手仍在工作時返回，並附帶一個摘要：已過時間（相對於時間盒）、尚未看到的進度行、觸及的檔案（以及哪些位於 Scope 外部）、自分派以來的提交數，以及方向指引計數。當副手切換分支或重新基底，使得 HEAD 不再從分派時的 HEAD 衍生時，只有自分派以來的提交被計為觸及。該摘要是主導者在報告之間讀取的全部內容；僅當摘要標記日誌為STALE時，它才會讀取窗格。- 方向指引是主導者發出的中途修正：
pair.sh new-steer，然後pair.sh steer。它會在副手工作時進入其輸入佇列；框架會在工具呼叫之間將它傳遞給副手，而副手會立即對其採取行動，而不是在步驟結束時。一個 Devin 副手會從其下一次的pair.sh step、notes或progress中以STEER:行的形式接收它，因為 Enter 鍵在將排隊訊息傳送給 Devin 的同時會取消其正在執行的指令。--interrupt會先取消正在執行的工具呼叫，適用於不能等待的方向。方向指引攜帶方向：已同意計劃未選擇的方法、範圍偏移、要跳過的步驟、即將跨越的禁止行，或來自人類的消息。審查可以在結束時捕捉到的任何內容都應等待審查。 - 副手同意或反對，如同對待計劃。同意：套用，在進度日誌中確認，繼續。反對：撰寫方向指引回應，附帶證據與替代方案，通知主導者，結束回合。主導者以一個取代被反對的方向指引的方向指引回應，無論是修訂版或撤回版，然後
pair.sh steer恢復副手。每個方向指引最多兩輪；決策權仍屬於主導者，持續的分歧則進入計劃輪次。 - 每個簡報最多兩個新的方向指引。第三個意味著簡報本身有問題：停止該單元並重新進行簡報。
各種任務工作階段
任何類型的副手（Claude、Codex、Devin、pi、Prime、Muse）在完成每個簡報時都會使用一個全新的對話。在產出、排隊、輪換或清理其儲存之前，請閱讀 Devin 或 Pi 的 Devin 工作階段生命週期，或 Prime 的 Prime 配接器。部分完成與被阻塞的工作會保留在其工作階段中；完成的簡報會離開佇列，等待主導者分派。dispatch 與 discuss 會自行先輪換副手（在其輸出中有 rotated:）；pair.sh rotate 則留給主導者手動執行。Pstack 儲存區在工作階段之間持續存在。
Muse Code
使用 --kind muse 作為任何角色。請閱讀 Muse 配接器 以了解其權限、信任、預檢與退出處理。Muse 每個窗格維護一個對話，因此不會在每個簡報後輪換。
Prime Agent
使用 --kind prime-agent 作為副手。請閱讀 Prime Agent 配接器 以了解原生模型參數、預檢、方向指引、精確的守護程序工作階段清理以及提供者容錯。Prime 使用共享儲存區協定，並且需要在每個完成的簡報後進行輪換。
Pi 副手與備用方案
pi 副手會透過其自身的事件向 Herdr（以及透過 pstack 擴充向 Rex）報告其狀態，並排隊方向指引而不取消正在執行的指令。當其模型位於可能失敗的路由之後時，使用 --fallback devin 產出它：spawn 會先檢查模型，而 pair.sh failover 會在中間過程中切換到備用方案。在產出 pi 副手之前，請閱讀 Pi 副手參考。
讓副手保持忙碌
副手是關鍵路徑：主導者在幾分鐘內完成報告的審查，而一個單元可能需要數十分鐘到數小時。三個習慣可以防止副手等待主導者。
- 為下一個簡報排隊。 當一個單元正在執行時，主導者起草下一個簡報，並使用
pair.sh queue將其保留。在done報告之後，副手會啟動一個全新的工作階段，主導者分派該簡報；pair.sh next拒絕。佇列只有一個槽位，且僅保留一個不依賴於正在執行單元審查的單元，因此revise會變成一個後續簡報，而不是重新處理已排隊的簡報。 - 在提交時審查。 一個會寫入檔案的簡報會說
commit: yes，而報告的head:會命名該提交。主導者在副手處理下一個單元時使用git show讀取它，並在pair.sh scratch <store> NNN-<slug>-review --at <head>中重新執行檢查，永遠不會在共享的工作樹中進行。 - 修正而非重新規劃。 主導者採納的反對意見會成為
agreed審查中的一個編號修正案。新的計劃輪次適用於設計變更...