cc-devflow 1.0.2 → 2.4.0

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

@@ -11,8 +11,11 @@ scripts:
 templates:
   flow: .claude/docs/templates/INIT_FLOW_TEMPLATE.md
   research: .claude/docs/templates/RESEARCH_TEMPLATE.md
+  brainstorm: .claude/docs/templates/BRAINSTORM_TEMPLATE.md
 guides:
   troubleshoot: .claude/docs/guides/INIT_TROUBLESHOOTING.md
+skills:
+  brainstorming: .claude/skills/flow-brainstorming/SKILL.md
 ---
 
 <!-- ============================================================
@@ -97,6 +100,9 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?" 或 --interactive
 1. 解析参数: REQ_ID|TITLE|PLAN_URLS
    → 验证 REQ_ID 格式: ^(REQ|BUG)-[0-9]+$
    → 提取 TITLE 和 PLAN_URLS
+   → 若 TITLE 含中文/非ASCII，使用模型意译生成 BRANCH_TITLE_EN（英文语义翻译，禁止拼音/音译）
+   → BRANCH_TITLE_EN 仅用于分支名，文档标题仍使用原始 TITLE
+   → 若意译不确定或未生成 ASCII 结果，向用户确认英文分支标题
 
 2. 前置条件检查
    → Run: {SCRIPT:prereq} --json --paths-only
@@ -112,6 +118,19 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?" 或 --interactive
 
 ---
 
+### Stage 1.2: Git Branch Creation
+
+```
+创建功能分支:
+→ Requirements: feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}
+→ Bug Fixes:    bugfix/${BUG_ID}-${slug(BRANCH_TITLE_EN)}
+
+Where BRANCH_TITLE_EN = TITLE 的英文意译 (语义为准，非拼音，使用模型意译)
+      slug() = lowercase, replace spaces/special chars with hyphens
+```
+
+---
+
 ### Stage 1.5: Context Loading (路线图与架构)
 
 **目标**: 理解需求在项目中的位置
@@ -132,7 +151,7 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?" 或 --interactive
 
 ```
 创建需求目录结构:
-→ Run: {SCRIPT:create} "${REQ_ID}" --title "${TITLE}" --json
+→ Run: {SCRIPT:create} "${REQ_ID}" --title "${TITLE}" --branch-title "${BRANCH_TITLE_EN}" --json (如有)
 
 生成文件:
 - devflow/requirements/${REQ_ID}/README.md
@@ -145,10 +164,89 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?" 或 --interactive
 
 ---
 
+### Stage 2.3: Brainstorming (North Star Capture)
+
+**目标**: 捕捉需求的原始意图，确保后续流程有明确的「北极星」可追溯
+
+**Iron Law**: `NO FLOW EXECUTION WITHOUT BRAINSTORM ALIGNMENT`
+
+```
+触发 flow-brainstorming skill:
+→ 参见 {SKILL:brainstorming} 了解完整流程
+
+执行步骤:
+1. Understanding the Idea
+   → 一次问一个问题，不要压垮用户
+   → 优先多选题，更容易回答
+   → 理解: 目的、约束、成功标准
+
+2. Exploring Approaches
+   → 提出 2-3 种方案及取舍
+   → 给出推荐方案和理由
+   → 让用户做最终决策
+
+3. Presenting the Design
+   → 分段呈现设计 (200-300 字/段)
+   → 每段后确认是否正确
+   → 涵盖: 架构、组件、数据流、测试
+
+4. Documentation
+   → 使用 {TEMPLATE:brainstorm} 模板
+   → 输出: devflow/requirements/${REQ_ID}/BRAINSTORM.md
+   → 必须包含: 原始需求、核心问题、成功标准、方案探索、最终决策
+
+Rationalization Prevention:
+| Excuse | Reality |
+|--------|---------|
+| "需求已经很清楚了" | Brainstorm 确保没有遗漏假设 |
+| "用户赶时间" | 头脑风暴节省后续返工时间 |
+| "这是小需求" | 小需求也有核心问题和成功标准 |
+
+Red Flags - STOP:
+→ 跳过问问题直接开始做
+→ 没有记录方案取舍就选定
+→ 没有写 BRAINSTORM.md 就进入下一阶段
+```
+
+**输出**: `devflow/requirements/${REQ_ID}/BRAINSTORM.md`
+
+**验证**:
+- [ ] BRAINSTORM.md 存在
+- [ ] 包含「原始需求」章节 (用户原话)
+- [ ] 包含「成功标准」章节
+- [ ] 包含「方案探索」章节 (2-3种)
+- [ ] 包含「最终决策」章节
+
+---
+
 ### Stage 2.5: Research (MCP Mandatory Flow)
 
 **目标**: 收集"真实材料"，所有步骤 **MANDATORY**
 
+**Manus 研究方法** (Planning-with-files 融合):
+
+```yaml
+原则 1: 大内容存文件
+  → 抓取的文档存 research/mcp/$(date +%Y%m%d)/
+  → 上下文只保留路径引用
+  → 避免塞满上下文窗口
+
+原则 2: 决策前读取
+  → 每次做研究决策前，先读 research/research.md Decisions 章节
+  → 确保不重复已有决策
+  → 注意力刷新，目标回到窗口
+
+原则 3: 失败尝试记录
+  → 研究中放弃的方案写入 research/attempts/
+  → 说明放弃原因和学习（见 ATTEMPT_TEMPLATE 格式）
+  → 失败是学习数据，不要隐藏
+
+原则 4: 增量追加
+  → 使用 append 而非 rewrite
+  → 保持研究历史完整
+  → 避免覆盖已有信息
+```
+
 ```
 S0: Internal Codebase Research (必需)
 → 分析现有代码库，生成 research/internal/codebase-overview.md
