name	multi-agent-orchestration
description	当用户要求你并行推进多个任务、一次性开多个 worker/agent 同时工作、用 tmux 启动多个独立 session、防止 PM 直接实现逃逸、或者你作为 PM 需要拆解并派发任务给多个独立 worker 时使用。触发词包括"并行推进""开多个""同时推进""派 worker""多 agent 并行""开 worker""tmux 启动""独立 session""防逃逸""分派任务""一起做"。不要用于单个短任务、跨平台任务状态管理、或 Git 分支/提交/PR/merge 安全规则。
license	MIT
homepage	https://github.com/cat-xierluo/legal-skills
author	杨卫薪律师（微信ywxlaw）
version	1.19.0

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. 执行模式

模式	适用	默认隔离
PM 直接处理	轻量、低风险、无并行价值	当前工作区
同宿主 Subagent	窄范围分析、审阅、局部修订、短任务一发跑完（替代已删除的 headless `-p`）	通常不新建 worktree
Claude Code Agent Teams	Claude Code 做 PM 且需要团队式协作	worktree + branch
tmux 独立 CLI session	需要跨产品 worker、长上下文、独立额度或独立进程	worktree + branch
tmux 轻量 session（`--no-worktree`）	派多个 worker 各自占一个独立文件夹、目标不是 git 仓、或不需要 git 级隔离	无 worktree，隔离 = 文件夹分离（非默认，见 §2.1.1）
Claude Code agent view	需要使用官方后台会话、peek/reply/attach 和 `claude agents` 总览	可用 Claude 官方 `--worktree` / `--tmux`，或手动 worktree
ACP adapter	项目已提供稳定 adapter，且需要结构化事件流	adapter 决定，仍建议 worktree + branch

headless / batch 模式（claude -p / codex exec - / opencode run / codebuddy -p / qoder -p）已于 v1.18.0 移除（DEC-044）。所有 tmux worker 必须交互式启动，PM 靠 tmux send-keys 投递 prompt 并全程可纠偏。短任务一发跑完的场景改用同宿主 Subagent，不要再派 tmux worker + headless——那既丢监控又白费编排开销。

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

2.1 防逃逸门禁

强制 session 触发条件：

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

触发后，PM 在任何业务实现前必须完成启动门禁：

创建或确认隔离 worktree、语义分支和 Session Context 路径。
启动 tmux session；Claude 官方 --worktree --tmux 可作为 Claude 专用等价入口。
用 tmux has-session / tmux list-sessions / claude agents --json 验证 session 存活，并确认 pane cwd 或 agent cwd 指向目标 worktree。
给 worker 发送 Bootstrap-only prompt 或 Full worker prompt，prompt 必须包含 Branch、Worktree、Session Context、Runtime Profile、Allowed files、Forbidden files、验证命令和 Execution Authority（安装门禁模式、精确授权命令、授权来源）。
在 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.1.1 轻量模式（无 worktree，非默认）

默认仍是 worktree + branch 隔离。轻量模式只在两种情况下启用，不是默认、不是静默降级：

用户显式要求：PM 看到用户明确说「不要 worktree / 直接改 / 单 session 派多个 worker 各管一个文件夹 / 轻量模式」，或直接传 spawn-worker.sh --no-worktree。
目标目录不是 git 仓：spawn-worker.sh 检测到 --project 不在 git work tree 内，自动切轻量并打印 SPAWN_WORKER_LIGHTWEIGHT_AUTO 通知（仍可被 --branch 缺省等线索识别）。用户既没传 --no-worktree 也没传 --branch/--worktree 才触发自动切换；显式 --branch 则仍走 worktree 模式，按普通流程处理（目标非 git 仓时报错）。

轻量模式下 worker 的隔离 = 文件夹分离，不是 git worktree：

worker 的 tmux session cwd 直接指向目标文件夹（--project，或 --worktree 覆盖的子目录），不建 worktree、不切分支、不算 base ref。
Isolation Gate 只验 pwd == 目标文件夹，不验 branch（目标可能根本不是 git 仓）。
METADATA.json 记 isolation.mode: "lightweight" + isolation.lightweight_auto（自动切时为 true），branch / base_ref / base_sha 留空。
Session Context 仍建在 <目标文件夹>/.claude/agent-sessions/<session>/，sentinel / pm-monitor / scope-guard 照常工作。

PM 派多个轻量 worker 时的硬约束：

每个 worker 占一个独立、互不重叠的文件夹。轻量模式没有 worktree 物理隔离，两个 worker 改同一 git 仓的重叠路径会互相覆盖——这种场景必须回到默认 worktree 模式。
越界防护更依赖 --allow-paths（scope-guard settings 硬拦）和 prompt scope 软约束，因为没有「独立 worktree 天然只看得见自己分支」这层兜底。
目标文件夹若是 git 仓，worker 共享主工作树：commit 走该仓当前分支，不要假设有独立分支/PR；目标若不是 git 仓，无 commit/PR，交付物直接落盘 + 写 RESULT.md 清单，PM 直接读文件 review。

什么时候不该用轻量模式：任务需要独立分支/PR、需要和主干隔离的验证、或多个 worker 可能改到同一仓库的重叠文件——这些都走默认 worktree 模式。

2.2 角色与后端

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

角色	职责	可由谁担任
PM	读取任务源、分组、启动 worker、巡检、验收、合并收口	当前 Codex、Claude Code、OpenCode 或其他主会话
Worker	在指定 worktree/branch 内完成限定任务	Claude Code、Codex、OpenCode、自定义 CLI、shell 脚本、未来 ACP agent
Reviewer	检查 diff、测试、范围和风险	PM、另一个 worker、code-review subagent

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 acp 能力时，worker backend 选 OpenCode（worker 走交互式 opencode --model，headless opencode run 已于 v1.18.0 移除）。
需要消耗 WorkBuddy/CodeBuddy 或 QoderWork 平台额度（复用桌面端登录态、零 API Key、含每日免费模型）时，worker backend 选 codebuddy / qoderwork-cn；这是跨工具例外（§2.3），适合额度分流或评测 fan-out。两者均由 render-runtime-profile.sh 统一生成命令（含 qoder 的 SDK 变量清除、codebuddy 的 -y）；外部 CLI backend 的 worker spawn 默认用 snapshot-copy-into-worktree（DEC-037）自包含。
其他 Agent 只要能用一行命令启动，并能在指定 cwd 读写文件，也可作为 custom CLI worker。
需要稳定进程生命周期和人工接管时，优先 tmux + worktree；触发 §2.1 时，tmux + worktree 是默认执行层，不是可静默跳过的建议。
ACP 只在 adapter 已稳定、能输出结构化状态时启用；没有 adapter 时不要为了协议增加不确定性。

