cc-devflow 1.0.3 → 2.4.0

package/.claude/commands/flow-dev.md

@@ -1,28 +1,99 @@
 ---
 name: flow-dev
-description: 'Execute development tasks following TDD order. Usage: /flow-dev "REQ-123" or /flow-dev'
+description: 'Execute development tasks following TDD order. Usage: /flow-dev "REQ-123" [--manual] [--max-iterations N]'
 scripts:
   prereq: .claude/scripts/check-prerequisites.sh
   check_tasks: .claude/scripts/check-task-status.sh
   mark_task: .claude/scripts/mark-task-complete.sh
   validate_constitution: .claude/scripts/validate-constitution.sh
+  verify_gate: .claude/scripts/verify-gate.sh
+  setup_loop: .claude/scripts/setup-ralph-loop.sh
+skills:
+  tdd: .claude/skills/flow-tdd/SKILL.md
+  verification: .claude/skills/verification-before-completion/SKILL.md
+  attention: .claude/skills/flow-attention-refresh/SKILL.md
 ---
 
 # Flow-Dev - 开发执行命令
 
+## TDD Iron Law (新增)
+
+参考 `{SKILL:tdd}`:
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+### TDD Checkpoint
+
+在 Phase 2 (Tests) 和 Phase 3 (Implementation) 之间，必须执行：
+
+```yaml
+⚠️ TEST VERIFICATION CHECKPOINT:
+  1. 运行所有 Phase 2 测试
+     → npm test (或 quickstart 中的测试命令)
+
+  2. 验证所有新测试 FAIL
+     → 如果任何测试 PASS → STOP
+     → 通过的测试 = 无效测试或代码已存在
+
+  3. 只有全部 FAIL 后才能进入 Phase 3
+
+  4. 如果已经写了实现代码:
+     → DELETE 代码
+     → 重新从 failing tests 开始
+```
+
+### Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Tests are ready, let's implement" | Run tests first. Verify they FAIL. |
+| "I'll run tests after implementation" | That's testing-after, not TDD. |
+| "Test passed, that's good" | Test passing before implementation = invalid test. |
+| "Just this once" | No exceptions. TDD is non-negotiable. |
+
 ## User Input
 ```text
-$ARGUMENTS = "REQ_ID? [--task T###]"
+$ARGUMENTS = "REQ_ID? [--task T###] [--manual] [--max-iterations N]"
+```
+
+- **REQ_ID**: 未提供时从当前分支或 `DEVFLOW_REQ_ID` 推断
+- **--task T###**: 指定起始任务（从该任务开始执行）
+- **--manual**: Manual模式，遇错停止等待人工修复（向后兼容）
+- **--max-iterations N**: Autonomous模式最大迭代次数（默认10）
+
+**默认行为**: Autonomous模式（自动重试直到完成）
+
+### 运行模式对比
+
+| | Manual模式 | Autonomous模式（默认） |
+|--|------------|----------------------|
+| 触发方式 | `--manual` | 默认（或指定 `--max-iterations`） |
+| 遇到错误 | 停止，等待人工修复 | 自动重试，记录 ERROR_LOG.md |
+| 注意力刷新 | Protocol 2（每任务） | Protocol 2 + Protocol 3（每迭代） + Protocol 4（遇错） |
+| 适用场景 | 复杂需求需人工判断 | 清晰需求可无人值守 |
+| 退出条件 | 任务失败可停止 | 迭代直到完成或达到上限 |
+
+**示例**:
+```bash
+/flow-dev "REQ-123"                      # Autonomous模式，max 10 iterations
+/flow-dev "REQ-123" --max-iterations 20  # Autonomous模式，max 20 iterations
+/flow-dev "REQ-123" --manual             # Manual模式，遇错停止
+/flow-dev "REQ-123" --task T005          # 从 T005 开始（Autonomous模式）
+/flow-dev "REQ-123" --task T005 --manual # 从 T005 开始（Manual模式）
 ```