@@ -198,19 +296,9 @@ Task 1-5: External Learning Materials (MCP)
 
 ---
 
-### Stage 3: Git Branch Creation
-
-```
-创建功能分支:
-→ Requirements: feature/${REQ_ID}-${slug(title)}
-→ Bug Fixes:    bugfix/${BUG_ID}-${slug(title)}
 
-Where slug() = lowercase, replace spaces/special chars with hyphens
-```
-
----
 
-### Stage 4: README Generation
+### Stage 3: README Generation
 
 ```
 生成工作流指南:
@@ -220,7 +308,7 @@ Where slug() = lowercase, replace spaces/special chars with hyphens
 
 ---
 
-### Stage 5: Exit Gate (5-Level Quality Check)
+### Stage 4: Exit Gate (5-Level Quality Check)
 
 **5层验证**:
 
@@ -244,7 +332,7 @@ Level 5: Git & Status & Constitution
 → orchestration_status.json 正确
 → Constitution 符合性检查
 
-→ 详见 {TEMPLATE:flow} Stage 5
+→ 详见 {TEMPLATE:flow} Stage 4
 ```
 
 ---
@@ -256,6 +344,7 @@ Level 5: Git & Status & Constitution
 ```
 devflow/requirements/${REQ_ID}/
 ├── README.md
+├── BRAINSTORM.md               # 需求的北极星 (Stage 2.3)
 ├── research/
 │   ├── internal/
 │   │   └── codebase-overview.md
@@ -274,7 +363,7 @@ devflow/requirements/${REQ_ID}/
 
 ### Git
 
-- **Branch**: `feature/${REQ_ID}-${slug(title)}`
+- **Branch**: `feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}`
 - **Status**: orchestration_status.json.status = "initialized"
 - **Phase**: orchestration_status.json.phase = "planning"
 

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

@@ -73,34 +73,42 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 
 **设计理念**: flow-new 是**编排器**（Orchestrator），串行调用 7-8 个阶段化命令
 
-**调用链**:
+**调用链** (v2.1.0 更新):
 ```
 /flow-new "REQ-123|Title|URLs"
   ↓
-[1/8] /flow-init "REQ-123|Title|URLs"
+[1/9] /flow-init "REQ-123|Title|URLs"
+      → 包含 Brainstorming，生成 BRAINSTORM.md ⭐ v2.1.0
   ↓
-[2/8] /flow-prd "REQ-123"
+[2/9] /flow-prd "REQ-123"
+      → 需要 BRAINSTORM.md 对齐检查 ⭐ v2.1.0
   ↓
-[2.3/8] /flow-checklist "REQ-123" (可选, 80%门禁)
+[2.3/9] /flow-checklist "REQ-123" (可选, 80%门禁)
   ↓