Backend → 默认模型速查表（同宿主 worker 仍按 §2.3 优先；以下默认仅在 PM 主动跨工具或用户明确指定该 backend 时生效）：

Backend	默认 model（首选 → 备选）	适用场景	备注
Claude Code	model 见 personal config `main_force.task_routing`（常规/高端 vs 简单+多模态，按任务路由非轮换）	默认主力 host；同 provider 并发上限见 `concurrency`，溢出到跨平台 backend	详细 provider 映射见 `config/claude-provider-registry.example.json`
Codex	（见 §2.4 codex_policy）	用户明确要求时	智能高额度贵，默认不主动派
OpenCode	`opencode:<provider>/<model>`	OpenCode 已有额度	按 OpenCode profile
`qoderclicn`（QoderWork CN）	model 见 personal config `backend_model_routing.qoderclicn`	用户主动要求 / 主力并发打满溢出（跨平台/跨额度避并发）	SDK 变量需清理
`codebuddy`（WorkBuddy/CodeBuddy）	model 见 personal config `backend_model_routing.codebuddy`	用户主动要求 / 主力并发打满溢出（跨平台/跨额度避并发）	默认带 `-y`

本表不列具体模型——模型与框架选型是个人偏好（每人可用的 provider/平台额度不同）。具体 model 全在 config/orchestration-personal.json（你的）+ .example.json（通用模板）；本表只列 backend 能力 + 模型配置字段位置，缺失时交 PM 按 §2.4 个人偏好读。

环境/profile 纪律：

PM 启动 worker 时必须显式写 Runtime Profile、settings/profile 路径、模型来源和关键环境变量处理方式，不假定 Claude Code、Codex、OpenCode 共享同一套 shell 环境。
Claude Code 第三方 API provider 推荐使用 provider registry：config/claude-provider-registry.example.json 描述多个 provider 的 base_url、auth_token_env / api_key_env、auth_type 和 models；真实 registry 放 ignored local 文件，真实 key 优先放环境变量。旧的单 provider --settings <*.settings.json> 路径保留兼容。
Claude Code 第三方 API provider profile 要保留 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / 默认模型映射；不要套用 OAuth 的清理命令。registry 模式由 wrapper 动态生成这些 env，不需要为每个模型维护一个 settings 文件。
Claude Code 第三方 API provider 必须显式传 --model <provider-model>，settings 文件也应包含 ANTHROPIC_MODEL / ANTHROPIC_MODEL_NAME。只传 --settings 不足以隔离用户级 ~/.claude/settings.json 或继承环境中的 ANTHROPIC_MODEL；实测会出现 settings 指向 GLM、界面和实际默认模型仍显示 MiniMax 的混合状态。
Claude Code 第三方 API provider 默认由 scripts/render-runtime-profile.sh 生成 scripts/claude-provider-env.sh wrapper 命令。wrapper 会先清理继承的 Claude/Anthropic provider 路由变量，再从目标 settings JSON 导入 env，或从 registry 的 provider/model intent 解析 env；补齐 ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY，设置 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1，并给 claude 注入 --setting-sources project,local，避免用户级 ~/.claude/settings.json 的 provider/model 污染本次 worker。
只有排障时才可用 --no-provider-env-isolation 绕过 wrapper；PM 必须在 Wave 计划和 METADATA.json 的 runtime.env_isolation 中记录这个例外，并启动后核对 banner / STATUS provider。
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 摘要里标注。

2.4 个人路由偏好（用户级，可被任何人自定义）

§2.2 / §2.3 给的是 skill 级默认规则，但每个用户的"主力 / 轮换 / 哪个 backend 给哪个模型"是个个人偏好，不应该硬编码进 skill。机制：

配置路径：config/orchestration-personal.json（在 skill 目录，但 gitignore 不入库——每人本地放自己的实际偏好；不 commit 进仓库，避免把个人模型/框架固化进通用 skill。.example.json 是入库的通用模板）。
模板路径：config/orchestration-personal.example.json（schema 文档 / 给 fork 用户的干净模板）。
读取时机：PM 派 worker 前先读 config/orchestration-personal.json；缺失则回落 .example.json 默认。
作用域：仅声明"偏好"（host、model 轮换、codex policy、跨工具 backend 的默认 model），不声明真实 token / key / endpoint——那些仍归 config/claude-provider-registry.*.json 管。

字段定义（与 example schema 对齐）：

字段	含义	缺省回落
`main_force.host`	PM 主力宿主工具（你用的 Agent 工具：`claude-code` / `codex` / `opencode`）	`claude-code`
`main_force.task_routing.high_end`	常规/高端任务的 model（你自选）	无（必填）
`main_force.task_routing.simple_multimodal`	简单任务+多模态/图片解读的 model（你自选）	无
`main_force.task_routing.default`	任务类型不明时回落（通常 = high_end）	无
`concurrency.max_per_provider`	同一 provider 并发上限（尽量更低避限流连累其他任务）	用户定（示例 3）
`concurrency.overflow_strategy`	超上限时溢出到哪些 backend（不同平台/额度避并发）	用户定
`codex_policy.policy`	`explicit_only` / `allowed`	`allowed`（向后兼容）
`backend_model_routing.<backend>.default_models`	跨平台 backend 的默认 model（首选在前）；`<backend>` = 你常用的 CLI 名	留空 → 不启用跨平台溢出

Codex 硬规则（个人偏好中最重要的一条）：

codex_policy.policy = "explicit_only" 时，PM 不主动把任何 worker 路由到 Codex；只有用户当轮明确说"用 Codex"才解封，并写到 Wave 计划里。
这条独立于 §2.3 同宿主优先：即使 §2.3 同宿主工具是 Codex host，PM 仍按此政策判断是否派 worker 到 Codex。
想恢复 Codex 默认可用，改 policy = "allowed"。

与 §2.2 / §2.3 / §3.3 的关系：

§2.2 backend 表 → §2.4 个人偏好 → §3.3 项目级 provider slot 默认 → 最终 backend / model 选择。优先级 §2.3（不主动跨工具）压 §2.2（多 backend），§2.4 个人偏好压 §2.2 默认 model 表，§3.3 项目级 provider slot 计划压 §2.4 通用 host。
§2.4 字段命名故意跟 §3.3 项目级 provider slot 不冲突：项目级 slot 写的是"这一 Wave 用哪个 slot 跑哪个 worker"（含 model、max_concurrency）；§2.4 写的是"我个人偏好默认用什么 host / 什么 backend 给什么 model"。前者落地到 Wave 计划，后者落地到 PM 派单决策。

