ccg-workflow 3.0.1 → 3.0.3

package/README.md

@@ -12,8 +12,9 @@
 [![Tests](https://img.shields.io/badge/Tests-139%20passed-brightgreen.svg)]()
 [![Follow on X](https://img.shields.io/badge/X-@CCG__Workflow-black?logo=x&logoColor=white)](https://x.com/CCG_Workflow)
 ![star](https://atomgit.com/fengshao1227/ccg-workflow/star/badge.svg)
+[![Docs](https://img.shields.io/badge/Docs-ccg.fengshao1227.com-blue?style=for-the-badge&logo=readthedocs&logoColor=white)](https://ccg.fengshao1227.com/)
 
-[简体中文](./README.zh-CN.md) | English
+[简体中文](./README.zh-CN.md) | English | [**Documentation**](https://ccg.fengshao1227.com/)
 
 </div>
 
@@ -249,4 +250,4 @@ MIT
 
 ---
 
-v3.0.0 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)
+v3.0.3 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)

package/README.zh-CN.md

@@ -13,8 +13,9 @@
 [![Tests](https://img.shields.io/badge/Tests-139%20passed-brightgreen.svg)]()
 [![Follow on X](https://img.shields.io/badge/X-@CCG__Workflow-black?logo=x&logoColor=white)](https://x.com/CCG_Workflow)
 ![star](https://atomgit.com/fengshao1227/ccg-workflow/star/badge.svg)
+[![Docs](https://img.shields.io/badge/文档站-ccg.fengshao1227.com-blue?style=for-the-badge&logo=readthedocs&logoColor=white)](https://ccg.fengshao1227.com/)
 
-[简体中文](./README.zh-CN.md) | English
+[简体中文](./README.zh-CN.md) | English | [**完整文档**](https://ccg.fengshao1227.com/)
 
 </div>
 
@@ -244,4 +245,4 @@ MIT
 
 ---
 
-v3.0.0 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)
+v3.0.3 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import cac from 'cac';
 import ansis from 'ansis';
-import { z as diagnoseMcpConfig, A as isWindows, B as readClaudeCodeConfig, C as fixWindowsMcpConfig, D as writeClaudeCodeConfig, r as readCcgConfig, b as initI18n, a as i18n, s as showMainMenu, i as init, E as configMcp, F as version } from './shared/ccg-workflow.2vO_S-e7.mjs';
+import { z as diagnoseMcpConfig, A as isWindows, B as readClaudeCodeConfig, C as fixWindowsMcpConfig, D as writeClaudeCodeConfig, r as readCcgConfig, b as initI18n, a as i18n, s as showMainMenu, i as init, E as configMcp, F as version } from './shared/ccg-workflow.DxKAcBrr.mjs';
 import 'inquirer';
 import 'ora';
 import 'node:child_process';

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { c as changeLanguage, x as checkForUpdates, y as compareVersions, d as createDefaultConfig, e as createDefaultRouting, g as getCcgDir, f as getConfigPath, t as getCurrentVersion, v as getLatestVersion, j as getWorkflowById, h as getWorkflowConfigs, a as i18n, i as init, b as initI18n, l as installAceTool, m as installAceToolRs, k as installWorkflows, p as migrateToV1_4_0, q as needsMigration, r as readCcgConfig, s as showMainMenu, o as uninstallAceTool, n as uninstallWorkflows, u as update, w as writeCcgConfig } from './shared/ccg-workflow.2vO_S-e7.mjs';
+export { c as changeLanguage, x as checkForUpdates, y as compareVersions, d as createDefaultConfig, e as createDefaultRouting, g as getCcgDir, f as getConfigPath, t as getCurrentVersion, v as getLatestVersion, j as getWorkflowById, h as getWorkflowConfigs, a as i18n, i as init, b as initI18n, l as installAceTool, m as installAceToolRs, k as installWorkflows, p as migrateToV1_4_0, q as needsMigration, r as readCcgConfig, s as showMainMenu, o as uninstallAceTool, n as uninstallWorkflows, u as update, w as writeCcgConfig } from './shared/ccg-workflow.DxKAcBrr.mjs';
 import 'ansis';
 import 'inquirer';
 import 'ora';

package/dist/shared/{ccg-workflow.2vO_S-e7.mjs → ccg-workflow.DxKAcBrr.mjs}

@@ -10,7 +10,7 @@ import fs from 'fs-extra';
 import { parse, stringify } from 'smol-toml';
 import i18next from 'i18next';
 
-const version = "3.0.1";
+const version = "3.0.3";
 
 function cmd(id, order, category, name, nameEn, description, descriptionEn, cmdOverride) {
   return {
@@ -1028,6 +1028,10 @@ async function installSkillFiles(ctx) {
       overwrite: true,
       errorOnExist: false
     });
+    const securityDir = join(skillsDestDir, "domains", "security");
+    if (await fs.pathExists(securityDir)) {
+      await fs.remove(securityDir);
+    }
     const replacePathsInDir = async (dir) => {
       const entries = await fs.readdir(dir, { withFileTypes: true });
       for (const entry of entries) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccg-workflow",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "Claude + Codex + Gemini multi-model collaboration system - smart routing development workflow",
   "type": "module",
   "packageManager": "pnpm@10.17.1",

package/templates/engine/model-router.md

@@ -46,8 +46,14 @@ Read ~/.claude/.ccg/config.toml
 | 不确定 | 双模型并行 | 各用对应 debugger |
 
 ### 实施阶段
-- 外部模型**仅提供建议**，Claude 执行所有文件修改
-- 外部模型有**零文件写入权限**
+
+**默认模式**（Claude 执行）：
+- 外部模型仅提供建议，Claude 执行所有文件修改
+
+**Codex Builder 模式**（用户选择时）：
+- backend 模型 + `$BACKEND/builder.md` — **有完整写权限**，直接写代码到文件系统
+- Claude 监控进度，审查产出，必要时接管
+- 适用于 M-L 复杂度、低中风险的明确实施任务
 
 ## 3. 调用模板
 
@@ -71,7 +77,7 @@ Bash({
 
 变量说明：
 - `$MODEL` — 选定的模型名（`codex` / `gemini` / `claude`）
-- `$ROLE` — 角色文件名（`analyzer` / `architect` / `reviewer` / `debugger` / `optimizer` / `tester`）
+- `$ROLE` — 角色文件名（`analyzer` / `architect` / `reviewer` / `debugger` / `optimizer` / `tester` / `builder`）
 - `$TASK_CONTENT` — 任务内容（需求 + 上下文）
 - `$OUTPUT_FORMAT` — 期望输出格式
 - `$SHORT_DESCRIPTION` — 简短描述（用于进度显示）

package/templates/engine/phase-guide.md

@@ -93,3 +93,115 @@ TeamCreate 失败（Agent Teams 未启用）→ Claude 自己按计划顺序实
 - 代码块标明语言
 - 变更摘要用 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` 字段 = 注入所有角色。

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

@@ -144,6 +144,13 @@ Gate: 用户已确认修复方向 ✓
      📍 Next: /ccg commit 提交修复
    ```
 
+#### Spec Evolution（归档前必须执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 分析本次调试的根因和修复方案，提炼可复用的调试经验和防御性编码约定
+2. 如有值得记录的经验（特别是非显而易见的坑）→ 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过
+
 **Task 更新**：`status → "archived"`
 
 **归档任务**：

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

@@ -136,19 +136,31 @@ TaskOutput({ task_id: "$FRONTEND_TASK_ID", block: true, timeout: 600000 })
   nextAction → "等待用户审批计划"
 ```
 
-**⛔ HARD STOP**：展示完整计划，并告知用户：
+**⛔ HARD STOP**：展示完整计划，并询问用户选择执行模式：
+
 ```
-审批后将使用 Agent Teams 并行实施（多个 Builder 同时写代码）。
+⛔ 计划审批 + 执行模式选择
+
+请审批以上计划，并选择谁来写代码：
+  [1] Agent Teams（Claude Builders 并行写，多文件同时进行）
+  [2] Codex（Codex 写代码，更快更便宜，Claude 监控审查）
 ```
-等待用户明确审批。未审批不可进入 Phase 4。
+
+等待用户明确审批 + 选择。未审批不可进入 Phase 4。
 
 用户确认后：`task.json: gate → null`
 
-### Phase 4: 实施（Agent Teams 并行）
+### Phase 4: 实施
 
 `[模式：执行]`
 
-**Gate check**: 用户已审批计划
+**Gate check**: 用户已审批计划 + 选择了执行模式
+
+根据用户选择的执行模式执行：
+
+---
+
+#### 模式 A: Agent Teams 并行（用户选 [1]）
 
 **⛔⛔⛔ 你的第一个动作必须是 TeamCreate。不是 Write，不是 Bash，不是 Read，是 TeamCreate。⛔⛔⛔**
 
@@ -225,21 +237,56 @@ SendMessage({ to: "reviewer", message: { type: "shutdown_request" } })
 2. 按 plan.md 中的 Layer 顺序逐文件实施
 3. 仍然遵守质量关卡
 
-### Phase 5: 优化审查 + 质量关卡 [required]
+---
+
+#### 模式 B: Codex 实施（用户选 [2]）
+
+**Task 更新**：`currentPhase → "4-implementation"`, `nextAction → "Codex Builder 执行 plan"`
+
+Claude 作为主导者，调用 Codex 写代码：
+
+**Step 1**: 将 plan.md 转为 Codex 可执行的任务描述（包含具体文件路径、变更说明、验证命令）
+
+**Step 2**: 调用 codeagent-wrapper + builder 角色：
+
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend codex {{GEMINI_MODEL_FLAG}}- \"$WORKDIR\" <<'CODEAGENT_EOF'\nROLE_FILE: ~/.claude/.ccg/prompts/codex/builder.md\n<TASK>\n按以下计划实施，逐个任务完成并验证。\n\n{plan.md 完整内容，包含文件路径、具体变更、验证命令}\n</TASK>\nOUTPUT: Execution Report (每个 task 的 PASS/FAIL + 变更文件列表)\nCODEAGENT_EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "Codex Builder: 执行实施计划"
+})
+```
+
+**Step 3**: 等待 Codex 完成，读取执行报告
+
+**Step 4**: Claude 审查产出：
+1. `git diff` 检查所有变更
+2. 确认变更在 plan 范围内（scope check）
+3. 如有小问题（<10 行）→ Claude 直接修复
+4. 如有大问题 → 再次调用 Codex 修复，或切换到 Claude 自己写
+
+**降级**：如果 Codex 返回错误或超时 → 告知用户 "Codex 执行失败，切换到 Agent Teams" → 按模式 A 执行
+
+### Phase 5: 迭代审查 [required · Ralph Loop]
 
 `[模式：优化]`
 
 **Gate check**: 实施已完成
 
-**Task 更新**：`currentPhase → "5-optimization"`, `nextAction → "双模型审查 + 质量关卡"`
+**Task 更新**：`currentPhase → "5-optimization"`, `nextAction → "Ralph Loop Round 1: 双模型审查 + 质量关卡"`
+
+参考 `phase-guide.md § 10 Ralph Loop` 执行迭代审查。最多 3 轮。
 
-#### 5a. 双模型交叉审查
+#### Round N 流程（N=1,2,3）
 
-**并行调用**：
+**5a. 双模型交叉审查（每轮 spawn 新 Agent，干净上下文）**
+
+**并行调用**（`run_in_background: true`）：
 - **backend 模型**：reviewer 角色 — 关注安全、性能、错误处理
 - **frontend 模型**：reviewer 角色 — 关注可访问性、设计一致性
 
-#### 5b. 质量关卡
+**5b. 质量关卡**
 
 **⛔ 以下 Skill 必须逐个调用执行，不可跳过，不可用自己的判断替代：**
 
@@ -247,17 +294,35 @@ SendMessage({ to: "reviewer", message: { type: "shutdown_request" } })
 2. 调用 Skill `verify-quality` — 等待报告
 3. 调用 Skill `verify-change` — 等待报告
 
-任何关卡报告 **Critical** → 必须修复后重新运行该关卡，才能进入 Phase 6。
-
-#### 5c. 综合报告
+**5c. 综合报告**
 
 整合审查意见 + 质量关卡结果，按严重度分级：
 - **Critical**：必须修复（阻塞交付）
 - **Warning**：建议修复
 - **Info**：供参考
 
-展示审查结果，用户确认后执行必要的优化。
-**持久化**：写入 `.ccg/tasks/{task-name}/review.md`
+**持久化**：写入 `.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: 最终验收
 
@@ -277,6 +342,13 @@ SendMessage({ to: "reviewer", message: { type: "shutdown_request" } })
      📍 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}/`

package/templates/engine/strategies/guided-develop.md

@@ -145,7 +145,17 @@ TaskOutput({ task_id: "<id>", block: true, timeout: 600000 })
   nextAction → "等待用户审批计划"
 ```
 
-**⛔ HARD STOP**：展示计划，等待用户确认后才能进入 Phase 5。
+**⛔ HARD STOP**：展示计划，并询问用户选择执行模式：
+
+```
+⛔ 计划审批 + 执行模式选择
+
+请审批以上计划，并选择谁来写代码：
+  [1] Claude 自己写（精细控制，逐步实施）
+  [2] Codex（Codex 写代码，更快更便宜，Claude 监控审查）
+```
+
+等待用户明确审批 + 选择。
 
 用户确认后：
 ```
@@ -154,40 +164,75 @@ TaskOutput({ task_id: "<id>", block: true, timeout: 600000 })
 
 ### Phase 5: 实施
 
+根据用户选择的执行模式：
+
+#### 模式 A: Claude 自己写（用户选 [1]）
+
 1. 严格按计划执行
 2. 遵循项目现有代码规范
 3. 每完成一个主要步骤，简要报告进度
 4. 遇到计划外的问题时告知用户，不自行扩大范围
 
+#### 模式 B: Codex 实施（用户选 [2]）
+
+Claude 作为主导者调用 Codex 写代码：
+
+1. 将 plan.md 转为 Codex 可执行的任务描述
+2. 调用 codeagent-wrapper + builder 角色（参考 model-router.md 调用模板，`$ROLE = builder`）
+3. 等待 Codex 完成，读取执行报告
+4. `git diff` 审查产出，确认在 plan 范围内
+5. 小问题 Claude 直接修复，大问题再调 Codex 或切换模式 A
+
+**降级**：Codex 失败/超时 → 切换到模式 A
+
 **Task 更新**：`currentPhase → "5-implement"`, `nextAction → "按计划执行实施"`
 
-### Phase 6: 验证 + 双模型审查 + 质量关卡
+### Phase 6: 迭代审查 [Ralph Loop]
 
 1. `git diff` 展示所有变更
 2. 运行测试（如果有）
 
-**⛔ 双模型交叉审查（变更 >30 行时必须执行）：**
+参考 `phase-guide.md § 10 Ralph Loop` 执行迭代审查（变更 >30 行时，最多 3 轮）。
+
+#### Round N 流程
+
+**⛔ 双模型交叉审查（每轮 spawn 新调用，干净上下文）：**
 3. 并行调用双模型（`run_in_background: true`，使用 model-router.md 模板）：
    - backend 模型 + reviewer 角色 — 安全、性能、错误处理
    - frontend 模型 + reviewer 角色 — 设计一致性（如涉及前端）
 4. 综合审查意见
 
-**⛔ 质量关卡（变更 >30 行时必须逐个调用 Skill，不可跳过）：**
+**⛔ 质量关卡（必须逐个调用 Skill，不可跳过）：**
 5. 调用 Skill `verify-quality` — 等待报告
 6. 调用 Skill `verify-security` — 等待报告（涉及 auth/input/crypto 时）
 7. 调用 Skill `verify-change` — 等待报告
-8. Critical 问题必须修复
-4. 检查是否满足验收标准
-5. 输出结果：
+
+**用户决定（⛔ 必须等待）：**
+- 有 Critical → `发现 N 个 Critical 问题。修复后再审一轮？[Y/n]`
+- 无 Critical → `审查通过。需要再审一轮？[y/N]`
+- 用户选择继续 → 修复 Critical 后回到 Round N+1
+- 用户选择停止 → 退出审查循环
+
+追加进度到 `.ccg/tasks/{task-name}/fix-log.jsonl`。
+
+8. 检查是否满足验收标准
+9. 输出结果：
    ```
    ✅ 开发完成
      变更: [N] 文件，[M] 行
      实现: [摘要]
      测试: [通过/跳过/失败情况]
-     质量: [Critical: N, Warning: N, Info: N]
+     审查: [N] 轮，[Critical: N, Warning: N, Info: N]
      📍 Next: 可以用 /ccg:commit 提交
    ```
 
+#### Spec Evolution（归档前必须执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 分析本次 `git diff` + 审查结果，提炼可复用的编码约定
+2. 如有值得记录的经验 → 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过
+
 **Task 更新**：`status → "archived"`
 
 **归档任务**：

package/templates/engine/strategies/refactor-safely.md

@@ -110,12 +110,16 @@ Gate: 所有步骤已执行 ✓
 Step [N/M]: [描述] — ✅ 测试通过 / ❌ 测试失败
 ```
 
-### Phase 5: 最终验证 + 双模型审查 + 质量关卡
+### Phase 5: 迭代审查 [Ralph Loop]
 
 1. 运行完整测试套件
 2. 对比基线：确保不引入新的失败
 
-**⛔ 双模型交叉审查（必须执行，使用 model-router.md 调用模板）：**
+参考 `phase-guide.md § 10 Ralph Loop` 执行迭代审查（最多 3 轮）。
+
+#### Round N 流程
+
+**⛔ 双模型交叉审查（每轮 spawn 新调用，干净上下文）：**
 
 3. 获取变更：`git diff` 全量输出
 4. 并行调用双模型审查（`run_in_background: true`）：
@@ -129,22 +133,35 @@ Step [N/M]: [描述] — ✅ 测试通过 / ❌ 测试失败
 7. 调用 Skill `verify-security` — 等待报告
 8. 调用 Skill `verify-change` — 等待报告
 
-**综合报告**：双模型审查 + 质量关卡，按严重度分级：
-- Critical → 必须修复后重新验证
-- Warning → 建议修复
-- Info → 供参考
+**综合报告**：双模型审查 + 质量关卡，按严重度分级
+
+**用户决定（⛔ 必须等待）：**
+- 有 Critical → `发现 N 个 Critical 问题。修复后再审一轮？[Y/n]`
+- 无 Critical → `审查通过。需要再审一轮？[y/N]`
+- 用户选择继续 → 修复后回到 Round N+1
+- 用户选择停止 → 退出审查循环
+
+追加进度到 `.ccg/tasks/{task-name}/fix-log.jsonl`。
 
 9. `git diff` 展示全部变更
-5. 输出结果：
+10. 对比基线，确认无回归
+11. 输出结果：
    ```
    ✅ 重构完成
      步骤: [N] 步全部通过
      变更: [文件数] 文件，[行数] 行
      测试: 基线 [N] 通过 → 重构后 [N] 通过
-     质量: [Critical: N, Warning: N, Info: N]
+     审查: [N] 轮，[Critical: N, Warning: N, Info: N]
      📍 Next: /ccg:commit 提交
    ```
 
+#### Spec Evolution（归档前必须执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 分析本次重构的 `git diff`，提炼可复用的重构模式和架构约定
+2. 如有值得记录的经验 → 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过
+
 **Task 更新**：`status → "archived"`
 
 **归档任务**：

package/templates/engine/strategies/review-audit.md

@@ -106,6 +106,13 @@ Gate: 双模型审查已返回 ✓
 
 如果有 Critical 发现，询问用户是否立即修复（可切换到 `direct-fix` 策略）。
 
+#### Spec Evolution（审查完成后执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 从审查发现中提炼可复用的编码规范（特别是 Critical/Warning 级反复出现的模式）
+2. 如有值得记录的经验 → 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过
+
 ---
 
 ## 铁律

package/templates/hooks/subagent-context.js

@@ -3,6 +3,8 @@
 // Injects spec + task context when:
 //   1. codeagent-wrapper is about to be called (Bash)
 //   2. Agent Team member is about to be spawned (Agent)
+// Supports role-based filtering: context.jsonl entries with "roles" field
+// are only injected when the agent's detected role matches.
 
 'use strict';
 
@@ -28,12 +30,11 @@ try {
   // Determine trigger type
   const command = toolInput.command || '';
   const teamName = toolInput.team_name || '';
-  const agentPrompt = toolInput.prompt || '';
+  const agentName = toolInput.name || '';
 
   const isCodeagentCall = command.includes('codeagent-wrapper');
   const isTeamSpawn = !!teamName;
 
-  // Only activate for codeagent-wrapper calls or Agent Team spawns
   if (!isCodeagentCall && !isTeamSpawn) {
     process.exit(0);
   }
@@ -45,20 +46,60 @@ try {
   const task = getActiveTask(root);
   if (!task) process.exit(0);
 
+  // --- Role detection ---
+  const ROLE_FILE_MAP = {
+    'reviewer': 'review',
+    'analyzer': 'research',
+    'debugger': 'debug',
+    'tester': 'review',
+    'architect': 'implement',
+    'optimizer': 'implement',
+    'frontend': 'implement'
+  };
+  const AGENT_NAME_PATTERNS = [
+    { pattern: /dev|builder|fix|impl/i, role: 'implement' },
+    { pattern: /review|check|audit/i, role: 'review' },
+    { pattern: /research|scout|explore|analy/i, role: 'research' },
+    { pattern: /debug|diagnos/i, role: 'debug' }
+  ];
+
+  let detectedRole = 'implement'; // default
+
+  if (isCodeagentCall) {
+    const roleMatch = command.match(/ROLE_FILE:.*\/(\w+)\.md/);
+    if (roleMatch) {
+      detectedRole = ROLE_FILE_MAP[roleMatch[1]] || 'implement';
+    }
+  } else if (isTeamSpawn && agentName) {
+    for (const { pattern, role } of AGENT_NAME_PATTERNS) {
+      if (pattern.test(agentName)) {
+        detectedRole = role;
+        break;
+      }
+    }
+  }
+
   const contextParts = [];
 
-  // Inject active task info for team members
   if (isTeamSpawn) {
     contextParts.push(`<ccg-active-task>
 Active task: ${task.dir}
 Task: ${task.title || task.id} (${task.status})
 Strategy: ${task.strategy}
 Phase: ${task.currentPhase}
+Agent role: ${detectedRole}
 </ccg-active-task>`);
   }
 
-  // Read context.jsonl entries (specs + research refs)
-  const entries = readContextJsonl(task.dir);
+  // Read context.jsonl with role-based filtering
+  const allEntries = readContextJsonl(task.dir);
+  const entries = allEntries.filter(entry => {
+    if (!entry.roles || !Array.isArray(entry.roles) || entry.roles.length === 0) {
+      return true; // no roles field = inject to all
+    }
+    return entry.roles.includes(detectedRole) || entry.roles.includes('all');
+  });
+
   if (entries.length > 0) {
     const specContents = [];
     for (const entry of entries) {
@@ -75,7 +116,7 @@ Phase: ${task.currentPhase}
     }
   }
 
-  // Read PRD and plan
+  // Read PRD and plan (always inject, role-independent)
   const prd = readFileSafe(path.join(task.dir, 'requirements.md'));
   const plan = readFileSafe(path.join(task.dir, 'plan.md'));
 
@@ -93,21 +134,23 @@ Phase: ${task.currentPhase}
     contextParts.push(taskContext.join('\n'));
   }
 
-  // Read research files
-  const researchDir = path.join(task.dir, 'research');
-  if (fs.existsSync(researchDir)) {
-    try {
-      const researchFiles = fs.readdirSync(researchDir).filter(f => f.endsWith('.md'));
-      if (researchFiles.length > 0) {
-        const researchContents = researchFiles.map(f => {
-          const content = readFileSafe(path.join(researchDir, f));
-          return content ? `--- research/${f} ---\n${content.substring(0, 1500)}` : null;
-        }).filter(Boolean);
-        if (researchContents.length > 0) {
-          contextParts.push(`<ccg-research>\n${researchContents.join('\n\n')}\n</ccg-research>`);
+  // Read research files (only for research + implement roles)
+  if (detectedRole === 'research' || detectedRole === 'implement') {
+    const researchDir = path.join(task.dir, 'research');
+    if (fs.existsSync(researchDir)) {
+      try {
+        const researchFiles = fs.readdirSync(researchDir).filter(f => f.endsWith('.md'));
+        if (researchFiles.length > 0) {
+          const researchContents = researchFiles.map(f => {
+            const content = readFileSafe(path.join(researchDir, f));
+            return content ? `--- research/${f} ---\n${content.substring(0, 1500)}` : null;
+          }).filter(Boolean);
+          if (researchContents.length > 0) {
+            contextParts.push(`<ccg-research>\n${researchContents.join('\n\n')}\n</ccg-research>`);
+          }
         }
-      }
-    } catch { /* silent */ }
+      } catch { /* silent */ }
+    }
   }
 
   if (contextParts.length === 0) process.exit(0);

package/templates/hooks/task-utils.js

@@ -152,6 +152,27 @@ function seedContextJsonl(taskDir, projectRoot) {
   try { fs.writeFileSync(jsonlPath, lines.join('\n') + '\n', 'utf-8'); } catch { /* silent */ }
 }
 
+function trackTurn(taskDir, phase, nextAction) {
+  const turnsPath = path.join(taskDir, '.turns.json');
+  let turns = [];
+  try { turns = JSON.parse(fs.readFileSync(turnsPath, 'utf-8')); } catch { /* fresh */ }
+  turns.push({ phase: phase || '', next: nextAction || '', ts: Date.now() });
+  if (turns.length > 10) turns = turns.slice(-10);
+  try { fs.writeFileSync(turnsPath, JSON.stringify(turns), 'utf-8'); } catch { /* silent */ }
+  return turns;
+}
+
+function detectLoop(turns, threshold) {
+  threshold = threshold || 3;
+  if (turns.length < threshold) return null;
+  const recent = turns.slice(-threshold);
+  const key = `${recent[0].phase}|${recent[0].next}`;
+  const allSame = recent.every(t => `${t.phase}|${t.next}` === key);
+  if (!allSame) return null;
+  const elapsed = (recent[recent.length - 1].ts - recent[0].ts) / 1000;
+  return { phase: recent[0].phase, nextAction: recent[0].next, count: threshold, elapsedSec: Math.round(elapsed) };
+}
+
 module.exports = {
   findProjectRoot,
   getActiveTask,
@@ -163,5 +184,7 @@ module.exports = {
   outputHook,
   archiveTask,
   autoCommitTask,
-  seedContextJsonl
+  seedContextJsonl,
+  trackTurn,
+  detectLoop
 };

package/templates/hooks/workflow-state.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 // CCG Workflow State Hook — UserPromptSubmit
 // Injects per-turn breadcrumb based on active task state.
+// Includes loop detection: warns when same phase+nextAction repeats 3+ turns.
 // Runs on EVERY user message. Must be fast (<1s) and never crash.
 
 'use strict';
 
 try {
-  const { findProjectRoot, getActiveTask, outputHook } = require('./task-utils.js');
+  const { findProjectRoot, getActiveTask, outputHook, trackTurn, detectLoop } = require('./task-utils.js');
 
   const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const root = findProjectRoot(cwd);
@@ -19,6 +20,9 @@ try {
     process.exit(0);
   }
 
+  const turns = trackTurn(task.dir, task.currentPhase, task.nextAction);
+  const loop = detectLoop(turns, 3);
+
   const lines = [
     '<ccg-state>',
     `Task: ${task.title || task.id} (${task.status})`,
@@ -31,6 +35,18 @@ try {
   }
 
   lines.push(`Next: ${task.nextAction || 'Continue current phase'}`);
+
+  if (loop) {
+    lines.push('');
+    lines.push(`⚠️ LOOP DETECTED: Phase "${loop.phase}" with same nextAction repeated ${loop.count} turns (${loop.elapsedSec}s).`);
+    lines.push('🔄 BREAK-LOOP PROTOCOL:');
+    lines.push('  1. STOP current approach immediately');
+    lines.push('  2. Root-cause analysis: why is this phase not progressing?');
+    lines.push('  3. Options: (a) try alternative approach, (b) escalate to user, (c) upgrade strategy');
+    lines.push('  4. If blocked by external dependency → tell user explicitly');
+    lines.push('  5. Do NOT repeat the same action — that is what caused this loop');
+  }
+
   lines.push('</ccg-state>');
 
   outputHook('UserPromptSubmit', lines.join('\n'));

package/templates/prompts/codex/builder.md

@@ -0,0 +1,61 @@
+# Codex Role: Builder (Implementation Agent)
+
+> For: /ccg:go strategies Phase 4/5 (execution), when user selects Codex as executor
+
+You are an implementation engineer. Claude has already planned the work — your job is to **write the code** exactly as specified in the plan.
+
+## PERMISSIONS
+
+- **FULL file system write permission** - You CAN and SHOULD create/modify/delete files
+- **FULL shell access** - You CAN run tests, linters, build commands
+- You operate in the project working directory provided
+
+## Execution Rules
+
+1. **Read context first** — Before writing, read all files referenced in the plan to understand existing patterns
+2. **Follow the plan exactly** — Do not add features, refactor, or "improve" things not in the plan
+3. **One task at a time** — Complete each task fully before moving to the next
+4. **Validate after each task** — Run the specified test/lint command after each change
+5. **Fix validation failures** — If a test fails after your change, fix it (max 3 attempts per task)
+6. **Stay in scope** — Only modify files listed in the plan. If you discover a necessary change outside scope, note it in your output but do NOT make it
+7. **Report progress** — After each task, output a status line
+
+## Output Format
+
+After completing all tasks, output a summary:
+
+```
+## Execution Report
+
+### Task 1: [description]
+- Status: PASS / FAIL
+- Files changed: [list]
+- Validation: [command] → [pass/fail]
+
+### Task 2: [description]
+- Status: PASS / FAIL
+- Files changed: [list]
+- Validation: [command] → [pass/fail]
+
+---
+OVERALL: [PASS/FAIL]
+Total files changed: [N]
+All validations passed: [yes/no]
+```
+
+## What NOT to Do
+
+- ❌ Do NOT refactor code outside the plan scope
+- ❌ Do NOT add comments explaining your changes
+- ❌ Do NOT install new dependencies unless the plan explicitly says to
+- ❌ Do NOT modify test files unless the plan explicitly includes them
+- ❌ Do NOT ask questions — if the plan is ambiguous, make the simplest choice that satisfies the spec
+
+## .context Awareness
+
+If the project has a `.context/` directory:
+1. Read `.context/prefs/coding-style.md` before writing code — follow those conventions
+2. Follow all coding conventions defined in prefs/
+
+If the project has `.ccg/spec/`:
+1. Read relevant spec files — follow those coding standards

package/templates/rules/ccg-skill-routing.md

@@ -4,7 +4,11 @@ When the user's request matches trigger keywords below, automatically READ the c
 
 **IMPORTANT**: Read the skill file FIRST, then respond. Do NOT fabricate domain knowledge from training data when a skill file exists.
 
-## Security Domain (`domains/security/`)
+## Security Domain (`domains/security/`) — NOT installed by default
+
+> Security domain files contain red team/pentest reference content that may trigger antivirus false positives.
+> They are NOT installed by default. To enable, manually copy from the npm package:
+> `cp -r $(npm root -g)/ccg-workflow/templates/skills/domains/security/ ~/.claude/skills/ccg/domains/security/`
 
 | Trigger Keywords | Skill File | Description |
 |------------------|-----------|-------------|