cc-devflow 1.0.1

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

@@ -0,0 +1,189 @@
+---
+name: flow-ui
+description: 'Generate interactive HTML prototype from PRD. Usage: /flow-ui "REQ-123" or /flow-ui'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  validate_constitution: .claude/scripts/validate-constitution.sh
+---
+
+# Flow-UI - UI 原型生成命令
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID?"
+```
+缺省时依据当前分支或 `DEVFLOW_REQ_ID` 自动解析。
+
+## 命令格式
+```text
+/flow-ui "REQ_ID"
+/flow-ui             # Auto-detect from current branch
+```
+
+## 触发原则
+- **自动触发**：PRD 含 UI 关键词（用户界面、前端、页面、交互…），或仓库存在 `package.json`、`src/components/` 等前端特征。
+- **手动触发**：用户显式调用 `/flow-ui`。
+- **自动跳过**：PRD 标注“纯后端/无 UI”，或项目缺少前端栈特征。跳过时记录 `ui_skipped`。
+
+## 执行流程
+
+### 阶段 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. 校验资产
+   → 必须存在:
+      • PRD.md（无 {{PLACEHOLDER}}）
+      • research/research.md
+      • orchestration_status.status == "prd_complete"
+   → 如果 UI_PROTOTYPE.html 已存在 → WARN 并确认覆盖
+
+3. UI 需求检测
+   → 检查 PRD 关键词 + 项目结构
+   → 如检测不到且用户拒绝继续 → 记录 EXECUTION_LOG "ui_skipped" 后退出
+```
+
+### 阶段 2: 设计风格加载与灵感采样
+```
+1. 检查项目级 STYLE.md 是否存在
+   → 检查 devflow/STYLE.md 文件
+   → 如存在:
+      • 加载 STYLE.md 作为首要参考（优先级最高）
+      • 所有颜色、字体、间距、组件必须严格遵循 STYLE.md
+      • 在 EXECUTION_LOG.md 记录 STYLE.md 版本和使用情况
+   → 如不存在:
+      • 使用默认采样策略（80+ 设计大师）
+      • 建议用户先运行 /flow-style 建立项目设计标准
+
+2. 从 PRD 抽取风格线索（作为 STYLE.md 的补充或默认策略）
+   → 背景/目标、用户画像、NFR 中的视觉/品牌要求
+   → 关键词示例: 现代、简约、科技感、典雅、活泼、企业级、极简、暗色、明快
+
+3. 建立关键词 → 设计风格/大师映射（仅在无 STYLE.md 时使用完整策略）
+   • 现代 / 简约 / 专业:
+       - 现代主义信息设计 (Josef Müller-Brockmann, Massimo Vignelli)
+       - 工业设计 (Dieter Rams, Jony Ive)
+   • 科技感 / 创新 / 动态:
+       - 生成艺术 (Refik Anadol, John Maeda)
+       - 未来派建筑 (Zaha Hadid, BIG)
+   • 典雅 / 文化 / 文艺:
+       - 亚洲与当代艺术 (原研哉, 草间弥生)
+       - 平面设计 (Paula Scher, Neville Brody)
+   • 活泼 / 年轻 / 时尚:
+       - 后现代图形 (David Carson, April Greiman)
+       - 抽象艺术 (Henri Matisse, Joan Miró)
+   • 企业级 / 金融 / 严肃:
+       - 现代主义建筑 (Le Corbusier, Alvar Aalto)
+       - 工业设计 (Braun School)
+   • 未匹配关键词:
+       - 默认组合: 现代主义 + 工业设计
+
+3. 可选灵感采集
+   → 若 PRD 或用户提供参考站点/风格，使用 WebSearch/WebFetch 收集视觉要点，
+     保存至 `research/ui_inspiration_*.md`
+
+4. 生成 `research/ui_design_strategy.md`
+   → 结构建议:
+     ```
+     # UI 设计策略 - ${REQ_ID}
+
+     ## 项目级风格指南引用（如存在）
+     - STYLE.md 路径: devflow/STYLE.md
+     - STYLE.md 版本: v1.0.0
+     - 必须遵循的设计元素:
+       • 颜色: 主色 #XXXXXX, 辅色 #XXXXXX, ...（来自 STYLE.md）
+       • 字体: Font Family, Weight, Size（来自 STYLE.md）
+       • 间距: 4px, 8px, 16px, ...（来自 STYLE.md）
+       • 组件风格: Button, Card, Input 样式（来自 STYLE.md）
+       • 阴影、圆角、动画等（来自 STYLE.md）
+     - STYLE.md 未覆盖的部分处理策略:
+       • 使用 PRD 风格线索 + 默认采样策略
+
+     ## PRD 风格提取
+     - 领域 / 用户画像 / 场景
+     - 关键词列表
+     - 明确要求 / 禁忌
+
+     ## 采样策略（仅在无 STYLE.md 或 STYLE.md 未覆盖部分）
+     - 选定流派 1 （大师列表 + 采样理由）
+     - 选定流派 2 （大师列表 + 采样理由）
+     - 默认样式（无关键词时的 fallback）
+
+     ## 色彩 / 字体 / 布局假设
+     - 主/辅色、对比度、排版方向
+     - （如有 STYLE.md，此部分直接引用 STYLE.md）
+
+     ## 交互与响应式要点
+     - 核心动效、断点策略、可访问性注意事项
+     - （如有 STYLE.md，响应式断点、动画时长等引用 STYLE.md）
+
+     ## 外部灵感 (如有)
+     - 引用链接 + 摘要
+     ```
+   → EXECUTION_LOG.md 记录策略生成、STYLE.md 使用情况、关键词
+```
+
+### 阶段 3: 调用 ui-designer Agent
+```
+Prompt 要求:
+  - 输入:
+      • PRD.md
+      • ui_design_strategy.md
+      • research 集合
+      • devflow/STYLE.md（如存在，必须作为首要参考）
+  - 输出: UI_PROTOTYPE.html
+  - 遵循模板 (.claude/docs/templates/UI_PROTOTYPE_TEMPLATE.md):
+      • 页面列表、组件清单、设计系统 (颜色/字体/间距)
+      • 响应式断点 (320/768/1024)
+      • 交互状态 (hover/active/disabled)
+      • 文档内注释说明各部分映射的 PRD 验收标准
+  - STYLE.md 约束（如存在）:
+      • 所有颜色必须使用 STYLE.md 定义的色板（主色、辅色、语义色、中性色）
+      • 所有字体必须使用 STYLE.md 定义的字体系统（字体族、字阶）
+      • 所有间距必须使用 STYLE.md 定义的间距系统（spacing scale）
+      • 所有组件样式必须遵循 STYLE.md 定义的组件规范（Button, Card, Input 等）
+      • 阴影、圆角、动画、透明度等必须遵循 STYLE.md
+      • 响应式断点必须遵循 STYLE.md（如有定义）
+      • 仅在 STYLE.md 未覆盖的部分，才使用默认采样策略（80+ 设计大师）
+  - Constitution: 禁止外链资源、禁止敏感数据硬编码
+```
+
+### 阶段 4: Exit Gate
+```
+1. 文件存在
+   → UI_PROTOTYPE.html
+   → research/ui_design_strategy.md
+
+2. 结构检查
+   → HTML 内包含设计系统、页面导航、组件说明
+   → 注释中标注 PRD 用户故事和验收点
+
+3. 状态更新
+   → orchestration_status:
+        status = "ui_complete"
+        completedSteps append "ui"
+   → 如跳过，则 status = "ui_skipped" 并记录原因
+
+4. 宪法校验（可选）
+   → {SCRIPT:validate_constitution} --type ui --severity warning
+```
+
+## 输出
+```
+✅ UI_PROTOTYPE.html
+✅ research/ui_design_strategy.md
+✅ EXECUTION_LOG.md 更新（完成或跳过）
+```
+
+## 错误处理
+- 缺少 PRD 或研究资产 → 提示先完成 `/flow-prd`、`/flow-init` Consolidation。
+- Agent 生成失败 → status 设为 `ui_generation_failed`，可修正后重试。
+- 用户确认跳过 → 标记 `ui_skipped`，后续流程仍可继续。
+
+## 下一步
+1. 审阅原型并与产品对齐。
+2. 若涉及前端实现，确保 `/flow-tech` 引用 UI_PROTOTYPE 中的组件与断点。
+3. Planner 在 `/flow-epic` 阶段加载页面/组件清单生成对应任务。

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