TODO（后续增强）：scripts/render-runtime-profile.sh 自动读 personal config（解析 main_force.task_routing → 默认 --model、解析 codex_policy.policy → 是否允许 codex backend、解析 backend_model_routing.<backend>.default_models → 跨工具 default）当前未实现；本次只做配置 + 文档 + PM 手动遵循，避免无人监督下改脚本引入新不确定性。需要做的时候开新 worker，不要在 PM 任务里顺手改。

3. 标准流程

读任务源与项目配置：若项目提供 .claude/orchestration.config.json 或等价配置，先读取 trunk、任务源、验证命令、可复制配置和 hook 边界；再用 cross-agent-coordination 判断可执行项、依赖和归属。
先分组：不要默认一个 Issue 一个 worker。文件范围重叠、同一章节/模块、存在依赖链的任务应同组顺序执行。
判定并行安全：只有文件范围清晰、无共享迁移/锁文件/schema、验收标准独立时才拆成多个 worktree 并行。
判定是否触发防逃逸门禁：只要用户或项目明确要求 tmux / 独立 session / 开 worker，按 §2.1 执行；门禁未通过前不写业务代码。
选择 worker backend 和 runtime profile：按任务复杂度、当前额度、模型偏好和是否需要独立进程，选择 Claude Code / Codex / OpenCode / custom CLI / shell / ACP。
PM 创建隔离环境：默认由 PM 创建 worktree、分支和 session context 目录，再把路径交给 worker；只有 Claude Code 官方 Agent Teams / agent view 明确使用自身 --worktree 能力时，才允许由 Claude Code 创建，但 PM 仍要验收分支、路径和隔离状态。用户明确要求「不要 worktree」或目标目录不是 git 仓时，改用轻量模式（§2.1.1）：spawn-worker.sh --no-worktree，worker 直接在目标文件夹工作，隔离靠文件夹分离 + scope-guard。
启动 worker 并验证门禁：给每个 worker 明确目标文件、允许修改范围、验证命令、session context 目录、提交和 PR 要求；默认启用 Agent 直接工具调用门禁，验证命令不构成安装授权，只有带授权来源的精确命令可以放行；确认 session 存活、cwd/branch 正确、runtime hook attestation 与 STATUS.json 出现，或已发送 bootstrap correction。
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 作为兜底观察。发现偏题、阻塞、范围扩大或无阶段性提交时介入。
PM 验收而非代写：PM 对 worker 结果做范围检查、测试复核和 review；发现问题优先发纠偏指令或派给 reviewer/另一个 worker，不默认自己改业务代码。
收口：worker 提交并开 PR 后，PM 做范围检查、触发 review、按 git-workflow 合并和清理。
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 / registry 或 settings/profile 路径 / 额度来源 / 并发槽位。超过 3-4 个 worker 时，不要压在单一 API provider 或同一个 provider key 上；应跨 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 推荐用 registry + provider id + model alias 区分，例如 config/claude-providers.local.json + <provider>/<model-alias>；旧路径也可用具体 settings 文件区分，例如 config/<your-provider>.settings.json。真实 registry/settings 文件保持本地 ignored，不提交；具体用哪个 provider/model 见 personal config。
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 示例：

Worker	任务风险	Backend	Settings/Profile	Slot
W1	高	Claude Code	`config/<provider-a>.settings.json`	`<provider-a>-1`
W2	中	Claude Code	`config/<provider-a>.settings.json`	`<provider-a>-2`
W3	低	Claude Code	`config/<provider-b>.settings.json`	`<provider-b>-1`
W4	低	Claude Code	`config/<provider-b>.settings.json`	`<provider-b>-2`
W5	文档/研究	Codex	`codex:<profile>`	`codex-1`
W6	重复性低风险	OpenCode/custom	`<provider/model or command label>`	`opencode-1`

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

多维度批量任务的颗粒度纪律：worker 在一个 prompt 里改多维度时，注意力会被高优维度占满、末位维度静默漏掉。多维度任务用 checklist prompt 强制逐维度（每维度独立 commit / 勾选）、大批量改后派 wave2 复查 worker 抓漏、精细深查（箭头 / 字体 / 像素）拆单维度 worker。详见 references/09-parallel-lessons.md G22。

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 按以下顺序决定是否自动继续：

读取任务源，关闭已完成项，识别可执行 pending task、依赖、文件范围和共享风险。
确认当前 Wave 没有未处理的 failed/blocked worker、未验收 PR、base drift、冲突、主干验证失败或敏感/破坏性操作。
根据上一 Wave 的 provider/model 评估调整并发：干净通过可维持或小幅增加，出现冲突、范围越界、验证失败或限流则降并发。
若仍有可安全并行的任务，创建下一 Wave；若只剩高冲突/高风险任务，降为 1-2 个 worker 或停下请求用户确认。
若成功条件满足，写 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 命令。

与 §2.4 个人偏好叠加（用户级 vs 项目级）：

维度	用户级（§2.4）	项目级（§3.3）
路径	`config/orchestration-personal.json`	`.claude/orchestration.config.json`
内容	个人主力 host、默认 model 轮换、Codex policy、跨工具 backend 默认 model	trunk / 任务源 / 验证命令 / 本项目 provider slot 默认计划 / hook
谁写	用户自己	项目维护者
谁读	PM 派 worker 前	PM 启动 Wave 前
优先级	低（个人通用偏好）	高（项目覆盖个人）

例：个人偏好 host=claude-code + model=<你的模型>；项目级 provider slot 计划写"本 Wave 的 W3/W4 走 <某 provider>"——则 W3/W4 用该 provider，其他 worker 仍按个人偏好。两者不冲突，也不应互相复制；项目级不写个人偏好字段（避免把 dotfile 化进仓库）。

配置安全规则：

永远不要默认复制 .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 明确列出的验证命令。

3.4 目标目录基线准备：untracked files → init commit（踩坑 2）

worktree 只复制 tracked tree，不会复制 untracked 文件。PM 派活前若目标目录是新建未提交的，worker 拿不到基线，task 必失败。

