ccg-ros2-workflow 2.2.1 → 3.0.0

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

@@ -0,0 +1,389 @@
+# 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 — 你必须在这里停下来，向用户展示以下选项并等待回复。不可跳过，不可默认选择。⛔⛔⛔**
+
+你现在必须输出以下内容（原样输出，不是代码块示例）：
+
+---
+⛔ **计划审批 + 执行模式选择**
+
+请审批以上计划，并选择谁来写代码：
+1. **Agent Teams** — Claude Builders 并行写，多文件同时进行
+2. **Codex / Antigravity** — 外部模型写代码，更快更便宜，Claude 监控审查
+
+请回复 1 或 2（或直接说"用team"/"用codex"等）。
+---
+
+**在用户回复之前，你不可以执行任何文件写入操作。** 未审批不可进入 Phase 4。
+
+用户确认后：`task.json: gate → null`
+
+### Phase 4: 实施
+
+`[模式：执行]`
+
+**Gate check**: 用户已审批计划 + 选择了执行模式
+
+根据用户选择的执行模式执行：
+
+---
+
+#### 模式 A: Agent Teams 并行（用户选 [1]）
+
+**⛔⛔⛔ 你的第一个动作必须是 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. 仍然遵守质量关卡
+
+---
+
+#### 模式 B: 外部模型并行实施（用户选 [2]）
+
+**Task 更新**：`currentPhase → "4-implementation"`, `nextAction → "Parallel Builder 执行 plan"`
+
+Claude 作为编排者，调用外部模型（Codex / Antigravity）**并行写代码**。
+
+**Step 1**: 从 plan.md 按**文件归属**拆分为并行子任务：
+- **Layer 1** — 无依赖（底层模块：model/store/util/schema）→ 并行
+- **Layer 2** — 依赖 Layer 1（上层：route/middleware/controller/component）→ 串行等 Layer 1
+- 每个子任务：文件范围 + 实施步骤 + 验证命令
+
+**Step 2**: 调用 codeagent-wrapper `--parallel` 模式：
+
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --parallel --backend {{BACKEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}- \"$WORKDIR\" <<'PARALLEL_EOF'\n---TASK---\nid: layer1-{name1}\nworkdir: $WORKDIR\n---CONTENT---\nROLE_FILE: ~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/builder.md\n<TASK>\n## 文件范围（⛔ 只改这些文件）\n{file1, file2}\n\n## 实施步骤\n{steps from plan.md Layer 1}\n\n## 验证命令\n{test/lint commands}\n</TASK>\n---TASK---\nid: layer1-{name2}\nworkdir: $WORKDIR\n---CONTENT---\nROLE_FILE: ~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/builder.md\n<TASK>\n## 文件范围\n{file3, file4}\n\n## 实施步骤\n{steps}\n</TASK>\n---TASK---\nid: layer2-{name3}\nworkdir: $WORKDIR\ndependencies: layer1-{name1},layer1-{name2}\n---CONTENT---\nROLE_FILE: ~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/builder.md\n<TASK>\n## 文件范围\n{file5, file6}\n\n## 实施步骤\n{steps from Layer 2}\n</TASK>\nPARALLEL_EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "Parallel Builder: {N} 个子任务（L1: {X} 并行 → L2: {Y} 串行）"
+})
+```
+
+拆分原则：
+- Layer 1 子任务数量 = plan 中无依赖的文件组数（通常 2-4 个）
+- 每个子任务的文件范围**不可重叠**
+- 可混合 backend（底层控制任务用 codex，上层应用任务用 antigravity）— 在 `---TASK---` 中指定 `backend: antigravity`
+
+**Step 3**: 等待完成，读取汇总报告（wrapper 自动合并所有子任务结果）
+
+**Step 4**: Claude 审查产出：
+1. `git diff` 检查所有变更
+2. 确认变更在 plan 范围内（scope check）
+3. 小问题（<10 行）→ Claude 直接修复
+4. 大问题 → 再调外部模型修复，或切换模式 A
+
+**降级**：外部模型失败/超时 → 告知用户，切换到模式 A 执行
+
+### Phase 5: 迭代审查 [required · Ralph Loop]
+
+`[模式：优化]`
+
+**Gate check**: 实施已完成
+
+**Task 更新**：`currentPhase → "5-optimization"`, `nextAction → "Ralph Loop Round 1: 双模型审查 + 质量关卡"`
+
+参考 `phase-guide.md § 10 Ralph Loop` 执行迭代审查。最多 3 轮。
+
+#### Round N 流程（N=1,2,3）
+
+**5a. 双模型交叉审查（每轮 spawn 新 Agent，干净上下文）**
+
+**并行调用**（`run_in_background: true`）：
+- **backend 模型**：reviewer 角色 — 关注安全、性能、错误处理
+- **frontend 模型**：reviewer 角色 — 关注可访问性、设计一致性
+
+**5b. 质量关卡**
+
+**⛔ 以下 Skill 必须逐个调用执行，不可跳过，不可用自己的判断替代：**
+
+1. 调用 Skill `verify-security` — 等待报告
+2. 调用 Skill `verify-quality` — 等待报告
+3. 调用 Skill `verify-change` — 等待报告
+
+**5c. 综合报告**
+
+整合审查意见 + 质量关卡结果，按严重度分级：
+- **Critical**：必须修复（阻塞交付）
+- **Warning**：建议修复
+- **Info**：供参考
+
+**持久化**：写入 `.ccg/tasks/{task-name}/review.md`（每轮覆盖）
+
+追加进度到 `.ccg/tasks/{task-name}/fix-log.jsonl`：
+```jsonl
+{"round": N, "critical": X, "warning": Y, "info": Z, "ts": "ISO"}
+```
+
+**5d. 用户决定（⛔ 必须等待）**
+
+展示审查结果后询问用户：
+- 有 Critical → `发现 N 个 Critical 问题。修复后再审一轮？[Y/n]`
+- 无 Critical 但有 Warning → `无 Critical 问题。需要再审一轮处理 Warning？[y/N]`
+- 全部通过 → 直接进入 Phase 6
+
+用户选择继续 →
+1. spawn fix-dev（**新 Agent，干净上下文**）修复 Critical/Warning
+2. fix-dev 完成后回到 5a 开始 Round N+1
+3. 追加修复记录到 fix-log.jsonl
+
+用户选择停止 → 进入 Phase 6
+
+**第 3 轮仍有 Critical** → 强制停止，建议回退到 Phase 3 重新规划。
+
+### 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}/ 中的完整记录
+   ```
+
+#### Spec Evolution（归档前必须执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 分析本次 `git diff` + `review.md`，提炼可复用的编码约定和经验教训
+2. 如有值得记录的经验 → 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过（不强行凑）
+
+**Task 更新**：`status → "archived"`
+
+**归档任务**：将 `.ccg/tasks/{task-name}/` 移动到 `.ccg/tasks/archive/YYYY-MM/{task-name}/`
+```bash
+mkdir -p .ccg/tasks/archive/$(date +%Y-%m) && mv .ccg/tasks/{task-name} .ccg/tasks/archive/$(date +%Y-%m)/
+```
+
+**自动提交归档**：
+```bash
+git add .ccg/tasks/ && git commit -m "chore: archive ccg task {task-name}"
+```
+
+```
+📍 Next: /ccg:commit 提交产品代码
+```
+
+---
+
+## 铁律
+
+- **Phase 3 必须用户审批** — HARD STOP，不可自动跳过
+- **Phase 2 双模型必须并行** — 不可串行调用
+- **外部模型返回前不可提前进入下一阶段** — 等待是必须的
+- **不可因为"任务简单"而跳过 [required] 阶段** — 每个阶段都有其价值
+- **外部模型零文件写入权限** — 所有修改由 Claude 执行
+- **评分 <7 或用户未审批时强制停止** — 不可绕过

