Multi Agent Orchestration

Multi-Agent Orchestration

PM 式多 Agent 本地执行编排。它回答一个问题：多个 Agent 如何在同一仓库里用独立 worktree/session 并行干活，并让当前主会话作为 PM 可巡检、可收口、可控制额度消耗。

PM 是当前负责拆解、派工、验收和收口的主会话，不绑定具体产品。Codex 可以做 PM 调 Claude Code 或 OpenCode worker；Claude Code 也可以做 PM 调 Codex 或 OpenCode worker。Skill 只规定角色、隔离、启动、状态和收口协议。

1. 边界

使用本 Skill：

• 需要 2 个以上本地 Agent / Codex / Claude session 并行工作。
• 任务需要独立 worktree、独立分支、独立 PR。
• PM 会话需要启动、监控、纠偏和收口多个 worker。
• 需要把简单任务路由给 Claude Code、Codex、OpenCode 或其他 CLI worker，以控制主会话 token 和不同模型额度消耗。

不使用本 Skill：

• 单个短任务、单文件修改、一次性问答。
• 任务主状态、负责人、依赖管理：用 cross-agent-coordination。
• 分支命名、提交格式、PR merge、push、冲突解决：用 git-workflow。
• 外部 Agent 邮件触发：用对应外部协作/邮件 Skill。

2. 执行模式

优先级由项目规则决定。若用户或项目明确要求使用 tmux / 独立 session / 开 worker，进入防逃逸门禁。

2.1 防逃逸门禁

强制 session 触发条件：

• 用户明确说 tmux、独立 session、开 worker、多 Agent 并行、你做 PM / orchestrator、不要你直接写，或项目规则要求 tmux / 独立 session。
• 任务需要独立额度、长上下文、后台持续运行、人工可接管，或同时推进 2 个以上本地 worker。

触发后，PM 在任何业务实现前必须完成启动门禁： 1. 创建或确认隔离 worktree、语义分支和 Session Context 路径。 2. 启动 tmux session；Claude 官方 --worktree --tmux 可作为 Claude 专用等价入口。 3. 用 tmux has-session / tmux list-sessions / claude agents --json 验证 session 存活，并确认 pane cwd 或 agent cwd 指向目标 worktree。 4. 给 worker 发送 Bootstrap-only prompt 或 Full worker prompt，prompt 必须包含 Branch、Worktree、Session Context、Runtime Profile、Allowed files、Forbidden files 和验证命令。 5. 在 1-2 分钟内确认 STATUS.json 出现；若未出现，只能发送 checkpoint-only 纠偏或重启 worker，不得直接接管业务实现。

降级规则：

• 显式要求 tmux 时，Agent Teams、Subagent、PM 直接处理都不是等价替代；除非用户明确同意降级。
• 显式要求独立 session 但未指定 tmux 时，默认使用 tmux；Claude 官方 --worktree --tmux 可用。Agent view / Agent Teams 只有在能证明独立后台会话、独立 cwd/worktree 和可巡检状态时才可替代。
• 门禁失败时，PM 必须报告阻塞和失败点；允许直接修改的仅限 worker prompt、Skill 文档、监控脚本或本地协作配置等编排层文件。
• 若 PM 触发例外直接处理业务代码，最终汇报必须写明例外原因、未使用 session 的具体门禁失败点和用户是否批准降级。

2.2 角色与后端

先分清角色，再选择后端：

PM 代理纪律：

• 如果用户明确要求当前会话做 PM / orchestrator / 多 Agent 编排，PM 默认不直接写业务代码；若同时触发 §2.1，必须先通过启动门禁。
• PM 的核心价值是 token efficiency、模型/额度路由、多线程推进、范围控制和验收收口；实现任务优先派给 worktree worker、独立 CLI session、Agent Teams 或 Subagent。
• PM 可以直接改代码的例外：任务极小且无并行价值、用户明确要求 PM 直接做、worker 连续纠偏失败且只剩窄范围收口、或需要立即修复 PM 自己生成的 orchestration 文档/配置。显式 tmux / 独立 session 要求下，这些例外必须先取得用户确认或记录门禁失败。
• PM 如果越过例外直接下场改代码，应在最终汇报说明原因；常规实现应通过 worker 产物、PM 纠偏和 PR review 完成。

后端选择规则：

• 当前主会话是什么不重要；默认“谁启动编排，谁就是 PM”。
• 需要通过第三方 Anthropic-compatible API 启动 Claude Code 时，worker backend 选 Claude Code；这是 Claude Code worker 的默认额度模式。
• 只有用户明确要走 Claude 订阅/OAuth 时，才使用 claude-oauth-* profile，并清理第三方 provider 环境变量。
• 需要消耗 Codex / OpenAI 额度或使用 Codex 配置时，worker backend 选 Codex。
• 需要消耗 OpenCode 已配置的 provider/model，或要使用 OpenCode 的 opencode run / opencode acp 能力时，worker backend 选 OpenCode。
• 其他 Agent 只要能用一行命令启动，并能在指定 cwd 读写文件，也可作为 custom CLI worker。
• 需要稳定进程生命周期和人工接管时，优先 tmux + worktree；触发 §2.1 时，tmux + worktree 是默认执行层，不是可静默跳过的建议。
• ACP 只在 adapter 已稳定、能输出结构化状态时启用；没有 adapter 时不要为了协议增加不确定性。

环境/profile 纪律：

• PM 启动 worker 时必须显式写 Runtime Profile、settings/profile 路径、模型来源和关键环境变量处理方式，不假定 Claude Code、Codex、OpenCode 共享同一套 shell 环境。
• Claude Code 第三方 API provider profile 要保留 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / 默认模型映射；不要套用 OAuth 的清理命令。
• Claude Code 订阅/OAuth profile 才清理第三方 provider 环境变量，避免误走外部 API。
• Codex / OpenAI worker、OpenCode worker 和 custom CLI worker 使用各自 profile；不要把 Anthropic provider 环境变量当作通用 worker 环境。
• Worker bootstrap 必须把 which claude/codex/opencode、版本号、cwd、关键 profile 名和 node/npm/python/cargo 等运行信息写入 STATUS.json，便于 PM 判断“环境不一样”是否影响任务。

2.3 同宿主优先：不默认跨 Agent 工具

默认让 worker 与 PM 跑在同一个 Agent 工具里：Claude Code 做 PM 就用 Claude Code worker，Codex 做 PM 就用 Codex worker，OpenCode 同理。不要为了"分流额度"默认把 worker 路由到另一种 Agent 工具。 这条优先于 §2.2 的多 backend 路由建议。

为什么默认同宿主：

• 同宿主 worker 共用一套 auth / settings / 上下文约定，启动和排障成本最低；跨工具会引入不同 profile、不同 env、不同 CLI 行为，编排层不确定性上升。
• 多 Agent 的核心收益是并行 + 范围隔离（独立 worktree / session）+ PM 收口，不是"跨工具"。并行价值来自独立 worktree / session / 额度 lane，与是否换工具无关。
• 跨工具只在有明确理由时才用（见下），不是默认。

同宿主 worker 的 auth 约定（重要，避免误判环境）：

• Claude Code PM 启动 Claude Code worker 时，worker claude 进程继承 PM 的 provider env（第三方 API 的 ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL，或 OAuth 会话）。即使目标 worktree 的 .claude/settings.json 为空或缺省，worker 也能用 PM 的 provider 跑起来，*不需要额外的 `config/.settings.json`**。
• 只有当需要把多个 Claude Code worker 分到不同 provider（例如一部分走 minimax、一部分走 glm）时，才用不同 settings 文件区分 slot；此时仍全部是 Claude Code worker，没有跨工具。
• 判断"worker 是否拿到 provider env"的标准：worker bootstrap 把可用 claude 版本和 provider 来源写进 STATUS.json；PM 看到 provider 来源为空或报 401/403 时，再决定是补 settings 还是降级，而不是默认先跨工具。

何时可以跨工具（例外，不是默认）：

• 当前宿主 provider 额度 / 限流 / 并发槽位不足以支撑本 Wave，且无法靠"降并发 / 拆下一 Wave"解决。
• 某个 worker 任务明显更适合另一种工具的模型能力（例如超长上下文研究、特定代码栈）。
• 用户明确要求混合 worker（例如"Claude Code 做 PM，重写 worker 用 Codex"）。

触发跨工具时的硬要求：PM 必须在 Wave 计划里写明为什么跨、每个 worker 的 backend / profile / auth 来源，以及跨工具带来的额外排障点。§3.1 的 provider slot 分配仍适用，但 slot 默认全部落在 PM 宿主工具上；跨工具 slot 是显式例外，需要在 Wave 摘要里标注。

3. 标准流程

1. 读任务源与项目配置：若项目提供 .claude/orchestration.config.json 或等价配置，先读取 trunk、任务源、验证命令、可复制配置和 hook 边界；再用 cross-agent-coordination 判断可执行项、依赖和归属。 2. 先分组：不要默认一个 Issue 一个 worker。文件范围重叠、同一章节/模块、存在依赖链的任务应同组顺序执行。 3. 判定并行安全：只有文件范围清晰、无共享迁移/锁文件/schema、验收标准独立时才拆成多个 worktree 并行。 4. 判定是否触发防逃逸门禁：只要用户或项目明确要求 tmux / 独立 session / 开 worker，按 §2.1 执行；门禁未通过前不写业务代码。 5. 选择 worker backend 和 runtime profile：按任务复杂度、当前额度、模型偏好和是否需要独立进程，选择 Claude Code / Codex / OpenCode / custom CLI / shell / ACP。 6. PM 创建隔离环境：默认由 PM 创建 worktree、分支和 session context 目录，再把路径交给 worker；只有 Claude Code 官方 Agent Teams / agent view 明确使用自身 --worktree 能力时，才允许由 Claude Code 创建，但 PM 仍要验收分支、路径和隔离状态。 7. 启动 worker 并验证门禁：给每个 worker 明确目标文件、允许修改范围、验证命令、session context 目录、提交和 PR 要求；确认 session 存活、cwd/branch 正确、STATUS.json 出现或已发送 bootstrap correction。 8. PM 巡检：优先查看 .claude/agent-sessions/<session-id>/STATUS.json、RESULT.md、PATCH_SUMMARY.md、git status、commit/PR 状态；Claude 官方 Agent Teams 则优先读取 ~/.claude/teams/<team>/ 和 ~/.claude/tasks/<team>/，claude agents --json、tmux pane 或 agent view 作为兜底观察。发现偏题、阻塞、范围扩大或无阶段性提交时介入。 9. PM 验收而非代写：PM 对 worker 结果做范围检查、测试复核和 review；发现问题优先发纠偏指令或派给 reviewer/另一个 worker，不默认自己改业务代码。 10. 收口：worker 提交并开 PR 后，PM 做范围检查、触发 review、按 git-workflow 合并和清理。 11. PM 必做实操验证：任何软件功能修改（不论 L1/L2/L3）worker 声称"完成"前，PM 必须真正启动 dev server（Vite dev / Tauri dev / 对应入口），用 Playwright MCP 或截图实际打开应用、点击按钮、切换 tab、调整窗口、输入文本，把验证证据（DOM 测量、关键断言、截图）写入 goal-contract.md 或对应 RESULT.md。仅靠 typecheck / 单测 / lint / build 全部通过就宣称"完成"是不充分的——这些只证明"代码能编译"，不证明"功能真的能用"。

3.1 Wave-Based Orchestration

Wave 是在同一 base ref、同一批冲突假设下启动的一组并行 worker。它用来记录“本项目已经并行推进过几轮”、控制并发风险，并让 PM 在每轮结束后复盘 provider/model 表现。

Wave 启动前，PM 必须写清：

• wave_id、base ref、目标、worker 清单、每个 worker 的分支/worktree/session。
• 每个 worker 的类型：ui-wiring（低风险 UI 接线）、contract-extension（共享契约/依赖变更）、tauri-command（Rust/Tauri/本机依赖）、docs/research、custom。
• runtime profile / provider / model / settings/profile 路径 / 额度来源 / 并发槽位。超过 3-4 个 worker 时，不要压在单一 API provider 或同一个 settings 文件上；应跨 Claude provider、Codex/OpenAI、OpenCode、local/OSS 等 profile 分流。
• 共享风险：package.json、锁文件、src-tauri/、src/shared/、全局布局、DEC 编号或同一模块入口。
• 预期 PR 数、收口顺序、下一 Wave 进入条件。

并发数量不是固定 3 个。文件范围独立、验证命令独立、无共享契约冲突时，默认目标可提高到 4-6 个 worker；纯文档、翻译、i18n、互不重叠 UI 接线可以更多。涉及共享依赖、锁文件、Tauri command、全局布局、DEC race 或同一模块入口时，降到 1-3 个并按依赖顺序推进。

Provider slot 分配是 PM 的显式规划，不是脚本自动猜测：

• 一个 slot 表示一条可并发额度 lane：backend + settings/profile path + provider + model + max_concurrency。
• Claude Code 第三方 provider 用具体 settings 文件区分，例如 config/minimax-M3.settings.json、config/glm-5.2.settings.json；真实 settings 文件保持本地 ignored，不提交。
• Codex 用 Codex profile / model 区分；OpenCode 用 provider/model profile 区分；custom worker 写明实际命令来源。
• 默认同一 provider/settings 文件最多放 3 个 worker；只有低风险任务且上一 Wave 表现稳定时才放到 4 个。需要 5-6 个 worker 时，优先拆到第二 provider 或 Codex/OpenCode/local profile。
• 高风险任务（共享契约、Tauri/Rust、本机依赖、锁文件）优先给上一 Wave 指令遵循和验证表现最好的 profile，且每个高风险共享域通常只开 1 个 worker。
• 如果本机只有一个可用 settings/profile，不要为了凑人数启动 5-6 个 worker；把并发 cap 降到 3-4，剩余任务进入下一 Wave。

6-worker 示例：

Wave 收口时，PM 记录每个 worker 的 merged / done-unmerged / blocked / deferred / restarted，并评估模型/provider 表现：Isolation Gate、STATUS 心跳、commit 节奏、范围遵循、验证通过率、review 修复次数、diff 质量、阻塞/幻觉/环境误判。下一 Wave 根据该评估调整任务分配：高风险任务给指令遵循和工程可靠性更好的 profile，低风险重复任务给成本或吞吐更优的 profile。