现象：spawn worker 后 ls worktree/<target>/ → 不存在（untracked 文件不在 tracked 树里）。
解决（启动 Wave 前必做）：
```
git add <target-untracked-dir>
git commit -m "[init] 基线：<target-untracked-dir>"
git push
```
确认远端 tracked 后再 spawn worker，worktree 才能正确 checkout 到基线文件。一句话记牢：untracked 文件先 init commit 推上远端，worker 才有基线可读。
路径含空格是常态（如 Library/Application Support）：spawn-worker.sh --project "<path with spaces>" 必须双引号包裹；脚本内部已用 "$VAR" 形式，可正常工作，但 PM 手写命令时勿漏引号（踩坑 4）。

3.5 spawn 后 auto-bypass（v1.18.3）—— PM 不需要手按 dialog

v1.18.3 关键修复：spawn-worker.sh 已自动化 trust + permission dialog 兜底，PM 不需要 tmux attach 盯 30-60s 手按。spawn-worker.sh 主流程调用三层保护：

trust_auto()（v1.17.5，保留）：同步 30s 监控 trust dialog，命中按 Enter 选 option 3（Trust folder and all subdirectories）。
permission_auto()（v1.18.3 关键修复）：同步 60s 监控 "Do you want to proceed?" dialog，命中改用数字键 2（不再用 Down Enter，PM 2026-07-08 wave-1 实测 Down Enter 在某些 TUI 状态不稳）。
permission_auto_bg()（v1.18.3 新加）：后台 watcher（disown），持续 7200s 监控 dialog 兜底。覆盖同步 60s 窗口外的 dialog（worker 启动后 60-7200s 期间任何 tool 调用都自动按 2）。

PM 派活后不需要 attach tmux 或手按 dialog。如果 worker 在 spawn 后 1-2 分钟还没写 STATUS.json，再看 sentinel/cron 通知（说明 dialog 真的卡了，再用 tmux attach 手动 inspect）。

v1.18.4 增：claude-code backend 默认全关上述三层监控（实测 --permission-mode auto --bare 不弹 dialog，省 90s 空等）；详见 §3.8.4。其他 backend 维持 v1.18.3 行为。

历史踩坑（v1.18.2 之前）：wave-1/2 PM 反复按 1/2 接 dialog（v1.18.2 文档化但未真正修）。v1.18.3 自动化了，按踩坑 7 修复。

MCP 选择 dialog 不被 auto-bypass 覆盖（2026-07-11 实测）：上述三层只处理 trust + "Do you want to proceed?" dialog；项目若配 MCP server，claude-code worker 启动还会弹「N new MCP servers found」选择 dialog，worker 卡住不写 STATUS。解法：worker 不需 MCP 时 spawn 后 tmux send-keys -t <session> Escape 拒绝全部，或 spawn 命令带 --strict-mcp-config --mcp-config '{"mcpServers":{}}' / 补 --bare。详见 references/09-parallel-lessons.md T6。

3.5.1 auto-bypass 实现细节（v1.18.3）

permission_auto 关键修复：旧版用 Down Enter（按箭头 + Enter 选 option 2），PM 2026-07-08 wave-1 实测在某些 TUI 状态不稳。v1.18.3 改用 tmux send-keys -t "$session" "2"（直接发数字键 2），稳定 work。
permission_auto_bg 后台 watcher：通过 ( permission_auto_bg "$SESSION" & disown ) & 启 disown，spawn-worker.sh 退出不影响 watcher。watcher 默认 7200s（与 sentinel --max-wait 对齐），可用 env var SPAWN_PERMISSION_BG_MAX_WAIT / SPAWN_PERMISSION_BG_POLL（默认 5s）调整。
新 flag --no-permission-auto：v1.18.3 精细 opt-out，只关 permission_auto + permission_auto_bg（不影响 trust_auto）。与 --no-trust-auto（同时关 trust + permission）区分。
smoke 验证：bash scripts/smoke-auto-bypass.sh（v1.18.3 新增）验 7 项：函数定义、数字键、bg 函数、flag 解析、调用点、usage、头部注释。

3.6 captcha 类 worker 必读（踩坑 6）

gov-info-query 三站共用 VL 验证码识别，频繁撞 429 Too Many Requests，是当前最大瓶颈。
PM 派 captcha 类 worker 时，prompt 必须点名 sibling skill ../captcha-auto/（HANDOFF.md §1 有 buildVisionRequestBody + retry/backoff），并要求：失败 ≤ 3 次 + 指数退避，仍失败则降级 JSON 交 PM 人工重跑，禁止自写 VL 调用。详见 references/08-workbuddy-cli-worker.md §13。
硬约束（用户强约束「captcha 一定不要我手动输入」）：worker 必须自动调用 captcha-auto skill 完成验证码识别——即由 worker 自己用 buildVisionRequestBody 构造请求 + 自管 fetch 调用，把识别结果回灌任务流程。严禁任何形式的「把验证码贴给用户 / 让用户手动输入 / 等用户键入验证码再继续」。这条约束与 §3.7 配套：PM 派发 prompt 必须把 captcha-auto 的绝对路径写进「Project Skills」段，worker 才能用 Read 按需读取并自动执行，而不是在独立 cwd 里找不到 skill 而退化成向用户要验证码。

本节即「派发 SOP 必带 skill 路径清单」：wave-1 期间 worker A/B/C 都因「不知道 sibling skill 路径」撞 captcha 429 / 花大量时间找路径。根因：非 Claude Code 的 worker（codebuddy / qoderwork / 跨工具 backend）跑在独立 cwd，默认看不到 Claude Code skills 目录，PM 不显式给路径，worker 就只能瞎找或退化成向用户要验证码。本节能范化未来 PM 派活。

强制规则（PM 派发前必做）：

PM 派活前，先在本机收集本项目相关的 sibling skill 路径清单。每个可能用到的 skill 跑一次：
```
ls <project-root>/<sibling-skill>/SKILL.md
```
把绝对路径（或相对 worktree 的稳定相对路径）记下来，例如：
- captcha-auto：/abs/path/to/captcha-auto/SKILL.md
- 其他任务相关 skill：同理逐个确认存在。
PM 把收集到的路径清单写进 worker prompt 的 「Project Skills」段（标准字段见下），要求 worker 用 Read 按需读取，不要靠 worker 自己猜路径。
任何涉及验证码的任务，PM 必须把 captcha-auto 的 SKILL.md 绝对路径写进「Project Skills」段——这是 §3.6「worker 必须自动调 captcha-auto、禁止用户手动输入」的前置条件。路径不进 prompt，worker 在独立 cwd 找不到 skill，就会退化成向用户要验证码，违反用户强约束。
「Project Skills」段是 worker prompt 的硬约束段，与 Isolation Gate / Heartbeat / Commit 同级，省略会直接导致收口失败（worker 找不到 skill → 卡死 / 偏题 / 向用户要验证码）。

