cc-devflow 2.4.6 → 4.1.0

package/.claude/skills/workflow/flow-init/assets/BRAINSTORM_TEMPLATE.md

@@ -0,0 +1,148 @@
+---
+req_id: "{REQ_ID}"
+title: "{TITLE}"
+created_at: "{ISO8601_TIMESTAMP}"
+brainstorm_version: "1.0"
+status: "draft"
+---
+
+# {REQ_ID} Brainstorm Record
+
+> **[PROTOCOL]**: 后续所有开发必须与本文档保持一致。如有偏离，需更新本文档并说明原因。
+
+## 原始需求（用户原话）
+
+> {用户的原始描述，一字不改，保留所有细节}
+
+## 核心问题定义
+
+### 解决什么问题？
+
+{一句话定义核心问题，例如："用户无法在移动端完成支付"}
+
+### 为谁解决？
+
+{用户画像，例如："日均活跃用户 10,000+，年龄 25-45，移动端为主"}
+
+### 现状痛点
+
+- {痛点1：具体描述，包含数据或用户反馈}
+- {痛点2}
+- {痛点3}
+
+## 成功标准
+
+### 如何判断需求完成？（验收标准）
+
+- [ ] {可度量的标准1，例如："支付成功率 ≥ 95%"}
+- [ ] {可度量的标准2}
+- [ ] {可度量的标准3}
+
+### 如何判断需求成功？（业务指标）
+
+- {业务指标1，例如："订单转化率提升 10%"}
+- {业务指标2}
+
+## 约束条件
+
+| 类型 | 约束 | 原因 |
+|------|------|------|
+| 技术 | {约束，例如："必须兼容 iOS 12+"} | {原因} |
+| 时间 | {约束，例如："2 周内上线"} | {原因} |
+| 资源 | {约束，例如："1 前端 + 1 后端"} | {原因} |
+| 安全 | {约束，例如："敏感数据需加密"} | {原因} |
+| 法规 | {约束，例如："符合 GDPR"} | {原因} |
+
+## 方案探索
+
+### 方案 A: {名称} ⭐ 推荐
+
+**描述**:
+{方案概述，100-200 字}
+
+**优势**:
+- {优势1}
+- {优势2}
+
+**劣势**:
+- {劣势1}
+- {劣势2}
+
+**适用场景**:
+{何时选择这个方案}
+
+**实现要点**:
+1. {关键步骤1}
+2. {关键步骤2}
+
+---
+
+### 方案 B: {名称}
+
+**描述**:
+{方案概述}
+
+**优势**:
+- {优势1}
+
+**劣势**:
+- {劣势1}
+
+**适用场景**:
+{何时选择这个方案}
+
+---
+
+### 方案 C: {名称}
+
+**描述**:
+{方案概述}
+
+**优势**:
+- {优势1}
+
+**劣势**:
+- {劣势1}
+
+**适用场景**:
+{何时选择这个方案}
+
+## 最终决策
+
+**选定方案**: 方案 {X}
+
+**选择理由**:
+{为什么选这个方案，而非其他方案}
+
+**否决理由**:
+- 方案 {Y}: {为什么不选}
+- 方案 {Z}: {为什么不选}
+
+## 关键决策记录
+
+| 决策点 | 决策 | 理由 | 日期 |
+|--------|------|------|------|
+| {问题1} | {选择} | {为什么} | {YYYY-MM-DD} |
+| {问题2} | {选择} | {为什么} | {YYYY-MM-DD} |
+
+## 风险识别
+
+| 风险 | 概率 | 影响 | 缓解策略 |
+|------|------|------|----------|
+| {风险1} | 高/中/低 | 高/中/低 | {应对措施} |
+| {风险2} | 高/中/低 | 高/中/低 | {应对措施} |
+
+## 变更历史
+
+| 版本 | 日期 | 变更内容 | 变更原因 |
+|------|------|----------|----------|
+| 1.0 | {YYYY-MM-DD} | 初始版本 | 头脑风暴完成 |
+
+---
+
+**⚠️ 追溯声明**:
+本文档是 {REQ_ID} 的「北极星」。后续 PRD、EPIC、TASKS、实现都必须与本文档保持一致。
+如发现偏离，必须：
+1. 确认偏离原因
+2. 更新本文档
+3. 记录变更历史

package/.claude/skills/workflow/flow-init/assets/INIT_FLOW_TEMPLATE.md

