feat(teams): teammateMode 默认翻转为 "iterm2" + 隐式团队余波同步 [v6.6.0] (#8)

模板默认 teammateMode "tmux" → "iterm2"（fail-loud：缺 it2 报错而非静默退回 in-process，正解 ADR-004 "以为开了分屏其实没开" 痛点）；"tmux"/"auto" 降为推荐 fallback。模板 min 维持 v2.1.154（Agent Teams 实验 flag、不构成 min 下限）。ADR-004 决策内修订（备选 D 采纳作默认 / 备选 A 降 fallback / §版本与查证 翻转回填 + 本机核验）；team-mode.md + FIRST_RUN.md 对齐。

同批：隐式团队余波同步（v2.1.178 移除 TeamCreate/TeamDelete）——agf-team-stop.md 删手动 TeamDelete 指引、team-capability-map.md 删 5 处恒 ❌ TeamCreate 行、team-mode.md 加隐式团队运行时说明。

MINOR v6.6.0。本机核验：it2 v0.2.3 + iTerm2 Python API + backendType:iterm2 通路存活；lint-all.sh 全过（44 文件/测试套）。

Author: pcliangx

.claude/commands/agf-team-stop.md

@@ -54,4 +54,4 @@ argument-hint: 无参数（自动识别 alive teammate）
 
 - 没有命中类型的 teammate alive → `"无可关闭 teammate（PL / 单实例角色不在默认关闭范围）。"` 退出
 - 不在 agent team 模式（无 `~/.claude/teams/<team-name>/` 目录）→ `"当前会话不是 agent team 模式，无 teammate 可关闭。"` 退出
-- 用户想连 PL / 长期角色一起关 → 不在本命令范围；告诉用户：`"PL 默认保留以接续后续需求；如确需全 team 解散，先手动 SendMessage shutdown_request 给 PL，然后 TeamDelete。"`
+- 用户想连 PL / 长期角色一起关 → 不在本命令范围；告诉用户：`"PL 默认保留以接续后续需求；如确需全 team 解散，先手动 SendMessage shutdown_request 给 PL，PL 退出后 team 目录随 session 结束自动清理（v2.1.178 起 TeamCreate / TeamDelete 工具已移除，无需手动操作）。"`

.claude/rules/team-mode.md

@@ -21,7 +21,7 @@ paths:
 2. 每个 teammate **必须用 subagent type 名字**（如 `product-lead`、`backend-dev`），**严禁** 用 `@.claude/agents/*.md` 文件引用——definition 已被 Claude Code 自动加载，再 `@` 引用只浪费 lead 的 token。
 3. 每个 teammate 必须给**可立即执行的初始任务**，禁止「待命 / standby」类占位任务（会让 Claude 倾向退化为 subagent）。
 4. Lead 固定为 `product-lead`，且 **lead = 主 session 本身**：由 `agf-team-start.sh`（或手动 `claude --agent product-lead`）以 `--agent product-lead` 启动。PL 走 `--agent` 路径，其 frontmatter（`permissionMode: acceptEdits` / `skills` / `memory`）**全生效**，团队权限基线 = PL 的 `acceptEdits`（**默认不再用 `--dangerously-skip-permissions`**）。**因此不要再把 `product-lead` 作为 teammate spawn**——PL 自身的首个任务（如起 PRD）由本 session 直接执行。前提：`product-lead.md` 的 `tools` 须含 `Agent`（spawn teammate 必需）。
-5. 显示模式由 `.claude/settings.json` 的 `teammateMode` 控制（当前 `tmux`），不要在 prompt 里指定 pane 行为。
+5. 显示模式由 `.claude/settings.json` 的 `teammateMode` 控制（当前 `iterm2`；无 it2 / 非 iTerm2 用户在用户级改 `tmux`/`auto`），不要在 prompt 里指定 pane 行为。
 6. 启动后 lead 必须显式确认「这是 agent team 而不是 subagent」，并报告每个 teammate 的 name + agent ID。
 7. 并行派发同类型 teammate 遵循 `.claude/standards/workflow.md` "Parallel Dispatch" 节，且**必须用 git worktree 隔离**（见同文件 worktree 节）。
 
@@ -32,7 +32,9 @@ paths:
 ## 已启用的运行时配置
 
 - `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`：在 `.claude/settings.json` 的 `env` 块声明，用户级 `~/.zshrc` 同时 export 作冗余兜底
-- `teammateMode: "tmux"`：请求 split panes（官方语义：启用 split-pane 并按终端自动判别走 tmux 还是 iTerm2）。**改自原默认 `"auto"`**——`"auto"` 仅当**已身处 tmux 会话内**（`TMUX` 已设）才走 split panes，"光装了 tmux / 在 iTerm2 里"都不算，否则回退 in-process。✅ **iTerm2 回退缺陷已实测确认修复（2026-06-11 本机复核）**：CC v2.1.170 + 纯 iTerm2（无 tmux server），`"tmux"` 设置成功 spawn 8 个 iTerm2 原生分屏 teammate（team config 记 `backendType:"iterm2"` + pane GUID，超出单 tab 容量自动溢出到第 2 个 tab——**找不到 teammate 时先翻 tab**）；历史缺陷见官方 issue [#24292](https://github.com/anthropics/claude-code/issues/24292) / [#23815](https://github.com/anthropics/claude-code/issues/23815)（均已关，CHANGELOG v2.1.77 对应条目），ADR-004 该项待办可销。tmux 路径（先 `tmux new -s claude` 再 `claude`）仍为备选。非 macOS / 无 tmux / VS Code 内置终端 / Windows Terminal / Ghostty 一律不支持 split panes → 静默 in-process。本项目默认值与降级取舍记录见 [ADR-004](../../docs/adr/004-teammate-mode-default.md)
+- **隐式团队（v2.1.178+）**：设上面 flag 后每个 session 自动拥有一个隐式团队——直接 spawn teammate（Agent 工具 `name` 参数）即可、无需建团步骤；PL session 退出时 team 目录（`~/.claude/teams/session-<id前8位>/`）随之自动清理。**v2.1.178 起 `TeamCreate` / `TeamDelete` 工具已移除**：启动协议第 1 条 `Create an agent team called <Name>Team` 触发句式仍有效（Claude 据此 spawn），但你传的 team name 现被忽略（改 session-derived）。「一 session 一 team / teammate 不能 spawn teammate / lead 固定 PL」不变。**模板 min 维持 v2.1.154 不上抬**——该下限由 Dynamic Workflows GA 决定（[ADR-002](../../docs/adr/002-dynamic-workflows-adoption.md)）、与 Teams 无关；Agent Teams 是实验 flag 功能、不构成 min 下限，v2.1.154–177 走旧 `TeamCreate` 流程亦可（`init-team.sh` warn 不 block）
+- `teammateMode: "tmux"`（**2026-06-23 起为推荐 fallback，模板默认已改 `"iterm2"`**）：请求 split panes（官方语义：启用 split-pane 并按终端自动判别走 tmux 还是 iTerm2）。**无 it2 / 非 iTerm2 / 跨平台的团队用户改设此值即恢复优雅降级**（不报错）。**曾为模板默认（2026-06-17→06-23）、更早改自 `"auto"`**——`"auto"` 仅当**已身处 tmux 会话内**（`TMUX` 已设）才走 split panes，"光装了 tmux / 在 iTerm2 里"都不算，否则回退 in-process。✅ **iTerm2 回退缺陷已实测确认修复（2026-06-11 本机复核）**：CC v2.1.170 + 纯 iTerm2（无 tmux server），`"tmux"` 设置成功 spawn 8 个 iTerm2 原生分屏 teammate（team config 记 `backendType:"iterm2"` + pane GUID，超出单 tab 容量自动溢出到第 2 个 tab——**找不到 teammate 时先翻 tab**）；历史缺陷见官方 issue [#24292](https://github.com/anthropics/claude-code/issues/24292) / [#23815](https://github.com/anthropics/claude-code/issues/23815)（均已关，CHANGELOG v2.1.77 对应条目），ADR-004 该项待办可销。tmux 路径（先 `tmux new -s claude` 再 `claude`）仍为备选。非 macOS / 无 tmux / VS Code 内置终端 / Windows Terminal / Ghostty 一律不支持 split panes → 静默 in-process。本项目默认值与降级取舍记录见 [ADR-004](../../docs/adr/004-teammate-mode-default.md)
+- `teammateMode: "iterm2"`（**v2.1.186 新增 · 模板默认（2026-06-23 起，见 [ADR-004](../../docs/adr/004-teammate-mode-default.md)）**）：强制走 iTerm2 原生分屏，**硬依赖 [`it2` CLI](https://github.com/mkusaka/it2)**——缺 it2 即报错并打印安装命令（区别于 `"tmux"` 的静默降级；fail-loud 正是选它作默认的理由）。前置：`pip install it2` + iTerm2 → Settings → General → Magic → Enable Python API，且 Claude Code ≥ v2.1.186（**模板 min 仍 v2.1.154 不上抬**——Teams 实验功能不构成 min 下限，见上「隐式团队」条）。**无 it2 / 非 iTerm2 / 跨平台的团队用户**：把 `teammateMode` 改回 `"tmux"`/`"auto"`（见上一条 fallback + CHANGELOG `Migration steps`）。另：v2.1.186 起 `"auto"` 语义已放宽为「tmux 会话内 **或** iTerm2 终端」均走 split panes（故上一条"auto 仅 tmux 会话内"为 ≤v2.1.185 旧语义）；`"auto"`/`"tmux"` 在 iTerm2 且 tmux 可作 fallback 时会弹"装 it2 或切 tmux"的 setup prompt。选型权衡见 [ADR-004 备选 D](../../docs/adr/004-teammate-mode-default.md)
 - `TeammateIdle` hook：`.claude/hooks/teammate-keepalive.sh`，task list 还有 pending 时阻止 teammate 提前 idle
 
 ## 反模式

.claude/settings.json

@@ -10,7 +10,7 @@
     "_OTEL_EXAMPLE_OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
     "_OTEL_EXAMPLE_OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf"
   },
-  "teammateMode": "tmux",
+  "teammateMode": "iterm2",
   "autoMemoryEnabled": true,
   "worktree": {
     "baseRef": "head"

CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to the AppGenesisForge AI team template are documented here.
 
 ---
 
+## [v6.6.0] — 2026-06-23 — teammateMode 默认翻转为 `"iterm2"`（v2.1.186）+ 隐式团队余波同步（v2.1.178）
+
+> **Why**: Claude Code v2.1.186 新增 `teammateMode: "iterm2"`（强制 iTerm2 原生分屏、硬依赖 [`it2` CLI](https://github.com/mkusaka/it2)、缺失即报错并打印安装命令），并放宽 `"auto"` 语义至「tmux 会话内 **或** iTerm2 终端」均走 split panes（原仅 tmux 会话内）。本模板主用场景为 macOS + iTerm2 + it2（本机已核验 it2 v0.2.3 + Python API + `backendType:"iterm2"` 通路存活），maintainer 复议判定：显式 `"iterm2"` 的 **fail-loud（缺 it2 报错而非静默退回 in-process）** 正解 ADR-004 当初"以为开了分屏其实没开"的痛点，价值高于跨平台优雅降级——故**模板默认 `teammateMode` 由 `"tmux"` 翻转为 `"iterm2"`**，跨平台降级由 `"tmux"`/`"auto"` fallback 承接（ADR-004 已带 verbatim 引用回填决策翻转）。此外同批同步另一项 Agent Teams 变更的文档余波——**v2.1.178 移除 `TeamCreate` / `TeamDelete`、改为每 session 隐式团队 + 退出自动清理**：清掉团队关停指引里残留的「手动 `TeamDelete`」与 5 处恒 ❌ 的 `TeamCreate` 能力行，并把隐式团队语义 + min 不上抬的理由写进 `team-mode.md`（详见 Changed）。
+>
+> **cost 档位**：Small（1 轮官方源核验【agent-teams 文档 + CHANGELOG v2.1.186 两源交叉】+ 本机环境实测 + ADR-004 决策翻转 + 多文件对齐）。
+>
+> **版本判定**：MINOR——Agent Teams 是实验 flag 功能（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`），其默认显示模式翻转不动 stable 模板契约（agents/skills/commands/hooks/standards 未改）；**模板 min 维持 v2.1.154 不上抬**（Teams 不构成 min 下限，见 `team-mode.md` §已启用的运行时配置）。
+
+### Changed
+
+- **`.claude/settings.json`**：`teammateMode` `"tmux"` → `"iterm2"`（**模板默认翻转**）。
+- **ADR-004 决策修订**（`"tmux"` → `"iterm2"`，Accepted 内修订）：新增"当前生效决策"框、备选 D 由"否决作默认 / 采纳 opt-in"翻为**采纳作模板默认**、备选 A（tmux）降为推荐 fallback、§版本与查证加官方语义 3 行 + 2026-06-23 决策翻转回填 + 本机核验；2026-06-17 tmux 决策段保留为沿革。
+- **`.claude/rules/team-mode.md`**：`iterm2` 升为默认 bullet、`tmux` 降为 fallback bullet、启动协议第 5 条「当前 iterm2」；标注 `"auto"` 原"仅 tmux 会话内"为 ≤v2.1.185 旧语义。
+- **`docs/FIRST_RUN.md`**：split-pane 段 + 前置表对齐 iterm2 默认（`it2` 前置 + Enable Python API + Claude Code ≥ v2.1.186）+ tmux/auto fallback。
+- **`CLAUDE.md`** 模板版本号 v6.5.0 → v6.6.0（min Claude Code 维持 **v2.1.154**——iterm2 默认不抬模板 min）。
+- **隐式团队余波同步（跟进 v2.1.178 移除 `TeamCreate` / `TeamDelete`）**：`.claude/commands/agf-team-stop.md` 全 team 解散指引删去失效的「手动 `TeamDelete`」、改为「PL 退出 → session 结束自动清理（工具已移除，无需手动操作）」；`docs/team-capability-map.md` 删除 5 个能力子表里的 `TeamCreate` 行（工具已移除、且全角色恒 ❌ 零信息量）；`.claude/rules/team-mode.md`「已启用的运行时配置」新增隐式团队 bullet（无需建团 / 退出自动清理 / team name 现 session-derived / min v2.1.154 不上抬的理由）。
+
+### Migration steps
+
+> 仅影响**启用 Agent Teams 且在非 macOS / 未装 `it2` / 非 iTerm2 终端**的下游 fork；不启用 Teams 或已具备 it2 + iTerm2 的用户无需动作。
+
+1. **想保留旧的优雅降级**：把 `teammateMode` 设回 `"tmux"` 或 `"auto"`（项目级或用户级 `~/.claude/settings.json` 均可）。
+2. **想用新默认 `"iterm2"`**：`pip install it2`（或 `uv tool install it2`）→ iTerm2 → Settings → General → Magic → Enable Python API → Claude Code 升到 ≥ v2.1.186。
+3. 未设 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`（不启用 Teams）则 `teammateMode` 不生效，无影响。
+
+### Verification
+
+- 官方事实经两源交叉核验：[agent-teams 文档](https://code.claude.com/docs/en/agent-teams)（§Choose a display mode，`min-version: 2.1.186` 标记）+ [CHANGELOG v2.1.186](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)（"Added `teammateMode: \"iterm2\"` setting with a warning when auto mode cannot find the `it2` CLI"）。
+- `.claude/settings.json` 由 `"tmux"` → `"iterm2"`（唯一运行行为改动）；hook / 脚本 / agents / skills / commands / standards 契约未动；`lint-all.sh` 通过（44 文件/测试套）。
+- **本机环境核验**（2026-06-23 · claude v2.1.186 · macOS）：`it2` CLI v0.2.3 已装 + iTerm2 Python API 已启用（`it2 ls` 成功枚举会话），`backendType:"iterm2"` 渲染通路实证存活（并发 team `session-66407a60` 的 5 个 teammate team config 均记 `iterm2`）；本会话所在 Warp 终端下 `"tmux"` 按预期降级 in-process。**未隔离验证**显式 `"iterm2"` vs `"tmux"` 自动判别（两者同产 `backendType:"iterm2"`）。详见 ADR-004 §版本与查证 2026-06-23 回填。
+
 ## [v6.5.0] — 2026-06-17 — DESIGN.md 设计 token SSOT + hook 安全/verdict 加固 + 专家评审收尾
 
 > **Why**: 两条线。① 借鉴 [xianxin-design-workflow](https://github.com/lxxgg92/xianxin-design-workflow) 引入**项目级设计 token SSOT**——此前各 feature 的 spec.md 各自内联声明颜色/间距，违反 AGF 自身单一来源原则；现以 `docs/design/DESIGN.md`（YAML token + on-* 对比配对 + Do/Don't）收口，spec/前端只引用 token，配套 coding 纪律 + reviewer 审查项形成逐环对账。② 一次三视角专家评审（架构/工程质量/产品）**实地复现并修复 3 项 hook 缺陷**（2 项实测可绕过、1 项造成只读 reviewer idle 死锁），补齐角色漂移 eval 覆盖（5→11/19），定稿唯一悬空的 ADR-004。

CLAUDE.md

@@ -1,6 +1,6 @@
 # AppGenesisForge
 
-> **Template Version: v6.5.0**（min Claude Code v2.1.154）。逐版本变更见 [CHANGELOG](CHANGELOG.md)。
+> **Template Version: v6.6.0**（min Claude Code v2.1.154）。逐版本变更见 [CHANGELOG](CHANGELOG.md)。
 
 ## Project Overview
 

docs/FIRST_RUN.md

@@ -37,7 +37,7 @@
 | Review AI agent 输出 | prompt 工程 + RAG 概念 |
 | 合并 main 前判定版本号 | SemVer + Keep a Changelog |
 | 跑 evals 漂移巡检 | `jq` |
-| Agent Team split panes 显示 | macOS + iTerm2 / tmux |
+| Agent Team split panes 显示（默认 iterm2） | macOS + iTerm2 + `it2`（无则改 `tmux`/`auto` fallback） |
 
 ### 不需要懂
 
@@ -86,7 +86,7 @@ cost-budget 自动核账、hook 实现细节（撞到走 PL 授权）、subagent
 ## 可选增强
 
 - **OTEL 观测**：长期运维时按 `.claude/standards/observability.md` 把 `.claude/settings.json` 的 `_OTEL_EXAMPLE_*` 占位改成正式键名 + 起 OTEL collector。
-- **Agent Team split panes 显示**（macOS）：`teammateMode: "tmux"`（模板默认，见 [ADR-004](adr/004-teammate-mode-default.md)）在 **iTerm2 直接 `claude`** 或 `tmux new -s claude && claude` 下均走原生分屏（2026-06-11 + 2026-06-17 实测）；不支持 split-pane 的终端（VS Code 内置 / Windows Terminal / Ghostty）静默回退 in-process，不影响功能。细节见 `.claude/rules/team-mode.md`。
+- **Agent Team split panes 显示**（macOS）：模板默认 `teammateMode: "iterm2"`（2026-06-23 起，见 [ADR-004](adr/004-teammate-mode-default.md)）——强制 iTerm2 原生分屏，**前置 `pip install it2` + iTerm2 → Settings → General → Magic → Enable Python API + Claude Code ≥ v2.1.186**；缺 it2 / 非 iTerm2 时**显式报错（fail-loud）**，刻意为之以免"以为开了分屏其实没开"。**无 it2 / 非 iTerm2 / 跨平台用户**：把 `teammateMode` 改回 `"tmux"` 或 `"auto"`（iTerm2/tmux 出原生分屏、其余终端静默 in-process 不影响功能）——改用户级 `~/.claude/settings.json` 即可、不动项目默认；模板 min 仍 v2.1.154（Teams 实验功能不抬 min）。细节见 `.claude/rules/team-mode.md`。
 - **GitHub Actions**：`.github/workflows/claude-code.yml` 是模板，**默认不启用**。启用需装 Claude Code GitHub App + 加 `ANTHROPIC_API_KEY` secret；默认只在 PR 加 `claude-review` label 时跑，避免每次 push 烧 token。
 
 ---