cc-devflow 2.4.6 → 4.1.0

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

@@ -1,370 +0,0 @@
----
-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
-  brainstorm: .claude/docs/templates/BRAINSTORM_TEMPLATE.md
-guides:
-  troubleshoot: .claude/docs/guides/INIT_TROUBLESHOOTING.md
-skills:
-  brainstorming: .claude/skills/flow-brainstorming/SKILL.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
-   → 若 TITLE 含中文/非ASCII，使用模型意译生成 BRANCH_TITLE_EN（英文语义翻译，禁止拼音/音译）
-   → BRANCH_TITLE_EN 仅用于分支名，文档标题仍使用原始 TITLE
-   → 若意译不确定或未生成 ASCII 结果，向用户确认英文分支标题
-
-2. 前置条件检查
-   → Run: {SCRIPT:prereq} --json --paths-only
-   → 检查 Git 状态是否干净
-   → 验证 devflow/ 目录存在
-
-3. 目录唯一性检查
-   → 确认 devflow/requirements/${REQ_ID}/ 不存在
-   → 如果存在 → ERROR (使用 --force 强制覆盖)
-
-4. 验证通过 → 继续 Stage 1.5
-```
-
----
-
-### 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 (路线图与架构)
-
-**目标**: 理解需求在项目中的位置
-
-```
-检查 ROADMAP.md 和 ARCHITECTURE.md:
-→ 如果存在: 加载上下文，展示需求位置
-→ 如果不存在: 提示可选运行 /core-roadmap
-
-→ 详见 {TEMPLATE:flow} Stage 1.5
-```
-
-**输出**: 显示需求在路线图和架构中的位置 (如果可用)
-
----
-
-### Stage 2: Directory Initialization
-
-```
-创建需求目录结构:
-→ Run: {SCRIPT:create} "${REQ_ID}" --title "${TITLE}" --branch-title "${BRANCH_TITLE_EN}" --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.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 (Subagent Mandatory)
-
-**目标**: 研究默认必跑，但将“研究型内容”隔离到 subagent，避免主会话上下文耗尽。
-
-**Iron Law**: 大内容落盘，主会话只返回「决策摘要 + 文件路径」。
-
-#### ✅ Mandatory: Call `flow-researcher` Subagent
-
-> subagent 负责内部/外部研究、落盘、任务回填、研究整合与质量验证；主 agent 只做编排与最终 Gate。
-
-```
-Task tool call:
-  description: "Run mandatory research for /flow-init (file-based memory)"
-  subagent_type: "flow-researcher"
-  model: "inherit"
-  prompt: (JSON)
-    {
-      "reqId": "${REQ_ID}",
-      "reqDir": "devflow/requirements/${REQ_ID}",
-      "title": "${TITLE}",
-      "planUrls": ["..."],
-      "contextFiles": {
-        "brainstorm": "devflow/requirements/${REQ_ID}/BRAINSTORM.md",
-        "roadmap": "devflow/ROADMAP.md",
-        "architecture": "devflow/ARCHITECTURE.md"
-      }
-    }
-```
-
-**期望输出** (由 subagent 写入):
-- `devflow/requirements/${REQ_ID}/research/internal/codebase-overview.md`
-- `devflow/requirements/${REQ_ID}/research/mcp/$(date +%Y%m%d)/**`
-- `devflow/requirements/${REQ_ID}/research/research-summary.md`
-- `devflow/requirements/${REQ_ID}/research/tasks.json` (decision/rationale/alternatives 完整)
-- `devflow/requirements/${REQ_ID}/research/research.md` (可通过 validate-research)
-
----
-
-### Stage 2.6: Research Consolidation
-
-> 该阶段由 `flow-researcher` subagent 执行（包含 tasks 生成/回填/整合/校验）。
-
-主 agent 在 Exit Gate 中只做最终验证与状态更新：
-- Run: `{SCRIPT:validate_research} "${REQ_DIR}" --strict`
-- `orchestration_status.json.phase0_complete = true`
-
----
-### Stage 3: README Generation
-
-```
-生成工作流指南:
-→ devflow/requirements/${REQ_ID}/README.md
-→ 包含: 需求概述、工作流步骤、检查清单
-```
-
----
-
-### Stage 4: Exit Gate (5-Level Quality Check)
-
-**5层验证**:
-
-```
-Level 1: File Existence Check
-→ 验证所有必需文件已创建
-
-Level 2: Research.md Structure Validation
-→ Run: {SCRIPT:validate_research} "${REQ_DIR}" --strict
-→ 检查 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 4
-```
-
----
-
-## 输出产物
-
-### Requirements
-
-```
-devflow/requirements/${REQ_ID}/
-├── README.md
-├── BRAINSTORM.md               # 需求的北极星 (Stage 2.3)
-├── 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"
-
----
-
-## 错误处理
-
-**常见错误**:
-→ 详见 `{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-prd.md

@@ -1,144 +0,0 @@
----
-name: flow-prd
-description: 'Generate Product Requirements Document. Usage: /flow-prd "REQ-123" or /flow-prd'
-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 生成命令
-
-## User Input
-```text
-$ARGUMENTS = "REQ_ID?"
-```
-若未提供则根据当前分支或 `DEVFLOW_REQ_ID` 自动解析。
-
-## 命令格式
-```text
-/flow-prd "REQ_ID"
-/flow-prd             # Auto-detect from current branch
-```
-
-## 执行流程
-
-### 阶段 1: Entry Gate
-```
-1. 解析 REQ_ID
-   → If argument provided: use it
-   → Else: run {SCRIPT:prereq} --json --paths-only
-   → If仍为空: ERROR "No requirement ID found."
-
-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
-      • research/tasks.json
-   → 缺少任何研究产物 → ERROR "Research artifacts missing. Run /flow-init consolidation."
-
-   **研究材料质量验证** (新增 - 2025-01-26):
-   → Run: {SCRIPT:validate_research} "${REQ_DIR}" --strict
-   → 验证 research.md 质量（5-Level 检查）:
-      • LEVEL 1: research.md 文件存在
-      • LEVEL 2: 必需章节完整 (Research Summary, Decisions)
-      • LEVEL 3: 无 TODO/PLACEHOLDER 占位符
-      • LEVEL 4: tasks.json 格式有效
-      • LEVEL 5: Constitution 合规
-   → 验证失败 → ERROR "research.md quality check failed. Fix issues before /flow-prd."
-
-   **CRITICAL**: 如果 research.md 包含 "TODO - fill decision outcome"，
-   说明 /flow-init 的研究任务未完成。prd-writer 无法使用不完整的研究材料。
-
-   **Fix Options**:
-     1. 手动填充 research/tasks.json 的 decision/rationale/alternatives 字段
-     2. 重新运行 consolidate-research.sh
-     3. 直接编辑 research/research.md 补充决策内容
-     4. 参考 .claude/docs/templates/RESEARCH_TEMPLATE.md 模板
-
-4. PRD 覆盖提示
-   → 若 PRD.md 已存在 → WARN 并确认是否覆盖
-
-5. 状态校验
-   → orchestration_status.status ∈ {"initialized", "prd_generation_failed"}
-   → 否则提示按流程顺序执行
-```
-
-### 阶段 2: 生成准备
-```
-1. Load PRD 模板 (.claude/docs/templates/PRD_TEMPLATE.md)
-2. 汇总上下文:
-   → research/research.md（Decision/Rationale/Alternatives）
-   → research/internal/codebase-overview.md
-   → research/mcp/*.md（如有）
-3. 更新 orchestration_status:
-   → status = "prd_generation_in_progress"
-   → phase = "planning"
-4. EXECUTION_LOG.md 记录启动条目
-```
-
-### 阶段 3: 调用 prd-writer Agent
-```
-Prompt 关键要点:
-  - 输入: REQ_ID, Title, research 集合, PRD 模板
-  - 要求:
-      • 按模板 Execution Flow 输出背景、目标、用户故事 (GWT)、NFR、技术约束、成功指标
-      • 记录 Constitution Check，确保无硬编码密钥、无部分实现
-      • 验证清单必须填写
-  - 输出: 完整 PRD.md
-  - 日志: log_event "${REQ_ID}" "PRD generation completed"
-```
-
-### 阶段 4: Exit Gate
-```
-1. 文件存在
-   → PRD.md 必须生成
-
-2. 结构检查
-   → 无 {{PLACEHOLDER}}
-   → 包含: 背景/目标、用户故事+GWT、NFR、技术约束、成功指标、Constitution Check、验证清单
-
-3. 宪法校验
-   → Run: {SCRIPT:validate_constitution} --type prd --severity warning
-   → 出现 ERROR 级违规时终止
-
-4. 状态更新
-   → orchestration_status:
-        status = "prd_complete"
-        phase = "epic_planning"
-        completedSteps append "prd"
-   → EXECUTION_LOG.md 记录完成
-```
-
-## 输出
-```
-✅ PRD.md (≥100 行、完整模板)
-✅ orchestration_status.json 更新 (prd_complete)
-✅ EXECUTION_LOG.md 记录
-```
-
-## 错误处理
-- 缺少研究产物 → 返回指令让用户重复 `/flow-init` consolidation。
-- PRD 生成失败 → 将 status 设为 `prd_generation_failed`，方便重试。
-- 宪法检查失败 → 显示违规列表并终止，待修复后重跑。
-
-## 下一步
-1. 审阅 PRD.md，确认需求准确。
-2. 运行 `/flow-tech` 生成技术方案及 data-model/contracts/quickstart。
-3. 使用 `/flow-epic` 做 Epic/TASKS 规划。

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

@@ -1,93 +0,0 @@
----
-name: flow-qa
-description: 'Execute quality assurance and security review. Usage: /flow-qa "REQ-123" or /flow-qa'
-scripts:
-  prereq: .claude/scripts/check-prerequisites.sh
-  check_tasks: .claude/scripts/check-task-status.sh
-  validate_constitution: .claude/scripts/validate-constitution.sh
----
-
-# Flow-QA - 质量保证命令
-
-## User Input
-```text
-$ARGUMENTS = "REQ_ID?"
-```
-未提供则根据当前分支或 `DEVFLOW_REQ_ID` 自动解析。
-
-## 执行流程
-
-### 阶段 1: Entry Gate
-```
-1. 解析 REQ_ID
-2. {SCRIPT:prereq} --json 验证:
-   → 存在 PRD.md、TECH_DESIGN.md、data-model.md、contracts/、quickstart.md、EPIC.md、TASKS.md
-   → orchestration_status.status ∈ {"development_complete", "qa_failed"}
-   → phase1_complete == true
-3. {SCRIPT:check_tasks} --json 确认 remaining == 0
-4. quickstart.md 中的测试命令必须全部通过（先 dry-run）
-5. TEST_REPORT.md / SECURITY_REPORT.md 已存在时提示是否覆盖
-```
-
-### 阶段 2: QA 准备
-```
-1. 执行 quickstart 中的覆盖率命令（如有）
-2. 收集上下文:
-   → PRD 用户故事、验收标准
-   → TECH_DESIGN 决策（安全、性能）
-   → data-model / contracts
-   → TASKS DoD、提交记录
-3. 更新 orchestration_status:
-   → status = "qa_in_progress"
-   → phase = "quality_assurance"
-4. EXECUTION_LOG.md 记录 QA 启动（含测试覆盖率）
-```
-
-### 阶段 3: Agents
-```
-1. qa-tester
-   → 输入: PRD, TECH_DESIGN, TASKS, test results, coverage
-   → 产出: TEST_PLAN.md (如缺失) / TEST_REPORT.md
-   → 覆盖内容: 覆盖率、TDD 合规、AC 覆盖、DoD 复核、缺失测试建议
-
-2. security-reviewer
-   → 输入: TECH_DESIGN 安全节、contracts、实现 diff、ENV/secret 配置
-   → 产出: SECURITY_PLAN.md (如缺失) / SECURITY_REPORT.md
-   → 检查: 认证/授权、输入验证、敏感信息、依赖风险、基础设施配置
-
-3. 可选: performance-reviewer（若 TECH_DESIGN 有性能方案）
-```
-
-### 阶段 4: Exit Gate
-```
-1. 验证报告存在:
-   → TEST_REPORT.md、SECURITY_REPORT.md
-2. 质量结论:
-   → 所有 gate (Coverage、TDD、Security) 均为 PASS；否则状态设为 qa_failed
-3. 宪法检查:
-   → {SCRIPT:validate_constitution} --type qa --severity warning
-4. 状态更新:
-   → orchestration_status.status = "qa_complete"
-   → completedSteps append "qa"
-   → lastQaAt = timestamp
-5. EXECUTION_LOG 记录完成
-```
-
-## 输出
-```
-✅ TEST_REPORT.md
-✅ SECURITY_REPORT.md
-✅ （可选）PERFORMANCE_REPORT.md
-✅ orchestration_status.json 更新 (qa_complete)
-✅ EXECUTION_LOG.md QA 记录
-```
-
-## 错误处理
-- quickstart 测试失败 → 返回错误并保持 qa_failed。
-- 报告中存在 BLOCKER → 阶段终止，需返回 `/flow-dev` 修复。
-- Constitution 违规 → 将问题标记为阻断项。
-
-## 下一步
-1. 处理 QA 报告中的问题（若有）。
-2. 确认验证通过后运行 `/flow-release`。
-3. 将报告随 PR 一并提交，供代码审阅与发布审批使用。