-[2.5/8] /flow-ui "REQ-123" (条件触发)
+[2.5/9] /flow-ui "REQ-123" (条件触发)
   ↓
-[2.7/8] /flow-tech "REQ-123" (必需)
+[2.7/9] /flow-tech "REQ-123" (必需)
   ↓
-[3/8] /flow-epic "REQ-123"
+[3/9] /flow-epic "REQ-123"
+      → bite-sized tasks (2-5分钟/任务) ⭐ v2.1.0
   ↓
-[4/8] /flow-dev "REQ-123"
+[4/9] /flow-dev "REQ-123"
+      → TDD Checkpoint (测试必须先 FAIL) ⭐ v2.1.0
   ↓
-[5/8] /flow-qa "REQ-123" --full
+[5/9] /flow-review "REQ-123" ⭐ v2.1.0 新增
+      → Two-Stage Review (Spec → Quality)
   ↓
-[6/8] /flow-release "REQ-123"
+[6/9] /flow-qa "REQ-123" --full
+  ↓
+[7/9] /flow-release "REQ-123"
+      → 分支完成决策 ⭐ v2.1.0
 ```
 
 ---
 
 ## 执行流程骨架
 
-### [1/8] 初始化 → /flow-init
+### [1/9] 初始化 → /flow-init
 
 ```
 调用: /flow-init "${REQ_ID}|${TITLE}|${PLAN_URLS}"
@@ -111,18 +119,24 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 ```
 
 **输出**:
-- Git分支: `feature/${REQ_ID}-${slug(title)}`
+- Git分支: `feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}`
 - 需求目录已创建
 - 研究材料已抓取
+- **BRAINSTORM.md** (需求北极星) ⭐ v2.1.0 新增
+
+> BRANCH_TITLE_EN 为 TITLE 的英文意译 (语义为准，非拼音，使用模型意译)
 
 ---
 
-### [2/8] PRD生成 → /flow-prd
+### [2/9] PRD生成 → /flow-prd
 
 ```
 调用: /flow-prd "${REQ_ID}"
 
-检查: PRD.md 存在且完整
+检查:
+  - BRAINSTORM.md 存在 ⭐ v2.1.0 新增
+  - PRD.md 存在且完整
+  - BRAINSTORM 对齐检查通过 ⭐ v2.1.0 新增
 
 → 详见 {TEMPLATE:orchestration} Stage 2
 ```
@@ -133,7 +147,7 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 
 ---
 
-### [2.3/8] 需求质量检查 → /flow-checklist (可选)
+### [2.3/9] 需求质量检查 → /flow-checklist (可选)
 
 ```
 触发条件: quality-rules.yml 中 checklist_gate_enabled: true
@@ -147,7 +161,7 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 
 ---
 
-### [2.5/8] UI原型生成 → /flow-ui (条件触发)
+### [2.5/9] UI原型生成 → /flow-ui (条件触发)
 
 ```
 触发条件 (任一满足):
@@ -169,7 +183,7 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 
 ---
 
-### [2.7/8] 技术方案设计 → /flow-tech (必需)
+### [2.7/9] 技术方案设计 → /flow-tech (必需)
 
 ```
 调用: /flow-tech "${REQ_ID}"
@@ -187,7 +201,7 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 
 ---
 
-### [3/8] Epic规划 → /flow-epic
+### [3/9] Epic规划 → /flow-epic
 
 ```
 调用: /flow-epic "${REQ_ID}"
@@ -195,17 +209,18 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 检查:
   - EPIC.md + TASKS.md 存在
   - TASKS 覆盖 TECH_DESIGN.md 所有技术层
+  - 任务粒度: 2-5分钟/任务 (bite-sized) ⭐ v2.1.0
 
 → 详见 {TEMPLATE:orchestration} Stage 3
 ```
 
 **输出**:
 - EPIC.md (Epic描述)
-- TASKS.md (单文件管理所有任务)
+- TASKS.md (单文件管理所有任务，bite-sized)
 
 ---
 