3.2 Goal-Driven Multi-Wave Loop

Orchestration Goal 是 PM 层目标循环，用来让多轮 Wave 在条件满足前持续推进。它不把所有任务交给单个 worker；PM 仍按 Wave 从任务源取下一批安全可并行项，worker 仍只执行自己的窄范围任务。

启动 Goal Loop 前，PM 必须写清 Goal Contract，模板见 templates/orchestration-goal.md：

• 任务源：如 docs/TASKS.md、GitHub Issues、项目配置中的 issue file。
• 成功条件：例如目标范围内没有可执行 pending task、所有已启动 worker 都进入 merged / done-unmerged / blocked / deferred，主干验证通过，文档已同步。
• 自主级别：plan-only（只规划下一 Wave）、auto-launch（可自动开下一 Wave）、auto-review（可自动复核 worker 结果）、auto-merge（在项目规则允许时按 git-workflow 合并）。
• 上限：最大 wave 数、每轮最大 worker、总 worker、预算/时间、provider 并发槽位。
• 继续条件和停止条件。

PM 可在支持的宿主中使用 Claude Code / Codex 的 /goal 来包住 PM loop，但 /goal 只负责让 PM 持续执行循环，不替代本 Skill 的 worktree、tmux、checkpoint、review 和 merge 门禁。Goal prompt 必须写明“PM 不直接实现业务代码；实现仍由 worker 完成”。

每轮 Wave 收口后，PM 按以下顺序决定是否自动继续： 1. 读取任务源，关闭已完成项，识别可执行 pending task、依赖、文件范围和共享风险。 2. 确认当前 Wave 没有未处理的 failed/blocked worker、未验收 PR、base drift、冲突、主干验证失败或敏感/破坏性操作。 3. 根据上一 Wave 的 provider/model 评估调整并发：干净通过可维持或小幅增加，出现冲突、范围越界、验证失败或限流则降并发。 4. 若仍有可安全并行的任务，创建下一 Wave；若只剩高冲突/高风险任务，降为 1-2 个 worker 或停下请求用户确认。 5. 若成功条件满足，写 final goal summary 并停止。

自动继续条件：

• 上一 Wave 的 worker 均为 merged、done-unmerged、deferred 或明确 blocked 且不会影响下一 Wave。
• 所有合并动作已按 git-workflow 处理，base ref、本地主干和远端主干一致或已明确记录差异。
• 必需验证通过；跳过的验证有清楚原因且不影响下一 Wave。
• 下一批任务的 allowed/forbidden files 清晰，且没有共享锁文件、schema、全局布局或 DEC 编号 race 未解决。
• provider 并发槽位足够，且没有连续限流、长延迟或 worker 指令遵循退化。

必须停止并汇报的条件：

• 任一 worker failed、blocked 且影响下一 Wave，或连续两次纠偏无效。
• PR 冲突、base drift、主干验证失败、测试不稳定、merge 权限不足或 GitHub/CI 状态不明。
• 下一批任务需要用户产品判断、破坏性文件操作、联网敏感处理、密钥/隐私处理或项目规则未授权的自动合并。
• 任务源含糊、依赖未满足、文件范围高度重叠，或只剩共享契约/锁文件/Tauri command 等高风险任务。
• 达到 Goal Contract 的 wave、worker、时间、预算或 provider 上限。

3.3 Optional Project Config

项目可放置 .claude/orchestration.config.json，模板见 templates/project-config.json。该配置只声明项目默认值，不替代 PM 判断，也不允许静默执行破坏性动作。

配置可声明：

• trunk/base ref、任务源、默认 worktree/session context 路径。
• 按 worker type 拆分的验证命令。
• provider slot 默认计划，供 Goal/Wave 启动清单引用。
• 可复制到 worktree 的非敏感配置文件，例如 .npmrc.example 或只读模板。
• post-create / pre-merge hook 命令。

配置安全规则：

• 永远不要默认复制 .env、真实 settings、token、key、cookie、证书或账号凭证。
• allowed_config_copy 只允许非敏感文件；forbidden_config_copy 命中时必须停止并报告。
• hook 默认只是声明。PM 只有在项目规则或用户明确授权时才运行；运行前应展示命令，必要时先 dry-run。
• spawn-worker.sh 不自动读取项目配置、不自动复制配置、不自动执行 hook，避免把可选约定升级成隐式副作用。
• 若配置缺失或字段不清楚，PM 回到 Skill 默认值：trunk=main、不复制配置、不跑 hook、只使用 worker prompt 明确列出的验证命令。

4. 命名规则

分支名面向远端协作和 PR，必须体现任务语义，不写执行来源。

docs/ch01-agent-intro
research/issue-13-ch08-materials
fix/agent-session-shell

worktree 路径只用于本地隔离，应加执行来源前缀：

.claude/worktrees/tmux-ch01-agent-intro
.claude/worktrees/team-agent-session-shell
.claude/worktrees/subagent-copyedit-ch02

不要把 tmux-、subagent-、team-、agentteam- 写进分支名。分支类型前缀和提交/PR 格式以 git-workflow 为准。

创建示例：

git worktree add .claude/worktrees/tmux-ch01-agent-intro -b docs/ch01-agent-intro
git worktree add .claude/worktrees/team-agent-shell -b fix/agent-session-shell

4.1 Session Context 目录

Worker 的本地状态统一写到当前 worktree 的 .claude/agent-sessions/<session-id>/（下文简称 Session Context），复用项目既有 .claude/ 协作空间，与 Claude Code 官方 Agent Teams 状态源明确区分。

.claude/agent-sessions/legal-ch01/METADATA.json
.claude/agent-sessions/legal-ch01/STATUS.json
.claude/agent-sessions/legal-ch01/RESULT.md
.claude/agent-sessions/legal-ch01/PATCH_SUMMARY.md

Claude Code 官方 Agent Teams 是另一套机制：团队配置在用户目录 ~/.claude/teams/<team-name>/config.json，任务状态在 ~/.claude/tasks/<team-name>/，inbox 在 ~/.claude/teams/<team-name>/inboxes/。使用官方 Agent Teams 时优先读写这些官方状态源；不要在项目里自造 .claude/teams/ 来冒充官方 team。

.claude/agent-sessions/ 是 PM 巡检状态，不属于业务 diff。PM 和 worker 都必须确认它不进入 commit / push / PR；需要时由 PM 在对应 worktree 的本地 exclude 中忽略。

5. Worker Prompt 模板

Worker prompt 应像启动 subagent 一样给足上下文：任务来源、验收标准、允许文件、禁止文件、验证命令、checkpoint 协议、隔离自检和 PM 纠偏协议都要写清。不要只给一句“实现某功能”，否则 worker 容易把环境、依赖或相关技术债扩展成自己的任务。

模板放在 templates/worker-prompt.md，包含两个可复制段落：

• Bootstrap-only prompt：只创建 STATUS.json，适合高延迟 provider 或 high-effort 模型的第一条消息。
• Full worker prompt：按 Context / Background / Mission / Scope / Deliverables / Process / Verification / Autonomy / Out of Scope / PM Correction 组织，接近派发 subagent 时的写法。

对高延迟 provider 或 high-effort 模型，优先用两段式启动：第一条消息使用 Bootstrap-only prompt 创建 Session Context/STATUS.json 并回报 runtime；PM 确认 checkpoint 后，再发送 Full worker prompt。这样能避免 worker 在长思考前没有可观测状态。

5.1 模板使用纪律（必读，实测踩坑）

PM 派 worker 时必须以 `templates/worker-prompt.md` 的 Full Worker Prompt 为骨架，把业务任务（Issue / 任务卡 / .task-issueN.md 内容）填进 Background / Mission / Scope / Deliverables / Verification 字段。不要用自定义简化 prompt（例如只写一个 BOOTSTRAP.md 指向业务 `.task` 文件）替代模板骨架——即便业务 .task 文件写得很细，没有模板骨架的编排层硬约束，worker 仍会在流程层失守。

模板里这些段落是 worker 可观测性和收口正确性的硬约束，省略会直接导致收口失败（以下后果均有实测对应）：

• Isolation Gate：worker 先确认 pwd / git branch，否则可能在 main 或错误 worktree 误改。
• Heartbeat cadence（每 10 分钟强制更 STATUS，即使无进展也写 `phase=thinking-deep`）：PM 靠 STATUS.updated_at 检测 silent worker。省略则 worker 写一次初始 STATUS 后再也不更新，PM 巡检信号失真、无法判断卡点。
• Commit Cadence + "commit 是强制收尾步骤"：即使任务要求"不 push / 不开 PR"，worker 也必须先 git add + git commit 自己的产出。省略则 worker 改完文件不 commit，PM 收口时 git diff --check main...HEAD 验的是空 diff（HEAD 仍在 base，假通过），PM 只能替 worker commit。rebase / reset 后尤其要重新确认改动已 commit。
• Canonical terminal status（`status="done"` 字面值）：sentinel 状态机按字面 done 匹配。省略则 worker 可能写 completed / finished 同义词，sentinel 不退出、PM 不被 harness 唤醒、worker 孤儿到 --max-wait 超时。

业务任务文件（.task-issueN.md 等）可作为 Mission / Scope 的附件让 worker 读取，但编排层骨架（Isolation Gate / Heartbeat / Commit / done 字面值）必须来自模板，不能靠业务文件或自定义 BOOTSTRAP 兜底。PM 若发现自己在手写 BOOTSTRAP 替代模板，应停下，改为套用 templates/worker-prompt.md 再派发。

6. 启动方式

默认工具面保持收敛：

• check-dependencies.sh：新机器或启动 Wave 前做一次 preflight。
• render-runtime-profile.sh：为每个 worker 渲染 backend/settings/profile/model/slot 和启动命令。
• spawn-worker.sh：创建 worktree、Session Context 和 tmux session。
• sentinel.sh：每个 worker 一个，PM 用 run_in_background=true 启，worker 终态时唤起 PM（见 §7.2）。
• pm-monitor.sh：多 worker/Wave 巡检；单 worker 或宿主唤醒才用 wait-worker.sh。

项目配置模板见 templates/project-config.json。PM 可以把其中的 trunk、验证命令和 provider slot 复制到本轮 Goal/Wave 计划，但脚本不会自动套用该配置。

其余脚本只在对应场景使用：worktree-status.sh 做只读总览，clean-worktree.sh 做 dry-run 清理，smoke-tmux-worker.sh / lint-wait-script.sh 只做 Skill 自测，terminal-split.sh 只是可选可视化辅助，不属于默认启动路径。

默认用 scripts/spawn-worker.sh 创建 worktree、Session Context 和 tmux session；它只负责隔离和启动，PM 仍必须发送 templates/worker-prompt.md 并确认 STATUS.json。不同 backend/profile 的启动命令可先用 scripts/render-runtime-profile.sh 生成，减少手写环境差异。

eval "$(bash scripts/render-runtime-profile.sh \
  --backend claude-code \
  --runtime-profile minimax \
  --api-provider minimax \
  --model claude-sonnet-4-5 \
  --provider-slot minimax-1 \
  --settings config/minimax-M3.settings.json)"

bash scripts/spawn-worker.sh \
  --project /path/to/repo \
  --branch docs/ch01-agent-intro \
  --session legal-ch01 \
  --worker-backend "$WORKER_BACKEND" \
  --runtime-profile "$RUNTIME_PROFILE" \
  --api-provider "$API_PROVIDER" \
  --model "$MODEL" \
  --provider-slot "$PROVIDER_SLOT" \
  --verify-cmd 'npm run typecheck' \
  --command "$WORKER_COMMAND"

启动后必须通过最小门禁：tmux has-session 存活、pane cwd 指向 worktree、git branch --show-current 等于目标分支、Session Context/METADATA.json 已记录 base/runtime/verification、Session Context/STATUS.json 在 1-2 分钟内出现。失败时停止 session 或发送 bootstrap correction，不要在 PM 主目录继续实现。

常用 worker command：

• Claude Code 第三方 provider：claude --settings <local-provider.settings.json> --permission-mode auto。真实 settings 不提交；模板见 config/claude-provider-settings.example.json。
• Claude Code 订阅/OAuth：env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_BASE_URL claude --permission-mode auto。
• Claude Code 批处理：claude --settings <settings> -p --output-format stream-json --permission-mode acceptEdits < /tmp/task.prompt.md。
• Codex：codex exec -a never -s danger-full-access - < /tmp/task.prompt.md。
• OpenCode：opencode run --format json --model <provider/model> "$(cat /tmp/task.prompt.md)"，或交互式 opencode --model <provider/model>。
• 自定义 CLI：任何能在指定 cwd 运行、接收 prompt、落盘 checkpoint 的命令。

`<` redirect 必须用 `bash -lc` 包（FaroPDF Wave 1 实战，见 [DEC-033]）：spawn-worker.sh:305 内部 tmux new-session -d -s "$SESSION" -c "$WORKTREE" "$COMMAND" 直接 exec command（不通过 shell），< / > / | / && 等 shell metachar 不展开。如果 --command 含 < 重定向，必须包 bash -lc 'real-command < /tmp/prompt.md'，否则 worker 进程拿不到 stdin 立即退出，sentinel 等 --max-wait 才 timeout。错误：--command 'claude -p < /tmp/x.md'；正确：--command "bash -lc 'claude -p < /tmp/x.md'"。

claude `-p` batch 模式有 autocompact thrash 风险（FaroPDF Wave 1 实战，见 [DEC-033]）：-p 是 print-and-exit 一发跑完模式，PM 无法中途纠偏。大 prompt（> 5KB）+ 大项目 codebase 会触发 claude 内部 Autocompact is thrashing 3 次后自动终止，worker 永远不到达终态，sentinel 等到 --max-wait。规避：（a）拆小 prompt < 3KB；（b）改用交互式 claude + tmux send-keys 投递 prompt（可纠偏）；（c）窄 scope worker（避免 claude 加载整个 codebase context）。

不要设 `--max-turns`：PM 重点是检测 worker 是否真在推进，而不是限制 turn 数。长任务通过 STATUS.json.updated_at、阶段性 commit、pm-monitor.sh stale 事件和 PM 纠偏控制。

