Claude-Code-Workflow/.claude/skills/team-planex/SKILL.md

---
name: team-planex
description: Unified team skill for plan-and-execute pipeline. 2-member team (planner + executor) with wave pipeline for concurrent planning and execution. All roles invoke this skill with --role arg. Triggers on "team planex".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---

# Team PlanEx

2 成员边规划边执行团队。通过逐 Issue 节拍流水线实现 planner 和 executor 并行工作：planner 每完成一个 issue 的 solution 后立即创建 EXEC-* 任务（含中间产物文件路径），executor 从文件加载 solution 开始实现。所有成员通过 `--role=xxx` 路由。

## Architecture Overview

```
┌──────────────────────────────────────────────┐
│  Skill(skill="team-planex", args="--role=xxx") │
└────────────────┬─────────────────────────────┘
                 │ Role Router
         ┌───────┴───────┐
         ↓               ↓
    ┌─────────┐    ┌──────────┐
    │ planner │    │ executor │
    │ PLAN-*  │    │ EXEC-*   │
    └─────────┘    └──────────┘
```

**设计原则**: 只有 2 个角色，没有独立 coordinator。SKILL.md 入口承担轻量编排（创建团队、派发初始任务链），然后 planner 担任 lead 角色持续推进。

## Role Router

### Input Parsing

Parse `$ARGUMENTS` to extract `--role`. If absent -> Orchestration Mode (SKILL.md as lightweight coordinator).

Optional flags: `--team` (default: "planex"), `--exec` (execution method), `-y`/`--yes` (auto mode).

### Role Registry

| Role | File | Task Prefix | Type | Compact |
|------|------|-------------|------|---------|
| planner | [roles/planner.md](roles/planner.md) | PLAN-* | pipeline (lead) | **压缩后必须重读** |
| executor | [roles/executor.md](roles/executor.md) | EXEC-* | pipeline | 压缩后必须重读 |

> **COMPACT PROTECTION**: 角色文件是执行文档，不是参考资料。当 context compression 发生后，角色指令仅剩摘要时，**必须立即 `Read` 对应 role.md 重新加载后再继续执行**。不得基于摘要执行任何 Phase。

### Dispatch

1. Extract `--role` from arguments
2. If no `--role` -> Orchestration Mode (SKILL.md as lightweight coordinator)
3. Look up role in registry -> Read the role file -> Execute its phases
4. Unknown role -> Error with available role list: planner, executor

## Input Types

支持 3 种输入方式（通过 args 传入 planner）：

| 输入类型 | 格式 | 示例 |
|----------|------|------|
| Issue IDs | 直接传入 ID | `--role=planner ISS-20260215-001 ISS-20260215-002` |
| 需求文本 | `--text '...'` | `--role=planner --text '实现用户认证模块'` |
| Plan 文件 | `--plan path` | `--role=planner --plan plan/2026-02-15-auth.md` |

## Shared Infrastructure

### Role Isolation Rules

#### Output Tagging（强制）

所有角色的输出（SendMessage、team_msg）必须带 `[role_name]` 标识前缀。

#### Planner 边界

| 允许 | 禁止 |
|------|------|
| 需求拆解 (issue 创建) | 直接编写/修改代码 |
| 方案设计 (issue-plan-agent) | 调用 code-developer |
| 冲突检查 (inline files_touched) | 运行测试 |
| 创建 EXEC-* 任务 | git commit |
| 监控进度 (消息总线) | |

#### Executor 边界

| 允许 | 禁止 |
|------|------|
| 处理 EXEC-* 前缀的任务 | 创建 issue |
| 调用 code-developer 实现 | 修改 solution/queue |
| 运行测试验证 | 为 planner 创建 PLAN-* 任务 |
| git commit 提交 | 直接与用户交互 (AskUserQuestion) |
| SendMessage 给 planner | |

### Team Configuration

| Key | Value |
|-----|-------|
| name | planex |
| sessionDir | `.workflow/.team/PEX-{slug}-{date}/` |
| artifactsDir | `.workflow/.team/PEX-{slug}-{date}/artifacts/` |
| issueDataDir | `.workflow/issues/` |

### Message Bus

每次 SendMessage 前，先调用 `mcp__ccw-tools__team_msg` 记录：

