From ffe3b427ce660a5372782996abdf5fb488a33f37 Mon Sep 17 00:00:00 2001
From: catlog22 <catlog22@github.com>
Date: Sun, 1 Mar 2026 21:01:26 +0800
Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=B7=BB=E5=8A=A0=E6=8A=80?=
 =?UTF-8?q?=E8=83=BD/=E5=9B=A2=E9=98=9F=E5=91=BD=E4=BB=A4=E5=AF=B9?=
 =?UTF-8?q?=E6=AF=94=E8=A1=A8=E5=92=8C=E4=BB=A3=E7=A0=81=E5=AE=A1=E6=9F=A5?=
 =?UTF-8?q?=E6=8A=A5=E5=91=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ccw/src/tools/read-many-files.ts             |  25 +-
 docs/.review/skill-team-comparison-review.md | 161 ++++++++++
 docs/skill-team-comparison.md                | 312 +++++++++++++++++++
 3 files changed, 497 insertions(+), 1 deletion(-)
 create mode 100644 docs/.review/skill-team-comparison-review.md
 create mode 100644 docs/skill-team-comparison.md

diff --git a/ccw/src/tools/read-many-files.ts b/ccw/src/tools/read-many-files.ts
index d9ea1736..18112b6f 100644
--- a/ccw/src/tools/read-many-files.ts
+++ b/ccw/src/tools/read-many-files.ts
@@ -96,7 +96,30 @@ export async function handler(params: Record<string, unknown>): Promise<ToolResu
   const cwd = getProjectRoot();
 
   // Normalize paths to array
-  const inputPaths = Array.isArray(paths) ? paths : [paths];
+  // Handle case where paths might be passed as JSON-encoded string (MCP client bug)
+  let inputPaths: string[];
+  if (Array.isArray(paths)) {
+    inputPaths = paths;
+  } else if (typeof paths === 'string') {
+    // Check if it's a JSON-encoded array
+    const trimmed = paths.trim();
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) {
+          inputPaths = parsed;
+        } else {
+          inputPaths = [paths];
+        }
+      } catch {
+        inputPaths = [paths];
+      }
+    } else {
+      inputPaths = [paths];
+    }
+  } else {
+    inputPaths = [String(paths)];
+  }
 
   // Collect all files to read
   const allFiles: string[] = [];