Claude Code agent view / 官方后台会话可作为 Claude 专用后端：claude agents、claude agents --json、版本支持时的 --worktree --tmux、--bg 或 /bg。使用前以本机 claude --help / claude agents --help 为准；只有能证明独立 cwd/worktree、可巡检状态和可接管会话时，才可替代 tmux。

Agent Teams 适合 Claude Code 团队式协作；仍要使用 worktree 隔离并把 workdir 指向带来源前缀的 worktree。ACP 只在 adapter 已稳定、能输出结构化状态时启用。Subagent 仅用于轻量、边界窄、输入少的任务；需要长时间写作、独立提交 PR 或跨大量材料整合时升级为 tmux / agent view / Agent Teams。

7. 巡检与介入

PM 巡检信号：

• worktree 是否有文件落盘、commit、PR。
• .claude/agent-sessions/<session-id>/METADATA.json 是否记录 base ref、runtime profile、provider slot、验证命令和 PR 占位。
• .claude/agent-sessions/<session-id>/STATUS.json 是否更新，是否报告 blocked / needs_input / done。
• .claude/agent-sessions/<session-id>/RESULT.md 和 PATCH_SUMMARY.md 是否存在，摘要是否足够 PM 不读完整日志也能验收。
• tmux pane 是否长时间只读材料、等待确认、偏题联网、反复规划不执行。
• worker 是否扩大改动范围或触碰共享文件。
• PR diff 是否只覆盖声明范围。

介入规则：

• 有持续输出、checkpoint 更新或文件在增长时继续等待。
• 启动后 1-2 分钟仍没有 Session Context/STATUS.json 时，先发送 checkpoint-only 纠偏；仍无响应时中断当前思考并重发 bootstrap 指令，不直接接管实现。
• 长时间无落盘但仍在规划时，先发送更窄的“先写目标文件”命令。
• worker 跳过 10-15 分钟 STATUS 心跳或 30-60 分钟阶段性 commit 时，PM 主动发送纠偏，要求立刻更新 STATUS 或提交当前已验证阶段；5 分钟内仍无 STATUS/commit/文件进展变化时，升级为重启 worker、派 reviewer 或 PM 窄范围收口。
• 发现轻度偏题、范围扩大、开始修环境/依赖、等待确认或验证方式偏离时，优先通过 tmux / agent view / inbox 发送纠偏指令，让 worker 自己回到范围内执行。
• 只有连续两次纠偏无效、worker 继续触碰禁止范围、准备执行破坏性 Git/文件操作、泄露敏感信息、或已无法在原 session 内恢复时，才停止 session 并由 PM 接管。
• 失败、重启或停止前先保留 worktree 和 Session Context，避免丢失已落盘产物。

tmux 纠偏示例：

tmux send-keys -t legal-ch01 -l -- "PM correction: stop dependency/runtime changes now. Return to ISS-017 only. Do not modify package files or environment config. Update .claude/agent-sessions/legal-ch01/STATUS.json with needs_input=false and continue with the OCR quality report scope."
sleep 0.1
tmux send-keys -t legal-ch01 Enter

纠偏 prompt 应包含四件事：停止什么、回到哪个任务、哪些文件/动作仍然禁止、下一步最小可执行动作。不要只写“你偏题了”。

完整字段见 references/03-checkpoint-files.md，可复制模板见 templates/checkpoint-status.json、templates/checkpoint-result.md 和 templates/checkpoint-patch-summary.md。PM 默认只读这些 checkpoint 和最终 diff，不定时拉完整日志。

可选自动 PM 监控脚本（保留 Agent Teams inbox、任务状态、Git SHA、PR 状态和 tmux session 多维巡检能力）：

bash scripts/pm-monitor.sh \
  --project /path/to/repo \
  --team-dir ~/.claude/teams/team-name \
  --tasks-dir ~/.claude/tasks/tasks-uuid \
  --claude-agents-cwd /path/to/repo \
  --wave-id wave-5 \
  --commit-stale-threshold 1800 \
  --progress-stale-threshold 1800 \
  --interval 60 \
  --log-file .claude/agent-sessions/pm-monitor/events.log \
  --branch docs/ch01-agent-intro:legal-ch01

经济型巡检规则：

• 不要让 PM 主会话每隔几分钟手动读取 worker 日志；那会抵消多 Agent 的 token efficiency。
• 轻量检查用 pm-monitor.sh --once，由 PM 在需要判断是否介入时运行一次，只读取事件行。
• 长任务用独立 shell/tmux/background job 运行 pm-monitor.sh --log-file ...，脚本持续写事件日志；PM 只在状态变化、用户询问、PR 收口或日志出现 AGENT_NEEDS_INPUT / CHECKPOINT_STALE / CHECKPOINT_TEST_FAILURE 时读取少量日志。
• 当前脚本只负责输出事件和写日志；是否自动唤起 PM 取决于宿主环境是否提供 automation / monitor / webhook。没有宿主唤醒能力时，默认用 --once 或低频读取 log tail，仍比前台反复巡检节省上下文。
• STATUS.json 只记录 PM 决策必需的结构化信号，详细实现说明继续写 RESULT.md 和 PATCH_SUMMARY.md。
• 单个 worker 的只读总览用 scripts/worktree-status.sh；清理用 scripts/clean-worktree.sh，默认 dry-run，真正删除必须显式 --execute。

7.1 主动等待与宿主唤醒

scripts/wait-worker.sh 是单 worker 等待器，不替代 pm-monitor.sh。它主读一个 STATUS.json，在 done、failed、blocked 或 stopped 时退出并输出 RESULT.md / PATCH_SUMMARY.md 路径。适合把“worker 完成时通知 PM”接到不同宿主。

状态源分层：

• METADATA.json 是 PM 启动时写入的静态上下文，记录 base/runtime/provider/verification，不作为完成判定。
• STATUS.json / RESULT.md / PATCH_SUMMARY.md 是完成、阻塞、验证和收口的主协议。
• tmux capture-pane 是诊断窗口，只在 checkpoint 缺失、过期、终态或显式要求时读取尾部输出。
• 不用 tmux pane 文本判断任务完成；完成标准仍是 checkpoint、git diff、验证和 PR 状态。

Claude Code PM：

• Bash background/run-in-background 只能让等待器在后台运行，不保证触发或唤醒当前 PM / agent session；多 worker 同时等待时尤其可能没有任何完成消息返回。
• 不要把 background Bash 当作可靠完成通知机制。它最多作为日志写入器或人工可查看的后台 job；PM 仍必须靠 STATUS.json、pm-monitor.sh --log-file、wait-worker.sh --once、tmux/agent view 显式巡检来收口。
• 单 worker 可临时用 background Bash 跑 wait-worker.sh，但启动时必须同时记录 log 文件或保留可查询命令；多 worker / Wave 默认使用 pm-monitor.sh --log-file，不要为每个 worker 启一个 background wait 并期待宿主逐个回调。
• 限定条件例外：§7.2 描述的 Sentinel 模式是本规则的"限定条件下可工作变体"——单 worker 单 sentinel、run_in_background=true 启、harness 100% re-invoke 可工作。Wave 6 启用 sentinel 之前仍按上述保守判断走。

  bash scripts/wait-worker.sh \
    --worktree .claude/worktrees/tmux-ch01-agent-intro \
    --session legal-ch01 \
    --tmux-session legal-ch01 \
    --interval 30

Codex PM：

• Codex CLI 的后台 shell 不会自动把完成事件推回当前对话；不要假定它等价于 Claude Code run_in_background。
• 在 Codex App 中，优先把 wait-worker.sh --once 接到当前 thread 的 heartbeat automation；完整 prompt 见 templates/codex-heartbeat-wait.md。创建、修改或删除 automation 时必须先查找并使用 automation_update 工具，不手写 raw RRULE。
• 没有 heartbeat/automation 能力时，Codex PM 使用 pm-monitor.sh --once 或 wait-worker.sh --once 低频手动巡检；长任务仍用 pm-monitor.sh --log-file 持续记录事件。

wait-worker.sh 的职责是等一个 worker 到终态；它输出终态，不负责唤醒宿主。多 worker、PR 状态、git SHA、gate 和 stale 事件仍由 pm-monitor.sh 负责。

7.2 Sentinel bash 模式（事件驱动 PM 唤醒）

适用：Wave 6 之后，每个 worker 配套启一个 sentinel，PM 由 harness task-notification

事件驱动地唤醒，零 idle token 消耗，保留多轮纠偏能力。设计依据见

references/04-sentinel-design.md；DEC-031 supersede DEC-030 的限定条件判断。

模式：每个 worker 配一个 scripts/sentinel.sh 进程。Sentinel 轮询 STATUS.json， 读到 done | failed | blocked | stopped 时 capture tmux pane tail、tmux kill-session、 exit。Sentinel 由 PM 用 run_in_background=true 启，exit 触发 harness task-notification → PM 被 re-invoke。

PM 端调用模式：每 worker 两次 Bash 调用：

# 1) Foreground: 创建 worktree + 启动 worker + 拿 gate 验证
bash scripts/spawn-worker.sh \
  --project /path/to/repo \
  --branch docs/ch01-agent-intro \
  --session legal-ch01 \
  --with-sentinel \  # 仅打印 SPAWN_WORKER_SENTINEL_CMD，不在内部启
  --command "$WORKER_COMMAND"

# 2) Background: sentinel 事件驱动 wake
# 从 spawn-worker.sh 输出里复制 SPAWN_WORKER_SENTINEL_CMD 那行
bash scripts/sentinel.sh \
  --status-file .claude/worktrees/tmux-docs-ch01-agent-intro/.claude/agent-sessions/legal-ch01/STATUS.json \
  --tmux-session legal-ch01 \
  --poll-interval 5 \
  --max-wait 7200
# ↑ 用 Bash run_in_background=true 启

为什么不在 spawn-worker.sh 内部启 sentinel：

• spawn-worker.sh 是 fg 工具，sentinel 是 bg 工具，职责分离
• 避免单 Bash 调用内 fork 多个 background（auto mode 拒率更高）
• PM 显式 opt-in 收 sentinel 通知（run_in_background=true）是 harness re-invoke 的前提

Sentinel 事件命名空间（独立于 WAIT_WORKER_*）：

PM 收到 notification 后的标准动作见 templates/pm-sentinel-response.md：

• Exit 0 = done：读 RESULT/PATCH_SUMMARY，跑 verify，review，merge
• Exit 2 = failed/blocked/stopped：读 STATUS.issues 决定 restart / block / defer
• Exit 124 = timeout：检查 worker tmux + STATUS 状态，纠偏或重启
• Exit 64 = usage error：检查 --status-file / --tmux-session 与 spawn-worker 一致性

降级路径：如果 sentinel 没启起来（auto mode 拒 / SIGKILL / 参数错），PM 回到 §7.1 行为：单 worker 用 wait-worker.sh --once，多 worker 用 pm-monitor.sh --log-file。 降级是 graceful 的，不是失败。

调优建议：

• --poll-interval：默认 5s。worker 单次 thinking 短时降到 1s，长时保持 5s
• --max-wait：默认 7200s（2h）。长 worker 拆 sub-task，每个 sub-task 自己的 max-wait
• --keep-tmux-on-terminal：review 阶段不杀 tmux，便于 PM tmux capture-pane 看 worker 收尾
• --pane-tail-lines 0：不需要 pane 快照时关掉，少 1 个 tmux capture-pane 调用

已知不覆盖：

• 多 sentinel 对单 worker 去重：PM 行为层保证 1:1
• Codex / OpenCode 路径：暂未实测，Codex 走 templates/codex-heartbeat-wait.md
• 高频 polling 风暴：worker 集群大、polling 间隔 < 2s 时单 worker CPU 可能略高，按需调

8. 收口

8.0 PM 在 Worker 提 PR 后的持续同步

worker 提 PR 不是 PM 收口完成的信号。从提 PR 到合并之间，PM 必须做两件事避免外部抢跑：

1. 提 PR 之后立即跑 mergeable 检查：

   gh pr view <N> --json state,mergeable,mergeStateStatus,baseRefName,headRefName

• mergeable=CONFLICTING / mergeStateStatus=DIRTY / baseRefName 落后：base 已被 doc-curator 或其他 PR 抢跑。立即按 git-workflow 的「base 落后 / 冲突处理」决策表（update branch vs rebase vs close-and-reopen）处理。
• mergeable=MERGEABLE 且 base 是最新：进入 review 流程。

2. PM 本地 main 立即 push：

• PM 在主目录 commit docs / DEC 之后立即 git push origin main，避免本地与 origin/main drift。
• drift 后 push 报 non-fast-forward，squash merge 引入的"内容相同但 history 不同"会让 git 误判冲突，恢复成本高。
• 看到 origin/main 领先本地时，先 git fetch origin + git switch -C main origin/main（不是 git pull，squash commit 不会自动 ff），再继续 PM 工作。

worker backend 选择（subagent / tmux / Agent Teams）见 §2.1。

8.1 收口标准步骤

worker 完成后： 1. 检查 git status --short、git diff --check main...HEAD、PR diff 范围。 2. 需要 review 时交叉审阅，分支作者不审自己的 PR。review 工具按项目类型选，不要默认 code-review：代码项目用 code-review subagent；书稿 / 文档 / 写作项目用 writing-reviewer（或项目领域审稿 skill）；研究 / 配置类 PR 用对应内容审查。项目应在自己的 AGENTS.md 里写明用哪个 review skill；没写时 PM 按项目性质判断，不假定 code-review。 3. 合并、push、PR 编号写入 commit、Issue 关闭等动作遵循 git-workflow。 4. 若 PM review 发现问题，优先通过 tmux / agent view / inbox 给原 worker 发送 review correction；worker 应追加修复 commit、重新运行验证并更新 PR，不由 PM 默认代写。 5. PM 复核 correction commit、验证结果和 PR diff 后，再决定是否进入 merge。 6. 合并后清理 worktree/session，先 dry-run 再显式执行：

bash scripts/clean-worktree.sh --project /path/to/repo --branch docs/ch01-agent-intro --session legal-ch01
bash scripts/clean-worktree.sh --project /path/to/repo --branch docs/ch01-agent-intro --session legal-ch01 --execute

9. 依赖

依赖按模式分层；只读文档不需要安装任何工具。首次在新机器上启动 worker 前，先运行：

