team

Team Skill

使用 Claude Code 的隐式 Agent 团队，生成 N 个协同工作的 Agent 来处理共享任务列表。Claude Code 2.1.178+ 移除了原生 TeamCreate/TeamDelete；在 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 下，每个会话有一个隐式团队，队友通过 Agent/Task 工具直接生成，并使用不同的 name 值。本技能仍在有文档说明的场景下保留 OMC 旧版的 tmux/CLI worker 编排（omc team / /omc-teams）。隐式团队与 omc team 不共享结果：一方完成并不代表另一方成功。

swarm 兼容性别名已在 #1131 中移除。

用法

/oh-my-claudecode:team N:agent-type "task description"
/oh-my-claudecode:team "task description"
/oh-my-claudecode:team ralph "task description"

参数

• N - 队友 Agent 的数量（1-20）。可选；默认根据任务拆解自动确定规模。
• agent-type - 用于 team-exec 阶段的 OMC Agent（例如 executor、debugger、designer、codex、gemini、antigravity）。可选；默认按阶段感知路由。使用 codex 生成 Codex CLI worker，使用 gemini 生成 Gemini CLI worker（企业版/API 密钥层级），或使用 antigravity 生成 Antigravity CLI（agy）worker（Google 推出的 Gemini CLI 后继者；需要安装相应的 CLI）。参见下方的阶段 Agent 路由。
• task - 要拆解并分配给队友的高层任务
• ralph - 可选修饰符。存在时，将团队流水线包裹在 Ralph 的持久化循环中（失败时重试，完成前进行架构师验证）。参见下方的 Team + Ralph 组合。

示例

/team 5:executor "fix all TypeScript errors across the project"
/team 3:debugger "fix build errors in src/"
/team 4:designer "implement responsive layouts for all page components"
/team "refactor the auth module with security review"
/team ralph "build a complete REST API for user management"
# With Codex CLI workers (requires: npm install -g @openai/codex)
/team 2:codex "review architecture and suggest improvements"
# With Gemini CLI workers (requires: npm install -g @google/gemini-cli)
/team 2:gemini "redesign the UI components"
# With Antigravity CLI workers (requires: install per https://antigravity.google)
/team 2:antigravity "redesign the UI components"
# Mixed: Codex for backend analysis, Gemini/Antigravity for frontend (delegate per-task with /oh-my-claudecode:ask)

架构

User: "/team 3:executor fix all TypeScript errors"
              |
              v
      [TEAM ORCHESTRATOR (Lead)]
              |
              +-- Use the session's implicit Claude Code team
              |       -> no TeamCreate call; lead remains current session
              |
              +-- Analyze & decompose task into subtasks
              |       -> explore/architect produces subtask list
              |
              +-- Create task list entries from the implementation plan
              |       -> TODO/task entries #1, #2, #3 with dependencies
              |
              +-- Update task-list entries (pre-assign owners)
              |       -> task #1 owner=worker-1, etc.
              |
              +-- Task(name="worker-1") x 3
              |       -> spawns teammates into the team
              |
              +-- Monitor loop
              |       <- teammate messages (auto-delivered by the active team surface)
              |       -> task-list/TodoWrite review for progress
              |       -> message teammates through the active team surface to unblock/coordinate
              |
              +-- Completion
                      -> request shutdown from each teammate through the active team surface
                      <- shutdown acknowledgement from teammates
                      -> state_clear(mode="team", session_id="<current_session_id>")
                      -> preserve shared/legacy state for explicit --all cleanup

原生 Claude Code 团队模型（2.1.178+）：

- No per-team ~/.claude/teams/<name>/ directory is created by this skill.
- No TeamCreate/TeamDelete calls are available.
- `team_name` is accepted by native Claude Code only as ignored legacy metadata; do not rely on it for routing.
- Spawn teammates directly via Agent/Task with `name="worker-N"`.

Goal 工作流关系

Team 是 OMC 中负责并行、分阶段执行的权威。请使用确定性的冲突策略 refuse、adopt_existing 和 artifact_only，而不是非确定性的警告处理。如果某个任务提到 Claude Code /goal、Ralph 或仅产物的 Ultragoal，除非 leader 明确移交，否则请保持 Team 作为主要循环权威。仅将 /goal 用作有文档说明的原生 Claude Code 移交目标，或作为来自 lead 会话的可见证据；不要声称 /goal 评估器会独立运行命令、读取文件或替代 team-verify / team-fix。仅产物的 Ultragoal 引用应被视为持久的目标账本/检查点/证据产物，而不是其本身进行的 worker 执行。

分阶段流水线（规范 Team 运行时）

Team 执行遵循分阶段流水线：

team-plan -> team-prd -> team-exec -> team-verify -> team-fix（循环）

阶段 Agent 路由

每个流水线阶段都使用专用 Agent——而不仅仅是执行器。由 lead 根据阶段和任务特征选择 Agent。

阶段	必需 Agent	可选 Agent	选择标准
team-plan	explore (haiku)、planner (opus)	analyst (opus)、architect (opus)	需求不明确时使用 analyst。系统边界复杂时使用 architect。
team-prd	analyst (opus)	critic (opus)	使用 critic 来质疑范围。
team-exec	executor (sonnet)	executor (opus)、debugger (sonnet)、designer (sonnet)、writer (haiku)、test-engineer (sonnet)	将 Agent 与子任务类型匹配。复杂自主工作使用 executor (model=opus)，UI 使用 designer，编译问题使用 debugger，文档使用 writer，测试创建使用 test-engineer。
team-verify	verifier (sonnet)	test-engineer (sonnet)、security-reviewer (sonnet)、code-reviewer (opus)	始终运行 verifier。认证/加密相关变更添加 security-reviewer。超过 20 个文件或架构变更添加 code-reviewer。code-reviewer 也涵盖风格/格式检查。
team-fix	executor (sonnet)	debugger (sonnet)、executor (opus)	类型/构建错误和回归隔离使用 debugger。复杂的多文件修复使用 executor (model=opus)。

路由规则：

1. 由 lead 按阶段选择 Agent，而不是用户。 用户的 N:agent-type 参数只覆盖 team-exec 阶段的 worker 类型。所有其他阶段使用适合该阶段的专家。
2. 专家 Agent 补充执行器 Agent。 将分析/审查路由到 architect/critic Claude Agent，将 UI 工作路由到 designer Agent。Tmux CLI worker 不参与 Claude 的原生团队消息传递。
3. 成本模式影响模型层级。 在降级模式下：在质量允许的情况下，opus Agent 降为 sonnet，sonnet 降为 haiku。team-verify 始终至少使用 sonnet。
4. 风险级别会升级审查。 安全敏感或超过 20 个文件的变更必须在 team-verify 中包含 security-reviewer + code-reviewer (opus)。

阶段进入/退出标准

• team-plan
  • 进入：团队调用已解析，编排开始。
  • Agent：explore 扫描代码库，planner 创建任务图，复杂任务可选 analyst/architect。
  • 退出：分解完成，并准备好可运行的任务图。