-未提供 REQ_ID 时从当前分支或 `DEVFLOW_REQ_ID` 推断；`--task` 用于指定起始任务。
 
 ## 执行流程
 
 ### 阶段 1: Entry Gate
 ```
-1. 解析 REQ_ID 与 --task
-   → If argument provided: split
-   → Else: run {SCRIPT:prereq} --json --paths-only
+1. 解析参数
+   → Parse: REQ_ID, --task, --manual, --max-iterations
+   → If REQ_ID not provided: run {SCRIPT:prereq} --json --paths-only
+   → Determine mode:
+      • --manual flag present → Manual mode
+      • Otherwise → Autonomous mode (default max_iterations = 10)
 
 2. 校验资产
    → 必须存在（/flow-tech 产物）:
@@ -43,7 +114,16 @@ $ARGUMENTS = "REQ_ID? [--task T###]"
    → Phase 顺序: Setup → Foundational → Phase 2 Tests First → ⚠️ Test Verification → Phase 3 Core Implementation → ...
    → 任务格式 `- [ ] T### [P?] [US?] Description (path)`
 
-4. 起始任务
+4. 模式初始化
+   → If Autonomous mode:
+      • Run: {SCRIPT:setup_loop} "${REQ_ID}" --max-iterations ${MAX_ITERATIONS}
+      • Creates .claude/ralph-loop.local.md (state file for Stop Hook)
+      • Creates ERROR_LOG.md if not exists
+      • Log to EXECUTION_LOG.md: "Starting Autonomous mode"
+   → If Manual mode:
+      • Log to EXECUTION_LOG.md: "Starting Manual mode"
+
+5. 起始任务
    → Run: {SCRIPT:check_tasks} --json
    → 若指定 --task，验证任务存在且未完成
    → 记录下一任务 ID
@@ -76,10 +156,18 @@ $ARGUMENTS = "REQ_ID? [--task T###]"
 4. 在 EXECUTION_LOG.md 记录 quickstart 版本 + STYLE.md 版本（如有）
 ```
 
-### 阶段 3: TDD 循环
+### 阶段 3: 执行循环
+
+**Manual 模式循环** (--manual):
 ```
 For each remaining task (顺序严格遵循 TASKS.md):
 
+**注意力刷新** (参见 {SKILL:attention} Protocol 2):
+→ Read: TASKS.md 当前任务 T### 段落 + DoD
+→ Read: quickstart.md 相关命令
+→ Focus: 这个任务的验收标准是什么？
+→ Then: 开始执行任务
+
 1. 读取任务定义
    → 提取 task id、phase、文件路径、是否 [P]
 
@@ -97,21 +185,93 @@ For each remaining task (顺序严格遵循 TASKS.md):
    → 测试失败/成功状态符合阶段要求
    → 文件路径与任务描述一致
 