bash scripts/check-dependencies.sh
bash scripts/check-dependencies.sh --backend claude-code --backend codex --check-gh

最小本地执行依赖

常见 Unix 工具如 awk、sed、grep、find、stat、date、mktemp 通常由系统提供；日期解析已兼容 macOS/Linux。

按模式启用的依赖

可选终端依赖

scripts/terminal-split.sh 只在对应终端场景下需要额外工具：Kitty 需要 kitty @，WezTerm 需要 wezterm cli，macOS GUI 终端自动化依赖 osascript，Warp/Ghostty/Zed/Terminal.app 分屏或新标签能力取决于本机应用和辅助功能授权。

完整依赖矩阵见 references/02-runtime-dependencies.md。依赖检查脚本只报告状态，不安装软件、不启动 worker、不改配置。

10. 参考

只在需要细节时读取：

核心编排参考（机制 / 依赖 / 收口）：

• references/01-model-selection-matrix.md：模型与执行模式选择。
• references/02-runtime-dependencies.md：按模式拆分的本地依赖矩阵和安装建议。
• references/03-checkpoint-files.md：STATUS.json、RESULT.md、PATCH_SUMMARY.md 的字段和模板。
• references/04-sentinel-design.md：PM 巡检（sentinel）bash 模式设计与信号。
• references/05-legal-domain-patterns.md：法律项目拆解样例（诉讼/非诉阶段模型、任务字段、Agent 路由）。
• config/claude-provider-settings.example.json：Claude Code 第三方 API provider settings 模板。

Agent CLI worker backend（先看总览，再查具体工具）：

• references/06-agent-cli-reference.md：本机所有 Agent CLI 完整参考手册（Claude Code / Codex / OpenCode / Hermes / Kimi / Gemini / QoderWork），含参数速查、tmux worker 模板、跨 CLI 对比矩阵和选用建议。
• references/07-qoderwork-cli-worker.md：QoderWork CLI（qoderclicn）作为 worker backend 的可行性研究，含 CLI 参数、模型列表、SDK 环境冲突、tmux 启动示例和适用场景。
• references/08-workbuddy-cli-worker.md：WorkBuddy / CodeBuddy CLI（codebuddy）作为 worker backend 的可行性研究，含 Kimi K2.6 书稿 worker 实测、权限模式、checkpoint/path 偏差和收口规则。

实战经验与排障：

• references/09-parallel-lessons.md：tmux/Agent Teams 实战坑点。
• references/10-agent-teams-troubleshooting.md：Agent Teams / agent view / Claude 原生 --worktree --tmux 后端排障。

官方文档：

• Claude Code agent view: https://code.claude.com/docs/en/agent-view
• Claude Code worktrees: https://code.claude.com/docs/en/worktrees
• Claude Code CLI usage: https://code.claude.com/docs/en/cli-usage
• Claude Code checkpointing: https://code.claude.com/docs/en/checkpointing

脚本：