• team-prd
  • 进入：范围不明确或缺少验收标准。
  • Agent：analyst 提取需求，可选 critic。
  • 退出：验收标准和边界明确。
• team-exec
  • 进入：任务列表分配和 worker 生成完成。
  • Agent：按子任务生成相应专家类型的 worker（见路由表）。
  • 退出：当前轮次的执行任务达到终态。
• team-verify
  • 进入：执行轮次结束。
  • Agent：verifier + 与任务匹配的审查者（见路由表）。
  • 退出（通过）：验证门禁通过，且无需后续处理。
  • 退出（失败）：生成修复任务，控制权移交至 team-fix。
• team-fix
  • 进入：验证发现缺陷/回归/未完成标准。
  • Agent：根据缺陷类型使用 executor/debugger。
  • 退出：修复完成，流程返回 team-exec，然后进入 team-verify。

验证/修复循环与停止条件

持续执行 team-exec -> team-verify -> team-fix，直到：

1. 验证通过且没有剩余的必需修复任务，或
2. 工作以带证据的明确终态 blocked/failed 结果结束。

team-fix 受最大尝试次数限制。如果修复尝试超过配置的限制，则转入终态 failed（无无限循环）。

运行收尾（任一终态结果）。 在 /oh-my-claudecode:cancel 状态清理之前，向 .omc/notepads/team/problems.md 追加至多三行事实性内容（阻塞项另外追加到 .omc/notepads/team/issues.md）——什么出了问题（在修复轮次后仍然存在的缺陷、三次触发的暂停）以及什么拖慢了进度（worker 环境摩擦、缺失的检查、无法获取的信息）。保留现有条目：只追加，绝不替换共享文件。如果没有观察结果，则不追加任何内容；空收尾是有效的，因此不要写“no lessons”。仅记录观察结果；将其落到仓库层面是 refit 的职责，且需经用户批准。对于终态 failed 结果，还要起草一个事故工作项，包含失败特征、证据指针和重开路径；将其追加到本地 .omc/notepads/team/issues.md。仅当用户或模式调用明确授权该外部操作时，才将其发布到跟踪器。

阶段交接约定

在阶段之间转换时，重要上下文——已做出的决策、被拒绝的备选方案、已识别的风险——仅存在于 lead 的对话历史中。如果 lead 的上下文被压缩或 Agent 重启，这些知识就会丢失。

每个完成的阶段必须在转换前生成交接文档。

Lead 将交接文档写入 .omc/handoffs/<stage-name>.md。

交接格式

## Handoff: <current-stage> → <next-stage>

- **Decided**: [key decisions made in this stage]
- **Rejected**: [alternatives considered and why they were rejected]
- **Risks**: [identified risks for the next stage]
- **Files**: [key files created or modified]
- **Remaining**: [items left for the next stage to handle]

交接规则

1. Lead 在生成下一阶段的 Agent 之前读取先前的交接文档。 交接内容会包含在下一阶段的 Agent 生成提示词中，确保 Agent 以完整上下文启动。
2. 交接文档会累积。 verify 阶段可以读取所有先前的交接文档（plan → prd → exec），以获得完整的决策历史。
3. 团队取消时，交接文档会保留在 .omc/handoffs/ 中，以便会话恢复。它们不会被原生 Claude Code 团队清理删除；Claude Code 2.1.178+ 中不存在 TeamDelete 调用。
4. 交接文档是轻量的。 最多 10-20 行。它们记录决策和理由，而不是完整规格（完整规格位于 DESIGN.md 等交付物文件中）。

示例

## Handoff: team-plan → team-exec

- **Decided**: Microservice architecture with 3 services (auth, api, worker). PostgreSQL for persistence. JWT for auth tokens.
- **Rejected**: Monolith (scaling concerns), MongoDB (team expertise is SQL), session cookies (API-first design).
- **Risks**: Worker service needs Redis for job queue — not yet provisioned. Auth service has no rate limiting in initial design.
- **Files**: DESIGN.md, TEST_STRATEGY.md
- **Remaining**: Database migration scripts, CI/CD pipeline config, Redis provisioning.

恢复与取消语义

• 恢复： 使用暂存状态 + 实时任务状态，从最后一个非终态阶段重新开始。读取 .omc/handoffs/ 以恢复阶段转换上下文。
• 取消： 使用 skills/cancel/SKILL.md 中的权威流程；不要在此处重复其标志、范围或状态清理 规则。.omc/handoffs/ 中的交接文件会保留以供恢复。
• 终态为 complete、failed 和 cancelled。

Windows psmux tmux 兼容性门禁

在原生 Windows 上，在检查实际的 tmux 兼容二进制文件之前，不要告诉用户 /team 需要 WSL，或 tmux 不可用。原生 psmux 会安装一个与 tmux 兼容的命令（通常是 tmux / tmux.cmd），并且是受支持的 Team 多路复用器。

在 Windows 上阻止或回退之前：

1. 检查 tmux -V（或平台等效命令，例如先 where tmux，再 tmux -V）。
2. 将成功由 psmux 支持的 tmux -V 视为 tmux 可用。
3. 如果 psmux/tmux 可用，继续正常的 Team 流程；不要输出需要 WSL 的指引。
4. 只有在没有可用的 tmux 兼容二进制文件时，才告诉用户安装 psmux 以获得原生 Windows 支持，或使用 WSL2 作为替代方案。

工作流

恢复检查（初始化之前）

在触碰 Team 状态之前，从调用上下文中解析当前会话身份。在命令行上下文中，OMC_SESSION_ID 是权威来源；在 hook 上下文中，负载的 session_id 是权威来源。当身份可用时，显式且一致地传递它：

state_read(mode="team", session_id="<current_session_id>")

不带 session_id 的 state_read 会读取旧版/聚合状态，并且可能包含其他会话。切勿从未限定范围的聚合响应中选择或恢复 Team。如果没有可用的身份，则仅使用显式标识的旧版状态；切勿从聚合响应中的会话条目推断归属关系。

在派生 slug、分解工作或写入/初始化状态之前，先读取现有的会话状态。如果 active=true 且 current_phase 为非终态，则使用该 Team 现有的交接文件和任务列表状态恢复记录的阶段。保留 team_name、current_phase、fix_loop_count、max_fix_loops、stage_history 以及所有其他现有的 Team 状态字段，包括 worker/task/launch-attempt 记录。在随后的每次 state_write 和 state_clear 中使用相同的 session_id，在现有状态锁下仅应用部分更新。不要运行下面的新 Team 初始化，不要派生替代 slug，不要创建重复任务，不要生成重复 worker，也不要重复启动尝试。

如果状态格式错误、无法读取或以其他方式损坏，报告诊断信息并保留原始字节。不要替换、清除、初始化它，也不要将其视为新运行。

以下初始化阶段仅适用于没有活动、限定范围状态的新运行。

阶段 1：解析输入

• 提取 N（Agent 数量），验证范围为 1-20
• 提取 agent-type，验证其映射到已知的 OMC subagent
• 提取 task 描述

阶段 2：分析与分解

使用 explore 或 architect（通过 MCP 或 Agent）分析代码库，并将任务分解为 N 个子任务：