-### [4/8] 开发执行 → /flow-dev
+### [4/9] 开发执行 → /flow-dev
 
 ```
 调用: /flow-dev "${REQ_ID}"
@@ -213,7 +228,7 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 执行模式: TDD (Tests First)
   Phase 1: 分析现有代码
   Phase 2: 编写测试 (Tests First)
-  TEST VERIFICATION CHECKPOINT (测试必须先失败)
+  ⚠️ TDD CHECKPOINT (测试必须先 FAIL) ⭐ v2.1.0
   Phase 3: 实现代码
   Phase 4: 测试验证 (测试必须通过)
   Phase 5: Git提交并标记完成
@@ -229,7 +244,30 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 
 ---
 
-### [5/8] 质量保证 → /flow-qa
+### [5/9] 代码审查 → /flow-review ⭐ v2.1.0 新增
+
+```
+调用: /flow-review "${REQ_ID}"
+
+Two-Stage Review:
+  Stage 1: Spec Compliance (规格合规)
+    → 不信任实现者报告，读代码验证
+    → 检查 scope creep
+    → BRAINSTORM 对齐检查
+  Stage 2: Code Quality (代码质量)
+    → 仅在 Stage 1 通过后执行
+    → 测试质量、Constitution 合规
+
+→ 详见 flow-review.md
+```
+
+**输出**:
+- SPEC_REVIEW.md (Stage 1)
+- CODE_QUALITY_REVIEW.md (Stage 2)
+
+---
+
+### [6/9] 质量保证 → /flow-qa
 
 ```
 调用: /flow-qa "${REQ_ID}" --full
@@ -251,12 +289,13 @@ Exit Gate检查:
 
 ---
 
-### [6/8] 发布管理 → /flow-release
+### [7/9] 发布管理 → /flow-release
 
 ```
 调用: /flow-release "${REQ_ID}"
 
 执行:
+  - 分支完成决策 (FF merge / PR / Squash / Cleanup) ⭐ v2.1.0
   - 生成发布计划
   - 更新 CLAUDE.md (如有重要架构变更)
   - 最终构建
@@ -277,19 +316,20 @@ Exit Gate检查:
 **实时进度** (详见 `{TEMPLATE:orchestration}` Progress Display Format):
 
 ```
-🎯 CC-DevFlow 完整需求开发流程
+🎯 CC-DevFlow 完整需求开发流程 (v2.1.0)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 需求: REQ-123 | 支持用户下单
 
-[1/8] ✅ 初始化完成
-[2/8] ✅ PRD生成完成
-[2.5/8] ✅ UI原型生成完成 ⚡️
-[2.7/8] ✅ 技术方案设计完成 🔧
-[3/8] ✅ Epic规划完成
-[4/8] 🔄 开发执行中... (8/18 已完成)
-[5/8] ⏳ 等待质量保证...
-[6/8] ⏳ 等待发布管理...
+[1/9] ✅ 初始化完成 (含 Brainstorming)
+[2/9] ✅ PRD生成完成 (BRAINSTORM 对齐)
+[2.5/9] ✅ UI原型生成完成 ⚡️
+[2.7/9] ✅ 技术方案设计完成 🔧
+[3/9] ✅ Epic规划完成 (bite-sized tasks)
+[4/9] 🔄 开发执行中... (8/18 已完成)
+[5/9] ⏳ 等待代码审查... ⭐ 新增
+[6/9] ⏳ 等待质量保证...
+[7/9] ⏳ 等待发布管理...
 ```
 
 ---
@@ -300,6 +340,7 @@ Exit Gate检查:
 
 ```
 devflow/requirements/${REQ_ID}/
+├── BRAINSTORM.md ⭐ v2.1.0 新增
 ├── research/ (初始化时生成)
 ├── PRD.md
 ├── UI_PROTOTYPE.html (条件)
@@ -308,8 +349,10 @@ devflow/requirements/${REQ_ID}/
 ├── contracts/openapi.yaml
 ├── quickstart.md
 ├── EPIC.md