-4. 标记完成
-   → Run: {SCRIPT:mark_task} T###
+4. 错误处理 (Manual 模式)
+   → 遇到错误 → 停止执行
+   → 提示用户修复问题
+   → 可选：记录到 ERROR_LOG.md
+
+5. 标记完成 (CRITICAL)
+   → Run: {SCRIPT:mark_task} T### (MANDATORY)
+   → 必须执行此脚本将 TASKS.md 中的 [ ] update 为 [x]
+   → 如果不执行此脚本，Check Tasks 将认为任务未完成并导致死循环
    → Git 提交 (一任务一提交)
 ```
 
+**Autonomous 模式循环** (默认):
+```
+FOR iteration in 1..max_iterations:
+
+  ┌──────────────────────────────────────────────────────┐
+  │ Step A: 注意力刷新 (Protocol 2 + Protocol 3)         │
+  ├──────────────────────────────────────────────────────┤
+  │ → Read: TASKS.md 第一个未完成任务 `- [ ]`             │
+  │ → Read: ERROR_LOG.md 最近 5 条记录（如存在）          │
+  │ → Read: quickstart.md 相关命令                        │
+  │ → Focus: 下一步行动 + 避免重复错误                     │
+  └──────────────────────────────────────────────────────┘
+
+  ┌──────────────────────────────────────────────────────┐
+  │ Step B: 执行任务 (TDD 方式)                           │
+  ├──────────────────────────────────────────────────────┤
+  │ → 提取任务 ID, phase, 文件路径                        │
+  │ → 遵循 {SKILL:tdd} 执行                              │
+  │ → Phase 2: 写测试，验证 FAIL                          │
+  │ → Phase 3: 写实现，验证 PASS                          │
+  │ → 后续 Phase: 按任务描述完成                          │
+  └──────────────────────────────────────────────────────┘
+
+  ┌──────────────────────────────────────────────────────┐
+  │ Step C: 错误处理 (Autonomous 自动重试)                │
+  ├──────────────────────────────────────────────────────┤
+  │ IF test fails OR build error:                        │
+  │   → Record error to ERROR_LOG.md (强制)              │
+  │   → Apply Protocol 4 (Error Recovery)                │
+  │   → Analyze root cause                               │
+  │   → Fix and re-run tests                             │
+  │   → Update ERROR_LOG.md with resolution              │
+  │ ELSE:                                                │
+  │   → Task succeeded                                   │
+  │   → Run: {SCRIPT:mark_task} T### (CRITICAL: MUST RUN)│
+  │   → NEVER skip this step. Task is NOT done until marked.│
+  │   → Git commit (one task per commit)                 │
+  └──────────────────────────────────────────────────────┘
+
+  ┌──────────────────────────────────────────────────────┐
+  │ Step D: 完成检查                                      │
+  ├──────────────────────────────────────────────────────┤
+  │ → Run: {SCRIPT:check_tasks} --json                   │
+  │ → IF remaining_tasks == 0:                           │
+  │     → Output "AUTONOMOUS_COMPLETE"                   │
+  │     → BREAK (Exit loop successfully)                 │
+  │ → ELSE IF iteration == max_iterations:               │
+  │     → Output status report                           │
+  │     → BREAK (Reached limit)                          │
+  │ → ELSE:                                              │
+  │     → Continue to next iteration                     │
+  │     → Stop Hook will re-inject same prompt           │
+  └──────────────────────────────────────────────────────┘
+
+END FOR
+
+Note: Stop Hook (.claude/hooks/ralph-stop-hook.sh) 会在 Autonomous 模式下:
+  • 检测 .claude/ralph-loop.local.md 存在
+  • 阻止退出，重新注入任务继续 prompt
+  • 直到 remaining_tasks == 0 或达到 max_iterations
+```
+
 ### 阶段 4: Exit Gate
 ```
 1. 所有任务完成?
    → {SCRIPT:check_tasks} --json 确认 remaining=0
 
-2. 代码质量
+2. 清理 Autonomous 状态文件（如存在）
+   → rm .claude/ralph-loop.local.md
+
+3. 代码质量
    → 运行 quickstart 中全量测试命令
    → 可选: {SCRIPT:validate_constitution} --type dev --severity warning
 
-3. 状态更新
+4. 状态更新
    → orchestration_status:
         status = "development_complete"
         completedSteps append "dev"