• 每个子任务应按文件范围或模块范围划分，以避免冲突
• 子任务必须相互独立，或具有清晰的依赖顺序
• 每个子任务需要简洁的 subject 和详细的 description
• 识别子任务之间的依赖关系（例如，“共享类型必须在消费者之前修复”）

阶段 3：初始化团队状态

使用会话隐式的 Claude Code 团队。不要调用 TeamCreate；Claude Code 2.1.178+ 已移除该工具，并在启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 时自动为会话提供一个隐式团队。

派生一个 slug，例如 fix-ts-errors，仅用于 OMC 状态、提示词标签、交接和人类可读的报告。原生 Claude Code 可能接受 team_name 作为旧版元数据，但路由时会忽略它。

使用 state_write MCP 工具写入 OMC 状态，以实现正确的会话作用域持久化：

对于此次以及后续每一次 Team 状态调用，都使用 Resume Check 中解析出的同一个 session_id；如果无法获得身份信息，则仅使用上文所述的明确标识的旧版状态。

state_write(mode="team", session_id="<current_session_id>", active=true, current_phase="team-plan", state={
  "team_name": "fix-ts-errors",
  "agent_count": 3,
  "agent_types": "executor",
  "task": "fix all TypeScript errors",
  "fix_loop_count": 0,
  "max_fix_loops": 3,
  "linked_ralph": false,
  "stage_history": "team-plan"
})

注意： MCP state_write 工具将所有值作为字符串传输。读取状态时，消费方必须将 agent_count、fix_loop_count、max_fix_loops 强制转换为数字，将 linked_ralph 强制转换为布尔值。

状态 schema 字段：

字段	类型	描述
active	boolean	团队模式是否处于活动状态
current_phase	string	当前流水线阶段：team-plan、team-prd、team-exec、team-verify、team-fix
team_name	string	用于状态、交接和报告的 OMC slug；原生 Claude Code 路由会忽略它
agent_count	number	工作 Agent 的数量
agent_types	string	team-exec 中使用的 Agent 类型，以逗号分隔
task	string	原始任务描述
fix_loop_count	number	当前修复迭代次数
max_fix_loops	number	失败前的最大修复迭代次数（默认值：3）
linked_ralph	boolean	团队是否链接到 ralph 持久化循环
stage_history	string	带时间戳的阶段转换列表，以逗号分隔

在每次阶段转换时更新状态：

state_write(mode="team", session_id="<current_session_id>", current_phase="team-exec", state={
  "stage_history": "team-plan:2026-02-07T12:00:00Z,team-prd:2026-02-07T12:01:00Z,team-exec:2026-02-07T12:02:00Z"
})

阶段 4：创建任务

使用 TodoWrite 或当前活动的任务列表界面为每个子任务创建任务列表条目。任务列表工具仅用于跟踪；它们不会创建原生团队。

// Task-list entry for subtask 1
{
  "subject": "Fix type errors in src/auth/",
  "description": "Fix all TypeScript errors in src/auth/login.ts, src/auth/session.ts, and src/auth/types.ts. Run tsc --noEmit to verify.",
  "activeForm": "Fixing auth type errors"
}

响应会存储一个任务文件（例如 1.json）：

{
  "id": "1",
  "subject": "Fix type errors in src/auth/",
  "description": "Fix all TypeScript errors in src/auth/login.ts...",
  "activeForm": "Fixing auth type errors",
  "owner": "",
  "status": "pending",
  "blocks": [],
  "blockedBy": []
}

对于有依赖关系的任务，在创建后更新当前活动的任务列表条目：

// Task #3 depends on task #1 (shared types must be fixed first)
{
  "taskId": "3",
  "addBlockedBy": ["1"]
}

从 lead 预分配 owner，以避免竞态条件（不存在原子认领机制）：

// Assign task #1 to worker-1
{
  "taskId": "1",
  "owner": "worker-1"
}

阶段 5：生成队友

使用 Agent/Task 工具直接生成 N 个队友，并使用不同的 name 值。每个队友都会获得团队工作前言（见下文）以及他们的具体任务分配。不要调用 TeamCreate，也不要依赖 team_name；Claude Code 2.1.178+ 在原生路由时会忽略它。

{
  "subagent_type": "oh-my-claudecode:executor",
  "name": "worker-1",
  "prompt": "<worker-preamble + assigned tasks>"
}

响应：

{
  "agent_id": "worker-1",
  "name": "worker-1"
}

副作用：

• 队友会被生成到会话的隐式 Claude Code 团队中
• 会自动创建一个内部任务（带有 metadata._internal: true），用于跟踪该 Agent 的生命周期
• 内部任务可能会出现在任务列表输出中——在统计真实任务时请将其过滤掉

重要： 并行生成所有队友（它们是后台 Agent）。不要等待一个完成后再生成下一个。

阶段 6：监控

主 orchestrator 通过两个渠道监控进度：

1. 入站消息 -- 队友在完成任务或需要帮助时会向 team-lead 发送消息。这些消息通过当前活跃的团队/会话界面到达。

2. 任务列表轮询/审查 -- 定期检查 TodoWrite 或当前活跃的任务列表界面，了解整体进度：

   #1 [completed] Fix type errors in src/auth/ (worker-1)
   #3 [in_progress] Fix type errors in src/api/ (worker-2)
   #5 [pending] Fix type errors in src/utils/ (worker-3)
   

   格式：#ID [status] subject (owner)

主负责人可采取的协调操作：

• 解除队友阻塞： 通过当前活跃的团队界面发送包含指导或缺失上下文的消息
• 重新分配工作： 如果某位队友提前完成，更新任务列表条目，将待处理工作分配给他们，并通过当前活跃的团队界面通知
• 处理失败： 如果某位队友报告失败，重新分配任务或生成替代者

任务看门狗策略

监控卡住或失败的队友：

• 最大进行中时长：如果某个任务保持 in_progress 状态超过 5 分钟且没有消息，发送状态检查
• 疑似失效 worker：无消息 + 任务卡住 10 分钟以上 → 将任务重新分配给另一个 worker
• 重新分配阈值：如果某个 worker 失败 2 个以上任务，停止向其分配新任务

阶段 6.5：阶段转换（状态持久化）

在每次阶段转换时，更新 OMC 状态：

// Entering team-exec after planning
state_write(mode="team", session_id="<current_session_id>", current_phase="team-exec", state={
  "stage_history": "team-plan:T1,team-prd:T2,team-exec:T3"
})

// Entering team-verify after execution
state_write(mode="team", session_id="<current_session_id>", current_phase="team-verify")

// Entering team-fix after verify failure
state_write(mode="team", session_id="<current_session_id>", current_phase="team-fix", state={
  "fix_loop_count": 1
})

这支持：

• 恢复：如果主负责人崩溃，state_read(mode="team", session_id="<current_session_id>") 会显示最后阶段和团队名称，用于恢复
• 取消：cancel 技能读取 current_phase，以了解需要执行哪些清理
• Ralph 集成：Ralph 可以读取团队状态，以了解流水线是完成还是失败

阶段 7：完成

当所有真实任务（非内部任务）已完成或失败时：