「Project Skills」段标准模板（嵌入 worker prompt，放在 Background 与 Mission 之间）：

## Project Skills（PM 派发必带，worker 用 Read 按需读取，不要靠猜路径）

PM 已在本机确认以下 sibling skill 路径存在，请在该路径下用 Read 读取 SKILL.md 及所需 references：

| Skill 名称 | SKILL.md 绝对路径 | 何时用 | 关键入口 |
|-----------|------------------|--------|---------|
| captcha-auto | /abs/path/to/captcha-auto/SKILL.md | 任何验证码识别（必自动调用，禁止用户手动输入） | HANDOFF.md §1 `buildVisionRequestBody` + 自管 fetch |
| <其他 skill> | /abs/path/to/<other>/SKILL.md | <触发场景> | <关键文件/函数> |

规则：
- 路径由 PM 派发前 `ls <project-root>/<skill>/SKILL.md` 校验存在；不校验就写进 prompt 视为 PM 失责。
- worker 在独立 cwd 下默认看不到这些 skill，必须靠本段路径 Read，禁止假定 skill 在默认搜索路径里。
- 未列出的 skill 不要自行臆测路径；需要时用 Read 试探并报 PM。

与 §3.6 的联动：

§3.6 是「worker 侧」约束：worker 必须自动调 captcha-auto（buildVisionRequestBody + 自管 fetch），禁止用户手动输入验证码。
§3.7 是「PM 侧」约束：PM 派活必须把 captcha-auto（及所有相关 sibling skill）的路径写进 prompt 的「Project Skills」段，worker 才有可读的东西。
两者配套：PM 给路径（§3.7）→ worker 读路径自动执行（§3.6）。缺 PM 给路径这步，§3.6 的「自动调」就无米下锅，必然退化成向用户要验证码。wave-2 派 D（shixin 双模式）+ wave-3 派 E（captcha 优化）都依赖本 SOP。

3.8 PM spawn 后异步判断 + 并行投递纪律（v1.18.4 实战增）

【红线警示】PM spawn 完一个 worker，绝对不要用 TaskOutput block=true / tmux attach / 任何 block 等 worker 跑完的调用。 spawn 是 fire-and-forget；立刻用下面 4 条核验命令 30 秒内确认 worker 就位，然后切回 PM 主循环。任何「等 spawn-worker.sh 退出才投 prompt」「等 STATUS.json 出现才派下一个 worker」都把 PM 主回合挂死，让 Wave 并行价值归零。

3.8.1 spawn 后 30 秒内必跑的 4 条核验命令（PM 第一动作清单）

spawn-worker.sh 退出后立即跑，不要 await：

# 1. tmux session 是否真的存活（< 1s）
tmux has-session -t "$SESSION" 2>/dev/null && echo "SESSION_OK" || echo "SESSION_MISSING"

# 2. pane cwd / prompt 是否已就位（< 1s）
tmux capture-pane -t "$SESSION" -p | tail -5

# 3. Session Context METADATA.json 是否已落盘
ls "$WORKTREE/.claude/agent-sessions/$SESSION/METADATA.json"

# 4. STATUS.json 是否 1-2 分钟内出现（用 timeout 卡死避免 block）
timeout 120 bash -c 'until [ -f "$WORKTREE/.claude/agent-sessions/$SESSION/STATUS.json" ]; do sleep 5; done'
# 120s 还没出现 → 触发 §2.1 纠偏流程，不要加长 timeout

PM 跑完 4 条立刻返回主循环。后续 worker 终态由 sentinel（§7.2）+ cron（§7.3）事件驱动接管，不要 PM 自己 poll 等。完整操作清单详见 templates/pm-spawn-postflight.md cheatsheet。

3.8.2 并行 spawn 投递纪律（spawn 阶段就并行，不要先串行后并行）

§3.1 提到 4-6 worker 并行（默认上行 218）但完全没讲 spawn 投递节奏。Wave 启动前 PM 必须判断：

文件域不重叠 + 验证命令独立 + 无共享契约冲突 → 一开始就并行 spawn（每个 worker 走 bg spawn-worker.sh + bg sentinel.sh 各一次 fg Bash 调用）
共享依赖 / 锁文件 / Tauri-Rust / DEC race → 降级到 1-3 个串行

并行 spawn 标准动作链（基于 DEC-038 监测层不变，spawn-worker.sh 退出后立刻 tmux send-keys 投 prompt）：

# 6 worker 一开始就并行（每次 = spawn-worker.sh + sentinel 各一次 Bash 调用）
# 不要先 spawn W1 后 await 等 W1 STATUS.json 才 spawn W2 —— 等于串行化

for w in w1 w2 w3 w4 w5 w6; do
  bash scripts/spawn-worker.sh --project ... --branch ... --session "$w" --with-sentinel --command "$W_CMD_$w"
  # ↑ fg spawn：拿 gate / 拿 sentinel cmd / 不 block 主进程（见 §3.5 v1.18.3 trust/permission 自动化 + §3.8.4 v1.18.4 默认 backend 分支）
  bash scripts/sentinel.sh ... --tmux-session "$w"  # run_in_background=true 下一回合
  # ↑ bg sentinel：exit 时 harness re-invoke PM（见 §7.2）
done
# 6 个 spawn 完 → 跑 §3.8.1 的 4 条核验 → 立即 `tmux send-keys` 投 prompt + 切回主循环

3.8.3 spawn 后不要做的事（反模式）

TaskOutput block=true 等 spawn-worker.sh 退出 → PM 主回合 hang → 并行价值归零（某多 worker Wave 实测白等 ~90s/次 × 3 worker）
tmux attach -t "$SESSION" 跟 worker 一起看 → 占 PM 主会话、无纠偏能力
while ! [ -f STATUS.json ]; do sleep 1; done 不带 timeout → PM 可能永久挂
spawn 完 6 worker 立刻 poll 等全部 done → Wave 串行化
spawn-worker.sh 内部 fork sentinel / pm-monitor → auto mode 拒多 background（见 CHANGELOG v1.18.1）

3.8.4 spawn-worker.sh 同步 dialog 监控默认行为（v1.18.4 改动）

claude-code backend + --permission-mode auto --bare 实测不弹 trust / permission dialog，但 v1.18.3 默认无条件走 trust_auto 30s + permission_auto 60s 同步监控 = 90s 空等（实测三个 worker 单次 spawn 主进程 2-4 min 才退出）。