• scripts/check-dependencies.sh：检查核心依赖、backend CLI、GitHub CLI 和终端分屏工具。
• scripts/render-runtime-profile.sh：按 backend/profile 生成 worker command、prompt context 和 spawn metadata。
• scripts/spawn-worker.sh：创建隔离 worktree、Session Context 和 tmux session，并输出启动 gate。
• scripts/pm-monitor.sh：自动 PM 巡检脚本，保留 checkpoint 文件、Agent Teams inbox、tasks、Git SHA、PR 状态、tmux session、Wave 和多信号进展监控。
• scripts/wait-worker.sh：单 worker 等待器，可接 Claude Code background Bash 或 Codex heartbeat automation。
• scripts/worktree-status.sh：单 worker 只读总览，展示 metadata、checkpoint、tmux 和 git 状态。
• scripts/clean-worktree.sh：worker session/worktree 安全清理，默认 dry-run，清理前展示 metadata 摘要。
• scripts/smoke-tmux-worker.sh：临时 repo 端到端 smoke test；只在修改 Skill 脚本后运行。
• scripts/smoke-provider-settings.sh：逐个验证 config/*.settings.json 能启动 Claude Code 并返回响应；新增或改 provider 后运行。
• scripts/lint-wait-script.sh：wait/monitor/custom wait 脚本 lint；只在修改 wait/monitor 脚本后运行。
• scripts/terminal-split.sh：可选可视化辅助，保留 iTerm2、Kitty、WezTerm、Warp、Ghostty、Zed、Terminal.app 支持；默认编排不依赖它。

模板：

• templates/worker-prompt.md：worker bootstrap 和完整派发 prompt 模板。
• templates/orchestration-goal.md：PM 级连续多 Wave Goal Contract 模板。
• templates/project-config.json：可选项目级编排配置模板，声明 trunk、任务源、验证命令、provider slot、非敏感配置复制和 hook 边界。
• templates/codex-heartbeat-wait.md：Codex App heartbeat 巡检 prompt。
• templates/wave-summary.md：每轮 Wave 收口和 provider/model 评估模板。
• templates/checkpoint-status.json：STATUS.json 模板。
• templates/checkpoint-result.md：完成/失败结果摘要模板。
• templates/checkpoint-patch-summary.md：PR review 用 diff 摘要模板。

Changelog

[1.16.2] - 2026-06-15

Fixed (文档层)

• `SKILL.md §6 启动方式` 加 2 段醒目警示，来源 FaroPDF v0.2 Wave 1 spawn ISS-071 worker 实战（[DEC-033]）：
• `<` redirect 必须用 `bash -lc` 包：spawn-worker.sh:305 tmux new-session -d -s "$SESSION" -c "$WORKTREE" "$COMMAND" 直接 exec command 不通过 shell，shell metacharacter 不展开。错误：--command 'claude -p < /tmp/x.md'；正确：--command "bash -lc 'claude -p < /tmp/x.md'"。
• claude `-p` batch 模式 autocompact thrash 风险：大 prompt（> 5KB）+ 大 codebase context 会触发 claude 内部 Autocompact is thrashing 3 次后自动终止，worker 永远不到达终态。规避：拆小 prompt < 3KB / 用交互式 claude + tmux send-keys / 窄 scope worker。

Reason

• 2026-06-15 FaroPDF v0.2 推进期间，PM 按 §3.1 启动 Wave 1（3 worker ISS-071/067/070 并行）。spawn ISS-071 一个验证链路，遇到 2 个 skill 层 bug：

1. --command 'claude -p < /tmp/iss-071-prompt.md' 启动后 worker 立即退出，sentinel 等 7211s 后 SENTINEL_TIMEOUT。 2. 修复 Bug 1 后 worker 真启动 + 写 STATUS.json bootstrap，4 分钟后 claude 进程 autocompact thrash 自动停止，sentinel 持续轮询。

• PM 决策取消 Wave 1，改单 session 直推 ISS-071。详见项目侧 FaroPDF/docs/DECISIONS.md DEC-104 + skill 侧 [DEC-033]。
• 本次只改文档警示，不动 spawn-worker.sh 脚本（自动检测 shell metachar 留 follow-up，避免覆盖用户的非 bash shell 选择）。

Follow-up (TASKS 已登记)

• spawn-worker.sh opt-in --shell-wrap flag 自动包 bash -lc（待证据足够时升级）
• templates/worker-prompt.md 加专门小节说明 claude -p 模式限制 + 替代方案
• memory project-multi-agent-state 补 Wave 1 / Bug A&B 经验

---

[1.16.1] - 2026-06-05

Fixed

• `scripts/sentinel.sh` synonym 兜底：case 分支接受 worker 实际写的 synonym 终态。成功终态 done|completed|finished|complete → exit 0；失败终态 failed|blocked|stopped|aborted|cancelled → exit 2。SENTINEL_UNKNOWN_STATUS 仍保留 *) 诊断 log，但不再让 worker 写 synonym 时死锁轮询到 --max-wait。

Changed

• `templates/worker-prompt.md` Process §9：新增"Canonical terminal status (mandatory)"步骤，明确 worker 终态必须用 status="done" exactly；defensively sentinel 也认 completed / finished / complete，但 worker 不得依赖 synonym。引用项目侧 DEC-060 / skill 侧 [DEC-032]。

Reason

• 来源：v1.16.0 sentinel bash 模式首次在 FaroPDF Wave 6 真用（2 worker 并行），两位 worker 写 status="completed" / status="finished" 逃过 sentinel case 分支的 done 严格判断，sentinel 持续空转，PM 收不到 harness task-notification，直到用户手动问"进度"才暴露。Spike 阶段只测了 done / failed 严格用法，没覆盖 LLM 写 synonym 的漂移。
• 验证：Wave 6 实战触发，PM 收口时 kill 2 sentinel（exit 143）+ 写双侧 patch 后已修复。Wave 7+ 工人按 worker-prompt.md §9 写 status="done"，sentinel 事件驱动链路恢复。
• 项目侧对应：FaroPDF 仓 docs/DECISIONS.md DEC-060（PR #48 / 2026-06-05）记录了实战触发 + 修复方案；本条 CHANGELOG 是 skill 侧 [DEC-032] 的实际交付记录。

[1.16.0] - 2026-06-05

Added

• Sentinel bash 模式（Task #9）：每个 worker 配一个 scripts/sentinel.sh 进程，PM 用 run_in_background=true 启，harness 在 sentinel exit 时通过 task-notification 自动 re-invoke PM，实现事件驱动 PM 唤醒，零 idle token 消耗。
• `scripts/sentinel.sh`：轮询 STATUS.json 终态（done | failed | blocked | stopped），命中后 capture tmux pane tail、tmux kill-session、exit。退出码 0/2/64/124 与 wait-worker.sh 对齐。复用 redact_sensitive_stream 内联（不抽公共库）。
• `templates/pm-sentinel-response.md`：PM 收到 sentinel task-notification 后的标准动作清单，按 exit code 分支（0=done, 2=failed/blocked/stopped, 124=timeout, 64=usage error），含范围检查、graceful 降级到 pm-monitor.sh 路径。
• `references/04-sentinel-design.md`：设计文档，复述 2026-06-05 3 phase spike 结果，解释为什么 Sentinel 模式与 DEC-030 假设不同（数量线性 / 单进程单 STATUS / 进程语义清晰 / graceful 降级）。
• `scripts/smoke-sentinel.sh`：端到端 smoke test，覆盖 done 路径（sentinel exit 0 + tmux killed + pane tail captured + redaction 工作）和 timeout 路径（sentinel exit 124 + max-wait 触发）。

Changed

• `scripts/spawn-worker.sh`：新增 --with-sentinel、--sentinel-poll-interval、--sentinel-max-wait、--keep-tmux-on-terminal 标志。--with-sentinel 启用时输出 SPAWN_WORKER_SENTINEL_CMD: ... 和 SPAWN_WORKER_RECOMMENDED_NEXT: ... 提示 PM 在下一次 Bash 调用里 run_in_background=true 启 sentinel。不在 spawn-worker 内部启 sentinel（职责分离 + 避免 auto mode 拒多 background）。
• `scripts/lint-wait-script.sh`：默认 lint 集合加入 sentinel.sh，复用现有 bash -n + substring expansion 检查。
• `SKILL.md` §6 工具面：列出 sentinel.sh；§7.1 增加脚注指向 §7.2（"§7.2 是本规则的限定条件下可工作变体"）；新增 §7.2 Sentinel bash 模式章节，描述 PM 端两次 Bash 调用模式、事件命名空间、降级路径、调优建议。
• `SKILL.md` frontmatter：version bump 1.15.1 → 1.16.0。
• `DECISIONS.md`：新增 [DEC-031] - 2026-06-05 - Sentinel bash 模式 (Task #9 实施)，限定条件下 supersede DEC-030，明确 sentinel 数 = 未完结 worker 数（线性而非 N×N）、单进程单 STATUS、graceful 降级是默认行为。DEC-030 文本保留（历史判断）。

Reason

• 来源：Wave 4/5 实际痛点——PM 用 pm-monitor.sh --log-file 巡检是 polling-based，事件驱动不闭环，PM 必须靠用户输入或低频轮询才能感知 worker 终态。Wave 5 收口时把 Task #9 标"designed, not implemented"。
• 验证：2026-06-05 30 分钟 Spike 在 Claude Code 实测 run_in_background=true Bash 任务，3 phases 全部通过——harness 不区分 exit code（0/1/124 都 re-invoke），多次并发 notification 同 turn 批处理，单 background 拒率 spike 实测 1/6，graceful 降级是默认行为。
• 结论：在限定条件下（sentinel 数线性、单进程单 STATUS、graceful 降级），run_in_background=true Bash 任务可以作为可靠的 PM 唤醒机制。Wave 6 启动时启用。

Out of Scope（避免在本次 PR 蔓延）

• Codex / OpenCode worker 的 sentinel 集成：暂未实测，Codex 走 templates/codex-heartbeat-wait.md
• 多 sentinel 对单 worker 去重：PM 行为层处理
• 重写 pm-monitor.sh（Task #6 单独 PR）

[1.15.1] - 2026-06-05

Changed

• Claude Code background wait caveat：修正 run-in-background 描述，明确 background Bash 只负责后台运行等待器，不保证把 worker 终态消息推回 PM / agent session。
• multi-worker monitoring：多 worker / Wave 默认使用 pm-monitor.sh --log-file + 显式低频巡检，不再建议为每个 worker 启 background wait 并期待宿主自动回调。

Reason

• 来源：用户在 Claude Code 中实测发现，background Bash 没有可靠触发 agent session；开启多个独立 worker 时可能没有任何消息返回。
• 结论：完成通知必须回到结构化 checkpoint、事件日志和显式巡检；background job 只能作为日志写入器或人工可查看后台进程。

[1.15.0] - 2026-06-05

Added

• optional project config template：新增 templates/project-config.json，声明 trunk、任务源、worktree/session 默认路径、按 worker type 拆分的验证命令、provider slot、非敏感配置复制清单和 hook 边界。

Changed

• SKILL.md config discipline：标准流程增加项目配置读取规则，明确配置只提供默认值，不替代 PM 判断。
• Goal/worker templates：增加 project config 字段，要求 PM 写明采用了哪些配置字段、忽略了哪些字段以及安全检查结果。

Reason

• 来源：TASKS 中仍有“评估项目级配置文件”待办，且用户关注脚本是否过度设计。
• 结论：采用轻量模板，不新增脚本、不自动读取、不自动复制配置、不自动执行 hook；.env、真实 settings、token/key/cert 等继续默认禁止。

[1.14.1] - 2026-06-05

Changed

• script surface governance：明确默认工具面只包含 dependency check、runtime profile render、spawn worker 和 PM monitor；status/clean/wait/test/terminal split 均按场景使用，避免 PM 被脚本数量牵引。
• provider slot planning：超过 4 个 worker 时，改为显式声明 backend + settings/profile path + provider + model + max concurrency，而不是脚本自动猜测用哪个 settings.json。
• templates：worker prompt、checkpoint、Goal Contract 和 Wave Summary 增加 settings/profile path，让每个 worker 的额度来源可审计但不暴露 settings 内容。

Reason

• 来源：用户担心脚本数量过多、出现过度设计，并追问超过 4 个 worker 时到底如何分配 settings.json。
• 结论：不新增自动 scheduler。现阶段应把 provider pool 做成 PM 可审计的显式 slot 表；如果只有一个可用 settings/profile，则并发 cap 降到 3-4，剩余任务进入下一 Wave。

[1.14.0] - 2026-06-05

Added

• runtime dependency matrix：新增 references/02-runtime-dependencies.md，按 core、tmux/worktree、PR/GitHub、worker backend、Codex heartbeat、terminal split 和验证工具拆分依赖。
• dependency checker：新增 scripts/check-dependencies.sh，可检查核心依赖、backend CLI、gh 和终端分屏工具；脚本只报告状态，不安装软件、不启动 worker。

Changed

• SKILL.md dependency section：将依赖说明从单张系统依赖表升级为分层依赖说明，明确 claude、codex、opencode、gh 不是所有模式的硬依赖。
• smoke test：smoke-tmux-worker.sh 纳入 dependency checker 基础回归。

Reason

• 来源：用户指出使用本 Skill 可能还有常规依赖需要安装，当前文档没有写清楚。
• 结论：依赖应按执行模式拆分，避免把所有可选 backend 都误解为必装，同时给 PM 一个启动前的本地检查入口。

[1.13.0] - 2026-06-05

Added

• runtime profile command helper：新增 scripts/render-runtime-profile.sh，按 claude-code、claude-oauth、codex、opencode、custom backend 生成 worker command、prompt context 和 spawn metadata，减少 PM 手写 provider/profile 命令。
• Agent Teams troubleshooting：新增 references/10-agent-teams-troubleshooting.md，覆盖 agent/team 不可见、错误 cwd、官方 worktree 状态映射、checkpoint 缺失、PR 收口和必须停止的场景。

Changed

• spawn flow：SKILL.md 启动示例改为先用 render-runtime-profile.sh 生成 runtime 字段，再传给 spawn-worker.sh，保持启动命令生成与 worktree/session gate 分离。
• smoke test：smoke-tmux-worker.sh 覆盖 runtime profile helper 的 custom、Claude Code 和 Codex 输出。

Reason

• 来源：用户要求继续推进 TASKS 中可落地的优化项。
• 结论：Agent Teams 排障指南和 runtime profile helper 都能本地落地并提升稳定性；Agent Teams feature flag、真实 Claude 原生 --worktree --tmux 后端和跨 PM/worker smoke 仍需要真实宿主环境验证。

[1.12.0] - 2026-06-05

Added

• Goal-Driven Multi-Wave Loop：SKILL.md 新增 PM 级 Orchestration Goal Loop，支持在成功条件满足前自动收口当前 Wave、读取任务源、选择下一批安全任务并启动下一 Wave。
• Goal Contract 模板：新增 templates/orchestration-goal.md，要求 PM 在连续推进前写清任务源、成功条件、自主级别、并发/预算上限、继续条件和停止条件。
• Goal Loop 状态映射：checkpoint-status.json 增加 orchestration_goal 字段；worker-prompt.md 增加 Goal ID / Loop Iteration，并明确 worker 不得自行领取其他任务。

Changed

• Wave summary：新增 Goal ID、loop iteration、continue/stop decision、remaining tasks 和 next Wave 字段，让每轮自动继续都有可审计记录。
• Skill 路由：明确 Claude Code / Codex /goal 可作为 PM loop 的宿主续跑能力，但不替代 worktree、tmux、checkpoint、review 和 merge 门禁。

Reason

• 来源：用户希望多 Agent 编排不止“一次运行一个 Wave”，而是在 PR 验收、验证和任务源状态正常时，能自动继续下一 Wave，直到目标范围内任务耗尽或触发停机条件。
• 结论：连续推进应放在 PM 层，不放给 worker；worker 保持窄任务边界，PM 负责任务池、Wave 收口、继续/停止判断和合并门禁。

[1.11.0] - 2026-06-04

Added

• Wave-Based Orchestration：SKILL.md 新增 Wave 一等调度概念，要求 PM 在每轮启动前记录 wave_id、worker 清单、base ref、共享风险、provider/model/slot、收口顺序和下一轮进入条件。
• 跨 provider 并发池：明确超过 3-4 个 worker 时不应压在单一 API provider 上，应跨 runtime profile/API 来源分流，并在 Wave 收口时评估模型/provider 表现。
• worker 类型与验证底线：worker prompt 新增 ui-wiring、contract-extension、tauri-command、docs/research 等类型，明确 Tauri/Rust worker 的 cargo check --offline 验证底线和 skipped verification 记录要求。
• Wave checkpoint 字段与 summary 模板：checkpoint-status.json 新增 wave、worker_class、provider/model/slot 和 model_evaluation 字段；新增 templates/wave-summary.md。
• 多信号进展巡检：pm-monitor.sh 新增 --wave-id、--progress-stale-threshold、WORKER_SILENT_PROGRESS、WORKER_NO_PROGRESS 和 WORKER_FINISHED_NO_PHASE_DONE，结合 STATUS、commit、file mtime 和 dirty state 判断 worker 是否真有进展。
• wait script lint：新增 scripts/lint-wait-script.sh，用于检查 wait/monitor/custom wait 脚本的 bash -n 和 ${VAR:0:N} substring 闭合错误。
• worktree metadata：spawn-worker.sh 在 Session Context 写入 METADATA.json，记录 base、session、runtime profile、provider slot、验证命令和 PR 占位；worktree-status.sh / clean-worktree.sh 会展示该摘要。

Changed

• worker prompt：加入 Wave 信息、provider slot、Decision ID race 规则、worker type rules 和验证底线。
• spawn gate：spawn-worker.sh、worktree-status.sh 和 clean-worktree.sh 使用物理路径解析，避免 macOS /var / /private/var 别名导致 cwd gate 误失败。
• worktree-status.sh：单 worker 只读总览增加 wave/provider/model/type 输出。
• smoke test：smoke-tmux-worker.sh 通过 spawn-worker.sh 创建 worker，覆盖 metadata 写入、总览展示和清理前摘要。
• parallel-lessons.md：补充 Wave worker 类型、Vitest/Vite 二进制资源兼容、DEC 编号 race 和 provider 并发池实战记录。

Reason

• 来源：用户要求评估 TASKS 中多个优化/升级建议，并把合理项升级为 multi-agent-orchestration 的正式机制。
• 结论：Wave、provider 并发池、多信号巡检、worker 类型、验证底线和 DEC race 属于高复用执行协议；Agent Teams 发布状态、终端 split-panes、底层 adapter、Snap mode 等仍留作后续研究。

[1.10.0] - 2026-06-04

Added

• worker 生命周期脚本：新增 spawn-worker.sh、worktree-status.sh、clean-worktree.sh 和 smoke-tmux-worker.sh，把 worktree/session 创建、单 worker 状态总览、安全清理和端到端 smoke test 固化为可执行入口。
• commit stale 事件：pm-monitor.sh 新增 --commit-stale-threshold 和 WORKER_STALE_NO_COMMIT，用于提示 session 存活但分支长时间没有阶段性提交的 worker。
• Codex heartbeat 模板：新增 templates/codex-heartbeat-wait.md，明确 Codex App 用 wait-worker.sh --once 做轻量唤醒，创建/修改 automation 时必须使用 automation_update 工具。
• Worker commit cadence：worker prompt 要求长任务每 30-60 分钟或阶段完成后生成可 review commit，并刷新 STATUS.json 的 Git 字段。

Changed

• wait-worker.sh 输出脱敏：tmux pane tail 和 RESULT tail 默认过滤 token/key/secret/auth/password 等敏感行，并替换常见 secret token 片段。
• SKILL.md 压缩启动章节：将长启动示例收束为 spawn-worker.sh + 常用 command 索引，保留防逃逸门禁和最小验证规则。
• checkpoint Git 字段：templates/checkpoint-status.json 增加 git.last_commit_at 和 git.commits_since_base，pm-monitor.sh / worktree-status.sh 同步显示。
• 脚本 shebang：核心脚本统一使用 /usr/bin/env bash；pm-monitor.sh 增加 bash 4+ 版本门禁，避免 macOS 系统 /bin/bash 3.2 运行关联数组失败。
• UTC 时间解析：pm-monitor.sh 和 wait-worker.sh 在 macOS 上按 UTC 解析 updated_at 的 Z 后缀，避免刚写入的 checkpoint 被误报 stale。

Reason

• 来源：用户希望把 “tmux 独立 session 防逃逸” 做成可执行、可验证、可 smoke 的完整协议，并适配 Codex 的后台等待/heartbeat 方式。
• 目标：让 PM 不再依赖手写命令和主观自律；启动、等待、监控、状态、清理和回归验证都有明确脚本入口。

[1.9.9] - 2026-06-03

Added

• wait-worker.sh tmux 诊断尾部输出：新增 --tmux-session、--pane-tail-lines、--include-pane-on 和 --stale-threshold。默认只在 checkpoint 缺失、过期或终态时读取 tmux pane tail。
• 状态源分层规则：SKILL.md §7.1 明确 STATUS.json / RESULT.md / PATCH_SUMMARY.md 是主协议，tmux capture-pane 只作诊断窗口，不作为完成标准。

Reason

• 来源：用户提出既然 background Bash 在运行，是否可以直接读取 tmux worker 输出。
• 结论：可以读，但要作为诊断兜底而非主状态源，避免屏幕输出截断、清屏、敏感信息和上下文膨胀影响 PM 判断。

[1.9.8] - 2026-06-03

Added

• scripts/wait-worker.sh：新增单 worker 等待器，可持续等待或 --once 快速检查 .claude/agent-sessions/<session>/STATUS.json，在 done / failed / blocked / stopped 时输出 RESULT/PATCH_SUMMARY 路径并退出。
• §7.1 主动等待与宿主唤醒：明确 wait-worker.sh 不替代 pm-monitor.sh；Claude Code 可接 Bash background/run-in-background，Codex App 则用当前 thread 的 heartbeat automation 调用 wait-worker.sh --once 实现主动唤醒。

Reason

• 来源：用户希望 Claude Code 的 Bash run_in_background 等待体验也能适配 Codex。
• 结论：Codex CLI 没有同名自动通知机制；Codex 适配应通过“通用等待脚本 + Codex heartbeat/thread wakeup”完成，避免把核心 monitor 绑定到单一宿主。

[1.9.7] - 2026-06-03

Added

• 防逃逸门禁：当用户或项目明确要求 tmux / 独立 session / 开 worker 时，PM 在业务实现前必须创建 worktree/branch、启动 session、验证 cwd/branch、派发 worker prompt 并确认 STATUS.json，否则报告阻塞，不得静默降级为 PM 直接实现或普通 Subagent。
• Worker Isolation Gate：templates/worker-prompt.md 要求 worker 在读任务或实现前确认 cwd、branch 和 worktree；不匹配时写 blocked STATUS.json 并停止。
• STATUS orchestration_gate 字段：templates/checkpoint-status.json 新增 session/cwd/branch/worktree/degraded/escape 结构化门禁字段，pm-monitor.sh 会输出 ORCHESTRATION_GATE_FAILED。

Fixed

• pm-monitor.sh 本地未 push 分支误退出：远端分支不存在时先查 merged PR；若本地分支仍存在，输出 BRANCH_NOT_PUSHED 并保持 monitor 运行。
• SESSION_GONE 去重：tmux session 消失事件只在状态变化时输出，避免低频巡检日志重复刷屏。

Reason

• 来源：用户反馈其他模型在 Claude Code 中反复没有按 tmux 独立 session 推进，需要把“不要逃逸”从建议性描述升级成可检查门禁。
• 目标：让 PM、worker 和 monitor 三层都能暴露逃逸：PM 不能绕过启动门禁，worker 不能在错误目录继续实现，monitor 能报告 gate 失败和本地分支未 push。

[1.9.6] - 2026-06-03

Changed

• SKILL.md §6 tmux / Claude Code worker 例子：去掉 --max-turns 20 的限制示例，加注"不要设 --max-turns；PM 重点是检测 worker 真在运转而不是限制 turn 数"。
• scripts/pm-monitor.sh BRANCH 状态区分：远端 branch 不存在时，区分两种情况：
• 本地 branch HEAD == main HEAD → BRANCH_NOT_PUSHED: $branch (waiting for worker to commit and push)（新事件）
• 本地 branch HEAD != main HEAD → BRANCH_MERGED: $branch（保留原行为）
• 解决"branch 还没 push 被误判为 merged"导致 monitor 立刻退出的问题。

Reason

• 来源：FaroPDF v0.1 Wave 2 启 worker 后 PM 监控失灵的根因分析。
• 主要根因：

1. worker prompt 没强调"启动后立即写 STATUS.json 心跳"，导致 max-turns 触发时没 STATUS.json，PM 无从判断 worker 真在运转。 2. SKILL 自带 pm-monitor.sh 的 BRANCH_MERGED 判断只看 origin/$branch 是否存在，忽略了"branch 还没 push"的常见 case，导致 monitor 立刻退出。 3. SKILL 例子给的 --max-turns 20 让我误以为应该设上限，实际应让 worker 跑自然结束。

[1.9.5] - 2026-06-03

Added

• §8.0 PM 在 Worker 提 PR 后的持续同步（精简版）：

1. 提 PR 之后立即跑 gh pr view <N> --json mergeable,mergeStateStatus,baseRefName；冲突走 git-workflow 决策表。 2. PM 在主目录 commit docs / DEC 之后立即 git push origin main，避免本地与 origin/main drift（squash merge 引入的"内容相同但 history 不同"会让 git 误判冲突）。

Reason

• 来源：FaroPDF v0.1 Wave 1 真实合并 PR #18 / #19 前的根因复盘。
• 主要根因：PM 没在 worker 提 PR 后立即跑 mergeable 检查；PM 本地 main commit DEC 后没立即 push。

[1.9.4] - 2026-06-03

Added

• parallel-lessons.md 新增 G17：任务编号从 ISS-NNN 改为 Task-NNN（与 project-init v1.1.1 对齐）。说明新约定、迁移规则，以及历史 lesson（如 G15 的 FaroPDF ISS-018）和 commit history 保持原样不改写。

[1.9.3] - 2026-06-03

Changed

• 将 checkpoint 可复制模板从 references/03-checkpoint-files.md 移到 templates/，包括 checkpoint-status.json、checkpoint-result.md 和 checkpoint-patch-summary.md。
• 新增 templates/worker-prompt.md，将 worker prompt 拆成 Bootstrap-only 和 Full worker 两段，并按 Context / Background / Mission / Scope / Deliverables / Process / Verification / Autonomy / Out of Scope / PM Correction 组织。
• 精简 SKILL.md 与 references/03-checkpoint-files.md：正文只保留规则、字段经济性和模板路径，避免 Skill 主体继续膨胀。

[1.9.2] - 2026-06-03

Changed

• 将 STATUS.json 升级为 v2 schema，补充 task_source、current_action、next_action、scope、runtime、git、pm_action_required、blocker、risks 和 last_pm_correction 等 PM 决策字段。
• 明确 STATUS.json 的经济性边界：只记录 PM 自动监控和 review 决策必需的结构化信号，不记录 token、完整环境变量、settings 内容或长日志。
• 增强 pm-monitor.sh：新增 --once、--interval、--stale-threshold、--log-file，支持一次性巡检、低频后台巡检和事件日志落盘。
• pm-monitor.sh 现在会从 checkpoint 输出 CHECKPOINT_STALE、AGENT_NEEDS_INPUT、CHECKPOINT_TEST_FAILURE、CHECKPOINT_PR 等事件，减少 PM 前台轮询需求。
• 补充经济型巡检规则：脚本负责事件输出和日志，是否自动唤起 PM 取决于宿主环境；无唤醒能力时用 --once 或低频读取 log tail。

[1.9.1] - 2026-06-03

Changed

• 将新 worker 的 checkpoint 目录从 .agent-context/ 调整为 .claude/agent-sessions/<session-id>/，复用项目既有 .claude/ 协作空间；pm-monitor.sh 仍兼容读取旧 .agent-context/。
• 明确 Claude Code 官方 Agent Teams 的状态源在 ~/.claude/teams/<team>/ 与 ~/.claude/tasks/<team>/，不要在项目内自造 .claude/teams/ 冒充官方 team。
• 明确 worktree、分支和 session context 默认由 PM 创建；只有 Claude Code 官方 Agent Teams / agent view 明确使用自身 --worktree 能力时，才允许 worker 侧创建隔离环境，PM 仍需验收。
• 将 PM review correction 固化为收口流程：PM review 失败时优先把具体修正发回原 worker，worker 追加修复 commit、更新验证和 PR，PM 再复核。
• 补充环境差异规则：Claude Code provider settings、Claude OAuth/订阅、Codex/OpenAI 和 OpenCode profile 必须分开声明，不默认清理或继承环境变量。

[1.9.0] - 2026-06-02

Changed

• 将 PM 从具体产品中解耦：当前 Codex、Claude Code 或其他主会话都可以担任 PM。
• 将 worker backend 抽象为 Claude Code、Codex、OpenCode、shell 和可选 ACP adapter，支持从 Claude Code 启动 Codex/OpenCode worker，或从 Codex 启动 Claude Code/OpenCode worker。
• 补充 runtime profile / 额度路由规则，明确 Claude Code worker 默认走第三方 API provider settings，订阅/OAuth 只作为显式例外。
• 补充 Claude Code 第三方 API provider settings 模式：通过 --settings /path/to/provider.settings.json 加载 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 和默认模型环境变量。
• 将 Claude Code worker 默认额度模式调整为第三方 API provider settings，并新增 references/claude-provider-settings.example.json 模板。
• 将 Claude Code tmux worker 默认启动方式调整为交互式后台终端 session；-p 仅作为批处理 prompt 的可选模式。
• 将 provider settings 示例调整为 Minimax Anthropic-compatible API 结构，保持 token、base URL、三类默认模型、timeout、thinking tokens 和行为开关一并配置。
• 增加结构化 checkpoint 三件套：.agent-context/STATUS.json、RESULT.md、PATCH_SUMMARY.md，并新增模板参考文档。
• 更新 pm-monitor.sh，支持从分支自动定位 worktree、监听 checkpoint 文件变化，并可选通过 --claude-agents-cwd 读取 Claude 官方后台 session 状态。
• 补充 Claude Code 官方 agent view / background session 入口：claude agents、claude agents --json、--worktree、--tmux，以及版本支持时的 claude --bg 和 /bg，作为 tmux 之外的 Claude 专用后台会话模式。
• 补充 OpenCode worker 支持：默认用 opencode run --format json --model <provider/model>，并将 opencode acp 记录为可选 ACP server 候选。
• 补充 custom CLI worker 模板，支持其他可一行命令启动、可在指定 worktree 中运行的 Agent。
• 将 ACP 定位为可选后端：协议层结构化，但默认仍以 tmux + worktree + checkpoint 文件 + git 状态 作为稳定执行层。
• 更新 Worker Prompt 模板，加入 PM Host、Worker Backend、Runtime Profile 和 .agent-context/STATUS.json / RESULT.md / PATCH_SUMMARY.md checkpoint 协议。
• 明确用户指定当前会话担任 PM agent 时，PM 默认不直接写业务代码；实现优先委派给 worktree worker、独立 session、Agent Teams 或 Subagent，PM 负责巡检、纠偏、review 和收口。
• 基于 FaroPDF ISS-018 实战补充流程约束：高延迟 provider 可两段式 bootstrap；.agent-context/ 只作本地 checkpoint，不进入 Git/PR；worker 不应等待 PM 下一步；STATUS 每次写入必须刷新 updated_at；窄范围实现默认 low/medium effort。

[1.8.2] - 2026-06-01

Changed

• 收口发布包参考文档，只保留模型/执行模式矩阵、实战坑点和法律项目拆解样例。
• 精简法律场景参考，移除未落地的未来模板路径和外部 catalog 设想，明确其只作为本地执行层拆分样例。

Removed

• 移除已落地或过时的历史平台调研、Agent Teams 优化积压和 Auto PM 蓝图文档，避免与当前 SKILL.md 实现机制重复或冲突。

[1.8.1] - 2026-05-20

Changed

• 同步相关 Skill 引用：cross-agent-collab 更名为 cross-agent-coordination 后，更新任务协调层边界说明和参考文档。

[1.8.0] - 2026-05-20

Changed

• 重命名 Skill：multi-agent-workflow → multi-agent-orchestration，标题改为 Multi-Agent Orchestration，以突出“本地多 Agent 执行编排”而非普通流程说明。
• 同步更新 SKILL.md description 和开篇说明，统一使用“执行编排”表述。
• 同步更新 cross-agent-coordination 中对本 Skill 的边界引用。

[1.7.0] - 2026-05-20

Changed

• 重命名 Skill：parallel-agent-workflow → multi-agent-workflow，标题改为 Multi-Agent Workflow，以匹配当前“多 Agent 本地执行编排”的职责边界。
• 优化 SKILL.md frontmatter description，补充正向触发场景和负向边界。
• 补充脚本依赖说明，明确 pm-monitor.sh 与 terminal-split.sh 的系统依赖和可选终端依赖。
• 同步更新 cross-agent-coordination 中对本 Skill 的边界引用。

[1.6.0] - 2026-05-19

Changed

• 精简 SKILL.md 为执行入口、命名规则、启动方式、巡检和收口规则；复杂细节转交 references/ 和 scripts/。
• 明确任务源由项目配置或项目上下文决定，不在 Skill 中写死固定文件路径。
• 保留 pm-monitor.sh 的自动 PM 巡检能力，包括 Agent Teams inbox、tasks、Git SHA、PR 状态和 tmux session 多维监控。
• 保留 terminal-split.sh 的多终端分屏能力，包括 iTerm2、Kitty、WezTerm、Warp、Ghostty、Zed 和 Terminal.app。

[1.5.0] - 2026-05-17

Added

• 新增从项目任务源形成本地执行计划的通用规则：提取 Issue ID、状态、推进建议、文件/组件、依赖和验收标准。
• 新增 待办事项分组策略：按文件/组件重叠、依赖链、并行安全度和 PR 审查边界决定多个 Issue 是否放入同一 worktree/session。
• 新增 L1/L2/L3 路由说明，明确不是一个 Issue 必然对应一个 session。

Changed

• multi-agent-orchestration 继续只拥有本地执行层；分组计划只服务本轮执行，不成为新的任务状态源。

[1.4.0] - 2026-05-17

Changed

• 明确本 Skill 只负责本地 Agent 会话、并行执行、PM 巡检和 worktree 隔离，不拥有任务主状态。
• 标准流程改为从项目任务源接任务；任务读取、外部 Agent 邮件触发和跨平台归属交给 cross-agent-coordination。
• 将 git-task-orchestrator 定位改为历史蓝图，不再作为当前协作入口，也不迁入其旧 worktree/session 方案。

[1.3.0] - 2026-05-09

Added

• 任务列表管理：复用 Agent Teams 的 tasks 目录结构（JSON 任务项 + .lock 文件锁 + .highwatermark 增量读取）
• 文件锁机制：agent 认领任务时用 flock() 防止并发冲突
• 高水位标记：agent 增量读取任务列表，已完成任务自动删除并更新 highwatermark
• pm-monitor.sh v4.1：新增 --tasks-dir 参数、check_task_states() 函数、TASK_STATUS/TASK_COMPLETED 事件
• 权限继承自动化：启动时自动从主仓库复制 .claude/settings.json 到每个 worktree
• Context 恢复：团队协议持久化到 worktree 的 CLAUDE.md，claude --continue 后协议不丢失

Changed

• §6.1 创建 Worktree 增加权限自动复制步骤
• §6.2 初始化增加共享任务列表创建
• §6.3 启动 Agent 增加 CLAUDE.md 持久化步骤
• §6.6 清理增加 tasks 目录清理
• pm-monitor.sh 支持 --tasks-dir 参数

[1.2.0] - 2026-05-09

Changed

• [重大] tmux 模式统一使用 Agent Teams 文件通信协议：tmux 仅作为进程管理层，通信层复用 ~/.claude/teams/ 的 inbox + tasks 机制
• tmux 模式从"降级模式"重命名为"扩展模式"，体现架构对等性
• pm-monitor.sh v4：新增 --team-dir 参数，支持 inbox health_report 轮询（6 个新事件类型），保留 git SHA 轮询作为第二维度
• 运行时干预改为 inbox 命令消息 + 短 send-keys 提醒（替代长文本 send-keys）
• 监控巡检改为读取 PM inbox health_report（首选），capture-pane 降为回退方案

Added

• Agent Teams 通信协议 prompt 模板（health_report 发送、命令检查、agent 间 inbox 通信）
• 团队目录初始化步骤（config.json + inbox 文件创建）
• health_report 消息类型（status/phase/progress/last_commit_sha/context_pct/issues）
• inbox 命令协议（continue/stop/check_review_feedback/rebase/commit_and_push）
• pm-monitor.sh 过时检测（5 分钟无 health_report 自动告警）
• 自动 PM 蓝图中的 tmux 扩展模式通信架构
• parallel-lessons.md 文件通信协议操作手册

[1.1.0] - 2026-05-08

Changed

• [重大] 默认使用 Agent Teams（Teammate 模式）：在 Claude Code 环境下，重任务优先使用官方 Agent Teams，tmux 降级为非 Claude Code 环境的备选方案
• 任务规模路由从二元（Subagent / tmux）升级为三元（Subagent / Agent Teams / tmux）
• 执行模式对比从二元表扩展为三元表（Subagent / Agent Teams / tmux Session）
• 监控方式从 tmux capture-pane 扩展为 Agent Teams 共享任务列表 + 邮箱系统
• 通信通道增加 Agent Teams 邮箱系统（双向通信，替代单向 send-keys）
• 新增环境检测逻辑（自动选择 Agent Teams 或 tmux 降级）
• 实战经验文档按 Agent Teams / tmux 降级 / 通用三类重组

Added

• SKILL.md §3 前置条件拆分为 Agent Teams 和 tmux 两组
• SKILL.md §4 环境检测与模式选择
• SKILL.md §5 Agent Teams 标准流程（规划/Worktree/启动 Teammates/监控/干预/审查/合并）
• SKILL.md §6 tmux 降级模式（保留完整流程）
• Agent Teams 详细技术调研

[1.0.0] - 2026-05-07

新增

• SKILL.md 核心技能定义，覆盖并行 Agent 完整生命周期
• terminal-split.sh 跨终端分屏脚本（支持 iTerm2/Kitty/WezTerm/Warp/Ghostty/Zed/Terminal.app）
• pm-monitor.sh 参数化 PM Monitor（基于 git SHA 变化，自动停止）
• 模型选择矩阵（L0/L1/L2 路由 + 运行时升降级）
• 执行模式选择（Subagent vs tmux + 混合模式）
• PM 巡检循环蓝图（健康/任务/PR 三维巡检）
• 实战经验教训文档（tmux 陷阱、合并冲突、IME 干扰）
• 与 git-task-orchestrator 的边界定义和协作路由
• 法律实务任务拆解模板（诉讼/非诉/尽调/合同审查）作为扩展参考
• 多 Agent 平台技术调研（Claude Code/OpenClaw/Codex/Hermes 对比 + Skills 生态评测）作为扩展参考

模型选择与执行模式矩阵

本文档为 SKILL.md 的 Level 2 参考文档，提供模型路由和执行模式选择的完整细节。

读取时机：规划并行任务、为 Agent 分配模型、选择 Subagent / Agent Teams / tmux 时。

---

1. 模型分级（L0 / L1 / L2）

模型路由只服务 worker，不绑定 PM 所在产品。Codex 做 PM 时可以启动 Claude Code 或 OpenCode worker；Claude Code 做 PM 时也可以启动 Codex 或 OpenCode worker。判断顺序是：任务复杂度 → 当前可用额度 → worker backend → 模型/环境变量。

1.1 能力定义

1.2 任务-模型路由

经验法则：任务描述包含"理解/分析/重构/设计"→ L2；包含"添加/补充/翻译/复制"→ L0；其余默认 L1。

1.3 额度 Profile

默认 Claude Code worker 使用 claude-provider。每个第三方 provider 使用一个本地 settings JSON，参考 config/claude-provider-settings.example.json；真实 token 文件应放在项目或用户目录的忽略路径中。settings 是完整环境变量组，包含 Haiku/Sonnet/Opus 默认模型、timeout、thinking tokens 和行为开关，所以启动命令不要额外指定 --model sonnet。只有用户明确要走订阅/OAuth 时，才使用 claude-oauth 并清理 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和第三方 ANTHROPIC_BASE_URL。

1.4 各执行模式下指定模型

Claude Code Agent Teams 模式：如果要走第三方 API，先让该 session 加载 provider settings。模型映射由 settings 里的 ANTHROPIC_DEFAULT_*_MODEL 变量提供。

Claude Code tmux worker（默认第三方 API settings）：tmux 启动的是一个后台独立终端 session，可 attach 或 capture。默认启动交互式 Claude Code，使用 --settings 加载整份 provider profile。模板见 config/claude-provider-settings.example.json。

tmux new-session -d \
  -s worker-claude-provider \
  -c .claude/worktrees/tmux-feature \
  'claude --settings /path/to/provider.settings.json --permission-mode auto'

批处理执行 prompt 时，再使用 Claude Code 的 -p 非交互模式：

tmux new-session -d \
  -s worker-claude-provider \
  -c .claude/worktrees/tmux-feature \
  'claude --settings /path/to/provider.settings.json -p --permission-mode auto --output-format stream-json < /tmp/task.prompt.md'

Claude Code tmux worker（可选订阅/OAuth）：只在用户明确要求使用 Claude 订阅/OAuth 时启用，启动命令里清掉第三方 provider 环境，避免误走 API key 或代理服务。

tmux new-session -d \
  -s worker-claude-oauth \
  -c .claude/worktrees/tmux-feature \
  'env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_BASE_URL claude --permission-mode auto'

Codex tmux worker：用 -m 或 profile 指定模型。

tmux new-session -d \
  -s worker-codex-l1 \
  -c .claude/worktrees/tmux-feature \
  'codex exec -m <codex-model> -a never -s danger-full-access - < /tmp/task.prompt.md'

OpenCode tmux worker：模型格式通常是 provider/model，先用 opencode models 查看可用项。

tmux new-session -d \
  -s worker-opencode-l1 \
  -c .claude/worktrees/tmux-feature \
  'opencode run --format json --model <provider/model> "$(cat /tmp/task.prompt.md)"'

OpenCode ACP server：仅在 PM 侧已有 ACP client/adapter 时使用。

tmux new-session -d \
  -s worker-opencode-acp \
  -c .claude/worktrees/tmux-feature \
  'opencode acp'

自定义 CLI worker：用于其他一行命令 Agent。把模型、provider、profile、权限参数放进命令；PM 只要求它在指定 worktree 内执行，并产出 checkpoint 三件套，或至少可由 Git 状态巡检。

tmux new-session -d \
  -s worker-custom \
  -c .claude/worktrees/tmux-feature \
  '<agent-command> < /tmp/task.prompt.md'

Hermes Agent tmux worker：Hermes 原生支持 --worktree，pooled auth 支持多 provider 自动 fallback。

tmux new-session -d \
  -s worker-hermes \
  -c .claude/worktrees/tmux-feature \
  'hermes --yolo -m gpt-4o'

或使用 Hermes 原生 worktree：

tmux new-session -d \
  -s worker-hermes \
  'hermes --worktree tmux-feature --yolo -m gpt-4o'

Kimi CLI tmux worker：原生 stream-json 输出，适合 PM 解析。

tmux new-session -d \
  -s worker-kimi \
  -c .claude/worktrees/tmux-feature \
  'kimi --print --output-format stream-json -y -m kimi-latest -c "$(cat /tmp/task.prompt.md)"'

Gemini CLI tmux worker：--approval-mode 提供 4 级审批控制。

tmux new-session -d \
  -s worker-gemini \
  -c .claude/worktrees/tmux-feature \
  'gemini -y --approval-mode auto_edit -m gemini-2.5-pro'

批处理模式：

tmux new-session -d \
  -s worker-gemini \
  -c .claude/worktrees/tmux-feature \
  "bash -lc 'gemini -p \"\$(cat /tmp/task.prompt.md)\" -m gemini-2.5-pro -y'"

QoderWork CLI tmux worker：消耗 QoderWork 平台额度，可利用元典/企查查 MCP 工具链。必须在干净终端启动（不能从 QoderWork 桌面端内部 session 启动）。

tmux new-session -d \
  -s worker-qoderwork \
  -c .claude/worktrees/tmux-feature \
  'qoderclicn -m qmodel_latest --permission-mode auto'

批处理模式：

tmux new-session -d \
  -s worker-qoderwork \
  -c .claude/worktrees/tmux-feature \
  "bash -lc 'qoderclicn -p \"\$(cat /tmp/task.prompt.md)\" -m qmodel_latest'"

交互式 tmux session：只在需要人工接管时用 /model 或 CLI 内部菜单切换模型。

# 启动 Claude Code 后切换模型
tmux send-keys -t session-name "/model" Enter
sleep 1
# 用 Up/Down 导航到目标模型（次数取决于菜单排序）
for i in 1 2 3; do tmux send-keys -t session-name Down; sleep 0.05; done
tmux send-keys -t session-name Enter

或在 prompt 文件开头声明模型偏好：

[模型建议: 这是 i18n 任务，适合轻量模型。请先 /model 切换。]

1.5 运行时升降级

升级（→ L2）：Agent 反复失败 >2 次、任务复杂度超预期

降级（→ L0）：架构设计完成进入实现、剩余为重复性工作

Agent Teams 模式下模型在创建时指定，升降级需重新创建 Teammate。

tmux 交互模式下：

# 中断 Agent 并切换模型
tmux send-keys -t session-name C-c
sleep 0.5
tmux send-keys -t session-name "/model" Enter
# 导航到目标模型后继续
tmux send-keys -t session-name -l -- "模型已升级，继续刚才的任务。"
tmux send-keys -t session-name Enter

Claude Code -p 批处理模式下，推荐停止旧 worker，保留 worktree，按更高 profile 重启，并在 prompt 中说明“接续当前 worktree 已有改动，不要回退”。

1.6 批量调度模板

# tasks.conf 格式: name  backend  worktree路径  profile  prompt文件
worker-1  claude    .claude/worktrees/i18n-fixes      claude-provider  /tmp/task-i18n.txt
worker-2  codex     .claude/worktrees/file-ops        codex-l1         /tmp/task-fileops.txt
worker-3  opencode  .claude/worktrees/ui-copy         opencode-l0      /tmp/task-copy.txt
worker-4  claude    .claude/worktrees/refactor-core   claude-provider  /tmp/task-refactor.txt
worker-5  hermes    .claude/worktrees/api-integration hermes-l1        /tmp/task-api.txt
worker-6  kimi      .claude/worktrees/translation     kimi-l0          /tmp/task-trans.txt
worker-7  gemini    .claude/worktrees/docs-update     gemini-l1        /tmp/task-docs.txt
worker-8  qoderwork .claude/worktrees/legal-research  qoderwork-l1     /tmp/task-legal.txt
worker-9  custom    .claude/worktrees/custom-agent    custom-cli       /tmp/task-custom.txt

---

2. 执行模式选择

2.1 三档 Claude Code worker

--max-turns、--worktree、--tmux、--bg 的可用性随 Claude Code 版本变化；使用前以当前 claude --help、claude agents --help 为准。无论使用哪一档，worker 都必须写 .claude/agent-sessions/{session}/STATUS.json、RESULT.md、PATCH_SUMMARY.md。

2.2 执行后端对比：Subagent / Agent Teams / tmux Session / ACP

2.3 路由矩阵

路由决策树：

任务时长 ≤15 分钟？
├─ 是 → Subagent
└─ 否 → 需独立 git 分支？
    ├─ 否 → Subagent
    └─ 是 → 当前 PM 是 Claude Code 且 Agent Teams 已启用？
        ├─ 是 → Agent Teams（split-panes）
        └─ 否 → 需要跨产品或额度路由？
            ├─ 是 → tmux worker（Claude/Codex/OpenCode）
            └─ 否 → tmux worker

2.4 混合模式

PM（Team Lead）
├── Subagent A: review PR #1              ← 分钟级，共享上下文
├── Subagent B: 研究 X 接入方案            ← 分钟级，共享上下文
├── Teammate 1: feat/i18n                 ← 小时级，L0，独立上下文
└── Teammate 2: feat/refactor             ← 小时级，L2，独立上下文

PM 在等待 Teammate 期间用 Subagent 处理短任务，不空闲。

tmux worker 模式下，将 Teammate 替换为独立 CLI session 即可。

Runtime Dependencies

读取时机：首次使用本 Skill、迁移到新机器、启动 Wave 前、脚本报 command not found 或日期解析异常时。

1. 依赖分层

常见 Unix 工具包括：awk、sed、grep、find、stat、date、mktemp、wc、tr。macOS 和 Linux 默认通常自带，但 date 参数不同，脚本已做 macOS/Linux 双路径解析。

2. macOS 安装建议

brew install bash tmux jq gh

可选 backend：

# 按实际来源安装
claude --version
codex --version
opencode --version

pm-monitor.sh 要求 bash 4+。在 macOS 上，如果默认 shell 仍调用系统 /bin/bash 3.2，应使用 Homebrew bash 运行：

/opt/homebrew/bin/bash scripts/pm-monitor.sh ...

或确保新版 bash 在 PATH 前面。

3. Linux 安装建议

Debian / Ubuntu:

sudo apt-get update
sudo apt-get install -y bash git tmux jq gh

不同发行版的 GitHub CLI 包名和安装源可能不同；以 GitHub CLI 官方安装方式为准。

4. 快速检查

bash scripts/check-dependencies.sh
bash scripts/check-dependencies.sh --backend claude-code --backend codex --check-gh --check-terminal-split

检查脚本只报告依赖状态，不安装软件，也不启动 worker。

5. 依赖边界

• 不要把 claude、codex、opencode 当作所有模式的硬依赖；只有选用对应 backend 时才需要。
• 不要默认复制 .env、真实 provider settings、token 或 key 到 worktree。
• gh 用于 PR/mergeability 判断；没有 gh 时 PM 必须用其他方式确认 PR 状态，不能假定已合并。
• Claude Code 原生 --worktree --tmux 可作为启动后端，但仍要接回本 Skill 的 METADATA.json / STATUS.json / Wave / review / merge 门禁。

Worker Checkpoint Files

读取时机：启动 worker、写 worker prompt、PM 巡检或收口时。

Worker 必须把进度压缩到 .claude/agent-sessions/<session-id>/，避免 PM 为了巡检频繁读取完整日志。这里的 checkpoint 是 PM 巡检文件协议，不等同于 Claude Code 自身用于回退会话的 checkpointing 功能。

1. 文件清单

2. METADATA.json

METADATA.json 由 PM 的 scripts/spawn-worker.sh 写入，属于静态执行上下文，不替代 worker 的心跳。它用于回答“这个 worktree 从哪里来、由谁跑、用了哪个 provider slot、预期怎么验证、PR 信息待填在哪里”。

PM 可用 scripts/worktree-status.sh 读取 metadata 摘要；清理前 scripts/clean-worktree.sh 也会显示 metadata，辅助判断是否要保留 worktree。

3. STATUS.json

复制 templates/checkpoint-status.json 到 Session Context/STATUS.json 后替换占位符。该 JSON 模板必须保持可被 jq 解析；不要在 JSON 文件内写注释。

status 取值：

字段经济性规则：

长任务应在完成一个可验证阶段或每 30-60 分钟生成一次可 review 的阶段性 commit，并同步刷新 git.last_commit_sha、git.last_commit_at 和 git.commits_since_base。提交格式仍由项目 git-workflow / git-batch-commit 决定。

Wave worker 应在 bootstrap 时写入 orchestration_goal.id、orchestration_goal.loop_iteration、wave.id、wave.worker_id、wave.role 和 worker_class.type。收口时由 worker 或 PM 填写 wave.exit_state 和 model_evaluation，用于下一 Wave 的 provider/model 路由。

不要把完整日志、长推理、完整环境变量或 token 写入 STATUS.json。runtime.settings_profile_path 只记录 settings 文件路径或 profile 名，不记录 settings 内容、密钥、认证头、完整 settings JSON 或完整 shell env。PM 读取 tmux pane 或 RESULT tail 时应使用 wait-worker.sh 的脱敏输出作为默认观察面。

4. RESULT.md

复制 templates/checkpoint-result.md，在完成、失败或主动停止时写入 Session Context/RESULT.md。RESULT 负责给 PM 快速理解结果，不要重复完整日志。

5. PATCH_SUMMARY.md

复制 templates/checkpoint-patch-summary.md，在有代码或文件 diff 时写入 Session Context/PATCH_SUMMARY.md。PATCH_SUMMARY 负责说明 diff 意图、范围、行为变化、测试和 review 重点。

6. PM 读取规则

PM 巡检优先顺序：

1. METADATA.json 2. STATUS.json 3. RESULT.md 4. PATCH_SUMMARY.md 5. git status --short 和 git diff --stat 6. tmux pane、agent view logs 或完整 stream-json 日志

只有 checkpoint 缺失、过期、互相矛盾或报告阻塞时，才读取完整日志。

Sentinel bash 模式 设计文档

读取时机：启用 sentinel、调查 PM 没被 worker done 事件唤醒、Sentinel 相关

性能调优时。

1. 问题

PM 多 Agent 编排的痛点是 PM 不能事件驱动地被唤醒：

• pm-monitor.sh --log-file 持续写事件日志，不主动唤起 PM
• wait-worker.sh 退出时 sentinel 还没被发明，是 polling-based
• DEC-030（2026-06-05）基于"background bash 不可靠"判断，保守地建议不要用 run_in_background=true 等待 worker

但是 2026-06-05 的 3 phase spike 实测验证：`run_in_background=true` Bash 任务在 exit 时 Claude Code harness 必 re-invoke 父 agent。Sentinel 模式把这件事工程化。

2. 模式

每个 worker 配一个轻量 sentinel bash 进程：

PM (foreground)              PM background (run_in_background=true)
   │                                │
   │ Bash: spawn-worker.sh          │ Bash: sentinel.sh
   │  → 创建 worktree               │  → poll STATUS.json
   │  → 启动 tmux worker            │  → 检测到 terminal
   │  → 输出 SPAWN_WORKER_GATE      │  → capture pane
   │  → 输出 SPAWN_WORKER_SENTINEL_CMD
   │                                │  → tmux kill-session
   │                                │  → exit
   │                                │
   │ 读取 gate 结果，决定下一步      │ ⬇ harness task-notification
   │                                │ PM 被 re-invoke

PM 端两次调用（foreground spawn + background sentinel），PM 主会话不被阻塞。

3. 关键约束与设计选择

3.1 Sentinel 是新脚本，不是 wait-worker.sh 的 flag

wait-worker.sh 的 contract 是"wait and report"（纯函数，可被 pm-monitor.sh 当只读探针用）。Sentinel 的 contract 是"wait and kill"（破坏性）。两者混淆会让 grep 规则和 pm-monitor 解析都混乱。分开维护。

3.2 杀 tmux 用 inline tmux kill-session，不调 clean-worktree.sh

clean-worktree.sh 同时处理 worktree 删除 / branch 删除 / force-remove-dirty 等"全量清理"动作。Sentinel 只想释放 worker tmux 资源，不要碰 worktree / branch（review 阶段还要看）。

3.3 Sentinel 输出到 SENTINEL_OUT.log，事件前缀 SENTINEL_*

WAIT_WORKER_* 事件家族由 pm-monitor.sh 当作只读探针事件消费。Sentinel 事件独立命名空间（SENTINEL_TERMINAL / SENTINEL_TMUX_KILLED / SENTINEL_TIMEOUT 等），不污染 WAIT_WORKER_* 消费者。

3.4 Reuse redact_sensitive_stream 内联复制，不抽公共库

wait-worker.sh:187-203 的 redact_sensitive_stream 函数直接复制进 sentinel.sh（line 73-89）。不抽成 lib-redact.sh：

• 抽公共库需要所有脚本 source，引入 cross-script 依赖
• 维护成本（更新 1 处 vs 2 处）大于 15 行代码体积的收益
• 万一 1 处更新漏掉，redact 行为不一致会泄漏密钥

3.5 退出码对齐 wait-worker.sh

0 = done，2 = failed/blocked/stopped，64 = usage error，124 = timeout。PM 端可以用同一段处理逻辑。

3.6 Sentinel 必须 run_in_background=true 启

Foreground 启的 Bash 任务退出时 harness 不 re-invoke。这是 sentinel 模式能 work 的关键 — run_in_background=true 是 PM 显式 opt-in，告诉 harness："这个任务的 exit 我想收到通知"。

3.7 不在 spawn-worker.sh 内部启 sentinel

Plan 阶段考虑过把 sentinel 启动合并进 spawn-worker.sh。否决的两个原因：

1. 职责分离：spawn-worker.sh 是 PM 用的 fg 工具，sentinel 是 PM 用的 bg 工具。混在一起会让 PM 看不到 gate 验证（如果 spawn-worker.sh 本身被 bg 启）。 2. 更稳的 auto mode 兼容性：Spike 2026-06-05 验证，单次 foreground Bash 调用 + 一次 explicit `run_in_background=true` 调用比"单次 Bash 内部 fork 多个 background"更不容易被 auto mode 拒。spawn-worker.sh 内部启 sentinel 会让单次 Bash 包含 1 个 fg 子进程 + 1 个 nohup'd background，auto mode 把它当作"多 background"可能拒。

替代方案：让 spawn-worker.sh 在 gate 通过后输出 SPAWN_WORKER_SENTINEL_CMD: ... 命令，PM 在自己的下一个 Bash 调用里 run_in_background=true 启它。两次 PM 调用 vs "一次但内部 fork"。

4. 与 DEC-030 的关系

4.1 DEC-030 的判断

DEC-030 说 background bash 不可靠，依据是：

多 worker 同时等待时尤其可能没有任何完成消息返回

意思是：如果 PM 启 N 个 background wait，harness 不会保证每条完成消息都送达 PM，事件可能丢。

4.2 Sentinel 模式如何不同

4.3 Spike 实测数据（2026-06-05）

3 phases 全部通过，可重放脚本保留在 /tmp/faropdf-spike-00{1,002,003-*}/：

关键观察：

• Harness 不区分 exit code，0 / 1 / 124 都 re-invoke
• 多次并发 notification 同 turn 批处理，不会拆成多次唤醒
• 单 background 调用拒率 < 100%（spike 1/6 = 17%），但 graceful 降级是默认行为

4.4 DEC-031（新建）的判断

Sentinel 模式是 DEC-030 的"限定条件下的可工作版本"：

• 限定条件：PM 同时启的 background sentinel 数量 = 当前未完结 worker 数（线性而非 N×N）
• 限定条件：每个 sentinel 是单进程、独立 cwd、独立 STATUS.json 路径
• 限定条件：sentinel 失败 = graceful 降级到 pm-monitor，不影响 Wave 整体进度

5. 失败降级路径

6. 调优

6.1 轮询间隔

默认 5s，spike 验证 1s 也行。

• 太密（< 2s）：worker 写 STATUS 时 sentinel 大量空转，浪费 CPU
• 太稀（> 30s）：PM 唤醒延迟 + worker 终态到 sentinel exit 的间隔变大
• 推荐：根据 worker 平均 step 长度调整。如果 worker 单次 thinking 5-10 分钟，5s 间隔足够；如果 worker 单次 30s，1s 间隔更即时

6.2 最大等待时间

默认 7200s（2h）。

• 配合 worker-prompt.md 的 30-60 分钟阶段 commit 习惯：worker 跑超 2h 大概率卡死或偏题，应已被 pm-monitor stale 告警
• 短任务（< 10 分钟）：可设 900s
• 长任务（> 2h）：考虑分 worker，每个 worker 自己的 --max-wait

6.3 阶段 commit 频率

Sentinel 依赖 STATUS.json 终态事件，不依赖 commit。但：

• 阶段 commit 帮助 PM 在 worker done 后快速 review
• pm-monitor.sh 的 WORKER_STALE_NO_COMMIT 告警和 sentinel 互补

7. 相关文件

• scripts/sentinel.sh：sentinel 主脚本
• scripts/spawn-worker.sh：输出 SPAWN_WORKER_SENTINEL_CMD 提示 PM
• scripts/smoke-sentinel.sh：端到端 smoke test
• scripts/lint-wait-script.sh：把 sentinel.sh 加进默认 lint
• templates/pm-sentinel-response.md：PM 收到 notification 后的响应清单
• references/03-checkpoint-files.md：STATUS.json 终态定义
• DEC-030：被 supersede 的历史判断
• DEC-031：sentinel 模式 DEC（新增）

8. 已知不覆盖

• 多 sentinel 对单 worker 去重：PM 行为层处理（一个 worker 只能启一个 sentinel），sentinel 假设 1:1
• Codex / OpenCode 路径：暂未实测 Codex heartbeat automation 集成，按 templates/codex-heartbeat-wait.md 单独处理
• Wave 6 之前：保留 DEC-030 文本，PM 仍可走 pm-monitor 巡检模式

并行 Agent 法律实务场景

来源：多会话并行 Agent 工作流研究 Part II

范围：法律项目任务拆解、诉讼/非诉模板、多 Agent 协同

---

1. 法律项目的任务拆解模式

法律工作与软件开发在任务拆解上有本质差异：

2. 诉讼项目模板

诉讼项目的典型阶段和 Agent 分派方式：

┌─ Phase 1: 案件评估 ──────────────────────────────────────┐
│ [Research Agent] 案由检索 → 类案检索 → 管辖权分析         │
│ [Analysis Agent] 诉讼请求设计 → 风险评估 → 策略建议       │
│ ⚠️ 依赖关系：研究完成 → 分析开始                          │
├─ Phase 2: 证据整理 ──────────────────────────────────────┤
│ [Research Agent × N] 多个证据线索并行调研                  │
│   - 证人证言准备                                          │
│   - 书证收集与整理                                        │
│   - 电子证据固定                                          │
│ [Integration Agent] 证据目录编制 → 证明力分析             │
│ ✅ 证据线索之间可并行                                     │
├─ Phase 3: 法律文书 ──────────────────────────────────────┤
│ [Writer Agent] 起诉状/答辩状 → 代理词 → 法律意见书        │
│ [Review Agent] 法律准确性审查 → 逻辑审查 → 格式审查       │
│ ⚠️ 依赖关系：Phase 1+2 完成 → 文书起草                    │
├─ Phase 4: 庭审准备 ──────────────────────────────────────┤
│ [Analysis Agent] 争议焦点整理 → 对方论点预测              │
│ [Writer Agent] 代理意见 → 庭审提纲                        │
│ ✅ 焦点整理和论点预测可并行                               │
├─ Phase 5: 庭后跟进 ──────────────────────────────────────┤
│ [Writer Agent] 代理词补充 → 庭后意见                      │
│ [Integration Agent] 案件总结 → 经验沉淀                   │
└──────────────────────────────────────────────────────────┘

诉讼项目的 Agent 路由矩阵：

3. 非诉项目模板

非诉项目（以尽职调查和合同审查为例）：

┌─ 尽职调查项目 ──────────────────────────────────────────┐
│                                                          │
│ [Research Agent × N] 并行尽调模块：                      │
│   ├── 公司基本情况（工商、股权结构）                      │
│   ├── 资产情况（不动产、知识产权）                        │
│   ├── 合同与债权债务                                      │
│   ├── 劳动用工                                            │
│   ├── 诉讼仲裁                                            │
│   └── 合规与监管                                          │
│                                                          │
│ [Analysis Agent] 各模块风险汇总 → 风险等级评定            │
│ [Writer Agent] 尽调报告初稿 → 问题清单                    │
│ [Review Agent] 法律准确性 + 披露完整性审查                │
│ [Integration Agent] 最终报告整合                          │
│                                                          │
│ ✅ 尽调模块之间天然可并行                                 │
│ ⚠️ 风险汇总依赖各模块完成                                │
└──────────────────────────────────────────────────────────┘

┌─ 合同审查项目 ──────────────────────────────────────────┐
│                                                          │
│ [Research Agent] 交易背景调研 → 行业惯例检索              │
│ [Analysis Agent × N] 并行审查维度：                      │
│   ├── 合同主体资格                                        │
│   ├── 权利义务条款                                        │
│   ├── 违约责任                                            │
│   ├── 知识产权归属                                        │
│   ├── 保密与竞业                                          │
│   └── 争议解决机制                                        │
│ [Writer Agent] 审查意见书 → 修改建议                      │
│ [Review Agent] 整体一致性 + 遗漏检查                      │
│                                                          │
│ ✅ 审查维度之间天然可并行                                 │
└──────────────────────────────────────────────────────────┘

4. 法律"类 Issue"拆解方法论

法律项目不一定使用 GitHub Issue。任务源由具体项目约定；cross-agent-coordination 可按项目配置解析和分配任务，本 Skill 只负责把可执行任务拆给本地 Agent 会话。

4.1 任务载体对比

4.2 法律项目的任务字段

{
  "task_id": "LIT-001",
  "title": "检索 XX 案由的类案裁判规则",
  "project_type": "litigation",
  "phase": "case_assessment",
  "status": "in_progress",
  "priority": "high",
  "owner": "claude",
  "platform": "claude-code",
  "archetype": "research",
  "external_agents": [],
  "deliverable": "research_report.md",
  "depends_on": [],
  "review_policy": "legal_accuracy",
  "risk_level": "medium",
  "updated_at": "2026-05-04T16:00:00+08:00"
}

与软件开发相比新增的字段：

• project_type：litigation（诉讼）/ non_contentious（非诉）/ legal_research（法律研究）
• phase：项目阶段（对应上方模板中的 Phase 1-5）
• external_agents：需要调用的外部法律 Agent（按项目实际安装填写）
• deliverable：产出物类型
• review_policy：审核策略（legal_accuracy / contract_review / compliance_check）

4.3 拆解流程

用户输入上下文（案件事实/项目背景/客户需求）
    ↓
[Analysis Agent] 识别项目类型和阶段
    ↓
[Planning] 根据模板生成任务清单
    ↓
[Dependency Analysis] 标注并行/串行关系
    ↓
[项目任务源] 写入主状态
    ↓
[Dispatch] 按依赖图启动 Agent（tmux 可视化）
    ↓
[Monitor] 轮询完成状态
    ↓
[Integration] 汇总产出 → Review → 定稿

5. 多 Agent 协同的法律场景

5.1 Agent 选择策略

不同法律任务的最优 Agent 组合：

6. 使用边界

本文档只提供法律项目在多 Agent 本地执行层的拆分样例，不定义任务主状态、外部 Agent 注册表或法律模板文件路径。

• 任务来源、负责人、依赖和交接记录由 cross-agent-coordination 及项目任务源维护。
• 本 Skill 只负责把已确认可执行的任务分配到本地 session、worktree 和 PM 巡检流程中。
• 需要法律检索、OCR、语音转写等能力时，在 worker prompt 中说明调用对应 Skill，不在本参考文档中新增独立 catalog。

Patch Summary

Intent

这次 diff 要解决的问题。

Scope

• 允许范围内的文件。
• 没有触碰的共享文件。

Behavioral Changes

• 用户可见或系统行为变化。

Tests

• 已运行测试。
• 未运行测试及原因。

Review Notes

• PM review 时应重点看的地方。

Result

Status

done

Summary

• 完成了什么。
• 没有完成什么。

Validation

• {{command}}: passed / failed / not run

Files Changed

• {{path}}: 改动目的。

Risks

• 剩余风险或未覆盖测试。

Next Steps

• 后续建议。