- 参数: operation="log", team=`<team-name>`, from=`<role>`, to=`<target-role>`, type=`<type>`, summary="[`<role>`] `<summary>`", ref=`<file_path>`
- **CLI fallback**: 当 MCP 不可用时 -> `ccw team log --team <team> --from <role> --to <target> --type <type> --summary "[<role>] ..." --json`

**Message types by role**:

| Role | Types |
|------|-------|
| planner | `wave_ready`, `issue_ready`, `all_planned`, `error` |
| executor | `impl_complete`, `impl_failed`, `wave_done`, `error` |

### Task Lifecycle (Both Roles)

每个 worker 启动后执行相同的任务发现流程：

1. 调用 `TaskList()` 获取所有任务
2. 筛选: subject 匹配本角色前缀 + owner 是本角色 + status 为 pending + blockedBy 为空
3. 无任务 -> idle 等待
4. 有任务 -> `TaskGet` 获取详情 -> `TaskUpdate` 标记 in_progress
5. Phase 2-4: Role-specific (see roles/{role}.md)
6. Phase 5: Report + Loop

**Resume Artifact Check** (防止恢复后重复产出):
- 检查本任务的输出产物是否已存在
- 产物完整 -> 跳到 Phase 5 报告完成
- 产物不完整或不存在 -> 正常执行 Phase 2-4

---

## Wave Pipeline (逐 Issue 节拍)

```
Issue 1:  planner 规划 solution -> 写中间产物 -> 冲突检查 -> 创建 EXEC-* -> issue_ready
                ↓ (executor 立即开始)
Issue 2:  planner 规划 solution -> 写中间产物 -> 冲突检查 -> 创建 EXEC-* -> issue_ready
                ↓ (executor 并行消费)
Issue N:  ...
Final:    planner 发送 all_planned -> executor 完成剩余 EXEC-* -> 结束
```

**节拍规则**:
- planner 每完成一个 issue 的 solution 后，**立即**创建 EXEC-* 任务并发送 `issue_ready` 信号
- solution 写入中间产物文件（`artifacts/solutions/{issueId}.json`），EXEC-* 任务包含 `solution_file` 路径
- executor 从文件加载 solution（无需再调 `ccw issue solution`），fallback 兼容旧模式
- planner 不等待 executor，持续推进下一个 issue
- 当 planner 发送 `all_planned` 消息后，executor 完成所有剩余任务即可结束

## Execution Method Selection

在编排模式或直接调用 executor 前，**必须先确定执行方式**。支持 3 种执行后端：

| Executor | 后端 | 适用场景 |
|----------|------|----------|
| `agent` | code-developer subagent | 简单任务、同步执行 |
| `codex` | `ccw cli --tool codex --mode write` | 复杂任务、后台执行 |
| `gemini` | `ccw cli --tool gemini --mode write` | 分析类任务、后台执行 |

### Selection Decision Table

| Condition | Execution Method | Code Review |
|-----------|-----------------|-------------|
| `--exec=agent` specified | Agent | Skip |
| `--exec=codex` specified | Codex | Skip |
| `--exec=gemini` specified | Gemini | Skip |
| `-y` or `--yes` flag present | Auto (default Agent) | Skip |
| No flags (interactive) | AskUserQuestion -> user choice | AskUserQuestion -> user choice |
| Auto + task_count <= 3 | Agent | Skip |
| Auto + task_count > 3 | Codex | Skip |

### Interactive Prompt (no flags)

当无 `-y`/`--yes` 且无 `--exec` 时，通过 AskUserQuestion 交互选择：

- **执行方式选项**: Agent / Codex / Gemini / Auto
- **代码审查选项**: Skip / Gemini Review / Codex Review / Agent Review

### 通过 args 指定

```bash
# 显式指定
Skill(skill="team-planex", args="--exec=codex ISS-xxx")
Skill(skill="team-planex", args="--exec=agent --text '简单功能'")

# Auto 模式（跳过交互，-y 或 --yes）
Skill(skill="team-planex", args="-y --text '添加日志'")
```

---

## Orchestration Mode

当不带 `--role` 调用时，SKILL.md 进入轻量编排模式（无独立 coordinator 角色，SKILL.md 自身承担编排）。