-├── TASKS.md
+├── TASKS.md (bite-sized)
 ├── tasks/*.completed
+├── SPEC_REVIEW.md ⭐ v2.1.0 新增
+├── CODE_QUALITY_REVIEW.md ⭐ v2.1.0 新增
 ├── TEST_PLAN.md + TEST_REPORT.md
 ├── SECURITY_PLAN.md + SECURITY_REPORT.md
 └── RELEASE_PLAN.md
@@ -390,5 +433,11 @@ gh pr merge <PR_NUMBER>
 **Related Documentation**:
 - [NEW_ORCHESTRATION_TEMPLATE.md](../.claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md) - 详细编排流程
 - [NEW_TROUBLESHOOTING.md](../.claude/docs/guides/NEW_TROUBLESHOOTING.md) - 故障排查指南
-- [flow-init.md](./flow-init.md) - 初始化阶段
-- [flow-dev.md](./flow-dev.md) - 开发阶段
+- [flow-init.md](./flow-init.md) - 初始化阶段 (含 Brainstorming)
+- [flow-review.md](./flow-review.md) - 代码审查阶段 ⭐ v2.1.0 新增
+- [flow-dev.md](./flow-dev.md) - 开发阶段 (TDD Checkpoint)
+- [flow-fix.md](./flow-fix.md) - Bug 修复流程 ⭐ v2.1.0 增强
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

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

@@ -5,6 +5,7 @@ scripts:
   prereq: .claude/scripts/check-prerequisites.sh
   validate_research: .claude/scripts/validate-research.sh
   validate_constitution: .claude/scripts/validate-constitution.sh
+  verify_gate: .claude/scripts/verify-gate.sh
 ---
 
 # Flow-PRD - PRD 生成命令
@@ -30,10 +31,22 @@ $ARGUMENTS = "REQ_ID?"
    → Else: run {SCRIPT:prereq} --json --paths-only
    → If仍为空: ERROR "No requirement ID found."
 
-2. 校验目录
+2. Brainstorm Alignment Check (新增)
+   → 读取 devflow/requirements/${REQ_ID}/BRAINSTORM.md
+   → 验证存在且包含必需章节:
+      • 原始需求
+      • 核心问题定义
+      • 成功标准
+      • 方案探索
+      • 最终决策
+   → 缺少 BRAINSTORM.md → ERROR "BRAINSTORM.md missing. Run /flow-init brainstorming."
+   → 加载「原始意图」作为 PRD 生成的北极星
+
+3. 校验目录
    → 使用 {SCRIPT:prereq} --json 获取路径
    → 必须存在:
       • devflow/requirements/${REQ_ID}/
+      • BRAINSTORM.md 
       • EXECUTION_LOG.md
       • orchestration_status.json (phase0_complete == true)
       • research/research.md
@@ -59,10 +72,10 @@ $ARGUMENTS = "REQ_ID?"
      3. 直接编辑 research/research.md 补充决策内容
      4. 参考 .claude/docs/templates/RESEARCH_TEMPLATE.md 模板
 
-3. PRD 覆盖提示
+4. PRD 覆盖提示
    → 若 PRD.md 已存在 → WARN 并确认是否覆盖
 
-4. 状态校验
+5. 状态校验
    → orchestration_status.status ∈ {"initialized", "prd_generation_failed"}
    → 否则提示按流程顺序执行
 ```

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

@@ -6,10 +6,43 @@ scripts:
   check_tasks: .claude/scripts/check-task-status.sh
   validate_constitution: .claude/scripts/validate-constitution.sh
   generate_status: .claude/scripts/generate-status-report.sh
+  verify_gate: .claude/scripts/verify-gate.sh
+skills:
+  finishing: .claude/skills/flow-finishing-branch/SKILL.md
+  verification: .claude/skills/verification-before-completion/SKILL.md
 ---
 
 # Flow-Release - 发布管理命令
 
+## 分支完成决策 (新增)
+
+参考 `{SKILL:finishing}` 原则，发布前需要决定分支处理方式：
+
+```yaml
+决策选项:
+  A) Fast-forward merge
+     → 适用: 小改动，单人开发，无需审查记录
+     → 命令: git checkout main && git merge --ff-only feature/xxx
+
+  B) Create PR (推荐)
+     → 适用: 需要记录，团队审查，CI 验证
+     → 命令: gh pr create
+
+  C) Squash and merge
+     → 适用: 多个提交需合并为一个
+     → 命令: gh pr merge --squash
+
+  D) Cleanup only
+     → 适用: 工作被废弃，只需清理分支
+     → 命令: git checkout main && git branch -D feature/xxx
+
+决策依据:
+  - 改动大小 (>10 files → PR)
+  - 是否需要审查 (团队项目 → PR)
+  - 提交历史是否清晰 (混乱 → Squash)
+  - 是否需要 CI 验证 (生产代码 → PR)
+```
+
 ## User Input
 ```text
 $ARGUMENTS = "REQ_ID?"