在遵循此工作流程之前，请先阅读运行时适配器。其运行时映射适用于所有引用的剧本和脚本。
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 中运行。 herdr或rex，以及 Python 3.11 或更高版本（python3），需在 PATH 中。scripts/pair.sh help列出了每个存储和通道操作；对于配对，使用它而不是手动构建的herdr或rex调用。- 以自动模式启动主智能体。Devin 默认使用
--permission-mode dangerous绕过权限。其他类型的智能体继承主智能体的模式。pair.sh permission打印检测到的主智能体模式。使用--permission <mode>或在--后的原生权限标志来覆盖默认值；--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、cwd、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 的辅助智能体。仅靠多路复用器的 settle 是不可信的：一个 Devin 辅助智能体在提示到达时和步骤之间显示空闲，并且在一个狭窄的窗格中可能显示整个运行已完成，因此 settle 会对照窗格的“esc 中断”行检查；在没有报告的情况下保持一分钟的 settle 会以 report: missing 结束等待。它们也会在签入间隔过去且辅助智能体仍在工作时返回，此时打印签入摘要而不是报告路径。当分发的简报报告一到达时，wait 也会立即返回，即使辅助智能体已经开始处理排队的简报；running: 随后会命名它正在处理的简报。notify 仅在主智能体空闲时提示它，因此等待中的主智能体永远不会被中断。你在压缩后收到的消息仍然会命名此技能和要读取的文件，因此重新加载技能并从该文件继续。
计划先行
实现仅从两个智能体都同意的计划开始。主智能体驱动实现、架构和系统设计：它起草 plans/NNN-<slug>.md，包含所选设计、它权衡的备选方案及其优缺点，然后通过 pair.sh discuss 发送。辅助智能体针对这些权衡进行头脑风暴，对每个步骤对照代码进行检查，并回答同意或反对并提供证据。主智能体在一个新的计划轮次中修改或回应反对，直到响应说同意且主智能体编写了裁决为 agreed 的审查。pair.sh dispatch 会拒绝一个 plan: 行未命名同意计划的功能、错误修复、重构、性能问题或 pstack-tdd 简报。只读和取证简报不需要计划；一个错误的诊断简报在其计划之前运行，因此计划依赖于运行时证据。三轮仍未达成一致则成为给人类的一个关卡，双方立场都在 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:行，因为将排队消息传送到 Devin 的 Enter 键会取消其正在运行的命令。--interrupt首先取消正在运行的工具调用，用于不能等待的方向调整。方向调整携带方向：同意计划未选择的方法、范围漂移、要跳过的步骤、即将越过的禁止行，或来自人类的消息。任何审查可以在结束时捕获的内容都等待审查。 - 辅助智能体同意或反对，就像对待计划一样。同意：应用，在进度日志中确认，继续。反对：编写方向调整响应，附带证据和替代方案，通知，结束本轮。主智能体用一个取代被反对方向调整的方向调整（修改或撤回）来回应，并且
pair.sh steer恢复辅助智能体。每个方向调整最多两轮；决定权在主智能体手中，持续的异议会进入一个计划轮次。 - 每个简报最多两个新的方向调整。第三个意味着简报是错误的：停止该单元并重新简报。
各种类型的任务会话
任何类型的辅助智能体（Claude、Codex、Devin、pi、Prime、Muse）在完成每个简报时都会使用全新的对话。在生成、排队、轮换或清理其存储之前，请阅读 Devin 会话生命周期 以了解 Devin 或 Pi，或阅读 Prime 适配器 以了解 Prime。部分完成和阻塞的工作保留在其会话中；完成的简报会使队列为空，等待主智能体分发。dispatch 和 discuss 会先自行轮换辅助智能体（在其输出中显示 rotated:）；pair.sh rotate 会保留给主智能体手动运行。pstack 存储在会话之间持久化。
Muse Code
对任何角色使用 --kind muse。阅读 Muse 适配器 了解其权限、信任、预检和退出处理。Muse 每个窗格保持一个对话，因此它不会按简报轮换。
Prime 智能体
对辅助智能体使用 --kind prime-agent。阅读 Prime 智能体适配器 了解原生模型参数、预检、方向调整、确切的守护进程会话清理和提供商故障转移。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审查中的一个编号修正案。新的计划轮次用于改变的设计。