**Invocation**: `Skill(skill="team-planex", args="任务描述")`

**Lifecycle**:

```
用户提供任务描述
  -> SKILL.md 解析输入（Issue IDs / 需求文本 / Plan 文件）
  -> 初始化 sessionDir + artifacts 目录
  -> 执行方式选择（见 Execution Method Selection）
  -> 创建 PLAN-001 任务（owner: planner）
  -> Spawn planner agent (后台)
  -> Spawn executor agent (后台)
  -> 返回（planner lead 后续推进）
```

**User Commands** (唤醒 / 检查状态):

| Command | Action |
|---------|--------|
| `check` / `status` | 输出执行状态图，不推进 |
| `resume` / `continue` | 检查 worker 状态，推进下一步 |

### Coordinator Spawn Template

SKILL.md 编排模式 spawn workers 时使用后台模式 (Spawn-and-Go):

**Planner Spawn**:

```
Task({
  subagent_type: "general-purpose",
  description: "Spawn planner worker",
  team_name: <team-name>,
  name: "planner",
  run_in_background: true,
  prompt: `你是 team "<team-name>" 的 PLANNER。

## 首要指令
你的所有工作必须通过调用 Skill 获取角色定义后执行：
Skill(skill="team-planex", args="--role=planner")

当前输入: <planner-input>
Session: <session-dir>

## 执行配置
executor 的执行方式: <execution-method>
创建 EXEC-* 任务时，description 中包含:
  execution_method: <method>
  code_review: <review-tool>

## 中间产物（必须）
每个 issue 的 solution 写入: <session-dir>/artifacts/solutions/{issueId}.json
EXEC-* 任务 description 必须包含 solution_file 字段指向该文件
每完成一个 issue 立即发送 issue_ready 消息并创建 EXEC-* 任务

## 角色准则
- 只处理 PLAN-* 任务，不执行其他角色工作
- 所有输出带 [planner] 标识前缀
- 仅与 coordinator 通信
- 不使用 TaskCreate 为其他角色创建任务（EXEC-* 除外）
- 每次 SendMessage 前先调用 mcp__ccw-tools__team_msg 记录

## 工作流程
1. 调用 Skill -> 获取角色定义和执行逻辑
2. 按 role.md 5-Phase 流程执行
3. team_msg + SendMessage 结果给 coordinator
4. TaskUpdate completed -> 检查下一个任务`
})
```

**Executor Spawn**:

```
Task({
  subagent_type: "general-purpose",
  description: "Spawn executor worker",
  team_name: <team-name>,
  name: "executor",
  run_in_background: true,
  prompt: `你是 team "<team-name>" 的 EXECUTOR。

## 首要指令
你的所有工作必须通过调用 Skill 获取角色定义后执行：
Skill(skill="team-planex", args="--role=executor")

## 执行配置
默认执行方式: <execution-method>
代码审查: <review-tool>
（每个 EXEC-* 任务 description 中可能包含 execution_method 覆盖）

## Solution 加载
优先从 EXEC-* 任务 description 中的 solution_file 路径读取 solution JSON 文件
无 solution_file 时 fallback 到 ccw issue solution 命令

## 角色准则
- 只处理 EXEC-* 任务，不执行其他角色工作
- 所有输出带 [executor] 标识前缀
- 根据 execution_method 选择执行后端（Agent/Codex/Gemini）
- 仅与 coordinator 通信
- 每次 SendMessage 前先调用 mcp__ccw-tools__team_msg 记录

## 工作流程
1. 调用 Skill -> 获取角色定义和执行逻辑
2. 按 role.md 5-Phase 流程执行
3. team_msg + SendMessage 结果给 coordinator
4. TaskUpdate completed -> 检查下一个任务`
})
```

---

## Cadence Control

**节拍模型**: Wave beat -- planner 持续推进，executor 并行消费。每个 wave = planner 完成一个 issue -> executor 开始实现。