v1.18.4 改动（scripts/spawn-worker.sh backend 分支化默认值）：

claude-code backend 默认 --no-trust-auto --no-permission-auto --no-permission-auto-bg → spawn 秒级返回
codebuddy / qoderwork-cn / codex / opencode 仍默认启（这些 backend 会真弹 dialog）
用户显式 --trust-auto / --permission-auto 可强制启用（升级后 dialog 行为变化兜底）

6 个 --*/--no-* flag 均可 force override 默认值（详见 scripts/spawn-worker.sh usage 段与 DEC-112）。

4. 命名规则

一处定义、各处引用一致（硬约束，实测踩坑）。 branch / worktree / session / run-dir / spec 必须从同一个 source 派生，在各处（PM Wave 计划、spawn-worker.sh 参数、worker prompt 里写的 Branch/Worktree/Session Context、METADATA.json、回归库 runs/<variant>/）引用完全一致。实测中 PM 手抖把 wr-v0107-<model-id>-ch08 的 wr- 前缀剥掉、或 branch 与 session 名对不上，直接导致 worker 的 Isolation Gate（pwd / git branch --show-current 自检）拦截、sentinel 找不到 STATUS.json、收口 git diff 验空 diff。规避：

PM 在 Wave 计划里一次写下 {branch, worktree, session, run-dir} 四元组，后续所有 tmux send-keys / 纠偏 / 收口命令都从该四元组复制，不在中途重新键入或简化。
scripts/spawn-worker.sh 内部已从单一 source 派生：BRANCH → safe_branch（worktree-safe）→ 默认 WORKTREE=.claude/worktrees/tmux-<safe_branch> → SESSION_CONTEXT=<worktree>/.claude/agent-sessions/<session>。PM 只需保证传入的 --branch 和 --session 本身一致且完整，helper 不会再让 worktree 与 branch 脱钩。
cross-model / 评测场景的命名四元组带模型标识（见 agent-eval-lab 的 model-aware 命名约定），整条链路用同一个 variant_slug，避免 PM 在不同环节用不同简称。

分支名面向远端协作和 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 时的写法。

Full worker prompt 的 Execution Authority 是硬约束段：默认禁止机器级和项目本地依赖安装；Authorized Install Commands 只能列完整、精确的命令，并同时记录 Install Authorization Source。缺工具时先查机器已有路径，仍缺则写 STATUS=blocked 与 RESULT，不得把“需要跑验证”解释成安装权限。项目锁文件驱动的正常本地依赖流程也须由 PM 明确列出精确命令，避免把项目内许可扩大成全局环境写入。

对高延迟 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。
claude-provider-env.sh：Claude Code 第三方 provider worker 的 registry/settings-derived env 隔离 wrapper。
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 m3 \
  --provider-slot minimax-1 \
  --provider-registry config/claude-providers.local.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" \
  --env-isolation "$PROVIDER_ENV_ISOLATION" \
  --verify-cmd 'npm run typecheck' \
  --command "$WORKER_COMMAND"

依赖安装默认 fail-closed。只有用户或项目规则明确批准时，才把完整精确命令及授权来源传给 spawn；下面仅展示参数结构，不代表自动授权：

bash scripts/spawn-worker.sh \
  --project /path/to/repo \
  --branch feat/example \
  --session example \
  --worker-backend claude-code \
  --allow-install-command 'npm ci' \
  --install-authorization-source '项目锁文件验证流程已明确批准' \
  --git-expected-name '<git name>' \
  --git-expected-email '<git email>' \
  --git-integration-base origin/main \
  --command "$WORKER_COMMAND"

spawn-worker.sh 会把 worker 可读镜像写入 Session Context，并把权威授权快照与 SHA-256 receipt 写到 Git common-dir 的 agent-authority/（worktree 外）。Claude Code / CodeBuddy / QoderWork 的 PreToolUse settings 从 spawn 进程环境快照取权威授权，直接 Shell 默认 fail-closed：窄生命周期命令或 spawn 发出的精确 allowed_shell_commands 才可运行；安装命令还必须精确命中单独的授权清单并带可审计来源。npx / npm exec / pnpm dlx 等可能按需获取依赖的命令不能借 --verify-cmd 隐式获权。spawn 只把初始状态记录为 settings_wired...runtime_unproven；hook 第一次真实收到 PreToolUse 后才在 PM receipt 同目录原子创建 *.hook-attested.json。PM 应以该文件作为 runtime hook 证据，不能把“settings 已写”当“CLI 已执行 hook”。这里约束的是 Agent 的直接工具调用边界；获准执行的项目脚本/测试及仓库 hooks 属于受信项目代码，不宣称提供 OS 容器级沙箱。

raw git push 不属于安全生命周期命令。PM 同时传 --git-expected-name、--git-expected-email、--git-integration-base 后，spawn 把四个一次性 GIT_AUTHOR_* / GIT_COMMITTER_* 变量绑定到 worker 进程（不写共享 repo config），并生成一个精确 safe-push command：它调用 git-workflow 的身份门禁核验远端 PR base 到当前 HEAD 的每个 commit，只 push 已核验 OID。三项缺一 fail-closed；未生成 safe-push 时 worker 必须报告 push blocked。

Claude Code --bare / --safe-mode / CLAUDE_CODE_SIMPLE=1 会跳过或可能跳过 hooks，--setting-sources 排除 local 也会使项目 hook 不生效；命令未暴露可证明的 claude token 同样不能冒充 hook mode。spawn 默认停止。对这些模式以及尚未接入 PreToolUse 的 backend（Codex / OpenCode / custom），只有用户或项目明确接受降级并通过 --allow-prompt-only-install-guard '<授权来源>' 留痕时，才进入 prompt_only_no_mechanical_enforcement，METADATA 不得声称存在进程快照机械门禁。

轻量模式（无 worktree，§2.1.1）——派多个 worker 各管一个独立文件夹、或目标不是 git 仓时用：

# 同一个 PM session 里，给两个不同文件夹各派一个轻量 worker
bash scripts/spawn-worker.sh \
  --project /path/to/folder-a \
  --session lite-folder-a \
  --no-worktree \
  --worker-backend claude-code \
  --model "$MODEL" \
  --allow-paths '/path/to/folder-a/**' \
  --command "$WORKER_COMMAND"

