cc-devflow 1.0.1

package/.claude/docs/templates/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/docs/templates/REVIEW-HIGH.md

@@ -0,0 +1,57 @@
+# High-Rigor Code Review Template
+
+## Summary
+- What changed:
+- Top risks:
+- Approval: `<approve|comment|request_changes|blocker>`
+
+## Affected files
+- `<path>` — `<reason>` (`added|modified|deleted`)
+
+## Root cause & assumptions
+- Analysis:
+- Assumptions:
+
+## Findings
+- [SEVERITY] [CATEGORY] Short title
+  - Where: `file:line-range`
+  - Evidence:
+  - Impact:
+  - Standards (CWE/OWASP/Policy):
+  - Repro:
+  - Recommendation:
+  - Tests:
+
+*(Repeat the findings block per issue.)*
+
+## Performance
+- Hotspots:
+- Complexity notes:
+- Bench/Monitoring plan:
+
+## Integration & Rollout
+- APIs/contracts:
+- DB migrations:
+- Feature flags & rollout:
+- Resilience:
+- Rollback plan:
+
+## Testing
+- Coverage summary:
+- Gaps:
+- Flakiness risks:
+- Targeted test plan:
+
+## Docs & Observability
+- Docs to update/create:
+- Logs/Metrics/Traces/Alerts:
+- Runbook updates:
+
+## Open questions
+- `<item>`
+
+## Final recommendation
+- Decision:
+- Must-fix before merge:
+- Nice-to-have post merge:
+- Confidence: `<low|medium|high>`

package/.claude/docs/templates/ROADMAP_DIALOGUE_TEMPLATE.md

@@ -0,0 +1,198 @@
+# Core-Roadmap Dialogue Template
+
+> 6-stage interactive dialogue script for `/core-roadmap`
+
+<!-- ============================================================
+     调用上下文声明 (Invocation Context Declaration)
+     ============================================================
+
+本模板由 `/core-roadmap` 命令通过 {TEMPLATE:dialogue} 引用加载。
+
+模板中的 {SCRIPT:xxx} 占位符引用 core-roadmap.md 头文件中的 scripts 定义：
+```yaml
+# 来源: .claude/commands/core-roadmap.md 头文件
+scripts:
+  calculate_quarter: .claude/scripts/calculate-quarter.sh
+  sync_progress: .claude/scripts/sync-roadmap-progress.sh
+```
+
+占位符解析:
+- {SCRIPT:calculate_quarter} → bash .claude/scripts/calculate-quarter.sh
+- {SCRIPT:sync_progress}     → bash .claude/scripts/sync-roadmap-progress.sh
+============================================================ -->
+
+---
+
+## Stage 0: Context Detection (上下文检测)
+
+```bash
+# 1. 检查 ROADMAP.md
+→ 存在: mode = "update"
+→ 不存在: mode = "create"
+
+# 2. 计算当前季度
+bash {SCRIPT:calculate_quarter}
+→ 获取: current_quarter, current_year, next_quarters[]
+
+# 3. 扫描 requirements/ 计算 Velocity
+→ 完成需求数、平均天数、季度容量
+
+# 4. 初始化 context 对象
+{
+  "mode": "create",
+  "velocity": {...},
+  "quarter_info": {...}
+}
+```
+
+---
+
+## Stage 1: Vision Statement (愿景声明)
+
+**对话引导**:
+```
+"描述未来 3 个月的核心愿景..."
+"1. 要解决什么核心问题？"
+"2. 目标用户是谁？"
+"3. 核心价值主张是什么？"
+"4. 期望达成的里程碑是什么？"
+```
+
+**收集**: `vision_statement`
+
+---
+
+## Stage 2: Project Analysis (项目分析)
+
+**自动执行**:
+```bash
+# 1. 扫描 requirements/REQ-*/PRD.md
+→ 分析完成需求的延伸方向
+
+# 2. 展示功能模块分布和技术栈
+→ 推荐延伸项目
+
+# 3. 用户确认 → Stage 3
+```
+
+---
+
+## Stage 3: Brainstorming (头脑风暴)
+
+**收集循环**:
+```
+对话收集候选项目:
+  - 标题
+  - 来源 (从哪个需求延伸)
+  - 描述
+  - 优先级 (P1/P2/P3)
+  - 预估工作量 (周数)
+
+分配 RM-ID: RM-001, RM-002, ...
+
+验证:
+  - 至少 1 个 P1 项目
+  - 总工作量 vs 容量 (警告超容量 30%)
+```
+
+**收集**: `candidates[]`
+
+---
+
+## Stage 4: Dependency Analysis (依赖分析)
+
+**收集循环**:
+```
+格式: {RM-ID} depends on {REQ-ID or RM-ID}
+
+验证:
+  - 检查循环依赖 (拓扑排序)
+  - 检查悬挂依赖 (被依赖项未完成)
+  - 生成依赖图预览
+```
+
+**收集**: `dependencies[]`
+
+---
+
+## Stage 5: Timeline Planning (时间线规划)
+
+**收集循环**:
+```
+分配项目到季度:
+  格式: {RM-ID} → Q{n}-{YYYY}
+
+验证:
+  - 依赖约束 (被依赖项在同季度或更早)
+  - 容量约束 (每季度 ≤ 150% 容量)
+
+生成时间线预览
+```
+
+**收集**: `timeline{}`
+
+---
+
+## Stage 6: Final Confirmation (最终确认)
+
+**展示完整规划汇总**:
+```
+- 愿景
+- 项目总览 (按优先级)
+- 季度分布
+- 依赖关系
+- 容量评估
+
+用户确认 → Stage 7
+用户修改 → 跳转到对应 Stage
+```
+
+---
+
+## Stage 7: Agent Invocation (生成文档)
+
+```bash
+# 1. 保存上下文
+→ .roadmap-context.json
+
+# 2. 调用 roadmap-planner Agent
+Prompt: "Generate ROADMAP.md and BACKLOG.md based on context..."
+→ 生成 devflow/ROADMAP.md
+→ 生成 devflow/BACKLOG.md
+
+# 3. 调用 architecture-designer Agent
+Prompt: "Generate ARCHITECTURE.md with 4 diagrams..."
+→ 生成 devflow/ARCHITECTURE.md (4个Mermaid图表)
+```
+
+---
+
+## Stage 8: Final Report (完成报告)
+
+**展示生成文件**:
+```
+✅ devflow/ROADMAP.md (路线图项目, 依赖图, 速度指标)
+✅ devflow/BACKLOG.md (所有候选项目详情)
+✅ devflow/ARCHITECTURE.md (4个架构图表)
+
+下一步建议:
+1. 审查路线图
+2. 开始首个需求: /flow-init "REQ-XXX|{RM-title}"
+3. 定期更新: /core-roadmap --regenerate
+4. 监控进度: /flow-status --all
+```
+
+---
+
+## Output Files
+
+```
+devflow/
+├── ROADMAP.md           # 路线图 (Milestones, Dependency Graph, Velocity)
+├── BACKLOG.md           # 积压清单 (所有 RM-ID 详情)
+└── ARCHITECTURE.md      # 架构文档 (4个Mermaid图表)
+```
+
+---
+
+**Last Updated**: 2025-12-19