@@ -0,0 +1,111 @@
+---
+name: flow-update
+description: 'Update task progress for cc-devflow requirements. Usage: /flow-update "REQ-123" "T012" [OPTIONS]'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  check_tasks: .claude/scripts/check-task-status.sh
+  mark_complete: .claude/scripts/mark-task-complete.sh
+  sync_marks: .claude/scripts/sync-task-marks.sh
+---
+
+# Flow-Update - 任务进度更新命令
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID TASK_ID [--status=STATE] [--progress=PCT] [--estimate=HRS] [--comment='...'] [--auto] [--test]"
+```
+
+## 命令格式
+```text
+/flow-update "REQ_ID" "TASK_ID" [OPTIONS]
+```
+
+### 支持选项
+- `--status=planning|in_progress|blocked|review|completed`
+- `--progress=0-100`
+- `--estimate=<hours>`
+- `--comment="text"`
+- `--auto`：基于 git diff + quickstart 测试估算进度
+- `--test`：运行 quickstart 中相关测试命令
+- `--no-sync`：跳过 TASKS.md 复选框同步
+
+## 执行流程
+
+### 阶段 1: Entry Gate
+```
+1. 参数解析
+   → 解析 REQ_ID、TASK_ID 与选项；校验格式 (REQ-\d+, T### 或 TASK_###)。
+
+2. 环境校验
+   → Run: {SCRIPT:prereq} --json --require-tasks
+   → 确认需求目录、TASKS.md、orchestration_status.json 存在。
+   → 确认当前分支对应 REQ_ID（feature/REQ-*）。
+
+3. 任务校验
+   → Run: {SCRIPT:check_tasks} --json --task "${TASK_ID}"
+   → 阻止更新已完成任务（除非 --status=completed 再次同步）。
+
+4. 快速一致性检查
+   → 若 TASKS.md 中该任务未标记 [ ] → [x]，记录当前状态以便后续同步。
+```
+
+### 阶段 2: 进度采集与验证
+```
+1. --auto 模式
+   → 分析 git diff 涉及的文件。
+   → 检查对应测试文件是否存在。
+   → 估算 progress / status 值（默认阈值：代码 ≥1 文件 → in_progress；测试通过 → review）。
+
+2. --test 模式
+   → 从 quickstart.md 中解析目标测试命令（匹配任务所属阶段）。
+   → 运行并捕获退出码；失败则阻断更新。
+
+3. DoD 对照
+   → 若 --status=completed：
+      • 测试必须通过（或显式跳过 --test 与 --auto）；
+      • `git status --short` 应为空。
+```
+
+### 阶段 3: 状态更新
+```
+1. 更新任务元数据
+   → 在 devflow/requirements/${REQ_ID}/tasks/${TASK_ID}.json 写入最新 status/progress/estimate/comment。
+   → 若任务目录不存在，则创建 tasks/ 并生成 JSON 框架。
+
+2. Mark script
+   → 对已完成任务调用 {SCRIPT:mark_complete} "${TASK_ID}"。
+   → 非完成任务但需要勾选同步时，调用 {SCRIPT:sync_marks}。
+
+3. orchestration_status
+   → 更新 lastTaskUpdate、completedTasks 数、blockers 等字段。
+   → 若所有任务完成且 status ≠ development_in_progress，则设置 status=development_complete。
+
+4. EXECUTION_LOG
+   → 追加进度行，包含任务、状态、备注、测试结果。
+```
+
+### 阶段 4: Exit Gate
+```
+1. 再次调用 {SCRIPT:check_tasks} --json 验证进度已反映在统计中。
+2. 如果 --test，确认测试命令通过且记录在 tasks/${TASK_ID}.json。
+3. 输出摘要（task id、status、progress、下个推荐动作）。
+```
+
+## 错误处理
+- 参数缺失或格式错误 → 立即终止并提示正确示例。
+- git 有未提交变更且 --status=completed → 拒绝更新，提示先提交。
+- 测试失败或 DoD 未满足 → 阻止状态升级为 completed。
+- 同步 TASKS.md 失败 → 提示使用 {SCRIPT:sync_marks} 手动修复。
+
+## 输出
+```
+✅ tasks/${TASK_ID}.json 更新
+✅ TASKS.md 复选框同步（除非 --no-sync）
+✅ orchestration_status.json.lastTaskUpdate 刷新
+✅ EXECUTION_LOG.md 记录本次更新
+```
+
+## 下一步
+- 若所有任务完成：立即运行 `/flow-qa`。
+- 若任务被阻塞：添加 `blocked` 注释并通知相关负责人。
+- 周期性执行 `/flow-status` 获取进度总览。

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

@@ -0,0 +1,115 @@
+---
+name: flow-upgrade
+description: 'PRD version management, analysis, and application workflow. Usage: /flow-upgrade "REQ-123" --analyze or --version="2.0.0" --reason="..."'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  manage_constitution: .claude/scripts/manage-constitution.sh
+  validate_constitution: .claude/scripts/validate-constitution.sh
+  impact_analyzer: .claude/scripts/analyze-upgrade-impact.sh
+---
+
+# Flow-Upgrade - PRD 版本管理工作流
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID [--analyze] [--version=SEMVER] [--reason='...'] [--rollback=SEMVER] [--compatibility --target=SEMVER]"
+```
+
+## 模式
+- `--analyze [--format=json] [--compare=version]`
+- `--version=SEMVER --reason="text" [--force]`
+- `--rollback=SEMVER [--confirm]`
+- `--compatibility [--target=SEMVER] [--baseline=SEMVER]`
+
+## 执行流程
+
+### 阶段 1: Entry Gate
+```
+1. 参数解析
+   → 校验 REQ_ID、版本字符串 (SemVer)、必需理由 (--reason) 等。
+
+2. 前置检查
+   → Run: {SCRIPT:prereq} --json --require-prd
+   → 确认 PRD.md、versions/ 历史目录存在。
+   → Git 工作区需干净（除非只做 analyze）。
+
+3. 状态确认
+   → orchestration_status.status 至少为 "prd_complete"。
+   → 若后续流程在开发阶段进行，提示可能影响当前迭代。
+```
+
+### 阶段 2A: 分析模式 (--analyze)
+```
+1. 调用 {SCRIPT:impact_analyzer} --req "${REQ_ID}" --compare "${VERSION?}" --format "${FORMAT}"
+2. 输出:
+   → change_detection_*.md
+   → impact_assessment_*.md
+   → upgrade_recommendation_*.md （建议版本 bump: major/minor/patch）
+3. 若 --format=json，打印 JSON 摘要供 CLI 解析。
+```
+
+### 阶段 2B: 升级模式 (--version)
+```
+1. 版本验证
+   → SemVer 合法、未占用。
+   → 提供 --reason。
+   → 若存在 breaking changes 且版本 bump 不够大 → 拒绝或要求 --force。
+
+2. 自动分析
+   → 执行分析模式，生成影响报告。
+   → {SCRIPT:validate_constitution} --type prd --severity warning
+
+3. 版本快照
+   → 创建 devflow/requirements/${REQ}/versions/vX.Y.Z/
+   → 拷贝 PRD.md、TECH_DESIGN.md 等相关文档。
+   → 生成 CHANGELOG 位于 versions/。
+
+4. 元数据更新
+   → 更新 PRD.md 头部版本号、修订日期。
+   → orchestration_status.version = "vX.Y.Z"、lastUpgradeReason。
+   → EXECUTION_LOG.md 记录升级摘要。
+
+5. 触发后续动作
+   → 提示重新运行 /flow-tech、/flow-epic 等受影响阶段。
+```
+
+### 阶段 2C: 回滚 (--rollback)
+```
+1. 确认目标版本存在。
+2. 如未指定 --confirm，提示用户确认。
+3. 将版本目录内容恢复至当前 PRD。
+4. 更新版本号、记录回滚原因。
+```
+
+### 阶段 2D: 兼容性检查 (--compatibility)
+```
+1. 比对基线与目标版本的差异。
+2. 输出兼容性矩阵（API、数据模型、非功能需求）。
+3. 标记潜在迁移任务。
+```
+
+### 阶段 3: Exit Gate
+```
+1. 核验版本快照目录、CHANGELOG、影响报告是否生成。
+2. 若版本号更新成功，提示下一步（重新跑 /flow-tech /flow-epic）。
+3. 失败时保持原状态，给出恢复指引。
+```
+
+## 输出
+```
+✅ versions/vX.Y.Z/ (含 PRD/TECH_DESIGN 快照、CHANGELOG)
+✅ impact_assessment_*.md / upgrade_recommendation_*.md
+✅ orchestration_status.json 更新 (version, lastUpgradeAt, reason)
+✅ EXECUTION_LOG.md 记录
+```
+
+## 错误处理
+- 版本号不合法或已存在 → 终止并提示示例。
+- breaking change 但版本 bump 不够 → 要求确认或提升版本级别。
+- Git 不干净 → 拒绝升级，要求先提交/清理。
+- 影响分析脚本失败 → 续写日志并保持现状。
+
+## 下一步
+- 若版本包含重大变更：立即通知团队重新生成技术方案和规划。
+- 使用 `/flow-status` 检查其他需求是否依赖该版本。
+- 需要宪法变更时调用 `/flow-constitution --amend`。

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

@@ -0,0 +1,96 @@
+---
+name: flow-verify
+description: 'Comprehensive consistency verification across documents and implementation. Usage: /flow-verify "REQ-123" or /flow-verify --all'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  validate_constitution: .claude/scripts/validate-constitution.sh
+  generate_status: .claude/scripts/generate-status-report.sh
+---
+
+# Flow-Verify - 一致性验证命令
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID? [--all] [--summary] [--critical-only] [--since=ISO] [--diff=RANGE] [--documents-only|--implementation-only|--tests-only]"
+```
+缺省 REQ_ID 时使用当前分支；`--all` 针对所有需求。
+
+## 验证维度
+- 文档链路：`PRD.md → TECH_DESIGN.md → data-model.md → contracts/ → EPIC.md → TASKS.md`
+- 实现链路：`代码实现 ↔ tests ↔ quickstart.md`
+- 状态链路：`orchestration_status.json`、`EXECUTION_LOG.md`
+
+## 执行流程
+
+### 阶段 1: Entry Gate
+```
+1. 参数解析
+   → 支持单需求、批量 (--all)、增量 (--since/--diff)、维度过滤 (--documents-only 等)
+
+2. 前置检查
+   → {SCRIPT:prereq} --json
+   → 确保存在: PRD.md, TECH_DESIGN.md, data-model.md, contracts/, quickstart.md, EPIC.md, TASKS.md
+   → orchestration_status.status 至少为 "dev_complete"（或用户指定跳过实现验证）
+
+3. 选择验证集合
+   → 单需求: 使用传入 ID
+   → --all: 枚举 devflow/requirements/**
+```
+
+### 阶段 2: 验证准备
+```
+1. 汇总上下文
+   → 读取研究/设计/规划/实现资产，构建追溯矩阵
+2. 配置验证级别
+   → 默认: 全量
+   → --summary: 仅关键阻断项
+   → --critical-only: 只输出严重问题
+3. 更新 EXECUTION_LOG.md 记录验证开始
+```
+
+### 阶段 3: Consistency Checks
+```
+1. 文档一致性
+   → PRD 用户故事 ↔ EPIC scopes ↔ TASKS phases
+   → TECH_DESIGN 决策 ↔ data-model / contracts / quickstart
+
+2. 实现一致性
+   → TASKS 任务 ↔ Git 提交 ↔ 测试文件
+   → quickstart 命令可执行性（dry-run 或脚本验证）
+
+3. 质量守则
+   → {SCRIPT:validate_constitution} --type verify --severity warning
+   → 检查 Simplicity / Anti-Abstraction / Integration-First、No Partial Implementation、No Dead Code 等
+```
+
+### 阶段 4: 报告输出
+```
+1. 生成 report
+   → 路径: devflow/requirements/${REQ_ID}/VERIFY_REPORT.md
+   → 包含: 概览、通过/失败项、严重度、建议、受影响文件
+
+2. 更新状态
+   → orchestration_status:
+        lastVerificationAt = ISO timestamp
+        verificationStatus = "passed" 或 "issues_found"
+   → EXECUTION_LOG 记录完成
+
+3. 可选: {SCRIPT:generate_status} 汇总全部需求验证结果
+```
+
+## 输出
+```
+✅ VERIFY_REPORT.md
+✅ orchestration_status.json（记录验证状态）
+✅ EXECUTION_LOG.md 更新
+```
+
+## 错误处理
+- 缺失关键资产 → 提示前置命令（/flow-prd、/flow-tech、/flow-epic、/flow-dev）。
+- 验证脚本失败 → 输出日志位置，保持 verificationStatus = "failed".
+- Constitution 违规 → 报告标记为 BLOCKER，需在发版前修复。
+
+## 建议后续
+1. 对 issues_found 的需求，回到对应阶段修复。
+2. 在 `/flow-release` 前确保最新验证为 PASS。
+3. 将验证报告纳入 QA 签核材料。

package/.claude/commands/problem-analyzer.md

@@ -0,0 +1,60 @@
+---
+name: problem-analyzer
+description: 'Diagnose incidents or regressions and outline minimal fixes. Usage: /problem-analyzer "<issue description>"'
+scripts:
+  analyze: .claude/scripts/run-problem-analysis.sh
+---
+
+# Problem-Analyzer - 问题诊断命令
+
+## User Input
+```text
+$ARGUMENTS = "<bug report | stack trace | failing test output>"
+```
+请提供问题现象、日志片段、相关模块等信息。若多个症状可使用多行或 Markdown 列表。
+
+## 执行流程
+
+### 阶段 1: 资料收集
+- 解析输入中的组件名称、报错关键字、最近提交 ID。
+- 自动查找与关键词匹配的文件（src/, tests/, migrations/ 等）供快速定位。
+
+### 阶段 2: 调用分析脚本
+```
+Run: {SCRIPT:analyze} --input "<payload>"
+```
+- 脚本聚合：
+  - git 历史：与问题模块相关的最近提交
+  - 日志/栈信息（如提供）
+  - 测试结果（若输入包含 failing tests）
+- 生成诊断草稿 (tmp/problem-analysis-*.json) 供审查。
+
+### 阶段 3: 结构化输出
+- 自动套用标准模板，输出：
+  - Affected files (路径 + 原因)
+  - Root cause （短说明 + 传播路径）
+  - Proposed fix（最小修复、阶段步骤、测试清单）
+  - Documentation gaps（需更新的 README/ADR/config/schema）
+  - Open questions / assumptions
+- 报告写入 `analysis/problem-${timestamp}.md` 并回显路径。
+
+## 诊断准则
+- 优先定位“一因多果”的根因；避免泛泛记录症状。
+- 修复建议需可落地：列出主要代码块/函数及测试更新。
+- 未知假设需明确列出并在 Open questions 中提醒跟进。
+
+## 错误处理
+- 输入不足 → 提示提供最少信息（现象 + 模块或错误消息）。
+- 自动定位失败 → 输出“人工筛查建议”并生成空模板。
+- 报告写入失败 → 保留临时 JSON 供手动导出。
+
+## 输出
+```
+✅ analysis/problem-*.md
+✅ 控制台显示根因摘要与建议修复
+```
+
+## 下一步
+- 将报告附于 bug ticket 或 PR 描述。
+- 根据 Proposed fix 执行修复，并在 `/flow-fix` 中引用该报告。
+- 诊断完成后，更新 README/ADR/运行手册中相关章节。