1. 验证结果 -- 检查所有真实任务（非内部任务）在 TodoWrite 或当前活跃的任务列表界面中是否标记为 completed
2. 关闭队友 -- 通过当前活跃的团队界面向每位活跃队友发送 shutdown_request：

   {
     "type": "shutdown_request",
     "recipient": "worker-1",
     "content": "All work complete, shutting down team"
   }
   

3. 等待响应 -- 每位队友以 shutdown_response(approve: true) 响应并终止
4. 清理 -- 在优雅关闭流程之后，针对所选会话及任何关联的 Ralph，遵循 skills/cancel/SKILL.md 中的 Team 流程； 原生 Claude Code 2.1.178+ 没有 TeamDelete。
5. 报告摘要 -- 向用户展示结果

Agent 前言

在生成队友时，将此前言包含在提示词中，以确立工作协议。根据每位队友的具体任务分配进行调整。

You are a TEAM WORKER in OMC team "{team_name}". Your name is "{worker_name}".
You report to the team lead ("team-lead").
You are not the leader and must not perform leader orchestration actions.

== WORK PROTOCOL ==

1. CLAIM: Check TodoWrite or the active task-list surface for tasks assigned to you (owner = "{worker_name}").
   Pick the first task with status "pending" that is assigned to you.
   Mark it `in_progress` using the active task-list surface:
   {"taskId": "ID", "status": "in_progress", "owner": "{worker_name}"}

2. WORK: Execute the task using your tools (Read, Write, Edit, Bash).
   Do NOT spawn sub-agents. Do NOT delegate. Work directly.

3. COMPLETE: When done, mark the task completed:
   {"taskId": "ID", "status": "completed"}

4. REPORT: Notify the lead through the active team/conversation surface:
   {"type": "message", "recipient": "team-lead", "content": "Completed task #ID: <summary of what was done>", "summary": "Task #ID complete"}

5. NEXT: Check TodoWrite or the active task-list surface for more assigned tasks. If you have more pending tasks, go to step 1.
   If no more tasks are assigned to you, notify the lead through the active team/conversation surface:
   {"type": "message", "recipient": "team-lead", "content": "All assigned tasks complete. Standing by.", "summary": "All tasks done, standing by"}

6. SHUTDOWN: When you receive a shutdown_request, respond with:
   {"type": "shutdown_response", "request_id": "<from the request>", "approve": true}

== BLOCKED TASKS ==
If a task has blockedBy dependencies, skip it until those tasks are completed.
Check TodoWrite or the active task-list surface periodically to see if blockers have been resolved.

== ERRORS ==
If you cannot complete a task, report the failure to the lead:
{"type": "message", "recipient": "team-lead", "content": "FAILED task #ID: <reason>", "summary": "Task #ID failed"}
Do NOT mark the task as completed. Leave it in_progress so the lead can reassign.

== RULES ==
- NEVER spawn sub-agents or use the Task tool
- NEVER run tmux pane/session orchestration commands (for example `tmux split-window`, `tmux new-session`)
- NEVER run team spawning/orchestration skills or commands (for example `$team`, `$autopilot`, `$ralph`, `omc team ...`, `omx team ...`)
- ALWAYS use absolute file paths
- ALWAYS report progress to "team-lead" through the active team/conversation surface
- Use direct team/conversation messages with type "message" only -- never "broadcast"

Agent 类型提示词注入（按 Worker 追加）

在编写队友提示词时，根据 worker 类型追加一段简短的补充内容：

• claude_worker：强调严格的 TodoWrite/任务列表更新、当前活跃的团队/会话消息，以及不使用编排命令。
• codex_worker：强调 CLI API 生命周期（omc team api ... --json）以及带 stderr 的显式失败 ACK。
• gemini_worker：强调有边界的文件所有权，以及每完成一个子步骤后的里程碑 ACK。
• antigravity_worker：与 gemini_worker 期望相同；强调有边界的文件所有权，以及每完成一个子步骤后的里程碑 ACK。

此补充内容必须保留核心规则：worker = 仅执行者，绝不担任 leader/orchestrator。

通信模式

队友 → 主负责人（任务完成报告）

{
  "type": "message",
  "recipient": "team-lead",
  "content": "Completed task #1: Fixed 3 type errors in src/auth/login.ts and 2 in src/auth/session.ts. All files pass tsc --noEmit.",
  "summary": "Task #1 complete"
}

主负责人 → 队友（重新分配或指导）

{
  "type": "message",
  "recipient": "worker-2",
  "content": "Task #3 is now unblocked. Also pick up task #5 which was originally assigned to worker-1.",
  "summary": "New task assignment"
}

广播（谨慎使用 -- 会发送 N 条独立消息）

{
  "type": "broadcast",
  "content": "STOP: shared types in src/types/index.ts have changed. Pull latest before continuing.",
  "summary": "Shared types changed"
}

关闭协议（BLOCKING）

对优雅路径至关重要： 按顺序执行这些步骤。在关闭得到确认或超时之前，绝不要清除 OMC 团队状态。--force 和 --force --all 调用是显式跳过等待的路径；它们仍使用规范的受保护的、会话范围的清除，遵守锁/所有权，并报告失败。单独的 --force 绝不会扩大作用范围。

步骤 1：验证完成情况

Verify via TodoWrite or the active task-list surface — all real tasks (non-internal) are completed or failed.

步骤 2：向每个队友请求关闭

Lead 发送：

{
  "type": "shutdown_request",
  "recipient": "worker-1",
  "content": "All work complete, shutting down team"
}

步骤 3：等待响应（BLOCKING）

• 遵循规范的取消流程：每个队友最多等待 15 秒以获取 shutdown_response，然后再用 5 秒进行协调
• 记录哪些队友已确认、哪些已超时
• 如果队友在这些等待之后仍未响应：记录警告，标记为无响应

队友接收并响应：

{
  "type": "shutdown_response",
  "request_id": "shutdown-1770428632375@worker-1",
  "approve": true
}

在批准后，队友终止或停止接受新工作。Claude Code 2.1.178+ 不暴露按团队的配置成员关系或 TeamDelete 清理；改为在 OMC 状态/报告中跟踪确认。

步骤 4：完成受保护的清理

在优雅处理后，遵循 skills/cancel/SKILL.md 中的团队取消流程；它会清除所选会话并处理关联的 Ralph。Claude Code 2.1.178+ 没有 TeamDelete。

步骤 5：仅针对 OMC tmux/CLI worker 的孤儿扫描

对于旧版 OMC tmux/CLI worker 运行（omc team / /omc-teams），检查在清理后存活的 worker 进程：

node "${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-orphans.mjs" --team-name fix-ts-errors

这会扫描与团队名称匹配的 OMC worker 进程，并终止陈旧的孤儿进程（SIGTERM → 等待 5 秒 → SIGKILL）。支持 --dry-run 以便检查。

优雅清除要求每个队友确认（shutdown_response 带 approve: true）或超时。request_id 来自请求；队友必须返回它，绝不能编造。

CLI Worker（Codex 和 Gemini）