@@ -119,16 +279,37 @@ For each remaining task (顺序严格遵循 TASKS.md):
 ```
 
 ## 运行提示
-- 始终使用 quickstart 中提供的命令（测试、lint、db migrate 等）。
-- Phase 2 的所有测试必须在实现前失败；若某测试直接通过，回滚并修正。
-- 遵循 TASKS.md 标注的 `[P]` 仅表示逻辑上可并行，实际执行依旧串行。
-- 如需恢复，可使用 `/flow-dev --task TXYZ` 指向首个未完成任务。
+- **默认 Autonomous 模式**: 遇错自动重试，无需人工干预
+- **使用 `--manual` 退出**: 适合需要人工判断的复杂场景
+- **使用 `/cancel-ralph` 停止**: 紧急停止 Autonomous 循环
+- 始终使用 quickstart 中提供的命令（测试、lint、db migrate 等）
+- Phase 2 的所有测试必须在实现前失败；若某测试直接通过，回滚并修正
+- 遵循 TASKS.md 标注的 `[P]` 仅表示逻辑上可并行，实际执行依旧串行
+- 如需恢复，可使用 `/flow-dev --task TXYZ` 指向首个未完成任务
 
 ## 错误处理
-- 缺少资产 → 引导用户先运行 `/flow-tech` 或 `/flow-epic`。
-- quickstart 命令失败 → 输出日志路径，要求修复环境后重试。
-- 任务执行失败 → 保留当前状态，不自动跳过。
+
+**Manual 模式**:
+- 缺少资产 → 引导用户先运行 `/flow-tech` 或 `/flow-epic`
+- quickstart 命令失败 → 输出日志路径，要求修复环境后重试
+- 任务执行失败 → 保留当前状态，停止执行，等待人工修复
+
+**Autonomous 模式**:
+- 缺少资产 → 同 Manual 模式（Entry Gate 阻止）
+- quickstart 命令失败 → 记录 ERROR_LOG.md，分析根因，自动修复，重试
+- 任务执行失败 → 记录 ERROR_LOG.md，Protocol 4 刷新注意力，自动重试
+- 达到 max_iterations → 输出状态报告（已完成/剩余任务），保持 development_in_progress
+- 紧急停止 → 使用 `/cancel-ralph` 删除状态文件，立即终止循环
+
+## 取消 Autonomous 循环
+
+```bash
+/cancel-ralph
+# 检查 .claude/ralph-loop.local.md 存在性
+# 删除状态文件，Stop Hook 将允许退出
+# 输出：Cancelled autonomous loop (was at iteration N)
+```
 
 ## 下一步
-1. 完成所有任务后运行 `/flow-qa` 进入测试与安全审查。
-2. 若有新技术引入，回到 `research/tasks.json` 补记并通知 planner。
+1. 完成所有任务后运行 `/flow-qa` 进入测试与安全审查
+2. 若有新技术引入，回到 `research/tasks.json` 补记并通知 planner

package/.claude/commands/flow-epic.md

@@ -8,10 +8,43 @@ scripts:
 agent_scripts:
   sh: .claude/scripts/update-agent-context.sh __AGENT__
   ps: scripts/powershell/update-agent-context.ps1 -AgentType __AGENT__
+skills:
+  tdd: .claude/skills/flow-tdd/SKILL.md
 ---
 
 # Flow-Epic - Epic 和任务规划命令
 
+## Bite-Sized Tasks 原则
+
+任务必须足够小：
+
+```yaml
+Task 粒度规范:
+  - 每个 step 2-5 分钟可完成
+  - "Write the failing test" = 1 step
+  - "Run it to make sure it fails" = 1 step
+  - "Implement minimal code to pass" = 1 step
+  - "Run tests and verify" = 1 step
+  - "Commit" = 1 step
+
+Task 内容规范:
+  - 精确的文件路径 (不是 "update the config")
+  - 完整的代码片段 (不是 "add validation")
+  - 精确的命令 + 期望输出
+  - 明确的验收标准
+
+Bad Task Examples:
+  ❌ "Implement user authentication"
+  ❌ "Add validation"
+  ❌ "Update the API"
+
+Good Task Examples:
+  ✅ "Create src/auth/login.ts with LoginRequest interface"
+  ✅ "Write failing test: POST /api/login returns 401 for invalid credentials"
+  ✅ "Run npm test -- --grep 'login' and verify test fails"
+  ✅ "Implement login handler to pass the test"
+```
+
 ## User Input
 ```text
 $ARGUMENTS = "REQ_ID?"

package/.claude/commands/flow-fix.md

@@ -1,6 +1,6 @@
 ---
 name: flow-fix
-description: 'One-shot BUG fix flow. Usage: /flow-fix "BUG-123|登录时报 500"'
+description: 'One-shot BUG fix flow with systematic debugging. Usage: /flow-fix "BUG-123|登录时报 500"'
 scripts:
   prereq: .claude/scripts/check-prerequisites.sh
   recover: .claude/scripts/recover-workflow.sh