bash scripts/spawn-worker.sh \
  --project /path/to/folder-b \
  --session lite-folder-b \
  --no-worktree \
  --worker-backend claude-code \
  --model "$MODEL" \
  --allow-paths '/path/to/folder-b/**' \
  --command "$WORKER_COMMAND"
# ↑ 两个 worker 各自 cwd 直接指向自己的文件夹，互不建 worktree；
#   隔离靠文件夹分离 + --allow-paths scope-guard，不靠 git worktree。
#   若 --project 不是 git 仓，--no-worktree 可省（脚本自动检测 + 打印 LIGHTWEIGHT_AUTO）。

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

【spawn 后 30 秒必跑 snippet · 详见 §3.8.1】 不要用 TaskOutput block=true 等 spawn-worker.sh 退出，跑完下面 4 条立刻返回主循环：

# 1. session 存活
tmux has-session -t "$SESSION" 2>/dev/null
# 2. pane 已交出 prompt（capture 尾部 5 行）
tmux capture-pane -t "$SESSION" -p | tail -5
# 3. METADATA.json 已落
ls "$WORKTREE/.claude/agent-sessions/$SESSION/METADATA.json"
# 4. STATUS.json 1-2 分钟内出现（带 timeout 异步等，避免 block PM 主回合）
timeout 120 bash -c 'until [ -f "$WORKTREE/.claude/agent-sessions/$SESSION/STATUS.json" ]; do sleep 5; done'

Wave 内 N 个 worker 跑 N 轮核验，30 秒内完成；中间不 poll 不 attach 不 block。完整 cheatsheet 见 templates/pm-spawn-postflight.md。

常用 worker command：

Claude Code 第三方 provider（推荐 registry）：用 render-runtime-profile.sh --backend claude-code --provider-registry <local-registry.json> --api-provider <provider-id> --model <model-alias> 生成命令；默认会包 scripts/claude-provider-env.sh，并把模型别名解析成真实 claude --model <provider-model>。真实 registry 不提交；模板见 config/claude-provider-registry.example.json。worker 不需 MCP 时在 --command 末尾加 --no-mcp，claude-provider-env.sh 会自动注入 --strict-mcp-config --mcp-config '{"mcpServers":{}}'，规避项目 .mcp.json 触发的「N new MCP servers found」选择 dialog（references/09-parallel-lessons.md T6）。已显式 --strict-mcp-config 时 wrapper 不叠加。
Claude Code 第三方 provider（兼容 settings）：也可用 render-runtime-profile.sh --backend claude-code --settings <local-provider.settings.json> --model <provider-model> 生成命令；真实 settings 不提交；模板见 config/claude-provider-settings.example.json。启动后必须检查 banner 模型名；若仍显示用户默认 provider，先停 worker 排查 registry/settings / wrapper / 环境继承。
Claude Code 订阅/OAuth：env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_BASE_URL claude --permission-mode auto。
Codex（交互式 TUI）：codex -a never -s danger-full-access [-m <model>] [-p <profile>]，PM 用 tmux send-keys 投递 prompt。
OpenCode（交互式）：opencode --model <provider/model>，PM 用 tmux send-keys 投递 prompt。
WorkBuddy / CodeBuddy（codebuddy）：用 render-runtime-profile.sh --backend codebuddy --model <平台模型> [--no-mcp] [--add-dir <dir>] 生成；吃 WorkBuddy 桌面端登录态和平台额度，无需 API Key。任务文件/素材在 worktree 外时加 --add-dir 声明跨目录访问（如 --add-dir /tmp）。详见 references/08-workbuddy-cli-worker.md。
QoderWork CN（qoderclicn）：用 render-runtime-profile.sh --backend qoderwork-cn --model <平台模型> [--no-mcp] [--dangerously-skip-permissions] 生成；脚本自动前置 env -u 清除 SDK 变量、处理含空格的二进制路径。详见 references/07-qoderwork-cli-worker.md。
自定义 CLI：任何能在指定 cwd 运行、接收 prompt、落盘 checkpoint 的交互式命令。

Claude CLI PATH 注入（v2.0）：scripts/ensure-claude-path.sh 提供 ensure_claude_in_path() 函数，按 ~/.local/bin → /opt/homebrew/bin → /usr/local/bin → ~/.cargo/bin 顺序探测并 prepend 到 PATH。spawn-worker.sh 和 claude-provider-env.sh startup 阶段均 source 一次，幂等；其他 launch 脚本也可 source "$SCRIPT_DIR/ensure-claude-path.sh"; ensure_claude_in_path 复用。日志前缀 SPAWN_WORKER_PATH_INJECT / SPAWN_WORKER_PATH_WARN（仅未命中时 warn，不报错）。

所有 worker 一律交互式启动，不要用 headless / -p / --mode batch / --prompt-file（v1.18.0 移除，见 DEC-044）：tmux 的价值就是 PM 能 tmux send-keys 投递 prompt 并全程纠偏；headless 一发跑完等于放弃监控，而那种短任务本就该用同宿主 Subagent，不该占 tmux worker 槽。render-runtime-profile.sh --mode batch / --prompt-file 现在直接报错。如果 --command 是自定义命令且含 < / > / | / && 等 shell metachar（tmux new-session 直接 exec、不经 shell），仍需手动包 bash -lc '<cmd>'。

不要设 --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_*）：

事件	触发
`SENTINEL_START`	启动时
`SENTINEL_PENDING`	STATUS.json 缺失
`SENTINEL_PANE_TAIL`	capture pane 前（best-effort）
`SENTINEL_TERMINAL`	检测到 `done` / `failed` / `blocked` / `stopped`
`SENTINEL_TMUX_KILLED` / `SENTINEL_TMUX_GONE`	kill tmux 之后
`SENTINEL_TIMEOUT`	`--max-wait` 到了还没看到终态

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 可能略高，按需调

7.3 cron + sentinel 标准组合（兜底监测，必挂两层）

sentinel（§7.2）是主监测：事件驱动、秒级抓 worker 终态 done、零 idle token。但 sentinel 单独有 3 个盲区，必须再挂一个 cron 兜底（周期巡检），两层组合才是标准模式，而非二选一：

sentinel 盲区	表现	cron 兜底如何抓到
(a) worker 硬卡死不写 STATUS	sentinel 轮询到 `--max-wait` 超时（exit 124），最长等 2h	cron 周期读 STATUS + pane，发现 stale 主动介入
(b) worker 用非标准 STATUS 文件名	sentinel 监听 `STATUS.json`，worker 写 `issue-XXX-status.json`，sentinel 轮询空文件到超时	cron 直接 `cat`/`grep` 多个候选文件名，命中即识别
(c) sentinel 自身被 SIGKILL/SIGTERM 或 harness 未 re-invoke	sentinel 静默消失，PM 永不被唤醒	cron 是独立 job，不依赖 sentinel 存活