团队技能支持混合执行，将 Claude agent 队友与外部 CLI worker（Codex CLI 和 Gemini CLI）结合。两种类型都可以进行代码更改——它们在能力和成本上有所不同。这些是独立的 CLI 工具，不是 MCP 服务。

执行模式

任务在分解期间会标记执行模式：

执行模式	提供方	能力
claude_worker	Claude agent	完整的 Claude Code 工具访问权限（Read/Write/Edit/Bash/Task）。最适合需要 Claude 推理 + 迭代工具使用的任务。
codex_worker	Codex CLI（tmux pane）	在 working_directory 中具有完整文件系统访问权限。通过 tmux pane 自主运行。最适合代码审查、安全分析、重构、架构。需要 npm install -g @openai/codex。
gemini_worker	Gemini CLI（tmux pane）	在 working_directory 中具有完整文件系统访问权限。通过 tmux pane 自主运行。最适合 UI/设计工作、文档、大上下文任务。需要 npm install -g @google/gemini-cli（企业/API-key 层级）。
antigravity_worker	Antigravity CLI（tmux pane）	在 working_directory 中具有完整文件系统访问权限。通过 tmux pane 自主运行。优势与 gemini_worker 相同；Google 的 Gemini CLI 继任者。按官方说明安装（agy 二进制文件）。

命令行 worker 的工作方式

Tmux 命令行 worker 在专用的 tmux 窗格中运行，并可访问文件系统。它们是自主执行者，而不仅仅是分析者：

1. Lead 将任务指令写入提示词文件
2. Lead 启动一个 tmux 命令行 worker，并将 working_directory 设为项目根目录
3. worker 读取文件、进行修改、运行命令——全部在工作目录内完成
4. 结果/摘要写入输出文件
5. Lead 读取输出，将任务标记为完成，并把结果提供给依赖任务

与 Claude 队友的关键区别：

• 命令行 worker 通过 tmux 运行，而不是 Claude Code 的工具系统
• 它们无法使用 Claude Code 原生的任务列表或团队消息界面
• Codex、Gemini、Grok、Antigravity 和 Claude 命令行 worker 会记录所分配任务的终态并退出
• Cursor worker 会留在交互式会话中，等待邮箱消息，仅在收到显式关闭指令时退出。Cursor 审查者任务的状态转换仍由 leader 负责
• Lead 管理它们的生命周期（启动、监控、收集结果）

Cursor/Codex 启动证据超时

v2 运行时最多等待 30 秒，以获取当前尝试的任务/状态证据。如果未获取到，一次只读窗格活动探测可以为繁忙的 Cursor/Codex worker 额外授予一个 30 秒证据窗口。空闲、已死亡或未验证的窗格只会获得正常的 1 秒最终复查。触发信号绝不会重发，仅凭窗格活动也绝不算作启动成功。如果窗格繁忙但仍没有当前尝试的证据，则以 worker_startup_evidence_missing_pane_busy 失败；其他所有未命中情况保持为 worker_startup_evidence_missing。该启动失败会读取所拥有的窗格一次，拼接折行的 tmux 行，并在捕获内容包含某个认领任务错误行时保留该行。该行不是启动证据，其他未命中情况不会读取窗格。

因此，繁忙 worker 的默认证据预算为 60 秒，再加上探测和证据读取开销（大约一分钟，而不是严格的 61 秒墙钟限制）。窗格创建、就绪和清理会增加额外时间。启动是串行的，因此这些等待可能按 worker 累积。OMC_TEAM_ENGAGED_PANE_RECHECK_MS 以毫秒为单位覆盖额外窗口；正值上限为 120000，而无效值或非正值保留默认值。

何时路由到何处

任务类型	最佳路由	原因
迭代式多步工作	Claude 队友	需要工具介导的迭代 + 团队沟通
代码审查 / 安全审计	命令行 worker 或专家 Agent	自主执行，擅长结构化分析
架构分析 / 规划	architect Claude Agent	具备代码库访问能力的强分析推理能力
重构（范围明确）	命令行 worker 或执行者 Agent	自主执行，擅长结构化转换
UI/前端实现	designer Claude Agent	设计专长，框架惯用法
大规模文档	writer Claude Agent	写作专长 + 大上下文以保持一致
构建/测试迭代循环	Claude 队友	需要 Bash 工具 + 迭代修复循环
需要团队协调的任务	Claude 队友	需要团队/对话状态更新

示例：带命令行 worker 的混合团队

/team 3:executor "refactor auth module with security review"

Task decomposition:
#1 [codex_worker] Security review of current auth code -> output to .omc/research/auth-security.md
#2 [codex_worker] Refactor auth/login.ts and auth/session.ts (uses #1 findings)
#3 [claude_worker:designer] Redesign auth UI components (login form, session indicator)
#4 [claude_worker] Update auth tests + fix integration issues
#5 [gemini_worker] Final code review of all changes

Lead 先运行 #1（Codex 安全分析），然后并行运行 #2 和 #3（Codex 重构后端，designer Agent 重新设计前端），接着运行 #4（Claude 队友处理测试迭代），最后运行 #5（Gemini 最终审查）。

预检分析（可选）

对于大型且目标不明确的任务，在创建团队之前先运行分析：

1. 启动 Task(subagent_type="oh-my-claudecode:planner", ...)，并附带任务描述 + 代码库上下文
2. 利用分析结果生成更好的任务分解
3. 创建团队和任务时附带更丰富的上下文

当任务范围不清晰，且在确定具体分解方案之前需要借助外部推理时，这尤其有用。

监控增强：Outbox 自动摄取

Lead 可以使用 outbox 读取工具主动摄取 CLI worker 的 outbox 消息，从而在原生团队/会话投递之外实现事件驱动的监控。

Outbox 读取函数

readNewOutboxMessages(teamName, workerName) -- 使用字节偏移游标读取单个 worker 的新 outbox 消息。每次调用都会推进游标，因此后续调用只返回自上次读取以来写入的消息。与 readNewInboxMessages() 的 inbox 游标模式一致。

readAllTeamOutboxMessages(teamName) -- 读取团队中所有 worker 的新 outbox 消息。返回 { workerName, messages } 条目数组，跳过没有新消息的 worker。适用于监控循环中的批量轮询。

resetOutboxCursor(teamName, workerName) -- 将某个 worker 的 outbox 游标重置回字节 0。适用于 lead 重启后重新读取历史消息或进行调试。

在监控阶段使用 getTeamStatus()

getTeamStatus(teamName, workingDirectory, heartbeatMaxAgeMs?) 函数提供统一的快照，组合了以下信息：

• Worker 注册 -- 哪些 MCP worker 已注册（来自 shadow registry / config.json）
• 心跳新鲜度 -- 根据心跳时间判断每个 worker 是否存活
• 任务进度 -- 每个 worker 及整个团队的任务计数（pending、in_progress、completed）
• 当前任务 -- 每个 worker 正在执行的任务
• 最近的 outbox 消息 -- 自上次状态检查以来的新消息

在监控循环中的使用示例：

const status = getTeamStatus("fix-ts-errors", workingDirectory);

