cc-devflow 1.0.1

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

@@ -0,0 +1,313 @@
+---
+name: flow-init
+description: 'Initialize requirement structure. Usage: /flow-init "REQ-123|Title|URLs"'
+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
+templates:
+  flow: .claude/docs/templates/INIT_FLOW_TEMPLATE.md
+  research: .claude/docs/templates/RESEARCH_TEMPLATE.md
+guides:
+  troubleshoot: .claude/docs/guides/INIT_TROUBLESHOOTING.md
+---
+
+<!-- ============================================================
+     头文件引用语法规范 (Header File Reference Syntax)
+     ============================================================
+
+命令头文件格式:
+```yaml
+scripts:
+  create: .claude/scripts/create-requirement.sh
+templates:
+  flow: .claude/docs/templates/INIT_FLOW_TEMPLATE.md
+guides:
+  troubleshoot: .claude/docs/guides/INIT_TROUBLESHOOTING.md
+```
+
+引用语法:
+- {SCRIPT:create}      → 执行 .claude/scripts/create-requirement.sh
+- {TEMPLATE:flow}      → 加载 .claude/docs/templates/INIT_FLOW_TEMPLATE.md
+- {GUIDE:troubleshoot} → 参考 .claude/docs/guides/INIT_TROUBLESHOOTING.md
+
+使用案例:
+```markdown
+# 正文中遇到:
+→ Run: {SCRIPT:create} "REQ-123" --title "User Auth"
+# 解释为:
+→ 执行命令: bash .claude/scripts/create-requirement.sh "REQ-123" --title "User Auth"
+
+# 正文中遇到:
+→ 详见 {TEMPLATE:flow} Stage 2.5
+# 解释为:
+→ 打开并阅读 .claude/docs/templates/INIT_FLOW_TEMPLATE.md 中的 Stage 2.5 章节
+
+# 正文中遇到:
+→ 遇到问题参考 {GUIDE:troubleshoot}
+# 解释为:
+→ 打开并阅读 .claude/docs/guides/INIT_TROUBLESHOOTING.md
+```
+
+规则: 遇到 {TYPE:key} 占位符时，去头文件 YAML 中找对应类型的 key，获取文件路径并执行/加载。
+============================================================ -->
+
+# Flow-Init - 需求初始化命令
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?" 或 --interactive
+```
+
+**格式**:
+- REQ_ID: `^(REQ|BUG)-[0-9]+$` (例如: REQ-123, BUG-456)
+- TITLE: 需求简短标题
+- PLAN_URLS: 计划文档URL，多个用逗号分隔 (可选)
+
+**示例**:
+```
+/flow-init "REQ-123|User Authentication"
+/flow-init "REQ-124|数据导出|https://docs.example.com/export-spec.md"
+/flow-init --interactive
+```
+
+---
+
+## 执行前加载
+
+**详细流程**:
+→ 参见 `{TEMPLATE:flow}` 获取完整执行流程
+
+**研究模板**:
+→ 参见 `{TEMPLATE:research}` 了解研究文档格式
+
+**故障排查**:
+→ 遇到问题参考 `{GUIDE:troubleshoot}`
+
+---
+
+## 执行流程
+
+### Stage 1: Entry Gate (参数验证)
+
+```
+1. 解析参数: REQ_ID|TITLE|PLAN_URLS
+   → 验证 REQ_ID 格式: ^(REQ|BUG)-[0-9]+$
+   → 提取 TITLE 和 PLAN_URLS
+
+2. 前置条件检查
+   → Run: {SCRIPT:prereq} --json --paths-only
+   → 检查 Git 状态是否干净
+   → 验证 devflow/ 目录存在
+
+3. 目录唯一性检查
+   → 确认 devflow/requirements/${REQ_ID}/ 不存在
+   → 如果存在 → ERROR (使用 --force 强制覆盖)
+
+4. 验证通过 → 继续 Stage 1.5
+```
+
+---
+
+### Stage 1.5: Context Loading (路线图与架构)
+
+**目标**: 理解需求在项目中的位置
+
+```
+检查 ROADMAP.md 和 ARCHITECTURE.md:
+→ 如果存在: 加载上下文，展示需求位置
+→ 如果不存在: 提示可选运行 /core-roadmap
+
+→ 详见 {TEMPLATE:flow} Stage 1.5
+```
+
+**输出**: 显示需求在路线图和架构中的位置 (如果可用)
+
+---
+
+### Stage 2: Directory Initialization
+
+```
+创建需求目录结构:
+→ Run: {SCRIPT:create} "${REQ_ID}" --title "${TITLE}" --json
+
+生成文件:
+- devflow/requirements/${REQ_ID}/README.md
+- devflow/requirements/${REQ_ID}/EXECUTION_LOG.md
+- devflow/requirements/${REQ_ID}/orchestration_status.json
+- devflow/requirements/${REQ_ID}/research/ (目录)
+
+→ 详见 {TEMPLATE:flow} Stage 2
+```
+
+---
+
+### Stage 2.5: Research (MCP Mandatory Flow)
+
+**目标**: 收集"真实材料"，所有步骤 **MANDATORY**
+
+```
+S0: Internal Codebase Research (必需)
+→ 分析现有代码库，生成 research/internal/codebase-overview.md
+
+Task 1-5: External Learning Materials (MCP)
+1. Official Documentation (Context7)
+2. Domain Tutorials (Web Search)
+3. Core Materials (WebFetch)
+4. Case Studies/Examples (Web Search + WebFetch)
+5. Summary & Recommendations
+
+→ 详见 {TEMPLATE:flow} Stage 2.5
+```
+
+**输出**:
+- `research/internal/codebase-overview.md`
+- `research/mcp/$(date +%Y%m%d)/official/*`
+- `research/mcp/$(date +%Y%m%d)/guides/*`
+- `research/mcp/$(date +%Y%m%d)/tutorials/*`
+- `research/mcp/$(date +%Y%m%d)/examples/*`
+- `research/research-summary.md`
+
+---
+
+### Stage 2.6: Research Consolidation
+
+```
+研究决策整合:
+1. Generate research tasks
+   → Run: {SCRIPT:research_tasks} "${REQ_DIR}"
+   → Output: research/tasks.json
+
+2. Populate task decisions
+   → Run: {SCRIPT:populate_tasks} "${REQ_DIR}"
+   → Fill decision/rationale/alternatives from research
+
+3. Consolidate research
+   → Run: {SCRIPT:consolidate} "${REQ_DIR}"
+   → Output: research/research.md
+   → Format: Decision/Rationale/Alternatives/Source
+
+4. Update status
+   → orchestration_status.json.phase0_complete = true
+
+→ 详见 {TEMPLATE:flow} Stage 2.6
+```
+
+---
+
+### 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
+
+```
+生成工作流指南:
+→ devflow/requirements/${REQ_ID}/README.md
+→ 包含: 需求概述、工作流步骤、检查清单
+```
+
+---
+
+### Stage 5: Exit Gate (5-Level Quality Check)
+
+**5层验证**:
+
+```
+Level 1: File Existence Check
+→ 验证所有必需文件已创建
+
+Level 2: Research.md Structure Validation
+→ Run: {SCRIPT:validate_research} "${REQ_DIR}"
+→ 检查 research.md 结构
+
+Level 3: Research.md Content Quality
+→ 无 TODO/FIXME/{{PLACEHOLDER}} 标记
+→ 每个 Decision block 完整
+
+Level 4: Research Tasks Validation
+→ 验证 tasks.json 格式和内容
+
+Level 5: Git & Status & Constitution
+→ Git 分支创建成功
+→ orchestration_status.json 正确
+→ Constitution 符合性检查
+
+→ 详见 {TEMPLATE:flow} Stage 5
+```
+
+---
+
+## 输出产物
+
+### Requirements
+
+```
+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(title)}`
+- **Status**: orchestration_status.json.status = "initialized"
+- **Phase**: orchestration_status.json.phase = "planning"
+
+---
+
+## 错误处理
+
+**常见错误**:
+→ 详见 `{GUIDE:troubleshoot}`
+
+**主要错误场景**:
+1. Invalid REQ_ID format → 检查格式
+2. REQ_ID already exists → 使用不同 ID 或 --force
+3. Git status not clean → commit/stash changes
+4. Research validation failed → 手动补充 research.md
+5. MCP fetch failed → 继续但标记待补项
+
+**恢复步骤**:
+→ 详见 `{GUIDE:troubleshoot}` Recovery Procedures
+
+---
+
+## Next Step
+
+```
+/flow-prd "${REQ_ID}"
+```
+
+生成产品需求文档
+
+---
+
+**Related Documentation**:
+- [INIT_FLOW_TEMPLATE.md](../.claude/docs/templates/INIT_FLOW_TEMPLATE.md) - 详细执行流程
+- [INIT_TROUBLESHOOTING.md](../.claude/docs/guides/INIT_TROUBLESHOOTING.md) - 故障排查指南
+- [RESEARCH_TEMPLATE.md](../.claude/docs/templates/RESEARCH_TEMPLATE.md) - 研究模板格式

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

@@ -0,0 +1,394 @@
+---
+name: flow-new
+description: 'One-shot requirement flow. Usage: /flow-new "REQ-123|支持用户下单|https://plan.example.com/Q1"'
+templates:
+  orchestration: .claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md
+guides:
+  troubleshoot: .claude/docs/guides/NEW_TROUBLESHOOTING.md
+---
+
+<!-- ============================================================
+     头文件引用语法规范 (Header File Reference Syntax)
+     ============================================================
+
+命令头文件格式:
+```yaml
+templates:
+  orchestration: .claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md
+guides:
+  troubleshoot: .claude/docs/guides/NEW_TROUBLESHOOTING.md
+```
+
+引用语法:
+- {TEMPLATE:orchestration} → 加载 .claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md
+- {GUIDE:troubleshoot}     → 参考 .claude/docs/guides/NEW_TROUBLESHOOTING.md
+
+使用案例:
+```markdown
+# 正文中遇到:
+→ 详见 {TEMPLATE:orchestration} Stage 4
+# 解释为:
+→ 打开并阅读 .claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md 中的 Stage 4 章节
+
+# 正文中遇到:
+→ 常见错误参见 {GUIDE:troubleshoot} Error 3
+# 解释为:
+→ 打开并阅读 .claude/docs/guides/NEW_TROUBLESHOOTING.md 中的 Error 3 章节
+```
+
+规则: 遇到 {TYPE:key} 占位符时，去头文件 YAML 中找对应类型的 key，获取文件路径并加载。
+============================================================ -->
+
+# Flow-New - 一键需求开发流
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
+```
+
+**格式**:
+- REQ_ID: 需求编号 (例如: REQ-123)
+- TITLE: 需求标题
+- PLAN_URLS: 计划文档URL，多个用逗号分隔 (可选)
+
+**示例**:
+```
+/flow-new "REQ-123|支持用户下单|https://plan.example.com/Q1"
+/flow-new "REQ-124|用户权限管理"
+```
+
+---
+
+## 执行前加载
+
+**详细编排流程**:
+→ 参见 `{TEMPLATE:orchestration}` 获取完整编排逻辑
+
+**故障排查**:
+→ 遇到问题参考 `{GUIDE:troubleshoot}`
+
+---
+
+## 架构说明
+
+**设计理念**: flow-new 是**编排器**（Orchestrator），串行调用 7-8 个阶段化命令
+
+**调用链**:
+```
+/flow-new "REQ-123|Title|URLs"
+  ↓
+[1/8] /flow-init "REQ-123|Title|URLs"
+  ↓
+[2/8] /flow-prd "REQ-123"
+  ↓
+[2.3/8] /flow-checklist "REQ-123" (可选, 80%门禁)
+  ↓
+[2.5/8] /flow-ui "REQ-123" (条件触发)
+  ↓
+[2.7/8] /flow-tech "REQ-123" (必需)
+  ↓
+[3/8] /flow-epic "REQ-123"
+  ↓
+[4/8] /flow-dev "REQ-123"
+  ↓
+[5/8] /flow-qa "REQ-123" --full
+  ↓
+[6/8] /flow-release "REQ-123"
+```
+
+---
+
+## 执行流程骨架
+
+### [1/8] 初始化 → /flow-init
+
+```
+调用: /flow-init "${REQ_ID}|${TITLE}|${PLAN_URLS}"
+
+检查: orchestration_status.json.status === "initialized"
+
+→ 详见 {TEMPLATE:orchestration} Stage 1
+```
+
+**输出**:
+- Git分支: `feature/${REQ_ID}-${slug(title)}`
+- 需求目录已创建
+- 研究材料已抓取
+
+---
+
+### [2/8] PRD生成 → /flow-prd
+
+```
+调用: /flow-prd "${REQ_ID}"
+
+检查: PRD.md 存在且完整
+
+→ 详见 {TEMPLATE:orchestration} Stage 2
+```
+
+**输出**:
+- PRD.md (用户故事 + GWT验收标准)
+- Constitution检查通过
+
+---
+
+### [2.3/8] 需求质量检查 → /flow-checklist (可选)
+
+```
+触发条件: quality-rules.yml 中 checklist_gate_enabled: true
+
+调用: /flow-checklist "${REQ_ID}"
+
+闸门: 完成度 ≥ 80%
+
+→ 详见 {TEMPLATE:orchestration} Stage 2.3
+```
+
+---
+
+### [2.5/8] UI原型生成 → /flow-ui (条件触发)
+
+```
+触发条件 (任一满足):
+  - PRD包含UI关键词 ("页面"/"表单"/"按钮" etc.)
+  - 项目包含 package.json 或 src/components/
+  - 用户显式请求
+
+调用: /flow-ui "${REQ_ID}"
+
+→ 详见 {TEMPLATE:orchestration} Stage 2.5 (包含 UI Detection Logic)
+```
+
+**输出** (如有UI需求):
+- UI_PROTOTYPE.html (响应式单文件原型)
+- research/ui_design_strategy.md
+
+**跳过** (无UI需求):
+- orchestration_status.json.ui_skipped = true
+
+---
+
+### [2.7/8] 技术方案设计 → /flow-tech (必需)
+
+```
+调用: /flow-tech "${REQ_ID}"
+
+检查: TECH_DESIGN.md 完整 (所有 Section 1-7)
+
+→ 详见 {TEMPLATE:orchestration} Stage 2.7
+```
+
+**输出**:
+- TECH_DESIGN.md (完整技术方案)
+- data-model.md (数据模型)
+- contracts/openapi.yaml (API契约)
+- quickstart.md (快速开始)
+
+---
+
+### [3/8] Epic规划 → /flow-epic
+
+```
+调用: /flow-epic "${REQ_ID}"
+
+检查:
+  - EPIC.md + TASKS.md 存在
+  - TASKS 覆盖 TECH_DESIGN.md 所有技术层
+
+→ 详见 {TEMPLATE:orchestration} Stage 3
+```
+
+**输出**:
+- EPIC.md (Epic描述)
+- TASKS.md (单文件管理所有任务)
+
+---
+
+### [4/8] 开发执行 → /flow-dev
+
+```
+调用: /flow-dev "${REQ_ID}"
+
+执行模式: TDD (Tests First)
+  Phase 1: 分析现有代码
+  Phase 2: 编写测试 (Tests First)
+  TEST VERIFICATION CHECKPOINT (测试必须先失败)
+  Phase 3: 实现代码
+  Phase 4: 测试验证 (测试必须通过)
+  Phase 5: Git提交并标记完成
+
+→ 详见 {TEMPLATE:orchestration} Stage 4
+```
+
+**输出**:
+- 实现代码
+- 测试代码
+- tasks/*.completed 标记
+- Git commits (每个任务一个)
+
+---
+
+### [5/8] 质量保证 → /flow-qa
+
+```
+调用: /flow-qa "${REQ_ID}" --full
+
+Exit Gate检查:
+  - ✅ 所有测试通过
+  - ✅ 代码覆盖率 ≥ 80%
+  - ✅ 无高危安全问题
+  - ✅ TypeScript类型检查通过
+
+→ 详见 {TEMPLATE:orchestration} Stage 5
+```
+
+**输出**:
+- TEST_PLAN.md
+- TEST_REPORT.md
+- SECURITY_PLAN.md
+- SECURITY_REPORT.md
+
+---
+
+### [6/8] 发布管理 → /flow-release
+
+```
+调用: /flow-release "${REQ_ID}"
+
+执行:
+  - 生成发布计划
+  - 更新 CLAUDE.md (如有重要架构变更)
+  - 最终构建
+  - 创建 GitHub Pull Request
+
+→ 详见 {TEMPLATE:orchestration} Stage 6
+```
+
+**输出**:
+- RELEASE_PLAN.md
+- CLAUDE.md (更新技术架构，如有)
+- GitHub Pull Request
+
+---
+
+## 进度展示
+
+**实时进度** (详见 `{TEMPLATE:orchestration}` Progress Display Format):
+
+```
+🎯 CC-DevFlow 完整需求开发流程
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+需求: 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] ⏳ 等待发布管理...
+```
+
+---
+
+## 输出产物
+
+**完整目录结构** (详见 `{TEMPLATE:orchestration}` Output Structure):
+
+```
+devflow/requirements/${REQ_ID}/
+├── research/ (初始化时生成)
+├── PRD.md
+├── UI_PROTOTYPE.html (条件)
+├── TECH_DESIGN.md
+├── data-model.md
+├── contracts/openapi.yaml
+├── quickstart.md
+├── EPIC.md
+├── TASKS.md
+├── tasks/*.completed
+├── TEST_PLAN.md + TEST_REPORT.md
+├── SECURITY_PLAN.md + SECURITY_REPORT.md
+└── RELEASE_PLAN.md
+```
+
+---
+
+## 中断与恢复
+
+```bash
+# 查看当前状态
+/flow-status REQ-123
+
+# 从中断点恢复
+/flow-restart "REQ-123"
+
+# 或手动执行特定阶段
+/flow-tech "REQ-123"
+/flow-epic "REQ-123"
+/flow-dev "REQ-123" --resume
+```
+
+---
+
+## 错误处理
+
+**常见错误**:
+→ 详见 `{GUIDE:troubleshoot}`
+
+**主要错误场景**:
+1. Stage command not found → 检查命令文件
+2. Status file corrupted → 重建或修复
+3. 中途中断无法恢复 → 使用 /flow-restart
+4. UI detection false positive → 在PRD明确标注
+5. Epic 未覆盖所有技术层 → 重新生成或手动补充
+6. QA gate failure → 补充测试/修复安全问题
+7. Build failure → 修复类型错误
+8. PR creation failed → 认证 gh CLI 或手动创建
+
+**恢复步骤**:
+→ 详见 `{GUIDE:troubleshoot}` Recovery Procedures
+
+---
+
+## 使用建议
+
+### ✅ 适合使用 flow-new
+
+- 简单明确的需求
+- 演示和学习工作流程
+- 快速原型开发
+- 熟悉的需求类型
+
+### ❌ 建议使用阶段化命令
+
+- 复杂需求，需要每个阶段审查
+- 需要在PRD阶段与需求方确认
+- 需要在Epic阶段调整任务分解
+- 开发过程中可能需要暂停调整
+
+---
+
+## Next Step
+
+```
+# 查看PR状态
+cat devflow/requirements/${REQ_ID}/RELEASE_PLAN.md | grep "PR URL"
+
+# 审查PR
+gh pr view <PR_NUMBER>
+
+# 合并PR
+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) - 开发阶段