@@ -0,0 +1,198 @@
+# Flow-Init Execution Flow Template
+
+> Detailed stages for `/flow-init` requirement initialization
+
+<!-- ============================================================
+     调用上下文声明 (Invocation Context Declaration)
+     ============================================================
+
+本模板由 `/flow-init` 命令通过 {TEMPLATE:flow} 引用加载。
+
+模板中的 {SCRIPT:xxx} 占位符引用 flow-init.md 头文件中的 scripts 定义：
+```yaml
+# 来源: .claude/commands/flow-init.md 头文件
+scripts:
+  create: .claude/scripts/create-requirement.sh
+  prereq: .claude/scripts/check-prerequisites.sh
+  research_tasks: .claude/scripts/generate-research-tasks.sh
+  populate_tasks: .claude/scripts/populate-research-tasks.sh
+  consolidate: .claude/scripts/consolidate-research.sh
+  validate_research: .claude/scripts/validate-research.sh
+```
+
+占位符解析:
+- {SCRIPT:prereq}           → bash .claude/scripts/check-prerequisites.sh
+- {SCRIPT:create}           → bash .claude/scripts/create-requirement.sh
+- {SCRIPT:research_tasks}   → bash .claude/scripts/generate-research-tasks.sh
+- {SCRIPT:populate_tasks}   → bash .claude/scripts/populate-research-tasks.sh
+- {SCRIPT:consolidate}      → bash .claude/scripts/consolidate-research.sh
+- {SCRIPT:validate_research} → bash .claude/scripts/validate-research.sh
+============================================================ -->
+
+---
+
+## Stage 1: Entry Gate (参数验证)
+
+```bash
+# 1. 解析参数
+REQ_ID|TITLE|PLAN_URLS → 验证 REQ_ID 格式: ^(REQ|BUG)-[0-9]+$
+→ 若 TITLE 含中文/非ASCII，使用模型意译生成 BRANCH_TITLE_EN（英文语义翻译，禁止拼音/音译）
+→ BRANCH_TITLE_EN 仅用于分支名，文档标题仍使用原始 TITLE
+→ 若意译不确定或未生成 ASCII 结果，向用户确认英文分支标题
+
+# 2. 前置条件检查
+bash {SCRIPT:prereq} --json --paths-only
+→ Git 状态干净 + devflow/ 目录存在
+
+# 3. 目录唯一性检查
+→ 确认 devflow/requirements/${REQ_ID}/ 不存在
+```
+
+---
+
+## Stage 1.2: Git Branch Creation
+
+```bash
+# 创建功能分支
+Requirements: feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}
+Bug Fixes:    bugfix/${BUG_ID}-${slug(BRANCH_TITLE_EN)}
+
+# BRANCH_TITLE_EN = TITLE 的英文意译 (语义为准，非拼音，使用模型意译)
+# slug() = lowercase, replace spaces/special chars with hyphens
+```
+
+---
+
+## Stage 1.5: Context Loading (路线图与架构)
+
+**目标**: 理解需求在项目中的位置
+
+```bash
+# 检查 ROADMAP.md 和 ARCHITECTURE.md
+→ 如果存在: 加载上下文，展示需求位置
+→ 如果不存在: 提示可选运行 /core-roadmap (不阻塞执行)
+```
+
+---
+
+## Stage 2: Directory Initialization
+
+```bash
+# 创建需求目录
+bash {SCRIPT:create} "${REQ_ID}" --title "${TITLE}" --branch-title "${BRANCH_TITLE_EN}" --json
+
+→ 若未生成 BRANCH_TITLE_EN，则省略 --branch-title
+
+# 生成文件
+devflow/requirements/${REQ_ID}/
+├── README.md
+├── EXECUTION_LOG.md
+├── orchestration_status.json
+└── research/ (空目录)
+```
+
+---
+
+## Stage 2.5: Research (Subagent Mandatory)
+
+**目标**: 研究默认必跑，但研究过程必须“隔离上下文”。
+
+**规则**: 大内容写入 `research/`，主会话只保留路径引用与决策摘要。
+
+### Mandatory: Call `flow-researcher` Subagent
+
+```
+Task tool call:
+  subagent_type: "flow-researcher"
+  prompt: (JSON) reqId/reqDir/title/planUrls/contextFiles
+```
+
+**产物** (由 subagent 写入):
+- `research/internal/codebase-overview.md`
+- `research/mcp/$(date +%Y%m%d)/**`
+- `research/research-summary.md`
+- `research/tasks.json`
+- `research/research.md`
+
+---
+
+## Stage 2.6: Research Consolidation
+
+> 该阶段由 `flow-researcher` subagent 执行（含 tasks 生成/回填/整合/校验）。
+
+---
+
+
+
+## Stage 3: README Generation
+
+```bash
+# 生成工作流指南
+→ devflow/requirements/${REQ_ID}/README.md
+→ 包含: 需求概述、工作流步骤、检查清单
+```
+
+---
+
+## Stage 4: Exit Gate (5-Level Quality Check)
+
+### Level 1: File Existence Check
+```bash
+→ 验证所有必需文件已创建
+```
+
+### Level 2: Research.md Structure Validation
+```bash
+bash {SCRIPT:validate_research} "${REQ_DIR}" --strict
+→ 检查 research.md 结构
+```
+
+### Level 3: Research.md Content Quality
+```bash
+→ 无 TODO/FIXME/{{PLACEHOLDER}} 标记
+→ 每个 Decision block 完整
+```
+
+### Level 4: Research Tasks Validation
+```bash
+→ 验证 tasks.json 格式和内容
+```
+
+### Level 5: Git & Status & Constitution
+```bash
+→ Git 分支创建成功
+→ orchestration_status.json 正确
+→ Constitution 符合性检查
+```
+
+---
+
+## Output Structure
+
+```
+devflow/requirements/${REQ_ID}/
+├── README.md
+├── research/
+│   ├── internal/
+│   │   └── codebase-overview.md
+│   ├── mcp/
+│   │   └── $(date +%Y%m%d)/
+│   │       ├── official/
+│   │       ├── guides/
+│   │       ├── tutorials/
+│   │       └── examples/
+│   ├── research.md
+│   ├── research-summary.md
+│   └── tasks.json
+├── EXECUTION_LOG.md
+└── orchestration_status.json
+```
+
+**Git**:
+- Branch: `feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}`
+- Status: orchestration_status.json.status = "initialized"
+- Phase: orchestration_status.json.phase = "planning"
+
+---
+
+**Last Updated**: 2025-12-19