for (const worker of status.workers) {
  if (!worker.isAlive) {
    // Worker is dead -- reassign its in-progress tasks
  }
  for (const msg of worker.recentMessages) {
    if (msg.type === "task_complete") {
      // Mark task complete, unblock dependents
    } else if (msg.type === "task_failed") {
      // Handle failure, possibly retry or reassign
    } else if (msg.type === "error") {
      // Log error, check if worker needs intervention
    }
  }
}

if (status.taskSummary.pending === 0 && status.taskSummary.inProgress === 0) {
  // All work done -- proceed to shutdown
}

基于 Outbox 消息的事件驱动操作

消息类型	操作
task_complete	将任务标记为已完成，检查被阻塞的任务是否已解除阻塞，通知依赖的 worker
task_failed	递增失败 sidecar，决定重试、重新分配还是跳过
idle	Worker 没有已分配的任务 -- 分配待处理工作或开始关闭
error	记录错误，检查心跳中的 consecutiveErrors 是否达到隔离阈值
shutdown_ack	Worker 已确认关闭 -- 可以安全地从团队中移除
heartbeat	更新存活状态跟踪（与心跳文件功能重叠，但有助于延迟监控）

这种方法为无法使用 Claude Code 团队消息工具的 MCP worker 提供了一种基于拉取的机制，补充了原生团队/会话消息传递。

错误处理

队友任务失败

1. 队友通过当前团队/会话界面将失败报告给 lead
2. Lead 决定：重试（将同一任务重新分配给同一或不同 worker）还是跳过
3. 要重新分配：更新当前任务列表条目中的新负责人，然后通过当前团队界面向新负责人发送消息

队友卡住（无消息）

1. Lead 通过 TodoWrite 或当前任务列表界面检测到 -- 任务在 in_progress 状态停留过久
2. Lead 通过当前团队界面向队友发送消息询问状态
3. 若无响应，则视为该队友已死亡
4. 通过当前任务列表界面将任务重新分配给另一个 worker

依赖被阻塞

1. 如果某个阻塞任务失败，负责人必须决定是否：
   • 重试该阻塞任务
   • 通过更新活动任务列表条目中的 blockedBy 元数据来移除依赖
   • 完全跳过被阻塞的任务
2. 通过活动团队界面将决策传达给受影响的队友

队友崩溃

1. 该队友的内部追踪将显示意外状态
2. 负责人将孤儿任务重新分配给剩余的工作者
3. 如有需要，用 Task(name="worker-N", subagent_type="...") 生成一个替补队友

Team + Ralph 组合

当用户调用 /team ralph、说出 "team ralph"，或同时组合两个关键词时，team 模式会将自身包裹在 Ralph 的持久化循环中。这提供了：

• Team 编排 -- 多 Agent 分阶段流水线，每个阶段配有专门的 Agent
• Ralph 持久化 -- 失败时重试、完成前由架构师验证、迭代追踪

激活

Team+Ralph 在以下情况激活：

1. 用户调用 /team ralph "task" 或 /oh-my-claudecode:team ralph "task"
2. 关键词检测器在提示词中同时发现 team 和 ralph
3. Hook 在 team 上下文中检测到 MAGIC KEYWORD: RALPH

状态关联

两种模式各自写入自己的状态文件，并带有交叉引用：

// Team state (via state_write)
state_write(mode="team", session_id="<current_session_id>", active=true, current_phase="team-plan", state={
  "team_name": "build-rest-api",
  "linked_ralph": true,
  "task": "build a complete REST API"
})

// Ralph state (via state_write)
state_write(mode="ralph", session_id="<current_session_id>", active=true, iteration=1, max_iterations=10, current_phase="execution", state={
  "linked_team": true,
  "team_name": "build-rest-api"
})

执行流程

1. Ralph 外层循环启动（第 1 次迭代）
2. Team 流水线运行：team-plan -> team-prd -> team-exec -> team-verify
3. 如果 team-verify 通过：Ralph 运行架构师验证（最低为 STANDARD 层级）
4. 如果架构师批准：两种模式完成，运行 /oh-my-claudecode:cancel
5. 如果 team-verify 失败或架构师拒绝：team 进入 team-fix，然后循环回 team-exec -> team-verify
6. 如果修复循环超过 max_fix_loops：Ralph 递增迭代次数并重试整个流水线
7. 如果 Ralph 超过 max_iterations：进入终止 failed 状态

幂等恢复

如果负责人在运行中途崩溃，team 技能应检测现有的 OMC 状态并恢复：

1. 读取 state_read(mode="team", session_id="<current_session_id>")，以获取活动的 OMC team slug、阶段和工作者标签
2. 使用 OMC 交接以及任务列表/TodoWrite 状态来确定当前进度
3. 恢复监控模式，而不是生成重复的队友
4. 从最后记录的阶段继续

这可以防止重复生成工作者，并允许从负责人故障中优雅恢复。

对比：Team 与旧版 Swarm

方面	Team（原生 Claude Code 2.1.178+）	Swarm（旧版 SQLite）
存储	OMC 状态/交接，外加 Claude Code 当前的任务列表界面	SQLite，位于 .omc/state/swarm.db
依赖	不需要 better-sqlite3	需要 better-sqlite3 npm 包
任务认领	Lead 通过任务列表/TodoWrite 状态预先分配具名 worker	SQLite IMMEDIATE 事务 —— 原子性
竞态条件	如果两个 Agent 认领同一任务则可能发生（通过预先分配缓解）	无（SQLite 事务）
通信	原生隐式团队消息/对话轮次	无（即发即忘的 Agent）
任务依赖	由 Lead 在任务列表/TodoWrite 状态中管理的依赖	不支持
心跳	Lead 通过缺失的消息/状态检测	手动心跳表 + 轮询
关闭	优雅的请求/响应协议，外加 OMC 状态清理	基于信号的终止
Agent 生命周期	通过具名 Agent/Task 派生和 OMC 状态跟踪	通过心跳表手动跟踪
进度可见性	带具名 worker 归属的任务列表/TodoWrite 状态	对 tasks 表的 SQL 查询
冲突预防	所有者标签（由 Lead 分配）	带超时的基于租约的认领
崩溃恢复	Lead 通过缺失的消息检测，重新分配	5 分钟租约超时后自动释放
状态清理	在队友关闭后清除 OMC 团队状态	手动 rm SQLite 数据库

何时使用 Team 而非 Swarm： 对于新的原生 Claude Code 工作，始终优先使用 /team。它使用 Claude Code 的隐式 Agent 团队，不需要外部依赖，支持 Agent 间协调，并具有任务依赖管理。

取消

Team 取消仅由 skills/cancel/SKILL.md 中的流程定义。它拥有标志矩阵、身份/故障关闭规则、 优雅和强制等待、会话作用域的受保护清理、Team 优先的关联 Ralph 处理、全会话授权以及未解决会话门控。 交接在取消后仍然存在；未捕获的 Team 根仍受保护。

关联模式取消（Team + Ralph）

关联的-Ralph 依赖由同一规范流程覆盖；不要 在此处重述第二套会话操作方案。

运行时 V2（事件驱动）