diff --git a/docs/.review/skill-team-comparison-review.md b/docs/.review/skill-team-comparison-review.md
new file mode 100644
index 00000000..622cfbed
--- /dev/null
+++ b/docs/.review/skill-team-comparison-review.md
@@ -0,0 +1,161 @@
+# Code Review Report
+
+**Target**: D:\Claude_dms3\docs\skill-team-comparison.md
+**Date**: 2026-03-01
+**Dimensions**: Correctness, Readability (Maintainability)
+
+---
+
+## Summary
+
+| Dimension | Critical | High | Medium | Low | Info |
+|-----------|----------|------|--------|-----|------|
+| **Correctness** | 0 | 1 | 2 | 1 | 0 |
+| **Readability** | 0 | 0 | 1 | 2 | 1 |
+
+**Quality Gate**: ⚠️ WARN (1 High issue found)
+
+---
+
+## Findings
+
+### Correctness Issues
+
+#### CORR-001 [High] team-issue 角色任务前缀描述不准确
+
+**Location**: 行 71, 288
+
+**Issue**: 文档中 team-issue 的角色描述为 `explorer, planner, reviewer, integrator, implementer`，但未说明对应的任务前缀 (EXPLORE-*, SOLVE-*, AUDIT-*, MARSHAL-*, BUILD-*)。
+
+**Current**:
+```
+| **team-issue** | explorer, planner, reviewer, integrator, implementer | general-purpose agents | Issue处理流程 | 探索→规划→审查→集成→实现 |
+```
+
+**Expected**: 添加任务前缀说明以提高准确性
+
+**Fix**:
+```markdown
+| **team-issue** | explorer (EXPLORE-*), planner (SOLVE-*), reviewer (AUDIT-*), integrator (MARSHAL-*), implementer (BUILD-*) | general-purpose agents | Issue处理流程 | 探索→规划→审查→集成→实现 |
+```
+
+---
+
+#### CORR-002 [Medium] team-executor-v2 前置条件描述不完整
+
+**Location**: 行 70, 84
+
+**Issue**: 文档说 team-executor-v2 需要"现有team-coordinate会话"，但实际它可以恢复任何 team-* 会话。
+
+**Current**:
+```
+| **team-executor-v2** | (动态角色) | team-worker agents | 恢复执行 | 纯执行，无分析，需现有会话 |
+```
+
+**Expected**: 更准确的描述
+
+**Fix**:
+```markdown
+| **team-executor-v2** | (继承会话角色) | team-worker agents | 恢复执行 | 纯执行，无分析，需现有team会话 |
+```
+
+---
+
+#### CORR-003 [Medium] 遗漏 workflow-wave-plan 命令
+
+**Location**: 规划类命令对比表
+
+**Issue**: 系统中存在 `workflow-wave-plan` 命令，但未在对比表中列出。
+
+**Recommendation**: 在规划类命令中添加此命令
+
+---
+
+#### CORR-004 [Low] team-planex 角色描述
+
+**Location**: 行 34, 294
+
+**Issue**: team-planex 角色描述为 `planner, executor`，但实际实现可能有更多细节。
+
+**Recommendation**: 验证并补充详细角色信息
+
+---
+
+### Readability Issues
+
+#### READ-001 [Medium] 决策流程图格式
+
+**Location**: 行 226-249
+
+**Issue**: ASCII 决策流程图在某些 Markdown 渲染器中可能显示不正确。
+
+**Recommendation**: 考虑使用 Mermaid 图表或添加渲染说明
+
+---
+
+#### READ-002 [Low] 表格宽度
+
+**Location**: 多处表格
+
+**Issue**: 部分表格列内容较长，在窄屏设备上可能需要水平滚动。
+
+**Recommendation**: 可接受，但可考虑在未来版本中优化
+
+---
+
+#### READ-003 [Low] 命令调用方式一致性
+
+**Location**: 命令速查表部分
+
+**Issue**: 部分命令同时列出了 `Skill()` 和 `/command` 两种调用方式，部分只有一种。
+
+**Recommendation**: 保持一致的格式
+
+---
+
+#### READ-004 [Info] 文档版本管理建议
+
+**Location**: 文档末尾
+
+**Suggestion**: 建议添加文档变更历史或链接到 CHANGELOG
+
+---
+
+## Recommended Actions
+
+### Must Fix (Before Final)
+
+1. **CORR-001**: 修复 team-issue 角色前缀描述
+
+### Should Fix (Next Iteration)
+
+2. **CORR-002**: 更新 team-executor-v2 描述
+3. **CORR-003**: 添加遗漏的命令
+
+### Nice to Have
+
+4. **READ-001**: 考虑图表格式优化
+5. **READ-004**: 添加版本管理
+
+---
+
+## Fixed Issues
+
+以下问题已在审查后立即修复：
+
+### FIX-001: team-issue 角色前缀
+
+**Before**:
+```
+| **team-issue** | explorer, planner, reviewer, integrator, implementer |
+```
+
+**After**:
+```
+| **team-issue** | explorer (EXPLORE), planner (SOLVE), reviewer (AUDIT), integrator (MARSHAL), implementer (BUILD) |
+```
+
+---
+
+*Review completed: 2026-03-01*
+*Reviewer: Claude Code (team-coordinate-v2)*
diff --git a/docs/skill-team-comparison.md b/docs/skill-team-comparison.md
new file mode 100644
index 00000000..e4338e0e
--- /dev/null
+++ b/docs/skill-team-comparison.md
@@ -0,0 +1,312 @@
+# Skill/Team 命令对比表
+
+本文档对比 d:\Claude_dms3 项目中的规划类和执行类 skill/team 命令，帮助选择合适的工具。
+
+---
+
+## 目录
+
+1. [规划类命令对比](#规划类命令对比)
+2. [执行类命令对比](#执行类命令对比)
+3. [Team Skill 架构对比](#team-skill-架构对比)
+4. [Claude vs Codex 执行方式](#claude-vs-codex-执行方式)
+5. [使用场景选择指南](#使用场景选择指南)
+
+---
+
+## 规划类命令对比
+
+### 单体规划 Skill
+
+| 命令 | 类型 | 输出 | 适用场景 | 特点 |
+|------|------|------|----------|------|
+| **workflow-plan** | 4阶段规划 | IMPL_PLAN.md, task JSONs, TODO_LIST.md | 标准功能开发 | 完整规划流程，支持冲突检测，可选验证 |
+| **workflow-lite-plan** | 轻量规划 | task JSONs | 快速任务 | 精简流程，直接执行，无验证阶段 |
+| **workflow-tdd-plan** | TDD规划 | IMPL_PLAN.md (含Red-Green-Refactor) | 测试驱动开发 | 强制TDD结构，测试先行 |
+| **brainstorm** | 头脑风暴 | guidance-specification.md, role分析, feature-specs | 需求探索 | 多角色分析，角色扮演，创意生成 |
+| **issue:plan** | Issue规划 | solution JSON per issue | Issue驱动开发 | 批量规划，自动绑定，冲突检测 |
+| **workflow-wave-plan** | CSV Wave规划 | task JSONs | 批量文件处理 | CSV分批，冲突解决，并行执行 |
+
+### Team 规划 Skill
+
+| 命令 | 角色 | 输出 | 适用场景 | 特点 |
+|------|------|------|----------|------|
+| **team-brainstorm** | ideator, challenger, synthesizer, evaluator | ideas/, critiques/, synthesis/, evaluation/ | 深度头脑风暴 | Generator-Critic循环，多角度分析 |
+| **team-planex** | planner, executor | solutions/ | Issue批量执行 | 规划+执行一体化，逐Issue节拍 |
+| **team-lifecycle-v5** (Spec阶段) | analyst, writer, reviewer | spec/, product-brief.md, requirements/, architecture/, epics/ | 全生命周期规格 | 完整规格文档，质量门控 |
+
+### 规划类详细对比
+
+```
+┌─────────────────┬───────────────────┬───────────────────┬───────────────────┐
+│                 │ workflow-plan     │ workflow-lite-plan│ issue:plan        │
+├─────────────────┼───────────────────┼───────────────────┼───────────────────┤
+│ 复杂度          │ 高 (4-6阶段)      │ 低 (1-2阶段)      │ 中 (3阶段)        │
+│ 验证阶段        │ ✓ (Phase 5)       │ ✗                 │ ✗                 │
+│ 冲突检测        │ ✓ (Phase 3)       │ ✗                 │ ✓                 │
+│ 上下文收集      │ ✓ (完整)          │ ✓ (轻量)          │ ✓ (ACE搜索)       │
+│ 任务依赖        │ ✓ (DAG)           │ 简单              │ ✓                 │
+│ 自动模式        │ -y/--yes          │ -y/--yes          │ -y/--yes          │
+│ 输出格式        │ IMPL_PLAN.md + JSON│ JSON only         │ solution JSON     │
+│ 适用规模        │ 中大型功能        │ 小任务/修复       │ Issue批量         │
+└─────────────────┴───────────────────┴───────────────────┴───────────────────┘
+```
+
+---
+
+## 执行类命令对比
+
+### 单体执行 Skill
+
+| 命令 | 类型 | 执行方式 | 适用场景 | 特点 |
+|------|------|----------|----------|------|
+| **workflow-execute** | 任务执行器 | code-developer agent | 规划后执行 | 会话发现，并行任务，进度跟踪 |
+| **workflow-lite-plan** (执行模式) | 轻量执行 | code-developer / CLI | 快速实现 | 内置执行，无会话 |
+| **review-code** | 代码审查 | read-only | 质量检查 | 多维度审查，自动修复建议 |
+
+### Team 执行 Skill
+
+| 命令 | 角色 | 执行方式 | 适用场景 | 特点 |
+|------|------|----------|----------|------|
+| **team-executor-v2** | (继承会话角色) | team-worker agents | 恢复执行 | 纯执行，无分析，需现有team会话 |
+| **team-issue** | explorer (EXPLORE), planner (SOLVE), reviewer (AUDIT), integrator (MARSHAL), implementer (BUILD) | general-purpose agents | Issue处理流程 | 探索→规划→审查→集成→实现 |
+| **team-testing** | strategist, generator, executor, analyst | general-purpose agents | 测试生成 | L1-L3分层，Generator-Critic循环 |
+| **team-lifecycle-v5** (Impl阶段) | planner, executor, tester, reviewer | team-worker agents | 全生命周期实现 | 规格→实现→测试→审查 |
+| **team-frontend** | analyst, architect, developer, qa | general-purpose agents | 前端开发 | ui-ux-pro-max集成，设计系统 |
+| **team-review** | scanner, reviewer, fixer | Skill invocation | 代码审查 | 扫描→审查→修复 |
+| **team-coordinate-v2** | (动态生成) | team-worker agents | 通用协调 | 动态角色生成，按需创建 |
+
+### 执行类详细对比
+
+```
+┌─────────────────┬───────────────────┬───────────────────┬───────────────────┐
+│                 │ workflow-execute  │ team-executor-v2  │ team-issue        │
+├─────────────────┼───────────────────┼───────────────────┼───────────────────┤
+│ 前置条件        │ 现有规划会话      │ 现有team会话       │ Issue ID          │
+│ 角色模型        │ 单一agent         │ 动态role-specs    │ 5固定角色         │
+│ 并行执行        │ ✓ (批量)          │ ✓                 │ ✓ (Batch模式)     │
+│ 消息总线        │ ✗                 │ ✓ (team_msg)      │ ✓ (team_msg)      │
+│ 进度跟踪        │ TodoWrite         │ TaskList + msg    │ TaskList + msg    │
+│ 会话恢复        │ --resume-session  │ 需session路径     │ check/resume      │
+│ 自动提交        │ --with-commit     │ ✗                 │ ✗                 │
+│ CLI集成         │ ✓                 │ ✗                 │ ✗                 │
+└─────────────────┴───────────────────┴───────────────────┴───────────────────┘
+```
+
+---
+
+## Team Skill 架构对比
+
+### 架构模式
+
+| 模式 | 使用命令 | 特点 |
+|------|----------|------|
+| **静态角色** | team-issue, team-testing, team-brainstorm, team-frontend, team-review | 预定义角色，role.md文件 |
+| **动态角色** | team-coordinate-v2, team-lifecycle-v5 | 运行时生成role-specs |
+| **混合模式** | team-planex, team-executor-v2 | 静态coordinator + 动态workers |
+
+### 通信模式
+
+| 模式 | 使用命令 | 特点 |
+|------|----------|------|
+| **SendMessage** | 所有team-* skills | 点对点通信 |
+| **team_msg MCP** | team-issue, team-testing, team-brainstorm, team-frontend | 消息总线日志 |
+| **shared-memory.json** | team-testing, team-brainstorm, team-frontend | 跨角色状态共享 |
+| **wisdom/** | team-lifecycle-v5, team-coordinate-v2 | 跨任务知识积累 |
+
+### Pipeline 模式
+
+| 模式 | 使用命令 | 流程 |
+|------|----------|------|
+| **线性** | team-review, team-issue (Quick) | A → B → C → D |
+| **Generator-Critic** | team-testing, team-brainstorm, team-frontend | Generator ↔ Critic (max N rounds) |
+| **Checkpoint** | team-lifecycle-v5, team-issue (Full) | Phase → Gate → Continue |
+| **Fan-out** | team-issue (Batch), team-brainstorm (Full) | [A, B, C] → D → E |
+
+---
+
+## Claude vs Codex 执行方式
+
+### 执行后端对比
+
+| 后端 | 工具 | 适用场景 | 特点 |
+|------|------|----------|------|
+| **Claude Agent** | code-developer, test-fix-agent | 同步执行，简单任务 | 内置agent，直接执行 |
+| **Codex CLI** | `ccw cli --tool codex --mode write` | 复杂任务，后台执行 | 异步执行，更强能力 |
+| **Gemini CLI** | `ccw cli --tool gemini --mode analysis` | 分析类任务 | 只读分析，语义搜索 |
+
+### 选择决策表
+
+| 条件 | 推荐后端 |
+|------|----------|
+| 任务数 ≤ 3 且简单 | Claude Agent |
+| 任务数 > 3 或复杂 | Codex CLI |
+| 只读分析 | Gemini CLI |
+| 需要后台执行 | Codex/Gemini CLI |
+| 需要即时反馈 | Claude Agent |
+
+### team-planex 执行方法选择
+
+```javascript
+// team-planex 支持三种执行后端
+--exec=agent   // code-developer subagent (默认)
+--exec=codex   // ccw cli --tool codex --mode write
+--exec=gemini  // ccw cli --tool gemini --mode write
+
+// 自动选择逻辑
+if (task_count <= 3) → Agent
+if (task_count > 3)  → Codex
+```
+
+### CLI 工具配置
+
+```json
+// ~/.claude/cli-tools.json
+{
+  "tools": {
+    "gemini": {
+      "enabled": true,
+      "primaryModel": "gemini-2.5-flash",
+      "tags": ["分析", "Debug"],
+      "type": "builtin"
+    },
+    "codex": {
+      "enabled": true,
+      "primaryModel": "gpt-5.2",
+      "type": "builtin"
+    }
+  }
+}
+```
+
+---
+
+## 使用场景选择指南
+
+### 按任务类型选择
+
+| 任务类型 | 推荐命令 | 备选命令 |
+|----------|----------|----------|
+| **新功能开发** | workflow-plan → workflow-execute | team-lifecycle-v5 |
+| **快速修复** | workflow-lite-plan | issue:plan → issue:execute |
+| **TDD开发** | workflow-tdd-plan → workflow-execute | - |
+| **需求探索** | brainstorm | team-brainstorm |
+| **Issue处理** | issue:plan → issue:queue → issue:execute | team-issue |
+| **测试生成** | team-testing | workflow-test-fix |
+| **前端开发** | team-frontend | - |
+| **代码审查** | team-review | review-code |
+| **恢复中断** | team-executor-v2 | workflow-execute --resume-session |
+
+### 按团队规模选择
+
+| 规模 | 推荐命令 | 原因 |
+|------|----------|------|
+| **单人快速** | workflow-lite-plan | 轻量，直接执行 |
+| **单人完整** | workflow-plan → workflow-execute | 完整流程，有验证 |
+| **多人协作** | team-coordinate-v2 | 动态角色，灵活分工 |
+| **专项团队** | team-* (按领域) | 领域专家角色 |
+
+### 按复杂度选择
+
+```
+复杂度低 (1-2任务)
+└─ workflow-lite-plan (推荐)
+└─ issue:plan (Issue驱动)
+
+复杂度中 (3-10任务)
+└─ workflow-plan → workflow-execute (推荐)
+└─ team-planex (Issue批量)
+
+复杂度高 (10+任务)
+└─ team-lifecycle-v5 (推荐)
+└─ team-coordinate-v2 (动态角色)
+```
+
+### 决策流程图
+
+```
+                    ┌─────────────────┐
+                    │   任务类型?     │
+                    └────────┬────────┘
+                             │
+         ┌───────────────────┼───────────────────┐
+         ↓                   ↓                   ↓
+    ┌─────────┐        ┌─────────┐        ┌─────────┐
+    │ 新功能  │        │ Issue   │        │ 探索/分析│
+    └────┬────┘        └────┬────┘        └────┬────┘
+         │                  │                  │
+         ↓                  ↓                  ↓
+    ┌─────────┐        ┌─────────┐        ┌─────────┐
+    │TDD需求? │        │批量?    │        │多角度?  │
+    └────┬────┘        └────┬────┘        └────┬────┘
+         │                  │                  │
+    ┌────┴────┐        ┌────┴────┐        ┌────┴────┐
+    ↓         ↓        ↓         ↓        ↓         ↓
+  是        否       是        否       是        否
+    │         │        │         │        │         │
+    ↓         ↓        ↓         ↓        ↓         ↓
+workflow-  workflow- team-    issue:   team-    brainstorm
+tdd-plan   plan      issue    plan     brainstorm
+```
+
+---
+
+## 命令速查表
+
+### 规划类
+
+| 命令 | 调用方式 |
+|------|----------|
+| workflow-plan | `Skill(skill="workflow-plan", args="任务描述")` |
+| workflow-lite-plan | `Skill(skill="workflow-lite-plan", args="任务描述")` |
+| workflow-tdd-plan | `Skill(skill="workflow-tdd-plan", args="TDD任务描述")` |
+| brainstorm | `Skill(skill="brainstorm", args="主题 --count 3")` |
+| issue:plan | `/issue:plan GH-123,GH-124` |
+
+### 执行类
+
+| 命令 | 调用方式 |
+|------|----------|
+| workflow-execute | `Skill(skill="workflow-execute")` 或 `/workflow-execute` |
+| team-executor-v2 | `Skill(skill="team-executor-v2", args="--session=.workflow/.team/TC-xxx")` |
+| team-issue | `Skill(skill="team-issue", args="GH-123")` |
+| team-testing | `Skill(skill="team-testing", args="测试任务描述")` |
+| team-lifecycle-v5 | `Skill(skill="team-lifecycle-v5", args="任务描述")` |
+| team-frontend | `Skill(skill="team-frontend", args="前端任务描述")` |
+| team-review | `Skill(skill="team-review", args="src/**/*.ts")` |
+
+---
+
+## 附录：命令分类汇总
+
+### Team Skills (19个)
+
+| 分类 | 命令 | 角色 |
+|------|------|------|
+| **通用协调** | team-coordinate, team-coordinate-v2 | coordinator + 动态角色 |
+| **执行器** | team-executor, team-executor-v2 | executor |
+| **全生命周期** | team-lifecycle-v3/v4/v5 | analyst, writer, planner, executor, tester, reviewer |
+| **Issue处理** | team-issue | explorer (EXPLORE), planner (SOLVE), reviewer (AUDIT), integrator (MARSHAL), implementer (BUILD) |
+| **测试** | team-testing | strategist, generator, executor, analyst |
+| **头脑风暴** | team-brainstorm | ideator, challenger, synthesizer, evaluator |
+| **前端** | team-frontend | analyst, architect, developer, qa |
+| **审查** | team-review | scanner, reviewer, fixer |
+| **专项** | team-quality-assurance, team-roadmap-dev, team-tech-debt, team-iterdev, team-uidesign, team-ultra-analyze | 特定领域角色 |
+| **规划执行** | team-planex | planner, executor |
+
+### Workflow Skills (7个)
+
+| 分类 | 命令 | 阶段数 |
+|------|------|--------|
+| **规划** | workflow-plan | 6阶段 |
+| **执行** | workflow-execute | 6阶段 |
+| **轻量** | workflow-lite-plan | 2阶段 |
+| **TDD** | workflow-tdd-plan | 7阶段 |
+| **测试修复** | workflow-test-fix | 4阶段 |
+| **多CLI** | workflow-multi-cli-plan | - |
+| **技能设计** | workflow-skill-designer | 4阶段 |
+
+---
+
+*文档生成日期: 2026-03-01*
+*版本: 1.0.0*