@@ -8,9 +8,19 @@ scripts:
 agent_scripts:
   sh: .claude/scripts/update-agent-context.sh __AGENT__
   ps: scripts/powershell/update-agent-context.ps1 -AgentType __AGENT__
+skills:
+  debugging: .claude/skills/flow-debugging/SKILL.md
+  verification: .claude/skills/verification-before-completion/SKILL.md
+  tdd: .claude/skills/flow-tdd/SKILL.md
 ---
 
-# Flow-Fix - 一键 BUG 修复流
+# Flow-Fix - 系统化 BUG 修复流
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
 
 ## User Input
 ```text
@@ -23,68 +33,165 @@ BUG_ID 必须满足 `BUG-\d+`；TITLE 为简洁现象描述。
 /flow-fix "BUG-123|登录时报500"
 ```
 
+---
+
+## 核心理念
+
+Bug 修复不是猜测游戏。系统化调试 = 更快修复 + 更少回归。
+
+```
+错误方式: 看到错误 → 猜测原因 → 尝试修复 → 失败 → 再猜...
+正确方式: 看到错误 → 调查根因 → 理解问题 → 写测试 → 修复 → 验证
+```
+
+### Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "我知道问题在哪" | 证明它。先调查。 |
+| "快速修复一下" | 快速修复 = 快速回归。系统化调试。 |
+| "没时间写测试" | 没测试 = 不知道是否真的修好了。 |
+| "这个改动很小" | 小改动也能引入大 bug。测试它。 |
+| "先修复，后调查" | 不理解问题就修复 = 猜测。 |
+| "试试这个" | "试试"不是调试。形成假设，验证它。 |
+
+### Red Flags - STOP
+
+如果你发现自己:
+- 没有复现就开始修复
+- 在"试试这个，试试那个"
+- 3+ 次修复尝试失败
+- 没写测试就说"修好了"
+- 改了很多文件来修一个 bug
+
+**STOP. 回到阶段 1. 调查根因。**
+
+---
+
 ## 执行流程
 
 ### 阶段 0: Entry Gate
 ```
 1. 解析 BUG_ID、TITLE
+   → 若 TITLE 含中文/非ASCII，使用模型意译生成 BRANCH_TITLE_EN（英文语义翻译，禁止拼音/音译）
+   → 若意译不确定或未生成 ASCII 结果，向用户确认英文分支标题
 2. {SCRIPT:prereq} --json 验证:
    → devflow/bugs/${BUG_ID}/ 是否存在（首次执行将创建）
    → Git 工作区干净
 3. 创建目录与分支:
-   → git checkout -b "bugfix/${BUG_ID}-${slug(TITLE)}"
+   → git checkout -b "bugfix/${BUG_ID}-${slug(BRANCH_TITLE_EN)}"
    → 初始化 devflow/bugs/${BUG_ID}/ 结构与 orchestration_status.json
 4. 检查 quickstart.md
    → 若需求目录已有 quickstart.md，复制引用用于测试执行
 ```
 
-### 阶段 1: 分析
+### 阶段 1: Root Cause Investigation (NO FIXES YET)
+
+**Iron Law**: 在这个阶段，**禁止写任何修复代码**。
+
+参考 `{SKILL:debugging}` Phase 1:
+
 ```
-1. 调用 bug-analyzer
-   → 输出 ANALYSIS.md（现象、复现、根因、影响范围）
-2. 更新 orchestration_status: status="analysis_complete"
-3. EXECUTION_LOG 记录分析完成时间
+Step 1: 完整阅读错误信息
+  → 不要跳过任何细节
+  → 记录: 错误类型、消息、堆栈跟踪
+  → 记录: 发生时间、频率、影响范围
+
+Step 2: 稳定复现
+  → 找到可靠的复现步骤
+  → 记录: 输入、环境、前置条件
+  → 如果无法复现 → 收集更多信息
+
+Step 3: 检查最近变更
+  → git log --oneline -20
+  → git diff HEAD~5
+  → 问: 什么变了？何时开始出问题？
+
+Step 4: 逆向追踪数据流
+  → 从错误点向上追踪
+  → 找到数据来源
+  → 识别数据在哪里变坏
 ```
 