默认情况下，团队运行时使用事件驱动架构，而非旧的 done.json 轮询看门狗：

• 无 done.json：任务完成通过 CLI API 生命周期转换（claim-task、transition-task-status）检测
• 基于快照的监控：每个轮询周期对任务和 worker 进行时间点快照，计算增量并发出事件
• 事件日志：所有团队事件追加到 .omc/state/team/{teamName}/events.jsonl
• Worker 状态文件：Worker 将状态写入 .omc/state/team/{teamName}/workers/{name}/status.json
• 保留项：Sentinel 门控（阻止过早完成）、熔断器（死 worker 检测）、失败附属文件

原生 CLI 团队作业需要实例绑定的 v2 运行时。在启动它们之前，取消设置禁用的 OMC_RUNTIME_V2 值（0、false、no 或 off）；不存在 仅面板的旧版清理回退方案。即使使用 --force，关闭也需要匹配的实例和 worker 启动证据。会话 state_clear 不会移除 原生运行时树，也不能替代原生团队关闭。

动态扩缩容

当设置 OMC_TEAM_SCALING_ENABLED=1 时，团队支持会话中途扩缩容：

• scale_up：向运行中的团队添加 worker（受 max_workers 限制约束）
• scale_down：移出空闲 worker 并优雅排空（worker 完成当前任务后再被移除）
• 基于文件的扩缩容锁可防止并发扩缩容操作
• 单调递增的 worker 索引计数器确保各次扩缩容事件中的 worker 名称唯一

配置

可选设置位于 .claude/omc.jsonc（项目）或 ~/.config/claude-omc/config.jsonc（用户）。项目值会覆盖用户值；OMC_TEAM_ROLE_OVERRIDES（环境变量 JSON）会覆盖两者。

{
  "team": {
    "ops": {
      "maxAgents": 20,
      "defaultAgentType": "claude",
      "monitorIntervalMs": 30000,
      "shutdownTimeoutMs": 15000,
    },
  },
}

• ops.maxAgents - 最大队友数（默认：20）
• ops.defaultAgentType - 当 /team 调用未指定时使用的 CLI 提供方（claude | codex | gemini | antigravity | grok | cursor，默认：claude）
• ops.monitorIntervalMs - 检查 TodoWrite 或当前任务列表界面的频率（默认：30s）
• ops.shutdownTimeoutMs - 等待关闭响应的时长（默认：15s）

注意： 原生 Claude Code 队友没有硬编码的默认模型；除非按角色覆盖，否则每个队友都会继承 lead 会话所配置的模型。OMC 的旧版 CLI worker 是独立进程：其提供方和模型来自 OMC 的团队路由，而非原生队友继承。

嵌套（Claude Code 2.1.217+）： Claude 队友是会话隐式团队中完整、独立的 Claude Code 会话（见第 5 阶段）。不要假定队友能或不能生成嵌套子 Agent：Claude Code 2.1.217–2.1.218 将 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 默认设为 1，而 2.1.219+ 默认设为 3，且当前设置控制主对话之下的子 Agent 层级。除非嵌套委派是有意为之且受当前运行时支持，否则应将每个队友规划为实际执行工作的单元。OMC CLI worker（claude、codex、gemini、grok、cursor，以及通过 ops.defaultAgentType 使用的 antigravity）是独立进程，不是 Claude Code 子 Agent，不受 Claude 的子 Agent 深度设置影响。

并发： 当前 OMC 团队 CLI 将 worker 扇出上限设为 20（MAX_WORKER_COUNT）；尽管配置 schema 中存在 ops.maxAgents，当前启动器并不会读取它。Claude Code 的 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 也默认为 20，但该限制适用于 Agent 生成的子 Agent；Claude Code 文档说明 agent-team 队友遵循各自的限制。不要把这两个值视为共享上限，也不要假定满员 OMC 团队恰好为零普通子 Agent 留出余量；当 lead 还需要 Agent 生成的工作时，应保守地设定 OMC 团队规模。

按角色的提供方与模型路由

适用范围： 仅适用于 /team。基于任务的委派使用 delegationRouting（见单独文档）。这两个系统按设计共存。

声明每个规范角色应由哪个提供方（claude、codex、gemini、antigravity、grok、cursor）和哪个模型层级支持。路由在团队创建时一次性解析，并持久化到 TeamConfig.resolved_routing —— 生成、扩容和重启都读取该快照，因此角色的 worker CLI 和模型在团队生命周期内保持稳定。

示例——用户目标映射

// .claude/omc.jsonc
{
  "team": {
    "roleRouting": {
      "orchestrator": { "model": "inherit" },
      "planner": { "provider": "claude", "model": "HIGH" },
      "analyst": { "provider": "claude", "model": "HIGH" },
      "executor": { "provider": "claude", "model": "MEDIUM" },
      "debugger": { "provider": "cursor" },
      "critic": { "provider": "codex" },
      "code-reviewer": { "provider": "gemini" },
      "test-engineer": { "provider": "gemini", "model": "MEDIUM" },
    },
  },
}

角色	提供方	模型
orchestrator	claude（固定）	继承发起会话
planner	claude	HIGH（opus）
analyst	claude	HIGH（opus）
executor	claude	MEDIUM（sonnet）
debugger	cursor	cursor-agent 默认
critic	codex	codex 默认
code-reviewer	gemini	gemini 默认
test-engineer	antigravity	antigravity 默认

规范角色

orchestrator、planner、analyst、architect、executor、debugger、critic、code-reviewer、security-reviewer、test-engineer、designer、writer、code-simplifier、explore、document-specialist。

用户友好的别名通过 normalizeDelegationRole() 进行规范化——例如 reviewer → code-reviewer、quality-reviewer → code-reviewer、harsh-critic → critic、build-fixer → debugger。已接受的别名键在生成解析快照时以及后续阶段路由中都会生效，而不仅仅是在校验时。未知角色会在解析阶段校验失败。

Spec 字段（TeamRoleAssignmentSpec）

• provider — "claude" | "codex" | "gemini" | "antigravity" | "grok" | "cursor"。省略 → 默认为 claude。
• model — 层级名称（"HIGH" | "MEDIUM" | "LOW"）或显式模型 ID。层级通过 routing.tierModels 解析。
• agent — 可选的 Claude Agent 名称（例如 "critic"、"executor"）。仅在解析出的 provider 为 claude 时生效。

orchestrator 固定为 claude；仅 model 可由用户配置。orchestrator 上的任何其他键都会被校验器拒绝。

cursor 以交互式 worker 的形式启动 cursor-agent。支持评审/裁决类角色（critic、code-reviewer、security-reviewer、test-engineer），并且它们会获得与其他非 Claude provider 相同的结构化裁决输出契约。leader 在消费裁决后负责终端任务状态转换；最终批准仍属于 lead 会话的职责。

环境变量覆盖

OMC_TEAM_ROLE_OVERRIDES='{"critic":{"provider":"codex"},"code-reviewer":{"provider":"gemini"}}'