package/templates/engine/strategies/git-action.md

@@ -0,0 +1,43 @@
+# Strategy: Git Action — Git 操作
+
+> 适用于 Git 相关操作。委托给现有的专用命令，不重复实现。
+
+## 适用条件
+- 用户请求 commit / rollback / branch 管理 / worktree 等 Git 操作
+- 任何复杂度级别
+
+---
+
+## 路由表
+
+根据用户请求中的关键词，加载对应的现有命令文件并按其指令执行：
+
+| 关键词 | 命令文件 | 说明 |
+|--------|---------|------|
+| commit, 提交 | `~/.claude/commands/ccg/commit.md` | 智能提交（conventional commit） |
+| rollback, 回滚, revert, undo | `~/.claude/commands/ccg/rollback.md` | 交互式回滚 |
+| clean branch, 清理分支 | `~/.claude/commands/ccg/clean-branches.md` | 清理已合并分支 |
+| worktree | `~/.claude/commands/ccg/worktree.md` | Worktree 管理 |
+
+## 执行方式
+
+1. 匹配关键词确定目标命令
+2. `Read("目标命令文件路径")` 加载完整指令
+3. 将用户的 `$ARGUMENTS` 作为该命令的输入
+4. 严格按照命令文件的指令执行
+
+## 未匹配的 Git 操作
+
+如果用户的 Git 请求不匹配上述任何命令（如 `push`, `merge`, `cherry-pick`, `stash` 等）：
+- Claude 直接处理
+- 遵循 Git 安全原则：
+  - 破坏性操作（force push, reset --hard）前必须确认
+  - 不自动 push 到远程（除非用户明确要求）
+  - 优先创建新 commit 而非 amend
+
+---
+
+## 铁律
+
+- **不重复实现** — 现有命令已经过充分测试，直接委托
+- **保持一致性** — 用户通过 `/ccg commit` 和 `/ccg:commit` 应得到相同结果