```
Wave Beat Cycle (逐 Issue 节拍)
===================================================================
  Event                    SKILL.md (编排)         Workers
-------------------------------------------------------------------
  用户调用 ---------> ┌─ 解析输入 ─────────┐
                      │  初始化 session      │
                      │  选择执行方式         │
                      ├─ 创建 PLAN-001 ─────┤
                      │  spawn planner ──────┼──> [Planner] Phase 1-5
                      │  spawn executor ─────┼──> [Executor] Phase 1 (idle)
                      └─ 返回 (编排结束) ───┘         │
                                                       │
  Wave 1:                                    Planner: issue-1 solution
                                             -> 写产物 -> 创建 EXEC-001
                                             -> issue_ready ---------> Executor 开始 EXEC-001
  Wave 2:                                    Planner: issue-2 solution
                                             -> 写产物 -> 创建 EXEC-002
                                             -> issue_ready ---------> Executor 并行消费
  ...
  Wave N:                                    Planner: all_planned
                                             Executor: 完成剩余 EXEC-*
===================================================================
```

**Pipeline 节拍视图**:

```
Wave pipeline (planner lead, executor follows)
──────────────────────────────────────────────────────────
Wave   1        2        3       ...      N       Final
       │        │        │                │         │
       P:iss-1  P:iss-2  P:iss-3         P:iss-N   P:all_planned
       ↓        ↓        ↓               ↓         ↓
       E:exec1  E:exec2  E:exec3         E:execN   E:finish
                │        │
         (并行消费，executor 不等 planner 全部完成)

P=planner  E=executor
```

**检查点 (Checkpoint)**:

| 触发条件 | 位置 | 行为 |
|----------|------|------|
| Planner 全部完成 | all_planned 信号 | Executor 完成剩余 EXEC-* 后结束 |
| Pipeline 停滞 | 无 ready + 无 running | Planner 检查并 escalate to user |
| Executor 阻塞 | Executor blocked > 2 tasks | Planner escalate to user |

**Stall 检测**:

| 检查项 | 条件 | 处理 |
|--------|------|------|
| Executor 无响应 | in_progress EXEC-* 无回调 | 报告等待中的任务列表 |
| Pipeline 死锁 | 无 ready + 无 running + 有 pending | 检查 blockedBy 依赖链 |
| Planner 规划失败 | issue planning error | Retry once, then skip to next issue |

---

## Task Metadata Registry

| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| PLAN-001 | planner | planning | (none) | 初始规划：需求拆解、issue 创建、方案设计 |
| EXEC-001 | executor | execution | PLAN-001 (implicit via issue_ready) | 第一个 issue 的代码实现 |
| EXEC-002 | executor | execution | (planner issue_ready) | 第二个 issue 的代码实现 |
| EXEC-N | executor | execution | (planner issue_ready) | 第 N 个 issue 的代码实现 |

> 注: EXEC-* 任务由 planner 在运行时逐个创建（逐 Issue 节拍），不预先定义完整任务链。

---

## Wisdom Accumulation (所有角色)

跨任务知识积累。SKILL.md 编排模式在 session 初始化时创建 `wisdom/` 目录。

**目录**:
```
<session-folder>/wisdom/
├── learnings.md      # 模式和洞察
├── decisions.md      # 架构和设计决策
├── conventions.md    # 代码库约定
└── issues.md         # 已知风险和问题
```

**Worker 加载** (Phase 2): 从 task description 提取 `Session: <path>`, 读取 wisdom 目录下各文件。
**Worker 贡献** (Phase 4/5): 将本任务发现写入对应 wisdom 文件。

---

## Session Directory

```
.workflow/.team/PEX-{slug}-{date}/
├── team-session.json           # Session state
├── artifacts/
│   └── solutions/              # Planner solution output per issue
│       ├── {issueId-1}.json
│       └── {issueId-N}.json
├── wisdom/                     # Cross-task knowledge
│   ├── learnings.md
│   ├── decisions.md
│   ├── conventions.md
│   └── issues.md
└── shared-memory.json          # Cross-role state
```

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| Unknown --role value | Error with available role list: planner, executor |
| Missing --role arg | Enter orchestration mode (SKILL.md as lightweight coordinator) |
| Role file not found | Error with expected path (roles/{name}.md) |
| Planner issue planning failure | Retry once, then report error and skip to next issue |
| Executor impl failure | Report to planner, continue with next EXEC-* task |
| No EXEC-* tasks yet | Executor idles, polls for new tasks |
| Pipeline stall | Planner monitors -- if executor blocked > 2 tasks, escalate to user |