优先级：OMC_TEAM_ROLE_OVERRIDES > .claude/omc.jsonc（项目）> ~/.config/claude-omc/config.jsonc（用户）> 内置默认值。无效 JSON 会记录一条警告并被忽略——环境变量覆盖是尽力而为的，绝不会中止运行。

缺失 CLI 预检

Team 启动时仅对其初始 worker 实际生效的 provider 进行严格预检，包括空闲 worker 分配和显式角色路由。角色路由决定每个 worker 的初始启动 provider；后续投递到现有 pane 的任务会保留该 worker 的 provider，不会按任务角色重新路由。若所选 provider 的二进制文件缺失、为相对路径或不受信任，则在创建任何 team 状态或多路复用器副作用之前失败。仅出现在路由快照或声明的 Agent 列表中的 provider——包括从未被选中启动的角色所对应的 provider——不会被探测。路由具有权威性：当所选角色的 provider 不可用时，运行时绝不会静默将其改为 Claude。扩容和 worker 恢复会独立地对其即将启动的 provider 进行预检，若不可用则按失败关闭处理。使用 omc doctor --team-routing 探测 provider 可用性。

粘性——解析一次，处处复用

解析后的路由在每个 team 内不可变。它决定每个 worker 的初始启动分配；现有 pane 中的后续任务会保留该 worker 的 provider，而不会触发按任务角色的 provider 重新路由。在 team 生命周期中途编辑配置不会影响正在运行的 team；新的 /team 调用会采用新的映射。Spawn、扩容和 worker 重启对其启动的 worker 使用同一快照，包括跨 worktree 分离的情况（该快照随 TeamConfig 一起传递）。

零配置行为

空的 team.roleRouting 保留补丁前的行为：每个 worker 都是 Claude，模型层级遵循 routing.tierModels，且 /team 3:executor ... 仍会启动三个 Claude Sonnet executor。

状态清理

使用 /oh-my-claudecode:cancel 进行 Team 和关联 Ralph 的清理；其权威流程会处理会话身份、锁/所有权、优雅等待与强制等待，以及旧版运行时清理。原生 Claude Code 2.1.178+ 没有 TeamDelete。对于正常完成，请在关闭协议之后调用它；未捕获的 Team 根和交接会被保留。

Git Worktree 集成

MCP worker 可以在隔离的 git worktree 中运行，以防止并发 worker 之间的文件冲突。

工作原理

1. 创建 worktree：在启动 worker 之前，调用 createWorkerWorktree(teamName, workerName, repoRoot)，在 .omc/worktrees/{team}/{worker} 创建一个隔离的 worktree，分支为 omc-team/{teamName}/{workerName}。

2. Worker 隔离：将 worktree 路径作为 worker 的 BridgeConfig 中的 workingDirectory 传入。Worker 仅在自己的 worktree 中运行。

3. 合并协调：worker 完成任务后，使用 checkMergeConflicts() 验证分支能否干净地合并，然后使用 mergeWorkerBranch() 以 --no-ff 方式合并，以获得清晰的历史记录。

4. 团队清理：团队关闭时，调用 cleanupTeamWorktrees(teamName, repoRoot) 移除所有 worktree 及其分支。

API 参考

函数	描述
createWorkerWorktree(teamName, workerName, repoRoot, baseBranch?)	创建隔离的 worktree
removeWorkerWorktree(teamName, workerName, repoRoot)	移除 worktree 和分支
listTeamWorktrees(teamName, repoRoot)	列出所有团队 worktree
cleanupTeamWorktrees(teamName, repoRoot)	移除所有团队 worktree
checkMergeConflicts(workerBranch, baseBranch, repoRoot)	非破坏性冲突检查
mergeWorkerBranch(workerBranch, baseBranch, repoRoot)	合并 worker 分支（--no-ff）
mergeAllWorkerBranches(teamName, repoRoot, baseBranch?)	合并所有已完成的 worker

重要说明

• tmux-session.ts 中的 createSession() 不负责创建 worktree —— worktree 生命周期通过 git-worktree.ts 单独管理
• 单个 worker 关闭时不会清理 worktree —— 仅在团队关闭时清理，以便进行事后检查
• 分支名称通过 sanitizeName() 进行清理，以防注入
• 所有路径都会进行目录遍历校验

注意事项

1. 内部/生命周期任务条目可能污染任务列表输出 -- 如果 Claude Code 报告了为已生成的队友创建的内部生命周期条目，在统计真实任务进度时应将其过滤掉。内部任务的主题通常是队友的名称。

2. 没有原子认领机制 -- 与 SQLite swarm 不同，原生任务列表/TodoWrite 状态不提供事务性认领。两个队友可能会竞相认领同一个任务。缓解措施： 负责人应在生成队友之前预先分配负责人。队友应只处理分配给他们的任务。

3. 通过任务列表工具暴露时，任务 ID 是字符串 -- ID 可能是自动递增的字符串（"1"、"2"、"3"），而不是整数。使用任务列表工具时，始终向 taskId 字段传递字符串值。

4. 没有 TeamDelete 清理 -- Claude Code 2.1.178+ 移除了 TeamDelete；请使用关闭消息加上 OMC 状态清理。

5. 消息会自动投递 -- 队友消息会作为新的对话轮次到达负责人。入站消息无需轮询或检查收件箱。但是，如果负责人正处于轮次中间（处理中），消息会排队，并在轮次结束时投递。

6. 不要在队友提示词中放入机密信息 -- 提示词可能会保留在日志、状态或对话历史中。请将凭据和敏感数据排除在队友提示词之外。

7. 关闭确认是状态/报告事件 -- 在队友批准关闭并终止后，请在 OMC 状态/报告中跟踪该确认。不要指望 Claude Code 团队成员配置会更新。

8. shutdown_response 需要 request_id -- 队友必须从传入的关闭请求 JSON 中提取 request_id 并将其传回。格式为 shutdown-{timestamp}@{worker-name}。伪造此 ID 将导致关闭静默失败。

9. 团队名称必须是有效的 slug -- 使用小写字母、数字和连字符。从任务描述中派生（例如，"fix TypeScript errors" 变成 "fix-ts-errors"）。

10. 广播代价高昂 -- 每次广播都会向每个队友发送一条单独的消息。默认使用 message（私信）。仅在真正全团队范围的关键警报时使用广播。

11. CLI worker 的生命周期跟随提供方 -- 参见 CLI Worker 如何运作。Tmux CLI worker 不使用 Claude Code 的原生任务列表或团队消息传递界面。

并行会话注意事项

• 多仓库工作区锚点： 在父目录放置一个 .omc-workspace 标记，以便跨子仓库的多个会话共享一个 .omc/。解析顺序：OMC_STATE_DIR > .omc-workspace > git > cwd。参见 docs/REFERENCE.md。
• 会话 ID 来源： 在 CLI 上下文中，OMC_SESSION_ID 环境变量优先；在 hook 上下文中，hook 载荷 data.session_id 优先。
• 计划 ID（如适用）： 团队状态是会话范围的。位于 .omc/handoffs/ 的团队交接按设计是共享的（参见工作区计划中的 Wave G）。
• 并行判定： 支持（按设计为会话范围 + 共享交接）