ccg-workflow 2.1.15 → 3.0.0

package/templates/engine/strategies/debug-investigate.md

@@ -0,0 +1,156 @@
+# Strategy: Debug Investigate — 深度调试
+
+> 适用于原因不明的复杂 bug，需要多模型并行诊断和交叉验证。
+
+## 适用条件
+- 复杂度 M 或以上
+- 错误原因不明确
+- 需要多角度诊断
+
+## 前置加载
+
+```
+Read("~/.claude/.ccg/engine/model-router.md")
+```
+
+---
+
+## 工作流状态机
+
+[phase-state:1-collect]
+当前阶段：信息收集
+📍 Next: 收集完错误信息后启动双模型诊断
+[/phase-state:1-collect]
+
+[phase-state:2-diagnose]
+当前阶段：双模型并行诊断
+Gate: 错误信息已收集 ✓
+📍 Next: 双模型诊断返回后进入交叉验证
+[/phase-state:2-diagnose]
+
+[phase-state:3-validate]
+当前阶段：交叉验证
+Gate: 双模型诊断已返回 ✓
+📍 Next: 假设排序后请用户确认修复方向
+[/phase-state:3-validate]
+
+[phase-state:4-confirm]
+当前阶段：用户确认（HARD STOP）
+Gate: 假设已排序 ✓
+📍 Next: 用户确认后进入修复
+[/phase-state:4-confirm]
+
+[phase-state:5-fix]
+当前阶段：修复与验证
+Gate: 用户已确认修复方向 ✓
+📍 Next: 修复完成后报告结果
+[/phase-state:5-fix]
+
+---
+
+## 阶段详情
+
+### Phase 1: 信息收集 [required]
+
+**Task 更新**：`currentPhase → "1-collect"`, `nextAction → "收集错误信息"`
+
+1. 收集错误上下文：
+   - 错误消息 / 堆栈跟踪
+   - 复现步骤（如果有）
+   - 最近的相关变更（`git log --oneline -10`）
+   - 环境信息（如相关）
+
+2. 搜索相关代码（Grep/MCP）
+3. 读取可能相关的文件
+
+### Phase 2: 双模型并行诊断 [required]
+
+**Gate check**: 错误信息已收集
+
+**并行调用**（`run_in_background: true`）：
+- **backend 模型**：debugger 角色
+  ```
+  <TASK>
+  需求：诊断以下问题
+  上下文：[错误信息、堆栈、相关代码]
+  </TASK>
+  OUTPUT: 诊断假设（按可能性排序，每个假设含：根因分析、证据、修复建议）
+  ```
+- **frontend 模型**：debugger 角色（相同格式）
+
+等待双模型返回。
+
+**Task 更新**：`currentPhase → "2-diagnose"`, `nextAction → "等待双模型诊断返回"`
+
+### Phase 3: 交叉验证
+
+**Gate check**: 双模型诊断已返回
+
+1. 对比两个模型的诊断结果
+2. 找出共识点（两个模型都指出的问题 → 高可信度）
+3. 找出分歧点（只有一个模型指出 → 需要验证）
+4. 综合排序所有假设：
+
+```
+🔍 诊断结果
+
+### 高可信度假设（双模型共识）
+1. [假设] — [证据]
+   修复方案: [具体方案]
+
+### 待验证假设（单模型提出）
+2. [假设] — [来源模型] — [证据]
+   修复方案: [具体方案]
+
+### 已排除
+- [假设] — [排除理由]
+```
+
+### Phase 4: 用户确认 [required · HARD STOP]
+
+**Gate check**: 假设已排序
+
+展示诊断结果，请用户选择修复方向：
+- 按假设 1 修复
+- 按假设 2 修复
+- 需要更多调查
+- 其他方向
+
+**Task 更新**：
+```
+更新 task.json:
+  currentPhase → "4-confirm"
+  gate → "user_approval_required"
+  nextAction → "等待用户确认修复方向"
+```
+
+**必须等待用户明确确认**，不可自动选择。
+
+用户确认后：`task.json: gate → null, currentPhase → "5-fix"`
+
+### Phase 5: 修复与验证
+
+**Gate check**: 用户已确认
+
+1. 按确认的方向应用修复
+2. 运行测试验证
+3. 如果修复无效 → 回退，尝试下一个假设，或返回 Phase 4 重新确认
+4. 输出结果：
+   ```
+   ✅ 调试完成
+     根因: [确认的根因]
+     修复: [应用的修复]
+     验证: [测试结果]
+     📍 Next: /ccg commit 提交修复
+   ```
+
+**Task 更新**：`status → "completed"`, `nextAction → "可用 /ccg:commit 提交修复"`
+
+---
+
+## 铁律
+
+- **Phase 4 是 HARD STOP** — 不可自动决定修复方向
+- **双模型诊断必须并行** — 独立诊断才有交叉验证价值
+- **修复前必须有诊断** — 不可跳过 Phase 2-3 直接改代码
+- **修复无效时必须回退** — 不可在错误方向上继续深入