频次（硬推荐，按任务粒度）：

短任务（单 worker、预计 < 1h）：~22 分钟
长流水线（多 worker / Wave / 预计 1-4h）：10-15 分钟
避免 :00 / :30 整点：所有用户挤在整点会 API 拥堵 + 触发速率限制；用错峰表达式如 3,13,23,33,43,53 * * * *（每 10 分钟错峰）或 7,29,51 * * * *（每 22 分钟错峰）。
不要低于 10 分钟：cron 每次 fire 都 re-invoke PM（读 STATUS + git + pane），过频会抵消多 Agent 的 token efficiency。

双信号卡死检测（避免误判 long thinking）：判 worker 卡死必须同时满足两条，缺一不可：

STATUS 信号：STATUS.json.updated_at 和文件 mtime 都 > 阈值（长流水线 20min、短任务 15min）未变。
pane 信号：tmux capture-pane 尾部出现死循环证据（连续重复行 / "Levitating… Nmin" 持续上涨但无新工具调用 / 报错堆栈不退出）。

只满足 (1) 不满足 (2)：worker 可能在 long thinking，发一条 tmux send-keys 心跳探针（"更新 STATUS heartbeat"），等下一轮 cron 再判，不立即重启。

cron prompt 用模板：templates/cron-monitor-prompt.md。模板含：worker session + STATUS 路径 + git 分支 + sentinel id + stale 阈值 + 收尾自删（worker 全部合入后 CronDelete）+ 无动作时一句话汇报（不膨胀上下文）。

与 §7.1 / §7.2 的关系：

§7.1 pm-monitor.sh / wait-worker.sh：PM 主动调用的只读巡检工具（一次性或低频 log）。
§7.2 sentinel：worker 终态事件驱动唤醒（秒级抓 done），主监测。
§7.3 cron：时间驱动兜底（抓 sentinel 盲区 + 卡死双信号 + sentinel 失效）。
三者叠加，不是替代。PM 派 worker 后必挂两层（sentinel + cron）；sentinel 是主，cron 是兜底，cron 触发后若发现 worker 仍在推进，只回一句话、不做大动作。

8. 收口

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

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

提 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 流程。
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 完成后：

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

以下安装命令仅供用户明确批准环境修改之后参考。worker 不得因检查结果缺依赖而自行执行；先运行只读检查、查找已有二进制，仍缺则写 BLOCKED/RESULT。

最小本地执行依赖

依赖	安装方式
`git`	通常随开发环境提供
`bash`	常规脚本需要 bash；`pm-monitor.sh` 需要 bash 4+
`jq`	macOS: `brew install jq` Linux: `sudo apt-get install jq`
`tmux`	macOS: `brew install tmux` Linux: `sudo apt-get install tmux`
`python3`	Agent 工具调用门禁和 scope guard 使用；缺失时 spawn fail-closed，不自动安装

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

按模式启用的依赖

模式	依赖
PR / mergeability 巡检	`gh`，且需要已登录
Claude Code worker	`claude`；第三方 provider 需要本地 settings 文件
Codex worker	`codex`
OpenCode worker	`opencode`
Codex heartbeat	Codex App automation 能力；创建/修改 automation 必须使用 `automation_update`
Claude 官方 agent view / `--worktree --tmux`	`claude`，必要时还需要 `tmux`

可选终端依赖

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

完整依赖矩阵见 references/02-runtime-dependencies.md。依赖检查脚本只报告状态，不安装软件、不启动 worker、不改配置。任何安装或全局 symlink 都必须先有用户明确授权，并作为精确命令写入 worker 的 Execution Authority。

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-registry.example.json：Claude Code 第三方 API provider/model registry 模板。
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/claude-provider-env.sh：从 Claude provider registry 或 settings JSON 构造本次 worker 的隔离 env，屏蔽用户级 provider/model 污染。
scripts/render-runtime-profile.sh：按 backend/profile 生成 worker command、prompt context 和 spawn metadata。
scripts/spawn-worker.sh：创建隔离 worktree、Session Context 和 tmux session，并输出启动 gate；--no-worktree 走轻量模式（worker 直接在目标文件夹工作，见 §2.1.1）。
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 摘要模板。

11. 评估与验收

评估范围

本 skill 评估对象 = spawn-worker + sentinel + pm-monitor + render-runtime-profile + clean-worktree 的协同行为;不评估具体 worker backend(claude / codex / opencode)本身的能力。

Hard Fail(出现即不通过)

防逃逸门禁未过(§2.1),PM 直接写业务代码。
spawn-worker.sh 启动后 pane cwd ≠ worktree 或（worktree 模式下）branch ≠ 目标分支(gate 失败)。轻量模式只验 cwd。
worker 写 STATUS 同义词(completed / finished)而非字面 done,sentinel 不退出。
worker 改完文件不 commit,PM 收口验到空 diff。轻量模式落在非 git 文件夹时无 commit，改验「交付物全部落盘 + RESULT.md 列清单」。
真实 settings(config/*.settings.json)进入 git 追踪或打包件。
worker 因验证缺工具而执行未在授权清单中的安装/全局环境写入命令，或安装授权缺少可审计来源。

Benchmark case

smoke-tmux-worker.sh:临时 repo e2e(spawn 1 worker 跑完,STATUS=done,diff 非空,clean 无残留)。
轻量模式 smoke：spawn-worker.sh --no-worktree --project <非 git 文件夹>，验 pane cwd = 目标文件夹、METADATA isolation_mode=lightweight、STATUS=done、交付物落盘。
建议补 smoke-e2e-wave.sh:spawn 2 worker 并行改不重叠文件,sentinel 等终态,验证两个 PR diff 范围独立、STATUS 均 done、clean 无残留。

静态检查 vs 动态评估

静态:lint-wait-script.sh(wait / monitor 脚本 lint)+ check-dependencies.sh(preflight 依赖检查)。
动态:smoke-tmux-worker.sh(e2e 端到端)+ smoke-provider-settings.sh(provider 验证,需真实 key,optional)。
安装权限故障注入：test-dependency-install-guard.sh（无授权机器安装/项目本地安装阻断、精确授权放行、缺授权来源 fail-closed、spawn hook/metadata 实际接入）。

Install Skill

Shared

SKILL.md