package/.claude/skills/workflow/flow-init/assets/RESEARCH_TEMPLATE.md

@@ -0,0 +1,276 @@
+# Research Summary — {FEATURE_NAME}
+
+> **Purpose**: Document all technical decisions made during requirement initialization
+> **Owner**: prd-writer / planner agents
+> **Status**: Living document (updated until PRD finalized)
+> **Template Version**: v1.0.0
+> **Constitution Compliance**: Article X.1 (Forced Clarification), Article X.2 (No Speculation)
+
+Generated: {GENERATED_AT}
+
+---
+
+## Decisions
+
+### R001 — {TOPIC_DESCRIPTION}
+- **Decision**: {技术选型或架构决策}
+- **Rationale**:
+  - {理由 1: 必须明确说明为什么选择这个方案}
+  - {理由 2: 至少提供 2 条理由，证明决策经过深思熟虑}
+  - {理由 3 (可选): 更多支持性论据}
+- **Alternatives Considered**:
+  - {替代方案 1}: {简要评估 - 为什么不选择}
+  - {替代方案 2}: {简要评估 - 优缺点对比}
+- **Source**: {来源: PRD.md:42 或 Tech-Choice:Frontend Framework}
+
+### R002 — {TOPIC_DESCRIPTION}
+- **Decision**: {实际选择的技术/方案}
+- **Rationale**:
+  - {业务需求匹配度}
+  - {技术优势或团队熟悉度}
+- **Alternatives Considered**:
+  - {对比方案}: {不选择的原因}
+- **Source**: {来源}
+
+---
+
+## Unresolved Questions
+
+> ⚠️ 使用 `[NEEDS CLARIFICATION]` 标记所有待澄清问题
+> 📌 每个问题必须包含: Context (上下文) + Impact (影响) + Blocked Tasks (阻塞任务)
+
+- **[NEEDS CLARIFICATION]**: {具体问题描述}
+  - **Context**: {为什么需要澄清这个问题}
+  - **Impact**: {不澄清会影响哪些决策或实现}
+  - **Blocked Tasks**: {哪些任务被阻塞 - 如 data-model.md, API contracts}
+
+---
+
+## Source Library
+
+> **说明**: 列出所有研究材料的相对路径（相对于 REQ_DIR）
+
+### Internal Codebase Research
+- `research/internal/codebase-overview.md` - 现有代码库结构和可复用模块
+- `research/internal/testing-strategy.md` - 现有测试框架和模式
+
+### External Research Materials (MCP)
+- `research/mcp/20250126/official/nextjs-docs.md` - Next.js 14 官方文档（App Router）
+- `research/mcp/20250126/guides/prisma-best-practices.md` - Prisma ORM 最佳实践
+- `research/mcp/20250126/security/auth0-vs-clerk.md` - 认证方案对比
+
+### Manual Research Notes
+- `research/manual/database-benchmarks.md` - 性能基准测试结果
+- `research/manual/team-feedback.md` - 团队技术偏好调研
+
+---
+
+## Research Completion Checklist
+
+> ✅ 使用此清单验证 research.md 是否完整且符合规范
+
+### Structure Validation
+- [ ] 包含 "## Decisions" 章节
+- [ ] 至少有 1 个 Decision block (### R001, R002, ...)
+- [ ] 包含 "## Source Library" 章节
+
+### Content Quality
+- [ ] 每个 Decision block 包含 Decision/Rationale/Alternatives 三部分
+- [ ] Rationale 至少 2 条理由（不能是单行敷衍）
+- [ ] Alternatives 至少 1 个具体方案（不能是 "无" 或 "未评估"）
+- [ ] 无 TODO 标记
+- [ ] 无 {{PLACEHOLDER}} 占位符
+- [ ] 无 FIXME/XXX 标记
+
+### Constitution Compliance
+- [ ] Article X.1: 所有 NEEDS CLARIFICATION 已明确标记
+- [ ] Article X.2: 无推测性语言（"可能"/"未来"/"预留"）
+- [ ] Article I.1: 无部分实现标记（"暂时"/"临时"/"简化版"）
+
+### Source Traceability
+- [ ] 每个 Decision 有明确的 Source 字段
+- [ ] Source Library 列出所有研究材料路径
+- [ ] 研究材料文件实际存在于 research/ 目录
+
+---
+
+## Usage Instructions
+
+### For AI Agents (prd-writer, planner)
+
+1. **Initialize from Template**:
+   ```bash
+   cp .claude/docs/templates/RESEARCH_TEMPLATE.md \
+      devflow/requirements/${REQ_ID}/research/research.md
+   ```
+
+2. **Fill Template Variables**:
+   - Replace `{FEATURE_NAME}` with actual feature title
+   - Replace `{GENERATED_AT}` with ISO 8601 UTC timestamp
+   - Replace all `{PLACEHOLDERS}` with actual content
+
+3. **Populate Decisions**:
+   - Read `research/tasks.json` for research task list
+   - For each task, create a Decision block
+   - Ensure Decision/Rationale/Alternatives are complete
+
+4. **Validate Before Saving**:
+   ```bash
+   bash .claude/scripts/validate-research.sh ${REQ_DIR} --strict
+   ```
+
+### For Human Developers
+
+1. **Manual Research Workflow**:
+   ```bash
+   # 1. Run flow-init (generates tasks.json)
+   /flow-init "REQ-123|Feature Name"
+
+   # 2. Research each task
+   # - Check existing codebase
+   # - Search official docs (use MCP)
+   # - Benchmark alternatives
+
+   # 3. Update tasks.json with findings
+   # - Add decision, rationale, alternatives fields
+   # - Update status to "completed"
+
+   # 4. Consolidate findings
+   bash .claude/scripts/consolidate-research.sh devflow/requirements/REQ-123
+
+   # 5. Validate
+   bash .claude/scripts/validate-research.sh devflow/requirements/REQ-123 --strict
+   ```
+
+2. **Direct Editing**:
+   - Copy this template to `research/research.md`
+   - Fill in decisions based on your research
+   - Run validation script before proceeding to /flow-prd
+
+---
+
+## Example: Complete Decision Block
+
+```markdown
+### R003 — Research authentication strategy for User Management System
+- **Decision**: Auth0 with Next.js Middleware integration
+- **Rationale**:
+  - Native support for Next.js App Router middleware authentication
+  - Pre-built UI components reduce frontend development time
+  - SaaS model eliminates need for auth infrastructure maintenance
+  - Compliance certifications (SOC 2, GDPR) included in Pro plan
+- **Alternatives Considered**:
+  - Clerk: Similar features but higher pricing at scale (>10k users)
+  - NextAuth.js: Open-source but requires self-hosting and security audits
+  - AWS Cognito: Lower cost but complex integration with Next.js middleware
+  - Custom JWT: Maximum flexibility but significant security risk and dev time
+- **Source**: PRD.md:89 (User Story US-002: User Authentication)
+```
+
+---
+
+## Anti-Patterns (避免这些错误)
+
+### ❌ Bad Example 1: 敷衍的 Rationale
+```markdown
+### R001 — Database choice
+- Decision: PostgreSQL
+- Rationale: 好用
+- Alternatives: MySQL
+```
+**问题**: Rationale 太简单，没有说明为什么好用。Alternatives 没有对比分析。
+
+### ❌ Bad Example 2: 包含 TODO
+```markdown
+### R001 — Database choice
+- Decision: TODO - fill decision outcome
+- Rationale: TODO - explain why
+- Alternatives: TODO - list alternatives
+```
+**问题**: 未完成的研究，validate-research.sh 会拒绝。
+
+### ❌ Bad Example 3: 推测性语言
+```markdown
+### R001 — Database choice
+- Decision: PostgreSQL
+- Rationale:
+  - 未来可能需要复杂查询
+  - 预留扩展性支持分片
+```
+**问题**: "未来可能"/"预留" 违反 Article X.2 (No Speculation)。
+
+### ✅ Good Example: 完整且符合规范
+```markdown
+### R001 — Research database choice for E-commerce Platform
+- **Decision**: PostgreSQL 15 with Prisma ORM
+- **Rationale**:
+  - PRD requires ACID transactions for order processing (US-005)
+  - Prisma provides type-safe database access aligned with TypeScript stack
+  - Team has 3 years PostgreSQL production experience (reduces onboarding time)
+  - Native JSON support needed for product catalog flexible attributes (US-012)
+- **Alternatives Considered**:
+  - MongoDB: No ACID transactions, unsuitable for financial operations
+  - MySQL: Weaker JSON support, no partial indexes (needed for US-012)
+  - Supabase: Vendor lock-in concerns, enterprise pricing unclear
+- **Source**: PRD.md:42 (User Story US-005: Order Processing)
+```
+
+---
+
+## Troubleshooting
+
+### Q: consolidate-research.sh 生成的 research.md 全是 TODO，怎么办？
+
+**A**: 这说明 `research/tasks.json` 缺少 `decision/rationale/alternatives` 字段。
+
+**解决方案 1** (推荐): 手动填充 tasks.json
+```json
+{
+  "tasks": [
+    {
+      "id": "R001",
+      "prompt": "Research database choice",
+      "status": "completed",
+      "decision": "PostgreSQL 15 with Prisma ORM",
+      "rationale": "ACID compliance, type-safe access, team experience",
+      "alternatives": "MongoDB (no ACID), MySQL (weaker JSON support)",
+      "source": "PRD.md:42"
+    }
+  ]
+}
+```
+
+**解决方案 2**: 直接编辑 research.md，参考此模板格式。
+
+**解决方案 3**: 跳过 consolidate-research.sh，完全手动创建 research.md。
+
+### Q: validate-research.sh 报错 "No Decision blocks found"，但我有内容？
+
+**A**: Decision block 必须符合格式 `### R001 —` (三个 #，空格，R + 数字，空格，破折号)。
+
+**正确格式**:
+```markdown
+### R001 — Topic description
+```
+
+**错误格式**:
+```markdown
+## R001 Topic   # ❌ 两个 # 不对
+### R1 - Topic  # ❌ 破折号是 - 不是 —
+### Decision 1  # ❌ 没有 R00X 编号
+```
+
+### Q: 我的 research.md 很长，可以拆分吗？
+
+**A**: 不建议拆分。research.md 是单一真相源 (Single Source of Truth)。
+- 如果决策太多（>20 个），考虑需求是否过大，应拆分为多个 REQ-ID。
+- 详细研究材料放在 `research/internal/` 或 `research/mcp/`，research.md 只记录决策摘要。
+
+---
+
+**Maintained By**: CC-DevFlow Team
+**Last Updated**: 2025-01-26
+**Related Docs**:
+- [flow-init.md](../../commands/flow-init.md) - 需求初始化流程
+- [validate-research.sh](../../scripts/validate-research.sh) - 验证脚本
+- [flow-init-optimization-plan.md](../../../flow-init-optimization-plan.md) - 优化方案

package/.claude/skills/workflow/flow-init/context.jsonl

@@ -0,0 +1,5 @@
+{"file": ".claude/rules/project-constitution.md", "reason": "Quality rules and constraints"}
+{"file": "devflow/ROADMAP.md", "reason": "Project roadmap context", "optional": true}
+{"file": "devflow/ARCHITECTURE.md", "reason": "Architecture context", "optional": true}
+{"file": "devflow/spec/frontend/index.md", "reason": "Frontend conventions", "optional": true}
+{"file": "devflow/spec/backend/index.md", "reason": "Backend conventions", "optional": true}