package/templates/engine/strategies/deep-research.md

@@ -0,0 +1,141 @@
+# Strategy: Deep Research — 深度研究
+
+> 适用于技术方案研究、对比分析。多模型并行探索，结构化输出。
+
+## 适用条件
+- 用户提出研究/分析/对比类问题
+- 不涉及代码修改（纯研究）
+- 任何复杂度级别
+
+## 前置加载
+
+```
+Read("~/.claude/.ccg/engine/model-router.md")
+```
+
+---
+
+## 工作流状态机
+
+[phase-state:1-clarify]
+当前阶段：明确研究问题
+📍 Next: 问题明确后启动多模型探索
+[/phase-state:1-clarify]
+
+[phase-state:2-explore]
+当前阶段：多模型并行探索
+Gate: 研究问题已明确 ✓
+📍 Next: 双模型结果返回后进入综合
+[/phase-state:2-explore]
+
+[phase-state:3-synthesize]
+当前阶段：综合分析
+Gate: 双模型探索已返回 ✓
+📍 Next: 输出结构化报告后进入讨论
+[/phase-state:3-synthesize]
+
+[phase-state:4-discuss]
+当前阶段：交互式讨论
+📍 Next: 用户满意后结束
+[/phase-state:4-discuss]
+
+---
+
+## 阶段详情
+
+### Phase 1: 明确问题 [required]
+
+1. 解析用户的研究意图：
+   - 要研究什么？
+   - 研究目的是什么？（做决策？了解现状？评估可行性？）
+   - 有什么约束或偏好？
+
+2. 如果问题太宽泛，先收窄：
+   ```
+   📋 研究范围
+     问题: [明确的研究问题]
+     目的: [决策/了解/评估]
+     约束: [时间/技术/资源约束]
+   ```
+
+### Phase 2: 多模型并行探索 [required]
+
+**Task 更新**：`currentPhase → "2-explore"`, `nextAction → "双模型并行探索"`
+
+**并行调用**（`run_in_background: true`）：
+- **backend 模型**：analyzer 角色
+  ```
+  <TASK>
+  需求：研究分析 [问题]
+  上下文：[项目上下文、技术栈、约束]
+  </TASK>
+  OUTPUT: 技术分析报告（可行性、架构选项、风险、成本估算）
+  ```
+- **frontend 模型**：analyzer 角色
+  ```
+  <TASK>
+  需求：研究分析 [问题]
+  上下文：[项目上下文、用户场景、约束]
+  </TASK>
+  OUTPUT: 用户/体验视角分析（UX 影响、用户流程、设计选项）
+  ```
+
+等待双模型返回。
+
+### Phase 3: 综合分析
+
+**Gate check**: 双模型探索已返回
+
+交叉对比双方视角。
+
+**持久化研究成果**（如有任务目录）：
+- 将双模型原始分析写入 `.ccg/tasks/{task-name}/research/backend-analysis.md`
+- 将双模型原始分析写入 `.ccg/tasks/{task-name}/research/frontend-analysis.md`
+
+输出结构化报告：
+
+```
+📋 研究报告: [主题]
+
+## 选项对比
+
+| 维度 | 方案 A | 方案 B | 方案 C |
+|------|--------|--------|--------|
+| 概述 | ... | ... | ... |
+| 优势 | ... | ... | ... |
+| 劣势 | ... | ... | ... |
+| 复杂度 | S/M/L | S/M/L | S/M/L |
+| 风险 | low/mid/high | ... | ... |
+| 预估工期 | ... | ... | ... |
+
+## 推荐
+
+**推荐方案 [X]**
+理由：[简明理由]
+
+## 注意事项
+- [关键风险或注意点]
+```
+
+### Phase 4: 交互式讨论
+
+用户可以：
+- 追问某个方案的细节
+- 要求更深入分析某个方面
+- 要求 POC / 原型验证
+- 确认结论并结束
+
+```
+📍 研究已完成。如需实施推荐方案，可以用 /ccg:go implement [方案描述]
+```
+
+**Task 更新**（如有）：`status → "completed"`, `nextAction → "研究完成，可实施推荐方案"`
+
+---
+
+## 铁律
+
+- **纯研究模式，不做代码修改** — 除非用户明确要求 POC
+- **结果必须结构化输出** — 表格对比，不是自由聊天
+- **必须给出推荐** — 不可只列选项不做判断
+- **双模型探索必须并行** — 独立视角更有价值