-### 阶段 2: 计划
+**输出**: ANALYSIS.md（现象、复现、根因假设、影响范围）
+
+### 阶段 2: Pattern Analysis & Planning
+
+参考 `{SKILL:debugging}` Phase 2:
+
 ```
-1. 调用 planner
+1. 找到正常工作的例子
+   → 类似功能哪里正常工作？
+   → 对比: 正常 vs 异常
+
+2. 与参考实现对比
+   → 官方文档怎么说？
+   → 其他项目怎么做？
+
+3. 调用 planner
    → 输入 ANALYSIS.md、现有 quickstart、代码结构
    → 产出 PLAN.md、tasks/ (TDD 顺序: Root Cause → Failing Test → Fix → Regression)
-2. 调用 qa-tester / security-reviewer
+
+4. 调用 qa-tester / security-reviewer
    → 生成 TEST_PLAN.md、SECURITY_PLAN.md
-3. orchestration_status: status="planning_complete"
 ```
 
-### 阶段 3: 修复执行
+**输出**: PLAN.md, tasks/, TEST_PLAN.md, SECURITY_PLAN.md
+
+### 阶段 3: 修复执行 (TDD)
+
+参考 `{SKILL:tdd}` + `{SKILL:debugging}` Phase 3-4:
+
 ```
-1. 主代理按 tasks/ 顺序执行:
+1. 先写失败测试用例
+   → 测试必须复现 bug
+   → 运行测试，确认失败
+   → 这是你的"红灯"
+
+2. 主代理按 tasks/ 顺序执行:
    → Phase 1: 重现/Root Cause (分析日志、添加监控)
    → Phase 2: Tests First (根据 quickstart 运行失败测试)
-   → Phase 3: Fix Implementation
+   → Phase 3: Fix Implementation (最小化改动)
    → Phase 4: Regression hardening
-2. 每个任务完成后:
+
+3. 每个任务完成后:
    → 运行 quickstart 中相关测试命令
    → Git 提交 (一任务一提交)
    → 更新 tasks/TASK_*.completed
-3. 可用 {SCRIPT:recover} 恢复中断的工作流
+
+4. 3+ 次修复失败 → STOP
+   → 停下来，质疑架构
+   → 可能问题比想象的更深
 ```
 
 ### 阶段 4: 验证与发布
+
+参考 `{SKILL:verification}`:
+
 ```
 1. qa-tester 生成 TEST_REPORT.md（必须全部通过）
 2. security-reviewer 生成 SECURITY_REPORT.md
 3. release-manager 生成 RELEASE_PLAN.md
 4. {SCRIPT:validate_constitution} --type bug_fix --severity warning
 5. orchestration_status: status="fix_complete"
+
+验证清单:
+  □ 根因已记录
+  □ 失败测试已写
+  □ 修复已实现
+  □ 测试通过
+  □ 无回归
+  □ 文档已更新 (如需要)
 ```
 
+---
+
 ## 产物结构
 ```
 devflow/bugs/${BUG_ID}/
-  ANALYSIS.md
-  PLAN.md
-  tasks/
+  ANALYSIS.md              # 根因分析
+  PLAN.md                  # 修复计划
+  tasks/                   # TDD 任务
   TEST_PLAN.md / SECURITY_PLAN.md
   TEST_REPORT.md / SECURITY_REPORT.md
   RELEASE_PLAN.md
@@ -102,3 +209,14 @@ devflow/bugs/${BUG_ID}/
 1. 提交 PR：`fix(${BUG_ID}): <summary>`
 2. 通知相关需求负责人回归验证。
 3. 评估是否需更新研究/技术设计文档以反映修复影响。
+
+---
+
+**Related Documentation**:
+- [flow-debugging](.claude/skills/flow-debugging/SKILL.md) - 4 阶段调试法
+- [flow-tdd](.claude/skills/flow-tdd/SKILL.md) - TDD 原则
+- [verification-before-completion](.claude/skills/verification-before-completion/SKILL.md) - 验证技能
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md