ccg-ros2-workflow 2.2.2 → 3.0.0

package/templates/commands-legacy/workflow.md

@@ -0,0 +1,283 @@
+---
+description: 'ROS2 多模型协作开发工作流（研究→构思→计划→执行→优化→评审→硬件部署），智能路由上层应用→{{FRONTEND_PRIMARY}}、底层控制→{{BACKEND_PRIMARY}}'
+---
+
+# Workflow - ROS2 多模型协作开发
+
+使用质量把关、MCP 服务和多模型协作执行 ROS2 结构化开发工作流。
+
+## 使用方法
+
+```bash
+/workflow <ROS2任务描述>
+```
+
+## 上下文
+
+- 要开发的任务：$ARGUMENTS
+- 带质量把关的结构化 7 阶段工作流（含硬件部署）
+- 多模型协作：{{BACKEND_PRIMARY}}（底层控制）+ {{FRONTEND_PRIMARY}}（上层应用）+ Claude（编排）
+- MCP 服务集成（ace-tool）以增强功能
+- 目标平台：ROS2 Humble / 物理机器人
+
+## 你的角色
+
+你是**ROS2 编排者**，协调多模型协作系统（研究 → 构思 → 计划 → 执行 → 优化 → 评审 → 硬件部署），用中文协助用户，面向专业机器人开发者，交互应简洁专业，避免不必要解释。
+
+**协作模型**：
+- **ace-tool MCP** – 代码检索 + Prompt 增强
+- **{{BACKEND_PRIMARY}}** – 底层控制：C++、硬件驱动、实时算法、控制器（**底层权威，可信赖**）
+- **{{FRONTEND_PRIMARY}}** – 上层应用：Launch、Python、RViz、仿真配置（**上层高手，底层意见仅供参考**）
+- **Claude (自己)** – 编排、计划、执行、交付
+
+---
+
+## 多模型调用规范
+
+**工作目录**：
+- `{{WORKDIR}}`：**必须通过 Bash 执行 `pwd`（Unix）或 `cd`（Windows CMD）获取当前工作目录的绝对路径**，禁止从 `$HOME` 或环境变量推断
+- 如果用户通过 `/add-dir` 添加了多个工作区，先用 Glob/Grep 确定任务相关的工作区
+- 如果无法确定，用 `AskUserQuestion` 询问用户选择目标工作区
+
+**调用语法**（并行用 `run_in_background: true`，串行用 `false`）：
+
+```
+# 新会话调用
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend <{{BACKEND_PRIMARY}}|{{FRONTEND_PRIMARY}}> {{GEMINI_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'
+ROLE_FILE: <角色提示词路径>
+<TASK>
+需求：<增强后的需求（如未增强则用 $ARGUMENTS）>
+上下文：<前序阶段收集的项目上下文、分析结果等>
+ROS2上下文：<colcon工作空间、package.xml、launch文件、节点架构等>
+</TASK>
+OUTPUT: 期望输出格式
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "简短描述"
+})
+
+# 复用会话调用
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend <{{BACKEND_PRIMARY}}|{{FRONTEND_PRIMARY}}> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"{{WORKDIR}}\" <<'EOF'
+ROLE_FILE: <角色提示词路径>
+<TASK>
+需求：<增强后的需求（如未增强则用 $ARGUMENTS）>
+上下文：<前序阶段收集的项目上下文、分析结果等>
+ROS2上下文：<colcon工作空间、package.xml、launch文件、节点架构等>
+</TASK>
+OUTPUT: 期望输出格式
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "简短描述"
+})
+```
+
+**角色提示词**：
+
+| 阶段 | 底层控制 | 上层应用 |
+|------|----------|----------|
+| 分析 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md` |
+| 规划 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/architect.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/architect.md` |
+| 审查 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/reviewer.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/reviewer.md` |
+
+**会话复用**：每次调用返回 `SESSION_ID: xxx`，后续阶段用 `resume xxx` 复用上下文（注意：是 `resume`，不是 `--resume`）。
+
+**并行调用**：使用 `run_in_background: true` 启动，用 `TaskOutput` 等待结果。**必须等所有模型返回后才能进入下一阶段**。
+
+**等待后台任务**（使用最大超时 600000ms = 10 分钟）：
+
+```
+TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
+```
+
+**重要**：
+- 必须指定 `timeout: 600000`，否则默认只有 30 秒会导致提前超时。
+如果 10 分钟后仍未完成，继续用 `TaskOutput` 轮询，**绝对不要 Kill 进程**。
+- 若因等待时间过长跳过了等待 TaskOutput 结果，则**必须调用 `AskUserQuestion` 工具询问用户选择继续等待还是 Kill Task。禁止直接 Kill Task。**
+- ⛔ **上层应用模型失败必须重试**：若上层应用模型调用失败（非零退出码或输出包含错误信息），最多重试 2 次（间隔 5 秒）。仅当 3 次全部失败时才跳过上层应用模型结果并使用单模型结果继续。
+- ⛔ **底层控制模型结果必须等待**：底层控制模型执行时间较长（5-15 分钟）属于正常。TaskOutput 超时后必须继续用 TaskOutput 轮询，**绝对禁止在底层控制模型未返回结果时直接跳过或继续下一阶段**。已启动的底层控制任务若被跳过 = 浪费 token + 丢失结果。
+
+---
+
+## 沟通守则
+
+1. 响应以模式标签 `[模式：X]` 开始，初始为 `[模式：研究]`。
+2. 核心工作流严格按 `研究 → 构思 → 计划 → 执行 → 优化 → 评审 → 硬件部署` 顺序流转。
+3. 每个阶段完成后必须请求用户确认。
+4. 评分低于 7 分或用户未批准时强制停止。
+5. 在需要询问用户时，尽量使用 `AskUserQuestion` 工具进行交互，举例场景：请求用户确认/选择/批准
+
+---
+
+## 执行工作流
+
+**任务描述**：$ARGUMENTS
+
+### 🔍 阶段 1：研究与分析
+
+`[模式：研究]` - 理解需求并收集 ROS2 上下文：
+
+1. **ROS2 环境检测**：
+   - 检查 colcon 工作空间结构（`src/`、`build/`、`install/`）
+   - 扫描 `package.xml` 文件，识别现有 ROS2 包
+   - 检查 launch 文件和配置文件
+2. **Prompt 准备**：直接将 $ARGUMENTS 作为后续多模型调用的输入。
+3. **上下文检索**：调用 `{{MCP_SEARCH_TOOL}}`，重点检索 ROS2 相关代码（节点、消息、服务、launch）
+4. **需求完整性评分**（0-10 分）：
+   - 目标明确性（0-3）、预期结果（0-3）、边界范围（0-2）、约束条件（0-2）
+   - ≥7 分：继续 | <7 分：⛔ 停止，提出补充问题
+
+### 💡 阶段 2：方案构思
+
+`[模式：构思]` - 多模型并行分析：
+
+**并行调用**（`run_in_background: true`）：
+- **底层控制模型**：使用分析提示词，输出底层控制可行性（C++ 节点/硬件驱动/实时性/消息定义）、方案、风险
+- **上层应用模型**：使用分析提示词，输出上层应用可行性（Launch 文件/Python 节点/RViz 配置/仿真）、方案、集成
+
+用 `TaskOutput` 等待结果。**📌 保存 SESSION_ID**（`BACKEND_SESSION` 和 `FRONTEND_SESSION`）。
+
+**务必遵循上方 `多模型调用规范` 的 `重要` 指示**
+
+综合两方分析，输出方案对比（至少 2 个方案），包含：
+- 节点架构设计（节点数量、职责划分）
+- Topic/Service/Action 选型
+- QoS 策略建议
+- 硬件依赖（CAN/串口/传感器）
+
+等待用户选择方案。
+
+### 📋 阶段 3：详细规划
+
+`[模式：计划]` - 多模型协作规划：
+
+**并行调用**（复用会话 `resume <SESSION_ID>`）：
+- **底层控制模型**：使用规划提示词 + `resume $BACKEND_SESSION`，输出底层控制架构（C++ 节点实现/控制算法/消息定义/CMakeLists.txt）
+- **上层应用模型**：使用规划提示词 + `resume $FRONTEND_SESSION`，输出上层应用架构（Launch 文件/参数配置/RViz 配置/Python 节点）
+
+用 `TaskOutput` 等待结果。
+
+综合两方规划，输出完整实施计划：
+- **节点清单**：每个节点的职责、订阅/发布的 Topic、提供的 Service
+- **消息定义**：自定义消息的 .msg 文件内容
+- **QoS 配置**：每个 Topic 的 QoS 策略（Reliability/Durability/History）
+- **Launch 配置**：启动顺序、参数传递、命名空间
+- **文件清单**：需要创建/修改的文件列表
+
+**⛔ HARD STOP**：展示计划，等待用户批准。未批准禁止进入执行阶段。
+
+### ⚙️ 阶段 4：代码执行
+
+`[模式：执行]` - Claude 主导实施：
+
+根据批准的计划，按以下顺序实施：
+
+1. **消息定义**（如需）：
+   - 创建 `msg/` 目录和 .msg 文件
+   - 更新 `CMakeLists.txt` 和 `package.xml`
+2. **C++ 节点**（底层控制）：
+   - 创建节点源文件（`src/`）
+   - 实现订阅/发布/服务
+   - 配置 CMakeLists.txt
+3. **Python 节点**（上层应用）：
+   - 创建 Python 节点（`scripts/` 或 `<package>/`）
+   - 实现 rclpy 逻辑
+   - 配置 setup.py
+4. **Launch 文件**：
+   - 创建 launch 文件（`launch/`）
+   - 配置节点启动、参数、重映射
+5. **配置文件**：
+   - 创建参数 YAML（`config/`）
+   - RViz 配置（`rviz/`）
+
+每完成一个模块，运行 `colcon build` 验证编译。
+
+### 🔧 阶段 5：优化审查
+
+`[模式：优化]` - 多模型并行审查：
+
+**并行调用**（复用会话 `resume <SESSION_ID>`）：
+- **底层控制模型**：使用审查提示词 + `resume $BACKEND_SESSION`，审查 C++ 代码、消息定义、实时性、线程安全
+- **上层应用模型**：使用审查提示词 + `resume $FRONTEND_SESSION`，审查 Launch 文件、参数配置、Python 代码、RViz 配置
+
+用 `TaskOutput` 等待结果。
+
+综合两方审查意见，Claude 整合修复：
+- **Critical 问题**：必须修复（QoS 不匹配、生命周期错误、线程不安全）
+- **Warning 问题**：建议修复（命名不规范、参数缺失、日志不足）
+- **Info 建议**：可选优化（性能优化、代码风格）
+
+### ✅ 阶段 6：最终评审
+
+`[模式：评审]` - 质量把关：
+
+1. **编译测试**：
+   ```bash
+   colcon build --packages-select <package_name>
+   colcon test --packages-select <package_name>
+   ```
+2. **静态检查**：
+   - C++: `cpplint` / `cppcheck`
+   - Python: `flake8` / `pylint`
+3. **ROS2 规范检查**：
+   - package.xml 完整性
+   - CMakeLists.txt 正确性
+   - Launch 文件语法
+4. **文档完整性**：
+   - README.md 包含使用说明
+   - 代码注释充分
+   - Launch 文件有说明
+
+输出评审报告，等待用户确认。
+
+### 🚀 阶段 7：硬件部署
+
+`[模式：硬件部署]` - 生成部署方案：
+
+1. **硬件依赖检查**：
+   - 串口设备（`/dev/ttyUSB*`、`/dev/ttyACM*`）
+   - CAN 总线（`can0`、`can1`）
+   - 传感器设备（相机、激光雷达）
+   - 权限配置（udev rules）
+2. **部署脚本生成**：
+   ```bash
+   # deploy.sh
+   #!/bin/bash
+   # 检查硬件设备
+   # 配置 udev rules
+   # 启动 ROS2 节点
+   # 监控运行状态
+   ```
+3. **Gazebo 仿真验证**（可选）：
+   - 生成 Gazebo world 文件
+   - 配置机器人模型（URDF/SDF）
+   - 启动仿真环境
+   - 验证节点通信
+4. **部署清单**：
+   - 硬件连接检查表
+   - 软件依赖安装命令
+   - 启动命令
+   - 故障排查指南
+
+输出部署文档和脚本，等待用户确认。
+
+---
+
+## 完成标准
+
+所有 7 个阶段完成后，输出最终交付清单：
+
+- ✅ ROS2 包结构完整（package.xml、CMakeLists.txt、setup.py）
+- ✅ 节点实现完成（C++/Python）
+- ✅ 消息定义正确（.msg/.srv/.action）
+- ✅ Launch 文件可用
+- ✅ 配置文件完整（params.yaml、rviz config）
+- ✅ 编译测试通过
+- ✅ 代码审查通过
+- ✅ 硬件部署方案就绪
+- ✅ 文档完整
+
+**🎉 ROS2 开发工作流完成！**

package/templates/engine/model-router.md

@@ -0,0 +1,123 @@
+# CCG 模型路由器 — 运行时模型选择框架
+
+> 本文件由策略文件通过 Read 加载，提供动态模型选择和 codeagent-wrapper 调用模板。
+
+## 1. 获取模型配置
+
+读取用户配置确定可用模型：
+
+```
+Read ~/.claude/.ccg/config.toml
+```
+
+从 `[routing]` 区块提取：
+- `frontend.primary` — 上层应用模型（默认 `gemini`）
+- `backend.primary` — 底层控制模型（默认 `codex`）
+- `geminiModel` — Gemini 型号（默认 `gemini-3.1-pro-preview`）
+
+如果配置文件不存在或不可读，使用默认值直接继续。
+
+## 2. 按阶段选择模型
+
+### 分析/研究阶段
+| 任务领域 | 推荐模型 | 角色提示词 |
+|---------|---------|-----------|
+| 底层控制/架构 | backend 模型 | `$BACKEND/analyzer.md` |
+| 上层应用/UI | frontend 模型 | `$FRONTEND/analyzer.md` |
+| 全栈 | 双模型并行 | 各用对应 analyzer |
+| 安全 | backend 模型 | `$BACKEND/analyzer.md` |
+
+### 规划阶段
+| 任务领域 | 推荐模型 | 角色提示词 |
+|---------|---------|-----------|
+| 架构设计 | backend 模型 | `$BACKEND/architect.md` |
+| ROS2系统集成 设计 | frontend 模型 | `$FRONTEND/architect.md` |
+| 全栈 | 双模型并行 | 各用对应 architect |
+
+### 审查阶段（始终双模型交叉验证）
+- backend 模型 + `$BACKEND/reviewer.md`
+- frontend 模型 + `$FRONTEND/reviewer.md`
+
+### 调试阶段
+| 任务领域 | 推荐模型 | 角色提示词 |
+|---------|---------|-----------|
+| 底层控制问题 | backend 模型优先 | `$BACKEND/debugger.md` |
+| 上层应用问题 | frontend 模型优先 | `$FRONTEND/debugger.md` |
+| 不确定 | 双模型并行 | 各用对应 debugger |
+
+### 实施阶段
+
+**默认模式**（Claude 执行）：
+- 外部模型仅提供建议，Claude 执行所有文件修改
+
+**Codex Builder 模式**（用户选择时）：
+- backend 模型 + `$BACKEND/builder.md` — **有完整写权限**，直接写代码到文件系统
+- Claude 监控进度，审查产出，必要时接管
+- 适用于 M-L 复杂度、低中风险的明确实施任务
+
+## 3. 调用模板
+
+### 获取工作目录
+
+先确定当前工作目录（不可从 $HOME 推断）：
+```
+WORKDIR=$(pwd)
+```
+
+### 新会话调用
+
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend $MODEL {{GEMINI_MODEL_FLAG}}- \"$WORKDIR\" <<'CODEAGENT_EOF'\nROLE_FILE: ~/.claude/.ccg/prompts/$MODEL/$ROLE.md\n<TASK>\n$TASK_CONTENT\n</TASK>\nOUTPUT: $OUTPUT_FORMAT\nCODEAGENT_EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "$SHORT_DESCRIPTION"
+})
+```
+
+变量说明：
+- `$MODEL` — 选定的模型名（`codex` / `gemini` / `claude`）
+- `$ROLE` — 角色文件名（`analyzer` / `architect` / `reviewer` / `debugger` / `optimizer` / `tester` / `builder`）
+- `$TASK_CONTENT` — 任务内容（需求 + 上下文）
+- `$OUTPUT_FORMAT` — 期望输出格式
+- `$SHORT_DESCRIPTION` — 简短描述（用于进度显示）
+
+### 复用会话调用
+
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend $MODEL {{GEMINI_MODEL_FLAG}}resume $SESSION_ID - \"$WORKDIR\" <<'CODEAGENT_EOF'\nROLE_FILE: ~/.claude/.ccg/prompts/$MODEL/$ROLE.md\n<TASK>\n$TASK_CONTENT\n</TASK>\nOUTPUT: $OUTPUT_FORMAT\nCODEAGENT_EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "$SHORT_DESCRIPTION"
+})
+```
+
+### 并行双模型调用模式
+
+同时启动两个模型，各自独立分析：
+
+1. 启动 backend 模型（`run_in_background: true`）
+2. 启动 frontend 模型（`run_in_background: true`）
+3. 等待两者完成：
+   ```
+   TaskOutput({ task_id: "$BACKEND_TASK_ID", block: true, timeout: 600000 })
+   TaskOutput({ task_id: "$FRONTEND_TASK_ID", block: true, timeout: 600000 })
+   ```
+4. 综合双方结果
+
+## 4. 等待与重试规则
+
+| 场景 | 策略 |
+|------|------|
+| frontend 模型失败 | 重试最多 2 次，间隔 5s |
+| backend 模型运行中 | 可能需要 5-15 分钟，保持轮询，永不终止 |
+| 3 次全败 | 降级为单模型模式，告知用户 |
+| 超时 | 600s 等待上限，超时后报告并询问用户 |
+
+## 5. SESSION_ID 管理
+
+- 每次 codeagent-wrapper 调用返回 `Session-ID: xxx`
+- 捕获并保存：`BACKEND_SESSION`、`FRONTEND_SESSION`
+- 后续阶段通过 `resume $SESSION_ID` 复用上下文
+- 复用会话可减少重复分析，提升效率

package/templates/engine/phase-guide.md

@@ -0,0 +1,207 @@
+# CCG 通用阶段指导
+
+> 本文件定义所有策略共享的阶段执行规范。策略文件可通过 Read 引用。
+
+## 1. 阶段状态自检
+
+每完成一个阶段，回顾对应的 `[phase-state:N]` 块：
+1. 确认该阶段的 Gate 条件已满足
+2. 输出 `📍 Next: [具体动作]` 告知用户下一步
+3. 如有 `[required]` 标记的阶段未完成，不可跳过
+
+## 2. Gate Check 执行规范
+
+Gate 是阶段间的硬性检查点。执行方式：
+
+- **数据 Gate**：检查前序阶段是否产出了必要数据（分析结果？计划文件？）
+- **确认 Gate（HARD STOP）**：必须等待用户明确确认才能继续
+- **质量 Gate**：检查产出物是否达到最低质量标准
+
+Gate 失败时：说明缺失什么，给出补救建议，不可绕过。
+
+## 3. Next-Action 格式
+
+每个阶段完成后输出：
+
+```
+📍 Next: [一句话描述下一步具体动作]
+```
+
+示例：
+- `📍 Next: 加载模型路由器，启动双模型并行分析`
+- `📍 Next: 请确认以上修复方案是否正确`
+- `📍 Next: 运行测试验证修复效果`
+
+## 4. 策略升级规则
+
+执行中发现复杂度超出当前策略能力时：
+
+1. 明确告知用户：`当前策略为 [名称]，但发现 [原因]，建议升级到 [目标策略]`
+2. 等待用户确认
+3. 确认后：`Read ~/.claude/.ccg/engine/strategies/[target].md`
+4. 从新策略的 Phase 1 开始（已完成的分析工作可复用）
+
+**只能升级，不能降级**（除非用户明确要求）。
+
+## 5. 错误恢复
+
+| 场景 | 处理方式 |
+|------|---------|
+| 外部模型调用失败 | 按模型路由器重试规则处理 |
+| 测试失败 | 分析失败原因，修复后重新运行 |
+| 用户要求中止 | 立即停止，报告已完成的工作 |
+| 意外文件冲突 | 报告冲突，等待用户决策 |
+
+## 6. Team Dispatch 协议
+
+当策略需要并行实施时，使用 Agent Teams：
+
+### 前置条件
+- 任务已拆分为文件级子任务（互不重叠）
+- plan.md 已审批
+
+### 标准流程
+```
+1. TeamCreate({ team_name: "{task-id}-team" })
+2. 同一消息内并行 spawn 所有 Layer 1 Builder
+3. 等待完成 → spawn Layer 2（如有）
+4. spawn Reviewer 快检
+5. Critical → spawn fix-dev（最多 2 轮）
+6. shutdown 所有 teammates
+```
+
+### Builder Prompt 必含项
+- `## 工作目录` — 绝对路径
+- `## 文件范围约束（⛔ 硬性规则）` — 只能改的文件列表
+- `## 实施步骤` — 具体操作
+- `## 验收标准` — 怎样算完成
+
+### Spec 注入
+PreToolUse Hook 自动为 Team member 注入：
+- context.jsonl 中列出的 spec 文件
+- requirements.md 和 plan.md 摘要
+- research/ 目录下的研究成果
+
+Builder 不需要在 prompt 中手动粘贴 spec — Hook 自动处理。
+
+### 降级方案
+TeamCreate 失败（Agent Teams 未启用）→ Claude 自己按计划顺序实施。
+
+## 7. 输出规范
+
+- 中文交流，技术术语保留英文
+- 代码块标明语言
+- 变更摘要用 git diff 格式
+- 研究结果用表格对比
+
+## 8. Spec Evolution Protocol — Spec 反馈环
+
+> 让 `.ccg/spec/` 从静态文档变为随项目开发自动进化的活知识库。
+
+### 触发条件
+
+任务归档前（status → "archived"），如果以下任一条件成立，**必须执行 Spec Evolution**：
+- 本次开发中发现了可复用的编码模式或约定
+- 外部模型审查提出了有价值的规范建议
+- 修复了一个非显而易见的坑（未来可能再踩）
+- 引入了新的第三方库/API/架构模式
+
+### 执行步骤
+
+1. **提炼经验**：分析 `git diff` + review.md（如有），提取可复用的经验教训
+2. **分类归属**：判断经验属于哪个 Spec 域：
+   - 底层控制相关 → `.ccg/spec/backend/index.md`
+   - 上层应用相关 → `.ccg/spec/frontend/index.md`
+   - 跨模块/通用 → `.ccg/spec/guides/index.md`
+3. **草拟更新**：以追加方式写出建议新增的 Spec 条目（不覆盖现有内容）
+4. **展示给用户**：
+   ```
+   📝 Spec Evolution — 本次开发经验提炼
+   
+   建议新增到 .ccg/spec/backend/index.md:
+     - [规范条目]（来源：{task-name}，{日期}）
+   
+   确认写入？[Y/n]
+   ```
+5. **用户确认后写入**（⛔ 不可静默写入 Spec）
+6. **无值得提炼的经验 → 跳过**（不要强行凑条目）
+
+### 条目质量标准
+
+好的 Spec 条目：
+- ✅ 具体：引用真实文件路径和 API 签名
+- ✅ 说明 Why：不只说"要这样做"，还说"因为…"
+- ✅ 可验证：子 Agent 能根据条目判断对错
+
+坏的 Spec 条目：
+- ❌ 空泛："写好的代码" / "注意安全"
+- ❌ 一次性：只对本次任务有价值，对未来无意义
+
+## 9. Loop Detection & Recovery — 死循环检测
+
+> workflow-state Hook 自动追踪每轮的 phase + nextAction。连续 3 轮无变化触发 Break-Loop Protocol。
+
+### 机制
+
+- Hook 在每轮用户消息时写入 `.ccg/tasks/{name}/.turns.json`（最近 10 轮滚动缓冲）
+- 检测规则：连续 3 轮 `phase` + `nextAction` 完全相同 → 判定为死循环
+- 触发后在 `<ccg-state>` 面包屑中注入 `⚠️ LOOP DETECTED` 警告
+
+### Break-Loop Protocol（Claude 收到警告后必须执行）
+
+1. **立即停止**当前重复动作
+2. **根因分析**（5 Why）：
+   - 是外部依赖阻塞？（网络/API/权限）→ 告知用户
+   - 是策略不适配？→ 建议升级策略
+   - 是信息不足？→ 向用户提问
+   - 是实现路径走死？→ 换方案
+3. **更新 task.json**：`nextAction` 必须变更为新的动作描述（打破循环）
+4. **如果连续 2 次触发 Break-Loop**（即 6 轮无进展）→ 强制暂停，输出完整状态摘要请用户介入
+
+## 10. Ralph Loop — 迭代审查协议
+
+> 审查不是一次性动作。每轮 spawn 新 Agent（干净上下文），读取磁盘最新状态重新验证，循环自修复。
+
+### 适用场景
+
+策略中标注为 `[Ralph Loop]` 的审查阶段，使用迭代审查代替一次性审查。
+
+### 标准流程
+
+```
+Round N (N=1,2,...,MAX_ROUNDS):
+  1. 双模型并行审查（每次 spawn 新 Agent，干净上下文）
+  2. 质量关卡（verify-security / verify-quality / verify-change）
+  3. 综合审查报告，按 Critical / Warning / Info 分级
+  4. 展示给用户，询问：
+     - 有 Critical → "发现 N 个 Critical 问题，是否修复后再审？[Y/n]"
+     - 无 Critical → "审查通过，是否需要再审一轮？[y/N]"
+  5. 用户选择继续 →
+     a. spawn fix-dev（新 Agent，干净上下文）修复 Critical 问题
+     b. 进度追加到 .ccg/tasks/{name}/fix-log.jsonl
+     c. 回到 Round N+1
+  6. 用户选择停止 → 退出循环，进入下一阶段
+```
+
+### 关键规则
+
+- **每轮审查必须是新 Agent** — 不复用上一轮的 Agent 上下文，避免"上下文污染越修越烂"
+- **fix-dev 也是新 Agent** — 从磁盘读取最新代码状态，只修分配的问题
+- **最多 3 轮**（MAX_ROUNDS=3）— 超过 3 轮说明问题根深，应该回退到规划阶段
+- **用户始终有决定权** — 每轮结束后由用户决定是否继续，不自动循环
+- **fix-log.jsonl 追踪进度** — 每轮结果追加一行 JSON，格式：
+  ```jsonl
+  {"round": 1, "critical": 2, "warning": 5, "fixed": ["file1:issue", "file2:issue"], "ts": "ISO"}
+  {"round": 2, "critical": 0, "warning": 3, "fixed": ["file3:issue"], "ts": "ISO"}
+  ```
+
+### context.jsonl 角色标注
+
+策展 context.jsonl 时，按角色标注 `roles` 字段：
+```jsonl
+{"file": ".ccg/spec/backend/index.md", "reason": "底层控制规范", "roles": ["implement", "review"]}
+{"file": ".ccg/tasks/{name}/plan.md", "reason": "实施计划", "roles": ["implement"]}
+{"file": ".ccg/tasks/{name}/research/lib-comparison.md", "reason": "库选型", "roles": ["research", "implement"]}
+```
+
+SubAgent-context Hook 自动按角色过滤：无 `roles` 字段 = 注入所有角色。