package/templates/engine/strategies/direct-fix.md

@@ -0,0 +1,108 @@
+# Strategy: Direct Fix — 直接修复
+
+> 适用于范围清晰、单文件的简单 bug 修复。Claude 独立完成，不调用外部模型。
+
+## 适用条件
+- 复杂度 S（单文件，<30 行变更）
+- 错误信息或复现路径明确
+- 风险 low 或 medium
+
+---
+
+## 工作流状态机
+
+[phase-state:1-locate]
+当前阶段：定位问题代码
+Gate: 项目上下文已获取 ✓（由 /ccg Phase 1 完成）
+📍 Next: 找到问题代码后进入诊断阶段
+[/phase-state:1-locate]
+
+[phase-state:2-diagnose]
+当前阶段：诊断根因
+Gate: 已找到相关代码 ✓
+📍 Next: 确定根因后进入修复阶段
+[/phase-state:2-diagnose]
+
+[phase-state:3-fix]
+当前阶段：应用修复
+Gate: 根因已确定 ✓
+📍 Next: 修复完成后进入验证阶段
+[/phase-state:3-fix]
+
+[phase-state:4-verify]
+当前阶段：验证修复
+Gate: 修复已应用 ✓
+📍 Next: 验证通过后报告结果，建议提交
+[/phase-state:4-verify]
+
+---
+
+## 阶段详情
+
+### Phase 1: 定位 [required]
+
+1. 从用户描述中提取关键信息：
+   - 错误消息（如果有）
+   - 发生位置（文件、功能、页面）
+   - 复现步骤
+
+2. 搜索相关代码：
+   - 有错误消息 → `Grep` 搜索错误文本
+   - 有文件/函数名 → 直接 `Read` 目标文件
+   - 信息不足 → 用 MCP 搜索工具或 `Grep` 按关键词搜索
+
+3. 读取找到的代码文件，理解上下文
+
+### Phase 2: 诊断 [required]
+
+1. 分析代码逻辑，找到 bug 的根因
+2. 如果有多个可能原因，按可能性排序
+3. 简要说明诊断结果：
+   ```
+   🔍 诊断
+     文件: [path:line]
+     根因: [一句话说明]
+     修复方案: [一句话说明]
+   ```
+
+### Phase 3: 修复
+
+1. 应用最小修复（只改必要的部分）
+2. 如果项目有测试 → 运行相关测试
+3. 如果没有测试 → 建议但不强制添加
+
+### Phase 4: 验证
+
+1. `git diff` 展示变更
+2. 确认修复合理性：
+   - 变更范围是否最小？
+   - 是否引入新问题？
+   - 边界条件是否考虑？
+3. 如果修复涉及认证/输入处理/安全相关代码 → `/verify-security` 安全扫描
+4. 输出结果：
+   ```
+   ✅ 修复完成
+     变更: [N] 文件，[M] 行
+     根因: [简述]
+     修复: [简述]
+     📍 Next: 可以用 /ccg:commit 提交
+   ```
+
+---
+
+## 升级规则
+
+如果在 Phase 1-2 中发现以下情况，建议升级：
+- 涉及 3+ 文件 → 升级到 `guided-develop`
+- 原因不明，需要深度调试 → 升级到 `debug-investigate`
+- 涉及架构问题 → 升级到 `refactor-safely`
+
+告知用户并等待确认后切换策略。
+
+---
+
+## 铁律
+
+- **不可在未读代码的情况下猜测修复方案** — Phase 1 必须实际读取代码
+- **最小修复原则** — 只改导致 bug 的部分，不做"顺手重构"
+- **不可跳过诊断直接改代码** — 即使"一眼看出问题"，也要经过 Phase 2 确认根因

