cc-devflow 1.0.1

package/.claude/commands/core-style.md

@@ -0,0 +1,293 @@
+---
+name: core-style
+description: 'Generate project-level design style guide. Usage: /core-style [--update]'
+scripts:
+  validate_constitution: .claude/scripts/validate-constitution.sh
+---
+
+# Flow-Style - 设计风格指南生成命令
+
+## User Input
+```text
+$ARGUMENTS = "[--update]"
+```
+`--update` 表示更新现有 STYLE.md，缺省表示生成新的风格指南。
+
+## 命令格式
+```text
+/core-style            # 生成新的设计风格指南
+/core-style --update   # 更新现有设计风格指南
+```
+
+## 触发原则
+- **项目初始化时**：在 `/core-roadmap` 之后，或作为独立命令运行
+- **设计风格变更时**：通过 `--update` 参数更新现有风格指南
+- **项目级别**：类似 `/core-roadmap`，为整个项目建立设计标准（SSOT）
+
+## 核心理念
+> "设计系统是视觉语言的语法，代码是语法的实现。无语法，则无一致性。"
+
+STYLE.md 是项目的**设计真理源（SSOT）**，后续所有 UI 相关工作必须遵循：
+- `/flow-ui` 生成的 UI_PROTOTYPE.html 必须严格遵循 STYLE.md
+- `/flow-dev` 前端开发代码必须严格遵循 STYLE.md
+
+## 执行流程
+
+### 阶段 1: Entry Gate & 项目类型检测
+```
+1. 检测现有风格指南
+   → 检查 devflow/STYLE.md 是否存在
+   → 如存在且无 --update 参数 → WARN 并询问是否覆盖
+   → 如存在且有 --update 参数 → 进入更新模式
+
+2. 检测项目类型
+   → 检查项目特征:
+      • package.json, src/components/, styles/, public/ 等前端文件
+      • 判断是新项目（无前端代码）还是现有项目（有前端代码）
+   → 记录项目类型到 EXECUTION_LOG.md
+
+3. 路由选择
+   → 新项目 → 进入阶段 2（参考设计采集）
+   → 现有项目 → 进入阶段 3（代码分析）
+   → 更新模式 → 进入阶段 3（代码分析 + 现有 STYLE.md 合并）
+```
+
+### 阶段 2: 参考设计采集与复刻（仅新项目）
+```
+1. 引导用户提供参考设计
+   → 提示用户:
+     "请提供你想要参考的设计，可以包括：
+      - 网站 URL（我会抓取并分析）
+      - 设计截图（PNG/JPG）
+      - 提取的 HTML + CSS 代码
+
+      我将帮你复刻这个设计到单 HTML 文件中。"
+
+2. 生成参考设计复刻
+   → 使用提示词:
+     "Help me rebuild exact same UI design in single html as reference-001.html.
+      Above is extracted css and design screenshot."
+   → 生成单 HTML 文件
+   → 保存到 devflow/research/style_reference_designs/reference-001.html
+   → 如有截图，保存到 devflow/research/style_reference_designs/reference-001.png
+
+3. 用户微调循环
+   → 提示用户打开 HTML 文件查看效果:
+     "请打开 devflow/research/style_reference_designs/reference-001.html 查看效果。
+
+      你满意吗？如果不满意，请告诉我需要调整的地方：
+      - 颜色（如：主色调太鲜艳，改为更柔和的蓝色）
+      - 字体（如：标题字体太粗，改为 medium weight）
+      - 间距（如：卡片间距太小，增加到 24px）
+      - 组件样式（如：按钮圆角太大，改为 4px）
+      - 其他..."
+   → 根据用户反馈调整 HTML
+   → 生成新版本：reference-002.html, reference-003.html, ...
+   → 重复此循环，直到用户满意
+
+4. 确认最终版本
+   → 用户确认满意后，询问:
+     "请确认这是最终版本吗？(y/n)"
+   → 用户确认后，复制最终版本为 reference-final.html
+   → 进入阶段 3 生成风格分析
+```
+
+### 阶段 3: 风格分析与 STYLE.md 生成
+```
+1. 分析输入源
+   → 新项目:
+      • 读取 devflow/research/style_reference_designs/reference-final.html
+      • 提取颜色、字体、间距、组件样式、动画、阴影等
+   → 现有项目:
+      • 使用 Glob 查找前端文件: **/*.{tsx,jsx,vue,svelte,css,scss,sass}
+      • 使用 Grep 搜索样式定义、Tailwind classes、CSS variables
+      • 分析组件结构、设计模式
+   → 更新模式:
+      • 结合现有 STYLE.md + 最新代码分析
+      • 保留现有定义，补充新发现的模式
+
+2. 生成风格分析文档
+   → 创建 devflow/research/style_analysis.md
+   → 结构:
+     ```
+     # 设计风格分析
+
+     ## 分析来源
+     - 参考设计: reference-final.html (新项目)
+     - 代码分析: src/components/**, styles/** (现有项目)
+     - 分析时间: YYYY-MM-DD 北京时间
+
+     ## 颜色提取
+     - 主色: #XXXXXX (使用频率: XX%)
+     - 辅色: #XXXXXX (使用频率: XX%)
+     - 成功色: #XXXXXX
+     - 警告色: #XXXXXX
+     - 错误色: #XXXXXX
+     - 中性色: #XXXXXX, #XXXXXX, ...
+
+     ## 字体分析
+     - 标题字体: Font Family, Weight, Size
+     - 正文字体: Font Family, Weight, Size
+     - 代码字体: Font Family (如有)
+     - 字体组合规律
+
+     ## 间距系统
+     - 基础单位: 4px / 8px / 16px
+     - 组件间距: 8px, 16px, 24px, 32px
+     - 布局间距: 48px, 64px, 96px
+
+     ## 组件样式模式
+     - 按钮: 圆角、阴影、hover 效果、padding
+     - 卡片: 圆角、阴影、边框、padding
+     - 输入框: 圆角、边框、focus 效果、padding
+     - ...
+
+     ## 其他设计元素
+     - 阴影 & 层级: box-shadow 定义
+     - 动画 & 过渡: transition, animation 定义
+     - 圆角: border-radius 规律
+     - 透明度: opacity 使用场景
+     ```
+   → EXECUTION_LOG.md 记录分析完成
+
+3. 调用 style-guide-generator Agent
+   → Prompt 要求:
+      • 输入: research/style_analysis.md + (reference-final.html 或项目代码)
+      • 输出: devflow/STYLE.md
+      • 遵循模板: .claude/docs/templates/STYLE_TEMPLATE.md
+      • 必须包含:
+        - Overview (设计系统概述)
+        - Color Palette (完整色板 + Hex/RGB/HSL)
+        - Typography (字体系统 + weight/size/line-height 组合)
+        - Spacing System (间距系统 + 使用示例)
+        - Component Styles (所有组件的详细样式定义)
+        - Shadows & Elevation (阴影系统 + 层级说明)
+        - Animations & Transitions (动画 + 过渡效果)
+        - Border Radius (圆角系统)
+        - Opacity & Transparency (透明度使用场景)
+        - Common Tailwind CSS Usage (如适用)
+        - Example Component Reference Design Code (示例组件代码)
+        - Design Principles (设计原则，如有)
+      • Constitution 约束:
+        - 禁止外链资源（字体、图片等必须本地化或使用 CDN）
+        - 禁止硬编码敏感数据
+        - 所有颜色必须提供 Hex 和语义化命名
+        - 所有示例代码必须可直接复用
+
+4. 生成 STYLE.md
+   → Agent 输出 devflow/STYLE.md
+   → 确保文档包含所有必需部分
+   → 确保示例代码完整可执行
+```
+
+### 阶段 4: Exit Gate
+```
+1. 文件完整性检查
+   → 必须存在:
+      • devflow/STYLE.md
+      • devflow/research/style_analysis.md
+   → 新项目还需:
+      • devflow/research/style_reference_designs/reference-final.html
+
+2. 结构检查
+   → STYLE.md 包含所有必需部分（Overview, Color Palette, Typography, ...）
+   → 包含至少 3 个完整的示例组件代码
+   → 所有颜色定义包含 Hex 值和语义化命名
+   → 所有字体定义包含 weight, size, line-height
+
+3. 宪法校验
+   → {SCRIPT:validate_constitution} --type style --severity warning
+   → 检查外链资源、硬编码数据等
+
+4. 状态更新
+   → 创建/更新项目级状态文件（如不存在）:
+      devflow/project_status.json:
+      {
+        "project_name": "Project Name",
+        "style_guide_complete": true,
+        "style_guide_version": "1.0.0",
+        "last_updated": "YYYY-MM-DD HH:mm 北京时间"
+      }
+   → EXECUTION_LOG.md 记录完成事件
+
+5. 后续集成提醒
+   → 输出提示:
+     "✅ STYLE.md 已生成！
+
+      后续工作流将自动引用此设计风格指南：
+      - /flow-ui 将严格遵循 STYLE.md 生成 UI 原型
+      - /flow-dev 前端开发将严格遵循 STYLE.md
+
+      下一步建议：
+      1. 审阅 devflow/STYLE.md 确保完整性
+      2. （可选）运行 /flow-prd 开始需求开发
+      3. （可选）运行 /core-roadmap 生成产品路线图"
+```
+
+## 输出
+```
+✅ devflow/STYLE.md                                         # 项目设计风格指南（SSOT）
+✅ devflow/research/style_analysis.md                      # 风格分析文档
+✅ devflow/research/style_reference_designs/reference-*.html  # 参考设计（新项目）
+✅ devflow/project_status.json                             # 项目级状态（更新）
+✅ EXECUTION_LOG.md                                        # 执行日志（更新）
+```
+
+## 错误处理
+- **STYLE.md 已存在且无 --update 参数** → 询问是否覆盖，用户拒绝则退出
+- **项目无前端特征且用户未提供参考设计** → 提示用户提供参考设计或确认是纯后端项目
+- **参考设计复刻失败** → 要求用户提供更详细的设计信息（HTML/CSS/截图）
+- **Agent 生成失败** → 保留 style_analysis.md，提示用户检查后重试
+- **宪法校验失败** → 根据 severity 决定是否阻塞（warning 级别仅提示）
+
+## 下一步
+1. **审阅 STYLE.md** - 确保设计风格指南完整且符合项目需求
+2. **更新现有组件**（现有项目）- 根据 STYLE.md 调整不一致的组件
+3. **运行 /flow-prd** - 开始需求开发（如适用）
+4. **运行 /core-roadmap** - 生成产品路线图（如适用）
+
+## 与其他工作流的集成
+
+### /flow-ui 集成
+- `/flow-ui` 在阶段 2（设计风格分析）时，优先加载 `devflow/STYLE.md`
+- 所有颜色、字体、间距、组件必须严格遵循 STYLE.md
+- 仅在 STYLE.md 未覆盖的部分，才使用默认采样策略（80+ 设计大师）
+
+### /flow-dev 集成
+- `/flow-dev` 在阶段 2（Quickstart 初始化）时，加载 `devflow/STYLE.md`
+- 所有前端代码生成必须遵循 STYLE.md 定义的风格
+- 特别注意：颜色、字体、间距、组件结构
+
+### /flow-verify 集成
+- `/flow-verify` 可检查代码是否符合 STYLE.md 定义的风格
+- 检查项：颜色使用、字体使用、间距使用、组件结构一致性
+
+## 设计哲学
+- **SSOT 原则**: STYLE.md 是项目设计的唯一真理源
+- **一致性优先**: 所有 UI 相关工作必须遵循 STYLE.md，避免风格碎片化
+- **可复用性**: 示例代码必须可直接复用，不是伪代码
+- **演进性**: 通过 `--update` 参数支持风格指南的迭代更新
+- **用户中心**: 新项目通过参考设计采集 + 微调循环，确保用户满意度
+
+## 补充说明
+
+### 为什么需要项目级设计风格指南？
+1. **避免风格碎片化**: 每个需求的 UI 可能由不同人开发，STYLE.md 确保一致性
+2. **提高开发效率**: 开发者直接引用 STYLE.md 的定义，无需重复决策
+3. **降低维护成本**: 统一的设计系统减少重复代码和样式冲突
+4. **提升用户体验**: 一致的视觉语言提升产品专业度和可用性
+
+### 参考设计微调循环的价值
+- **用户满意度**: 允许用户在实际 HTML 中看到效果并迭代调整
+- **设计精准度**: 通过多次微调，确保最终风格指南真正符合用户期望
+- **避免返工**: 早期确定设计风格，避免后期大规模重构
+
+### 现有项目 vs 新项目
+- **新项目**: 通过参考设计建立设计系统（主动定义）
+- **现有项目**: 通过代码分析提取设计系统（被动提取）
+- **更新模式**: 结合现有定义 + 最新代码，持续演进
+
+### STYLE.md 的演进策略
+- **版本控制**: 每次更新增加版本号（记录在 project_status.json）
+- **向后兼容**: 更新时保留现有定义，仅补充新模式
+- **变更追踪**: 在 EXECUTION_LOG.md 记录每次更新的原因和变更内容

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

@@ -0,0 +1,245 @@
+---
+name: flow-archive
+description: 'Archive completed/deprecated requirements. Usage: /flow-archive "REQ-123" or /flow-archive --list'
+scripts:
+  archive: .claude/scripts/archive-requirement.sh
+---
+
+# Flow-Archive - 需求归档命令
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID?" | "--list" | "--restore REQ_ID"
+```
+未提供 REQ_ID 时，根据当前分支或 `DEVFLOW_REQ_ID` 自动解析。
+
+## 命令格式
+```text
+/flow-archive "REQ-123"                      # 归档已完成需求
+/flow-archive "REQ-123" --reason deprecated  # 标记为废弃归档
+/flow-archive --list                         # 列出所有归档
+/flow-archive "REQ-123" --restore            # 恢复归档需求
+```
+
+### 参数说明
+- **REQ_ID**: 需求编号，格式 REQ-XXX 或 BUG-XXX
+- **--reason**: 归档原因
+  - `completed` (默认) - 需求已完成并发布
+  - `deprecated` - 需求已废弃，不再需要
+  - `obsolete` - 需求已过时，被新需求取代
+  - `superseded` - 被其他需求合并或替代
+- **--list**: 列出所有归档的需求
+- **--restore**: 将归档的需求恢复到活跃目录
+
+## 执行流程
+
+### 阶段 1: Entry Gate (参数验证)
+```
+1. 解析命令参数
+   → 检测模式: archive | list | restore
+
+2. 验证 REQ_ID 格式
+   → 必须匹配: ^(REQ|BUG)-[0-9]+(-[0-9]+)?$
+
+3. 检查需求状态
+   → 归档模式: 需求必须存在于 devflow/requirements/ 或 devflow/bugs/
+   → 恢复模式: 需求必须存在于 devflow/archive/{YYYY-MM}/
+
+4. 验证归档原因
+   → 必须是: completed, deprecated, obsolete, superseded 之一
+
+*GATE CHECK: 参数验证通过*
+```
+
+### 阶段 2: 归档执行
+```
+1. 确定归档目标目录
+   → 格式: devflow/archive/{YYYY-MM}/{REQ_ID}/
+   → 年月使用北京时间
+
+2. 备份当前状态
+   → 读取 orchestration_status.json 的 status 字段
+   → 保存为 statusBeforeArchive
+
+3. 移动目录
+   → mv devflow/requirements/{REQ_ID}/ → devflow/archive/{YYYY-MM}/{REQ_ID}/
+   → 或 mv devflow/bugs/{BUG_ID}/ → devflow/archive/{YYYY-MM}/{BUG_ID}/
+
+4. 更新状态文件
+   → orchestration_status.json:
+     {
+       "status": "archived",
+       "archivedReason": "{reason}",
+       "archivedAt": "{ISO8601+08:00}",
+       "archiveLocation": "{target_path}",
+       "statusBeforeArchive": "{previous_status}"
+     }
+
+5. 追加 EXECUTION_LOG.md
+   → 记录归档时间、原因、位置
+```
+
+### 阶段 3: 列表模式 (--list)
+```
+1. 扫描 devflow/archive/ 目录
+   → 按月份组织: devflow/archive/{YYYY-MM}/
+
+2. 收集归档信息
+   → 读取每个归档需求的 orchestration_status.json
+   → 提取: reqId, title, archivedReason, archivedAt
+
+3. 格式化输出
+   → 表格形式展示: 月份 | 需求ID | 归档原因 | 标题
+```
+
+### 阶段 4: 恢复模式 (--restore)
+```
+1. 定位归档需求
+   → 在 devflow/archive/*/ 中搜索 {REQ_ID}
+
+2. 验证目标位置
+   → 确认 devflow/requirements/{REQ_ID}/ 不存在
+   → 避免覆盖现有需求
+
+3. 移动回活跃目录
+   → mv devflow/archive/{YYYY-MM}/{REQ_ID}/ → devflow/requirements/{REQ_ID}/
+
+4. 恢复状态
+   → 读取 statusBeforeArchive，恢复为 status
+   → 删除归档相关字段 (archivedAt, archivedReason, archiveLocation)
+
+5. 记录恢复事件
+   → EXECUTION_LOG.md 追加恢复记录
+```
+
+## 输出产物
+
+### 归档后目录结构
+```text
+devflow/
+├── requirements/          # 活跃需求
+│   └── REQ-004/          # 进行中的需求
+├── archive/               # 归档区
+│   ├── 2025-12/          # 按月份组织
+│   │   ├── REQ-003/      # 已归档需求
+│   │   │   ├── README.md
+│   │   │   ├── PRD.md
+│   │   │   ├── EPIC.md
+│   │   │   ├── EXECUTION_LOG.md
+│   │   │   ├── orchestration_status.json  # status: "archived"
+│   │   │   └── research/
+│   │   └── REQ-001/
+│   └── 2025-11/
+│       └── REQ-002/
+└── bugs/                  # 活跃Bug
+```
+
+### 归档后状态文件
+```json
+{
+  "reqId": "REQ-003",
+  "title": "分支命名优化",
+  "status": "archived",
+  "archivedReason": "completed",
+  "archivedAt": "2025-12-16T16:30:00+08:00",
+  "archiveLocation": "devflow/archive/2025-12/REQ-003",
+  "statusBeforeArchive": "release_complete",
+  "completedSteps": ["init", "prd", "epic", "dev", "qa", "release"],
+  "prUrl": "https://github.com/xxx/xxx/pull/6"
+}
+```
+
+## 成功输出
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ 需求 REQ-003 已归档
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   原位置: devflow/requirements/REQ-003
+   新位置: devflow/archive/2025-12/REQ-003
+   归档原因: completed
+   归档前状态: release_complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 列表输出
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📦 归档需求列表
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+月份       | 需求ID       | 归档原因     | 标题
+───────────────────────────────────────────────────────────────
+2025-12    | REQ-003      | completed    | 分支命名优化
+2025-12    | REQ-001      | deprecated   | 旧版登录功能
+2025-11    | REQ-002      | superseded   | 用户管理V1
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 错误处理
+
+### 常见错误
+
+**1. 需求不存在**
+```
+ERROR: 需求目录不存在: devflow/requirements/REQ-999
+```
+
+**2. 需求已归档**
+```
+ERROR: REQ-003 已经在归档中: devflow/archive/2025-12/REQ-003
+如需重新归档，请先使用 --restore 恢复
+```
+
+**3. 恢复时目标已存在**
+```
+ERROR: 目标目录已存在: devflow/requirements/REQ-003
+请先删除或重命名现有目录
+```
+
+**4. 无效的归档原因**
+```
+ERROR: 无效的归档原因: cancelled
+有效选项: completed deprecated obsolete superseded
+```
+
+## 最佳实践
+
+### 何时归档
+- ✅ 需求已完成并成功发布 (`/flow-release` 后)
+- ✅ 需求被明确取消或废弃
+- ✅ 需求被新需求完全取代
+
+### 何时恢复
+- 🔄 需要参考历史实现
+- 🔄 需要基于旧需求进行迭代
+- 🔄 错误归档需要撤销
+
+### 不要归档
+- ❌ 仍在进行中的需求
+- ❌ 暂停但计划继续的需求
+- ❌ 需要长期维护的需求
+
+## 与其他命令的关系
+
+```text
+/flow-init → /flow-prd → /flow-epic → /flow-dev → /flow-qa → /flow-release
+                                                                    ↓
+                                                            /flow-archive ← 工作流终点
+                                                                    ↓
+                                                            devflow/archive/{YYYY-MM}/
+```
+
+## 脚本集成
+
+```bash
+# 归档需求
+.claude/scripts/archive-requirement.sh "REQ-003" --reason completed
+
+# 列出归档 (JSON格式)
+.claude/scripts/archive-requirement.sh --list --json
+
+# 恢复需求
+.claude/scripts/archive-requirement.sh "REQ-003" --restore
+
+# 预览操作
+.claude/scripts/archive-requirement.sh "REQ-003" --dry-run
+```