# Team Mode

> Multi-agent collaboration overlay for ce:plan/work/review. ce:brainstorm structured convergence is built-in to [P] mode, not via [T]. Enables contract-gated execution with single writer principle, real Agent Teams verifier, and deterministic patch gate.

- **Type:** Skill
- **Install:** `agentstack add skill-jerrylalala-compound-engineering-team-mode`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Jerrylalala](https://agentstack.voostack.com/s/jerrylalala)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Jerrylalala](https://github.com/Jerrylalala)
- **Source:** https://github.com/Jerrylalala/compound-engineering/tree/main/plugins/compound-engineering/skills-custom/team-mode

## Install

```sh
agentstack add skill-jerrylalala-compound-engineering-team-mode
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Team Mode Overlay

> **核心理念**：合约边界 + 单写者原则 + 独立验证者 = 问题在发生前被拦截。
>
> **各命令的实现层次不同**：
> - `ce:work [T]`：真实 Claude Code Agent Teams（TeamCreate + 独立 context window + SendMessage）
> - `ce:brainstorm [P]`：[P] 结束后自动触发探索者+挑战者收敛（无独立 [T] 参数，避免与 Claude Code Agent Teams 混淆）
> - `ce:plan [T]`：同一 agent 多任务（有意设计，合约生成和追溯审查是顺序文档处理，不需要验证循环）
> - `ce:review [T]`：规则引擎（有意设计，Patch Gate 是 deterministic whitelist check，零 token）

本 skill 是叠加在 `ce:plan`/`ce:work`/`ce:review` 之上的 overlay。各命令通过检测 `[T]`、`[T+]` token 激活对应的角色集和机制。`ce:brainstorm` 不支持 `[T]` 参数，结构化收敛已内置为 `[P]` 的自动后续行为。

---

## 参数变体

| Token | ce:work 实现 | ce:plan/review 实现 | 适用场景 |
|-------|-------------|---------------------|---------|
| `[T]` | TeamCreate + verifier teammate（独立 context window）+ lead 扮演合约主+执行者 | 同一 agent（plan=合约生成，review=规则引擎） | 默认，大多数任务 |
| `[T+]` | 在 `[T]` 基础上额外 spawn risk-guard teammate | 同 `[T]`（plan/review 无额外角色） | auth/payment/migration 高风险路径 |

> **ce:brainstorm 不使用 [T] 参数**：结构化收敛（探索者+挑战者）已内置为 [P] 结束后的自动行为，避免与 Claude Code 原生 Agent Teams 混淆。

---

## 角色定义

| 中文名 | 适用阶段 | 职责 | 生命周期 |
|--------|---------|------|---------|
| **合约主** | plan, work | 执行前写边界合约（allowed_files/forbidden_surfaces/invariants），全程持有合约权威。`.team-contract.md` 作为团队章程（所有 teammate 启动时读取），不是通信介质 | 全程存活（文件持久化） |
| **执行者** | work | **唯一可写共享代码的角色**（单写者原则）。遇越界暂停上报，不自行决策 | 按任务运行 |
| **验证者** | work | 独立 context window 的真实 teammate。等待 lead 发 SendMessage 通知，运行不变式检查，只读不写，回复 PASS/FAIL | 事件驱动（每 Unit 完成后收到 SendMessage） |
| **风险卫** | work（[T+]） | 独立 context window 的真实 teammate。等待 lead 发 Unit 开始通知，检测高风险关键词，回复拦截或通过，要求用户确认才继续 | 仅 [T+] 模式，Unit 开始前 |
| **追溯审查** | plan | 搜索 `docs/solutions/` 查找历史相关案例，检查计划决策是否与已记录 gotcha 矛盾，将发现追加到计划 Open Questions 节 | ce:plan Phase 4.5（只读） |
| **探索者** | brainstorm | 聚焦「这个想法在技术上可行吗？」，提出具体验证路径和可达条件 | ce:brainstorm [P] 结束后自动触发（非独立参数） |
| **挑战者** | brainstorm | 质疑假设，寻找边界条件和反例，防止过早收敛 | ce:brainstorm [P] 结束后自动触发（非独立参数） |

### 各阶段角色集

| 阶段 | 默认角色 | [T+] 追加 |
|------|---------|-----------------|
| `/ce:brainstorm [P]` | [P] 结束后自动收敛（探索者+挑战者，内置，无需 [T]） | — |
| `/ce:plan [T]` | 合约主 + 追溯审查 | — |
| `/ce:work [T]` | 合约主 + 执行者 + 验证者 | 风险卫 |
| `/ce:review [T]` | 现有多个专业审查 agent + Patch Gate | — |

**[T+] 在各命令的行为**：
- `ce:plan [T+]`：等同于 `[T]`（plan 阶段无风险卫角色，触发同样的 Phase 4.5 合约生成）
- `ce:work [T+]`：在 3 角色基础上追加风险卫（4 角色完整模式）
- `ce:review [T+]`：等同于 `[T]`（Patch Gate 行为无差别）

传入不支持 [T+] 差异的命令时，AI 应将其等同处理为 [T]，不产生错误。

---

## 单写者原则（Iron Law）

**ONLY 执行者 writes to shared checkout.**

```
其他角色职责分配：
  合约主   → 只读 .team-contract.md；写入仅限合约文件本身（初始化阶段）
  验证者   → 只读代码和测试输出；不修改任何文件（包括 .team-contract.md）
  风险卫   → 只读代码；不修改任何文件
  执行者   → 唯一可修改业务代码的角色；验证失败时负责写入 last_verification_failure
```

**违反后果**：
- 如果非执行者角色尝试写代码 → 立即停止，上报违规，等待用户确认
- 如果执行者尝试写 allowed_files 以外的文件 → 暂停，报告越界，等待用户确认
- 如果执行者尝试写 forbidden_surfaces 中的文件 → 拒绝执行，要求修改计划

**为什么这条规则比增加 agent 更有效**：多个 agent 并发写代码会导致冲突、覆盖、和状态不一致。单写者消除这类错误的根源，而不是事后补救。

---

## .team-contract.md 格式规范

> **Source of Truth**：本节是 `.team-contract.md` 格式的唯一权威定义。`ce:plan/SKILL.md` 的 Phase 4.5 包含格式副本用于生成指引，若两处有出入，以本节为准。

合约文件使用 YAML frontmatter（而非 Markdown 表格），便于规则引擎程序化解析：

```yaml
---
team_mode: true
generated_by: "ce:plan [T]"
generated_at: YYYY-MM-DD
plan_source: docs/plans/PLAN_FILENAME.md
plan_source_commit:    # 生成时 plan_source 的最新 commit hash，用于检测计划是否已更新
allowed_files:
  - path/to/file1.md
  - path/to/file2.md
forbidden_surfaces:
  - plugins/compound-engineering/.claude-plugin/plugin.json
  - CHANGELOG.md
required_invariants:
  - "bash scripts/check-handoff.sh 必须通过"
  - "不得移除 argument-hint 中已有的 [C][G][P] 标志"
max_files_per_patch: 1
last_verification_failure: null
---

# Team Contract

## 背景
[可选：描述本次任务的背景和边界约束]
```

### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `allowed_files` | string[] | 执行者在本次任务中允许修改的文件列表（由 ce:plan 从 Implementation Units 提取）。**匹配规则：精确路径匹配（完整 repo-relative 路径），不支持通配符（`src/*` 无效），不支持目录前缀（`src/` 不匹配 `src/foo.ts`），如需覆盖目录须逐个列出文件** |
| `forbidden_surfaces` | string[] | 绝对禁止自动修改的文件（版本文件、schema、认证配置等） |
| `required_invariants` | string[] | 每次变更后必须满足的不变式（由 ce:plan 从 `## 验收场景` 章节和 Unit Verification 字段转换） |
| `max_files_per_patch` | int | 单次 autofix patch 允许修改的最大文件数（默认 1，即 one-finding-one-patch） |
| `last_verification_failure` | string\|null | 执行者记录最近一次验证失败信息（null 表示无失败） |
| `plan_source_commit` | string\|null | 生成合约时 plan_source 的 git commit hash；ce:work 加载时与当前 hash 对比，检测计划是否已更新 |

---

## 各命令激活方式

### ce:plan [T]

> **实现层次**：同一 agent 执行合约主和追溯审查两项任务（有意设计）。
> 原因：plan 阶段是文档生成，不是验证循环；合约主从计划文件提取 allowed_files 是文档处理，追溯审查是历史搜索，两者都是顺序任务，spawn 真实 teammate 的开销不合理。`.team-contract.md` 作为后续 ce:work 阶段所有 teammate 共享的团队章程。

在 Phase 4（Write the Plan）之后触发 Phase 4.5（合约生成）：

```
合约主激活：
  1. 读取刚生成的计划文件
  2. 从所有 Implementation Units 的 Files 字段收集 allowed_files
  3. 从计划描述识别高风险文件 → forbidden_surfaces
  4. 从 `## 验收场景` 章节和 Unit Verification 字段转换 → required_invariants
  5. 写入 .team-contract.md（repo 根目录）

追溯审查激活：
  1. 搜索 docs/solutions/ 查找历史相关案例
  2. 检查计划决策是否与历史 gotcha 矛盾
  3. 将发现追加到计划的 Open Questions 节
```

### ce:work [T] / [T+]

使用 Claude Code 原生 Agent Teams（真实独立 context window），而非角色模拟。

#### Phase -1: 真实 Agent Teams 初始化

```
1. 检测 team token 变体（default/full）

2. 创建命名团队（精确到秒，防止同小时内重复碰撞）：
   TEAM_NAME = "ce-work-{YYYYMMDDTHHmmss，如20260410T143022}"
   TeamCreate(TEAM_NAME)

3. 读取 .team-contract.md（如存在，来自 ce:plan [T] 生成的合约）
   版本检测：合约加载后，运行：
     git log -1 --format='%H' -- 
   将结果与合约中的 plan_source_commit 对比：
   - plan_source_commit 为 null：提示"计划版本未记录"，跳过版本检测，继续
   **版本检测说明**：`plan_source_commit` 在典型工作流（ce:plan 生成后立即执行 ce:work）中始终为 null，版本检测跳过是预期行为。
   - 一致：正常继续
   - 不一致：警告"⚠️ 计划已更新，建议重新运行 /ce:plan [T] 刷新合约"，询问用户是否继续

4. Spawn verifier teammate（只读角色，独立 context window）：
   Agent(
     team=TEAM_NAME,
     name="verifier",
     prompt="""
       你是验证者 teammate（只读角色，不修改任何文件）。
       启动后读取 .team-contract.md，了解 required_invariants。
       等待 lead 通过 SendMessage 激活。每次收到消息时执行一次验证，完成后回复结果，然后等待下一次激活。

       消息格式（Lead → 你）：
         「Unit {unit_id} 已完成。变更文件：[file1, file2, ...]。请验证。」
         「所有 Unit 完成。请运行全量集成验证。」

       收到后执行：
       1. 读取 .team-contract.md 中的 required_invariants（只读）
       2. 读取变更文件内容（只读）
       3. 运行 required_invariants 中的所有验证命令
       4. 通过 SendMessage 回复 lead：
          - 通过：「Unit {unit_id}: PASS. 所有 invariants 验证通过。」
          - 失败：「Unit {unit_id}: FAIL. 原因：{reason}. 命令输出：{output}」

       铁律：
       - 严禁修改任何文件（包括 .team-contract.md）
       - 严禁执行写操作（git commit、文件写入等）
       - 收到「所有 Unit 完成」后，运行全量验证，这是最后一次检查
     """
   )

5. [T+] 额外 spawn risk-guard teammate（只读角色）：
   Agent(
     team=TEAM_NAME,
     name="risk-guard",
     prompt="""
       你是风险卫 teammate（只读角色，不修改任何文件）。
       等待 lead 发来 Unit 开始通知。每次收到通知时执行一次风险检测，完成后回复结果，然后等待下一次通知。

       消息格式（Lead → 你）：
         「Unit {unit_id} 开始。描述：{desc}。文件：[file1, ...]」

       收到后执行：
       检测以下高风险关键词（在描述和文件名中）：
         auth / session / permission / payment / billing / migration / schema / seed

       回复格式：
       - 无风险：「Unit {unit_id}: 风险卫通过。」
       - 有风险：「⚠️ Unit {unit_id}: 风险拦截。涉及高风险路径 [{keywords}]。需用户确认后继续。」

       铁律：严禁修改任何文件
     """
   )

6. 宣告团队就绪：
   「🤝 Agent Team 已就绪：{TEAM_NAME}
    - lead（主 agent）：执行实现，持有合约权威
    - verifier：独立 context window，接收单元完成通知，运行不变式验证（只读）
    [T+]: - risk-guard：独立 context window，拦截高风险路径（只读）」
```

#### Phase 2: 每个 Implementation Unit 的执行流程

```
[T+] 模式 - Unit 开始前：
  1. SendMessage("risk-guard", "Unit {unit_id} 开始。描述：{desc}。文件：[files]")
  2. 等待 risk-guard 回复（最多 30 秒）：
     - 通过 → 继续执行该 Unit
     - 风险拦截 → 使用 AskUserQuestion 要求用户确认，用户确认后继续，拒绝后跳过该 Unit

执行前文件边界检查（主 agent 自检）：
  - 核对 Unit 的 Files 列表是否都在 allowed_files 内
  - 如有越界：暂停，上报，等待用户确认

Unit 执行完成后：
  1. SendMessage("verifier", "Unit {unit_id} 已完成。变更文件：[files]。请验证。")
  2. 等待 verifier 回复（最多 60 秒）：
     - PASS → 继续下一 Unit
     - FAIL → 读取失败详情 → 修复 → 重发：
       「Unit {unit_id} 已修复：{修复说明}。变更文件：[files]。请重新验证。」
     - 超时（60s 无回复）：
       「⚠️ Verifier 未响应，切换主 agent 同步验证模式」
       主 agent 直接运行 required_invariants，继续流程

并行 subagent 的文件边界约束（当 ce:work 派发多个并行 subagent 时）：
  - 合约主在派发前检查各 Unit 的 Files 列表是否互不重叠
  - 如有交集：将涉及共享文件的任务改为串行
  - 所有并行 subagent 完成后，verifier 额外运行一次全量集成验证

全部 Unit 完成后（全量集成验证）：
  SendMessage("verifier", "所有 Unit 完成。请运行全量集成验证（所有 required_invariants）。")
  等待最终 PASS
```

#### Phase 4: 收尾

```
TeamDelete(TEAM_NAME)
清理 .context/compound-engineering/ 中 team 相关状态文件（如有）
```

#### 消息协议（固定格式）

```
Lead → Verifier：
  「Unit {unit_id} 已完成。变更文件：[file1, file2, ...]。请验证。」
  「Unit {unit_id} 已修复：{修复说明}。变更文件：[files]。请重新验证。」
  「所有 Unit 完成。请运行全量集成验证。」

Verifier → Lead：
  「Unit {unit_id}: PASS. {可选说明}」
  「Unit {unit_id}: FAIL. 原因：{reason}. 命令输出：{output}」

Lead → Risk-Guard：
  「Unit {unit_id} 开始。描述：{desc}。文件：[file1, ...]」

Risk-Guard → Lead：
  「Unit {unit_id}: 风险卫通过。」
  「⚠️ Unit {unit_id}: 风险拦截。涉及高风险路径 [{keywords}]。需用户确认。」
```

#### 降级策略

```
若 TeamCreate 调用失败或平台不支持 Agent Teams：
  - 宣告：「⚠️ Agent Teams 不可用，降级为角色模拟模式（主 agent 顺序切换角色）」
  - 验证者逻辑：每 Unit 完成后，主 agent 直接运行 required_invariants
  - 其余流程不变（合约边界、风险卫关键词检测仍生效）

若 verifier teammate 意外停止（TeammateIdle hook 触发）：
  - 宣告：「⚠️ Verifier teammate 已停止，切换主 agent 验证模式」
  - 主 agent 直接运行 required_invariants 完成剩余验证
```

**[T]+[T] 的 Phase 3.5 Layer 3 全局确认**（补充单任务局部验证）：
- Layer 3 只核查跨任务维度的验收场景（不重复 team 验证者 Hook 已覆盖的单任务条目）
- 若发现跨任务组合破坏了不变式：进入标准 BLOCKED 检查点（见下方），不触发新一轮 team 验证者 Hook
- 并行 subagent 场景下，Layer 3 全局确认在所有 subagent 完成后额外运行一次全局不变式检查

#### BLOCKED 检查点（仅当 [T] 同时激活时）

当 Phase 3.5 验证失败达到 2 轮上限，ce:work 使用标准 AskUserQuestion 工具（team 模式下的提示文字包含团队上下文）：

> "⚠️ [T]+[T] 验证未通过（已重试 N 轮）
> 团队模式失败层：[层名] — [失败原因摘要]
> Layer 0 层内重试：[N] 次
>
> 1. 查看详细错误，执行者手动修复后重新运行验证（重置轮次）
> 2. 跳过验证，降级为标准模式继续 Phase 4（PR 描述标注验证未通过）
> 3. 停止，稍后处理"

选择说明：
- 选 1 → 执行者读取 `.context/compound-engineering/ce-work-verification.json` 的 layer 失败信息，修复后重置 verification_rounds，重跑 Phase 3.5
- 选 2 → 继续 Phase 4，在 PR/commit 描述中标注「⚠️ [T] 验证未通过，人工跳过」
- 选 3 → 结束，保留 `.context/compound-engineering/ce-work-verification.json` 供后续参考

### ce:review [T]（autofix 和 interactive 模式有效，report-only/headless 无效）

> **实现层次**：规则引擎，无需 Agent Teams（有意设计）。
> Patch Gate 是 deterministic whitelist check：对每条 finding 检查 allowed_files/forbidden_surfaces/max_files_per_patch/required_invariants，无需 agent 间通信，零额外 token。

在 Stage 5 路由规范化后执行 Deterministic Patch Gate（规则引擎，不消耗额外 token）。

完整 Patch Gate 逻辑见 `ce:review Stage 5 步骤 6.5`。规则摘要：

```
加载 .team-contract.md → 对每条 safe_auto finding：
  规则1（文件范围）：finding.file ∉ allowed_files → gated_auto
  规则2（禁止区域）：finding.file ∈ forbidden_surfaces → gated_auto（需人工确认）
  规则3（单补丁约束）：涉及文件数 > max_files_per_patch → gated_auto
  规则4（不变式验证）：required_invariants 非空 → fixer 需验证后落盘
```

---

## 降级行为（无 .team-contract.md 时）

所有命令在未找到 `.team-contract.md` 时必须优雅降级：

| 情况 | 行为 | 设计原因 |
|------|------|---------|
| ce:work [T] 无合约 | 提示建议先运行 `/ce:plan [T]`；询问是否继续无合约模式（仅宣告角色，不检查边界） | ce:work 会实际修改代码，无合约执行风险较高，需用户知情后确认 |
| ce:review [T] 无合约 | 跳过 Patch Gate，记录警告："未找到 .team-contract.md，Patch Gate 已禁用" | Patch Gate 是审查加强层，跳过不影响代码修改安全性；中断审查流程对用户影响更大 |
| ce:plan [T] | 合约不适用于 plan 前阶段，正常执行合约生成 | — |

---

## 与现有 overlays 的关系

| 现有 Overlay | 与 team-mode 的关系 |
|-------------|-------------------|
| `review-contract` | [T] 模式下，review-contract 的 Tier 分类被 Patch Gate 消费（Blocking Tier → 强制 gated_auto） |
| `patch-approval` | patch-approval 使用隔离 git clone 生成 patch；team-mode 的 Patch Gate 在此之前执行白名单检查 |
| `ce-work-integration` | task-bundle 状态追踪与 team-mode 互补：bundle 追踪任务状态，team-mode 追踪边界合约 |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Jerrylalala](https://github.com/Jerrylalala)
- **Source:** [Jerrylalala/compound-engineering](https://github.com/Jerrylalala/compound-engineering)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jerrylalala-compound-engineering-team-mode
- Seller: https://agentstack.voostack.com/s/jerrylalala
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.