cc-devflow 1.0.2 → 2.4.0

package/.claude/skills/flow-brainstorming/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: flow-brainstorming
+description: "在 /flow-init 阶段强制触发，用于捕捉需求的原始意图、探索方案、记录决策。确保后续流程有明确的北极星可追溯。"
+---
+
+# Flow Brainstorming - 需求头脑风暴
+
+## Overview
+
+将用户的模糊想法转化为清晰的设计规格，通过自然对话捕捉原始意图。
+
+**核心原则**：需求的原始意图是整个开发流程的「北极星」，后续每个阶段都应能追溯并验证是否偏离。
+
+## The Iron Law
+
+```
+NO FLOW EXECUTION WITHOUT BRAINSTORM ALIGNMENT
+```
+
+每个后续 flow-* 阶段开始前，必须确认与 BRAINSTORM.md 一致。
+
+## The Process
+
+### Phase 1: Understanding the Idea
+
+**一次问一个问题**，不要用多个问题压垮用户：
+
+1. 检查项目现状（文件、文档、最近提交）
+2. 问问题来细化想法：
+   - 优先多选题（更容易回答）
+   - 一个消息只问一个问题
+   - 如果话题需要更多探索，分成多个问题
+3. 聚焦理解：**目的、约束、成功标准**
+
+**问题示例**：
+```
+这个需求主要解决什么问题？
+A) 新增功能
+B) 修复现有问题
+C) 性能优化
+D) 重构/技术债
+```
+
+### Phase 2: Exploring Approaches
+
+- 提出 2-3 种不同方案，说明取舍
+- 给出你的推荐方案及理由
+- 让用户做决策
+
+**方案呈现格式**：
+```markdown
+### 方案 A: {名称} ⭐ 推荐
+
+**描述**: ...
+**优势**: ...
+**劣势**: ...
+**适用场景**: ...
+
+### 方案 B: {名称}
+...
+```
+
+### Phase 3: Presenting the Design
+
+一旦理解了要构建什么：
+
+1. 分段呈现设计（每段 200-300 字）
+2. 每段后询问是否正确
+3. 涵盖：架构、组件、数据流、错误处理、测试
+4. 准备好返回澄清
+
+### Phase 4: Documentation
+
+将验证过的设计写入 BRAINSTORM.md：
+
+```
+devflow/requirements/${REQ}/BRAINSTORM.md
+```
+
+**必须包含**：
+- 原始需求（用户原话，一字不改）
+- 核心问题定义
+- 成功标准
+- 约束条件
+- 方案探索（2-3种）
+- 最终决策及理由
+
+## Key Principles
+
+| 原则 | 说明 |
+|------|------|
+| **一次一个问题** | 不要用多个问题压垮用户 |
+| **多选题优先** | 比开放问题更容易回答 |
+| **YAGNI 无情** | 从所有设计中移除不必要的功能 |
+| **探索替代方案** | 在确定前总是提出 2-3 种方案 |
+| **增量验证** | 分段呈现设计，验证每段 |
+| **灵活应变** | 有不明白的地方就返回澄清 |
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "需求已经很清楚了" | Brainstorm 确保没有遗漏假设 |
+| "用户赶时间，跳过吧" | 头脑风暴节省的是后续返工时间 |
+| "这是小需求" | 小需求也有核心问题和成功标准 |
+| "方案很明显" | 明显的选择也需要记录理由 |
+| "已经讨论过了" | 口头讨论不是文档，没有追溯性 |
+| "先做再说" | 先想清楚再做，节省 3 倍时间 |
+
+## Red Flags - STOP
+
+如果你发现自己：
+- 跳过问问题直接开始做
+- 用户说"我知道要什么"就不问了
+- 没有记录方案取舍就选定
+- 没有写 BRAINSTORM.md 就进入下一阶段
+
+**STOP。返回正确流程。**
+
+## Integration with CC-DevFlow
+
+### flow-init 阶段
+
+```yaml
+Entry Gate:
+  - 解析 REQ-ID 和标题
+  - 触发 flow-brainstorming skill
+
+Brainstorm Phase:
+  1. 问问题理解需求（一次一个）
+  2. 探索 2-3 种方案
+  3. 确认最终方案
+  4. 输出 BRAINSTORM.md
+
+Exit Gate:
+  - 验证 BRAINSTORM.md 存在
+  - 验证包含必要章节
+```
+
+### 后续 flow-* 阶段
+
+```yaml
+Entry Gate 添加:
+  step: Brainstorm Alignment Check
+    - read: devflow/requirements/${REQ}/BRAINSTORM.md
+    - verify:
+        - 原始问题是否仍然是解决目标？
+        - 选定方案是否仍然适用？
+        - 约束条件是否发生变化？
+    - if 发现偏离:
+        - ask_user: "发现与原始意图偏离，是否更新 BRAINSTORM.md？"
+        - action: 记录偏离原因，更新文档
+```
+
+## Output Template
+
+参见 `.claude/docs/templates/BRAINSTORM_TEMPLATE.md`
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/skills/flow-debugging/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: flow-debugging
+description: "4-phase systematic debugging for flow-fix. NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST."
+---
+
+# Flow Debugging - Systematic Debugging Method
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+Bug fixing is not a guessing game. Systematic debugging = faster fixes + fewer regressions.
+
+## The 4-Phase Process
+
+```
+Phase 1: ROOT CAUSE INVESTIGATION (NO FIXES YET)
+    ↓
+Phase 2: PATTERN ANALYSIS
+    ↓
+Phase 3: HYPOTHESIS AND TESTING
+    ↓
+Phase 4: IMPLEMENTATION (TDD)
+```
+
+## Phase 1: Root Cause Investigation
+
+**Iron Law**: In this phase, **NO FIX CODE ALLOWED**.
+
+```yaml
+Step 1: Read Error Completely
+  - Don't skip any details
+  - Record: error type, message, stack trace
+  - Record: when it happens, frequency, impact
+
+Step 2: Stable Reproduction
+  - Find reliable reproduction steps
+  - Record: inputs, environment, preconditions
+  - If can't reproduce → gather more information
+
+Step 3: Check Recent Changes
+  - git log --oneline -20
+  - git diff HEAD~5
+  - Ask: What changed? When did it start failing?
+
+Step 4: Trace Data Flow Backwards
+  - Start from error point
+  - Trace upstream
+  - Find where data goes wrong
+```
+
+**Output**: Root cause hypothesis (evidence-based, not a guess)
+
+## Phase 2: Pattern Analysis
+
+```yaml
+Step 1: Find Working Examples
+  - Where does similar functionality work?
+  - Compare: working vs broken
+
+Step 2: Compare with Reference
+  - What does official documentation say?
+  - How do other projects do it?
+  - What's different?
+
+Step 3: Identify Patterns
+  - Is this a known bug pattern?
+  - Search: error message + framework name
+```
+
+**Output**: Confirmed or refined root cause hypothesis
+
+## Phase 3: Hypothesis and Testing
+
+```yaml
+Step 1: Form Single Hypothesis
+  - "The problem is because X"
+  - Hypothesis must be verifiable
+
+Step 2: Test One Variable at a Time
+  - Change only one factor
+  - Observe result
+  - Record: what changed, what happened
+
+Step 3: 3+ Failed Fixes → STOP
+  - If 3+ fix attempts fail
+  - Stop and question architecture
+  - Problem may be deeper than thought
+```
+
+**Red Flag**: If you're "trying this, trying that", you're guessing, not debugging.
+
+## Phase 4: Implementation (TDD)
+
+**Prerequisite**: Phases 1-3 complete, root cause confirmed
+
+```yaml
+Step 1: Write Failing Test First
+  - Test must reproduce the bug
+  - Run test, confirm it fails
+  - This is your "red light"
+
+Step 2: Implement Single Fix
+  - Fix only the root cause
+  - Don't "while I'm here" other things
+  - Minimal change
+
+Step 3: Verify
+  - Run test, confirm it passes
+  - Run related tests, confirm no regression
+  - Manual verify original issue resolved
+```
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "I know where the problem is" | Prove it. Investigate first. |
+| "Quick fix" | Quick fix = quick regression. Systematic debug. |
+| "No time for tests" | No tests = don't know if really fixed. |
+| "Small change" | Small changes can introduce big bugs. Test it. |
+| "Fix first, investigate later" | Fixing without understanding = guessing. |
+| "Let me try this" | "Trying" is not debugging. Form hypothesis, verify it. |
+| "It's obvious" | Nothing is obvious. Prove with evidence. |
+| "I've seen this before" | Every bug is unique. Investigate this one. |
+
+## Red Flags - STOP
+
+If you find yourself:
+- Fixing without reproduction
+- "Trying this, trying that"
+- 3+ failed fix attempts
+- Saying "fixed" without tests
+- Changing many files for one bug
+
+**STOP. Go back to Phase 1. Investigate root cause.**
+
+## Debug Output Template
+
+```markdown
+# Bug Analysis - ${BUG_ID}
+
+## Phase 1: Root Cause Investigation
+
+### Error Details
+- Type: [error type]
+- Message: [error message]
+- Stack: [key stack frames]
+
+### Reproduction
+- Steps: [1, 2, 3...]
+- Frequency: [always/sometimes/rare]
+- Environment: [conditions]
+
+### Recent Changes
+- [relevant commits]
+
+### Data Flow Analysis
+- [where data goes wrong]
+
+### Root Cause Hypothesis
+[Evidence-based hypothesis]
+
+## Phase 2: Pattern Analysis
+
+### Working Example
+[Where similar code works]
+
+### Comparison
+[Difference between working and broken]
+
+### Confirmed Root Cause
+[Refined hypothesis]
+
+## Phase 3: Hypothesis Testing
+
+### Hypothesis
+[Single testable hypothesis]
+
+### Test Results
+| Change | Result |
+|--------|--------|
+| [change 1] | [result] |
+
+## Phase 4: Implementation
+
+### Failing Test
+[Test code that reproduces bug]
+
+### Fix
+[Minimal fix code]
+
+### Verification
+- [ ] Test passes
+- [ ] No regression
+- [ ] Manual verification
+```
+
+## Integration with flow-fix
+
+This skill is the core methodology for `/flow-fix` command:
+
+```yaml
+/flow-fix phases:
+  阶段 1: Root Cause Investigation → This skill Phase 1
+  阶段 2: Pattern Analysis & Planning → This skill Phase 2
+  阶段 3: 修复执行 (TDD) → This skill Phase 3-4
+  阶段 4: 验证与发布 → verification-before-completion
+```
+
+## Cross-Reference
+
+- [flow-fix.md](../../commands/flow-fix.md) - Bug fix command
+- [flow-tdd/SKILL.md](../flow-tdd/SKILL.md) - TDD enforcement
+- [verification-before-completion](../verification-before-completion/SKILL.md) - Verification skill
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/skills/flow-finishing-branch/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: flow-finishing-branch
+description: "Decide how to complete a development branch: merge, PR, squash, or cleanup."
+---
+
+# Flow Finishing Branch - 分支完成决策
+
+## Overview
+
+When development work is complete, you need to decide how to integrate it. This skill guides that decision.
+
+## Decision Options
+
+### A) Fast-forward Merge
+
+```yaml
+When to use:
+  - Small changes (< 5 files)
+  - Single developer
+  - No review needed
+  - Clean commit history
+
+Command:
+  git checkout main
+  git merge --ff-only feature/xxx
+  git branch -d feature/xxx
+
+Pros:
+  - Fast
+  - Clean history
+  - No merge commit
+
+Cons:
+  - No review record
+  - No CI verification
+```
+
+### B) Create PR (Recommended)
+
+```yaml
+When to use:
+  - Team projects
+  - Need review record
+  - CI verification required
+  - Production code
+
+Command:
+  git push -u origin feature/xxx
+  gh pr create --title "..." --body "..."
+
+Pros:
+  - Review record
+  - CI verification
+  - Discussion thread
+  - Audit trail
+
+Cons:
+  - Takes longer
+  - Requires reviewer
+```
+
+### C) Squash and Merge
+
+```yaml
+When to use:
+  - Many small commits
+  - Messy commit history
+  - Want single commit in main
+
+Command:
+  gh pr merge --squash
+
+Pros:
+  - Clean main history
+  - Single logical commit
+  - Hides WIP commits
+
+Cons:
+  - Loses detailed history
+  - Harder to bisect
+```
+
+### D) Cleanup Only
+
+```yaml
+When to use:
+  - Work was abandoned
+  - Experiment failed
+  - Requirements changed
+
+Command:
+  git checkout main
+  git branch -D feature/xxx
+  git push origin --delete feature/xxx  # if pushed
+
+Pros:
+  - Clean slate
+  - No dead branches
+
+Cons:
+  - Work is lost (unless needed later)
+```
+
+## Decision Matrix
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Decision Matrix                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Files Changed    Review Needed    History Clean    Action  │
+│  ─────────────    ─────────────    ─────────────    ──────  │
+│  < 5              No               Yes              A) FF   │
+│  < 5              No               No               C) Sq   │
+│  Any              Yes              Yes              B) PR   │
+│  Any              Yes              No               C) Sq   │
+│  N/A              N/A              N/A (abandoned)  D) Del  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Pre-Completion Checklist
+
+Before choosing any option, verify:
+
+```yaml
+□ All tests pass
+□ Build succeeds
+□ No lint errors
+□ Documentation updated (if needed)
+□ EXECUTION_LOG.md updated
+□ No uncommitted changes
+```
+
+## The Process
+
+```yaml
+1. Verify completion
+   → Run tests, build, lint
+   → Check all tasks done
+
+2. Assess the work
+   → How many files changed?
+   → Is review needed?
+   → Is commit history clean?
+
+3. Choose option
+   → Use decision matrix
+   → Default to PR if unsure
+
+4. Execute
+   → Run appropriate commands
+   → Verify success
+
+5. Cleanup
+   → Delete local branch
+   → Delete remote branch (if not PR)
+```
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "PR is overkill" | PR provides audit trail. Use it. |
+| "I'll review my own code" | Self-review misses issues. Get another pair of eyes. |
+| "History doesn't matter" | History helps debugging. Keep it clean. |
+| "Just merge it" | Verify first. Merge second. |
+
+## Integration with flow-release
+
+This skill is used in `/flow-release` to decide branch handling:
+
+```yaml
+/flow-release execution:
+  1. Verify all gates pass
+  2. Load this skill
+  3. Present options to user
+  4. Execute chosen option
+  5. Update status
+```
+
+## Cross-Reference
+
+- [flow-release.md](../../commands/flow-release.md) - Release command
+- [verification-before-completion](../verification-before-completion/SKILL.md) - Verification skill
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/skills/flow-receiving-review/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: flow-receiving-review
+description: "Handle code review feedback with technical rigor. Don't blindly agree - verify before implementing."
+---
+
+# Flow Receiving Review - 处理代码审查反馈
+
+## The Iron Law
+
+```
+VERIFY FEEDBACK BEFORE IMPLEMENTING - DON'T BLINDLY AGREE
+```
+
+## Overview
+
+When receiving code review feedback, maintain technical rigor. Reviewers can be wrong. Your job is to:
+1. Understand the feedback
+2. Verify it's correct
+3. Then implement (or push back)
+
+## The Process
+
+### Step 1: Understand the Feedback
+
+```yaml
+For each comment:
+  1. Read completely - don't skim
+  2. Identify the concern:
+     - Is it a bug?
+     - Is it a style preference?
+     - Is it a performance issue?
+     - Is it a security concern?
+  3. If unclear → ASK for clarification
+     - "Could you elaborate on why X is problematic?"
+     - "What specific scenario does this address?"
+```
+
+### Step 2: Verify the Feedback
+
+```yaml
+Before implementing ANY change:
+  1. Is the feedback technically correct?
+     - Does the suggested change actually fix the issue?
+     - Could it introduce new problems?
+
+  2. Does it align with project standards?
+     - Check Constitution
+     - Check existing patterns
+
+  3. Is there evidence?
+     - Can you reproduce the issue?
+     - Does the suggested fix work?
+
+If feedback seems wrong:
+  → Don't silently disagree
+  → Don't blindly implement
+  → Respond with your analysis
+```
+
+### Step 3: Respond Appropriately
+
+```yaml
+If feedback is correct:
+  → Acknowledge: "Good catch, fixing now"
+  → Implement the fix
+  → Verify the fix works
+
+If feedback is unclear:
+  → Ask: "Could you clarify what you mean by X?"
+  → Don't guess the intent
+
+If feedback seems incorrect:
+  → Explain your reasoning
+  → Provide evidence
+  → "I considered X, but Y because Z. What do you think?"
+
+If feedback is a preference (not a bug):
+  → Discuss trade-offs
+  → Defer to project standards if they exist
+```
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Reviewer knows better" | Reviewers make mistakes. Verify. |
+| "Just do what they say" | Blind compliance = poor code. |
+| "Don't want to argue" | Technical discussion ≠ argument. |
+| "It's faster to just change it" | Wrong changes waste more time. |
+| "They'll reject if I push back" | Good reviewers appreciate rigor. |
+
+## Red Flags - STOP
+
+If you find yourself:
+- Implementing changes you don't understand
+- Agreeing with feedback you think is wrong
+- Not asking clarifying questions
+- Making changes without verifying they work
+
+**STOP. Understand first. Verify second. Implement third.**
+
+## Response Templates
+
+### Agreeing with Feedback
+```
+Good catch! You're right that [issue]. I've updated [file] to [fix].
+Verified by running [test/command].
+```
+
+### Asking for Clarification
+```
+I want to make sure I understand correctly. Are you suggesting [interpretation]?
+If so, I'm wondering about [concern]. Could you elaborate?
+```
+
+### Respectfully Disagreeing
+```
+I considered [suggestion], but I went with [current approach] because:
+1. [Reason 1]
+2. [Reason 2]
+
+The trade-off is [X]. What do you think about [alternative]?
+```
+
+### Requesting Evidence
+```
+I'm having trouble reproducing [issue]. Could you share:
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details
+```
+
+## Integration with flow-review
+
+This skill is used in `/flow-review` when processing reviewer feedback:
+
+```yaml
+After receiving review:
+  1. Load this skill
+  2. Process each comment using the 3-step process
+  3. Respond appropriately
+  4. Track changes in EXECUTION_LOG.md
+```
+
+## Cross-Reference
+
+- [flow-review.md](../../commands/flow-review.md) - Two-stage review command
+- [spec-reviewer.md](../../agents/spec-reviewer.md) - Spec compliance agent
+- [code-quality-reviewer.md](../../agents/code-quality-reviewer.md) - Quality review agent
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md