package/templates/engine/strategies/full-collaborate.md

@@ -0,0 +1,291 @@
+# Strategy: Full Collaborate — 完整多模型协作
+
+> 适用于复杂功能开发，需要多模型并行分析、规划和审查。等效于 /ccg:workflow。
+
+## 适用条件
+- 复杂度 L/XL（5+ 文件，跨模块，架构级变更）
+- 风险 medium 或 high
+- 需要多角度分析和交叉验证
+
+## 前置加载
+
+```
+Read("~/.claude/.ccg/engine/model-router.md")
+```
+
+---
+
+## 工作流状态机
+
+[phase-state:1-research]
+当前阶段：研究与分析 [模式：研究]
+📍 Next: 需求评分 ≥7 后进入多模型构思
+[/phase-state:1-research]
+
+[phase-state:2-ideation]
+当前阶段：多模型构思 [模式：构思]
+Gate: 需求完整性评分 ≥7 ✓
+📍 Next: 双模型分析结果返回后进入规划
+[/phase-state:2-ideation]
+
+[phase-state:3-planning]
+当前阶段：详细规划 [模式：计划]
+Gate: 双模型分析已返回 ✓
+📍 Next: 用户审批计划后进入实施（HARD STOP）
+[/phase-state:3-planning]
+
+[phase-state:4-implementation]
+当前阶段：实施 [模式：执行]
+Gate: 用户已审批计划 ✓
+📍 Next: 实施完成后进入优化审查
+[/phase-state:4-implementation]
+
+[phase-state:5-optimization]
+当前阶段：优化审查 [模式：优化]
+Gate: 实施已完成 ✓
+📍 Next: 审查结果整合后进入最终验收
+[/phase-state:5-optimization]
+
+[phase-state:6-final]
+当前阶段：最终验收 [模式：评审]
+Gate: 优化审查已完成 ✓
+📍 Next: 验收通过后建议提交
+[/phase-state:6-final]
+
+---
+
+## 阶段详情
+
+### Phase 1: 研究与分析 [required]
+
+`[模式：研究]`
+
+1. **需求增强**：分析 $ARGUMENTS 的意图、缺失信息、隐含假设，补全为结构化需求（目标、约束、范围、验收标准）
+2. **上下文检索**：用 MCP 搜索工具收集项目上下文
+3. **需求完整性评分**（0-10）：
+   - 目标明确性（0-3）、预期结果（0-3）、边界范围（0-2）、约束条件（0-2）
+   - ≥7：继续 | <7：停止，提出补充问题
+
+**Task 更新**：
+```
+更新 .ccg/tasks/{task-name}/task.json:
+  currentPhase → "1-research"
+  nextAction → "需求增强 + 上下文检索"
+```
+持久化：写入 `.ccg/tasks/{task-name}/requirements.md`
+
+### Phase 2: 多模型构思 [required]
+
+`[模式：构思]`
+
+**Gate check**: 需求评分 ≥7
+
+**并行调用**（`run_in_background: true`）：
+- **backend 模型**：analyzer 角色 — 技术可行性、后端方案、风险评估
+- **frontend 模型**：analyzer 角色 — UI 可行性、前端方案、用户体验
+
+使用 model-router.md 中的调用模板。
+
+等待双模型返回：
+```
+TaskOutput({ task_id: "$BACKEND_TASK_ID", block: true, timeout: 600000 })
+TaskOutput({ task_id: "$FRONTEND_TASK_ID", block: true, timeout: 600000 })
+```
+
+**保存 SESSION_ID**（`BACKEND_SESSION` / `FRONTEND_SESSION`）用于后续复用。
+
+**重试规则**：
+- frontend 模型失败 → 重试 2 次，间隔 5s
+- backend 模型执行中（5-15 分钟正常）→ 持续等待，**绝不终止**
+- 3 次全败 → 降级为单模型，告知用户
+
+综合双方分析，输出方案对比（至少 2 个方案）。
+
+**Task 更新**：`currentPhase → "2-ideation"`, `nextAction → "综合分析结果，进入规划"`
+**持久化**：写入 `.ccg/tasks/{task-name}/analysis.md`
+
+**策展 context.jsonl**：
+在进入 Phase 3 前，策展 `.ccg/tasks/{task-name}/context.jsonl`：
+- 检查 `.ccg/spec/` 存在 → 列出相关 spec 文件
+- 将 analysis.md 加入（子 Agent 在规划阶段需要参考分析结果）
+- 格式：每行 `{"file": "路径", "reason": "原因"}`
+
+### Phase 3: 详细规划 [required]
+
+`[模式：计划]`
+
+**Gate check**: 双模型分析已返回
+
+**并行调用**（复用会话 `resume`）：
+- **backend 模型**：architect 角色 + `resume $BACKEND_SESSION`
+- **frontend 模型**：architect 角色 + `resume $FRONTEND_SESSION`
+
+综合双方规划，输出详细实施计划：
+- 实施步骤（按文件/模块分组）
+- 架构决策及理由
+- 测试策略
+- 风险及缓解措施
+
+**持久化**：写入 `.ccg/tasks/{task-name}/plan.md`
+
+**Task 更新**：
+```
+更新 task.json:
+  currentPhase → "3-planning"
+  gate → "user_approval_required"
+  nextAction → "等待用户审批计划"
+```
+
+**⛔ HARD STOP**：展示完整计划，并告知用户：
+```
+审批后将使用 Agent Teams 并行实施（多个 Builder 同时写代码）。
+```
+等待用户明确审批。未审批不可进入 Phase 4。
+
+用户确认后：`task.json: gate → null`
+
+### Phase 4: 实施（Agent Teams 并行）
+
+`[模式：执行]`
+
+**Gate check**: 用户已审批计划
+
+**⛔⛔⛔ 你的第一个动作必须是 TeamCreate。不是 Write，不是 Bash，不是 Read，是 TeamCreate。⛔⛔⛔**
+
+**你绝对不可以自己用 Write/Edit 工具写产品代码。所有代码由 Team Builder 写。你只做编排。**
+
+**Task 更新**：`currentPhase → "4-implementation"`, `nextAction → "TeamCreate → spawn Builders"`
+
+#### Step 1: 拆分子任务
+
+从 plan.md 中提取实施步骤，按**文件归属**拆分为独立子任务：
+- 每个子任务有明确的文件范围（互不重叠）
+- 标注依赖关系：Layer 1（无依赖）→ Layer 2（依赖 Layer 1）
+
+#### Step 2: 创建 Team（必须执行）
+
+**立即调用 TeamCreate，不可跳过或假设会失败：**
+```
+TeamCreate({ team_name: "{task-id}-team", description: "CCG 实施团队" })
+```
+
+⚠️ 只有当 TeamCreate **实际返回错误**时（Agent Teams 未启用），才可降级为自己写。**不可预判失败而跳过。**
+
+#### Step 3: 并行 spawn Layer 1 Builders
+
+**所有 Layer 1 Builder 必须在同一条消息中 spawn**（一条消息多个 Agent 调用 = 真正并行）：
+
+```
+Agent({
+  team_name: "{task-id}-team",
+  name: "dev-1",
+  model: "sonnet",
+  prompt: "你是 Builder，负责实施子任务 1。\n\n## 工作目录\n{WORKDIR}\n\n## 文件范围约束（⛔ 硬性规则）\n你只能创建或修改以下文件：\n- {file1}\n- {file2}\n严禁修改其他文件。违反 = 任务失败。\n\n## 实施步骤\n{steps from plan.md}\n\n## 验收标准\n{criteria from prd}\n\n完成后标记任务 completed。"
+})
+Agent({
+  team_name: "{task-id}-team",
+  name: "dev-2",
+  model: "sonnet",
+  prompt: "..."
+})
+// ... 所有 Layer 1 dev 在这一条消息里
+```
+
+#### Step 4: 等待 Layer 1 → spawn Layer 2
+
+- teammates 完成后自动通知（不需要轮询）
+- Layer 1 全部完成后 → 在新消息中 spawn Layer 2 Builders
+- Builder 遇到问题 → SendMessage 指导
+
+#### Step 5: spawn Reviewer 快检
+
+```
+Agent({
+  team_name: "{task-id}-team",
+  name: "reviewer",
+  model: "sonnet",
+  prompt: "审查所有变更文件（git diff）。运行 lint/typecheck/test。输出 Critical/Warning/Info 分级报告。完成后标记 completed。"
+})
+```
+
+Critical → spawn fix-dev 修复（最多 2 轮）。
+
+#### Step 6: shutdown + cleanup
+
+```
+SendMessage({ to: "dev-1", message: { type: "shutdown_request" } })
+SendMessage({ to: "dev-2", message: { type: "shutdown_request" } })
+SendMessage({ to: "reviewer", message: { type: "shutdown_request" } })
+```
+
+#### 降级方案（仅当 TeamCreate 实际报错时）
+
+如果 TeamCreate 返回错误（如 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 未启用），则：
+1. 告知用户："Agent Teams 未启用，降级为顺序实施"
+2. 按 plan.md 中的 Layer 顺序逐文件实施
+3. 仍然遵守质量关卡
+
+### Phase 5: 优化审查 + 质量关卡 [required]
+
+`[模式：优化]`
+
+**Gate check**: 实施已完成
+
+**Task 更新**：`currentPhase → "5-optimization"`, `nextAction → "双模型审查 + 质量关卡"`
+
+#### 5a. 双模型交叉审查
+
+**并行调用**：
+- **backend 模型**：reviewer 角色 — 关注安全、性能、错误处理
+- **frontend 模型**：reviewer 角色 — 关注可访问性、设计一致性
+
+#### 5b. 质量关卡
+
+**⛔ 以下 Skill 必须逐个调用执行，不可跳过，不可用自己的判断替代：**
+
+1. 调用 Skill `verify-security` — 等待报告
+2. 调用 Skill `verify-quality` — 等待报告
+3. 调用 Skill `verify-change` — 等待报告
+
+任何关卡报告 **Critical** → 必须修复后重新运行该关卡，才能进入 Phase 6。
+
+#### 5c. 综合报告
+
+整合审查意见 + 质量关卡结果，按严重度分级：
+- **Critical**：必须修复（阻塞交付）
+- **Warning**：建议修复
+- **Info**：供参考
+
+展示审查结果，用户确认后执行必要的优化。
+**持久化**：写入 `.ccg/tasks/{task-name}/review.md`
+
+### Phase 6: 最终验收
+
+`[模式：评审]`
+
+**Task 更新**：`currentPhase → "6-final"`, `nextAction → "最终验收"`
+
+1. 对照计划检查完成情况
+2. 运行测试验证功能
+3. `git diff` 全量变更摘要
+4. 输出结果：
+   ```
+   ✅ 协作开发完成
+     变更: [N] 文件，[M] 行
+     方案: [选定方案摘要]
+     审查: [Critical: N, Warning: N, Info: N]
+     📍 Next: /ccg commit 提交，或查看 .ccg/tasks/{task-name}/ 中的完整记录
+   ```
+
+**Task 更新**：`status → "completed"`, `nextAction → "可用 /ccg:commit 提交"`
+
+---
+
+## 铁律
+
+- **Phase 3 必须用户审批** — HARD STOP，不可自动跳过
+- **Phase 2 双模型必须并行** — 不可串行调用
+- **外部模型返回前不可提前进入下一阶段** — 等待是必须的
+- **不可因为"任务简单"而跳过 [required] 阶段** — 每个阶段都有其价值
+- **外部模型零文件写入权限** — 所有修改由 Claude 执行
+- **评分 <7 或用户未审批时强制停止** — 不可绕过