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.18.2"

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

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 在任何业务实现前必须完成启动门禁：

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.1.1 轻量模式（无 worktree，非默认）

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

1. 用户显式要求：PM 看到用户明确说「不要 worktree / 直接改 / 单 session 派多个 worker 各管一个文件夹 / 轻量模式」，或直接传 spawn-worker.sh --no-worktree。
2. 目标目录不是 git 仓：spawn-worker.sh 检测到 --project 不在 git work tree 内，自动切轻量并打印 SPAWN_WORKER_LIGHTWEIGHT_AUTO 通知（仍可被 --branch 缺省等线索识别）。

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

• worker 的 tmux session cwd 直接指向目标文件夹（--project，或 --worktree 覆盖的子目录），不建 worktree、不切分支、不算 base ref。
• Isolation Gate 只验 pwd == 目标文件夹，不验 branch（目标可能根本不是 git 仓）。
• METADATA.json 记 isolation_mode: "lightweight"，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 代理纪律：

• 如果用户明确要求当前会话做 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 时生效）：

本表不列具体模型——模型与框架选型是个人偏好（每人可用的 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 对齐）：

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. 标准流程

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 仍要验收分支、路径和隔离状态。用户明确要求「不要 worktree」或目标目录不是 git 仓时，改用轻量模式（§2.1.1）：spawn-worker.sh --no-worktree，worker 直接在目标文件夹工作，隔离靠文件夹分离 + scope-guard。
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 / 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 示例：

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

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 命令。

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

例：个人偏好 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 前必做）：

``bash 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 主流程调用三层保护：

1. `trust_auto()`（v1.17.5，保留）：同步 30s 监控 trust dialog，命中按 Enter 选 option 3（Trust folder and all subdirectories）。
2. `permission_auto()`（v1.18.3 关键修复）：同步 60s 监控 "Do you want to proceed?" dialog，命中改用数字键 `2`（不再用 Down Enter，PM 2026-07-08 wave-1 实测 Down Enter 在某些 TUI 状态不稳）。
3. `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.2 之前）：wave-1/2 PM 反复按 1/2 接 dialog（v1.18.2 文档化但未真正修）。v1.18.3 自动化了，按踩坑 7 修复。

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 派发前必做）：

1. PM 派活前，先在本机收集本项目相关的 sibling skill 路径清单。每个可能用到的 skill 跑一次：

``bash ls <project-root>/<sibling-skill>/SKILL.md `` 把绝对路径（或相对 worktree 的稳定相对路径）记下来，例如：

• captcha-auto：/abs/path/to/captcha-auto/SKILL.md
• 其他任务相关 skill：同理逐个确认存在。

1. PM 把收集到的路径清单写进 worker prompt 的 「Project Skills」段（标准字段见下），要求 worker 用 Read 按需读取，不要靠 worker 自己猜路径。
2. 任何涉及验证码的任务，PM 必须把 captcha-auto 的 SKILL.md 绝对路径写进「Project Skills」段——这是 §3.6「worker 必须自动调 captcha-auto、禁止用户手动输入」的前置条件。路径不进 prompt，worker 在独立 cwd 找不到 skill，就会退化成向用户要验证码，违反用户强约束。
3. 「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。

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 时的写法。

对高延迟 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"

轻量模式（无 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 主目录继续实现。

常用 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。
• 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 的交互式命令。

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

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

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

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

• 短任务（单 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 卡死必须同时满足两条，缺一不可：

1. STATUS 信号：STATUS.json.updated_at 和 文件 mtime 都 > 阈值（长流水线 20min、短任务 15min）未变。
2. 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 必须做两件事避免外部抢跑：

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

``bash 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 流程。

1. 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-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(出现即不通过)

1. 防逃逸门禁未过(§2.1),PM 直接写业务代码。
2. spawn-worker.sh 启动后 pane cwd ≠ worktree 或（worktree 模式下）branch ≠ 目标分支(gate 失败)。轻量模式只验 cwd。
3. worker 写 STATUS 同义词(completed / finished)而非字面 done,sentinel 不退出。
4. worker 改完文件不 commit,PM 收口验到空 diff。轻量模式落在非 git 文件夹时无 commit，改验「交付物全部落盘 + RESULT.md 列清单」。
5. 真实 settings(config/*.settings.json)进入 git 追踪或打包件。

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)。