cc-devflow 4.1.5 → 4.2.0

package/.claude/commands/core/architecture.md

@@ -29,6 +29,36 @@ architecture-designer (research, no dialogue)
 ARCHITECTURE.md (4 diagrams)
 ```
 
+## Harness Engineering 增强（Long-running Session Protocol）
+
+为防止跨上下文窗口后出现“图表半生成、ADR 丢失、误判已完成”，执行分为 Initializer 与 Worker 两类会话。
+
+### Phase 0: Initializer Session（首次或 --force）
+
+先建立/刷新架构任务工件（不要一次性生成整份文档）：
+- `devflow/.core-harness/architecture/checklist.json`
+  - 列出 4 张图、ADR、NFR、演进路径等验收项，默认 `passes=false`
+- `devflow/.core-harness/architecture/progress.md`
+  - 记录本次修改、风险、下一步
+- `devflow/.core-harness/architecture/init.md`
+  - 固定启动流程（读取 ROADMAP、读取最近进展、执行 Mermaid 冒烟验证）
+
+### Worker Session（增量交付）
+
+每个窗口只处理一个子目标，例如：
+- 只完成一张 Mermaid 图并自检语法
+- 只补齐 ADR 与对应图表映射
+- 只修复依赖图节点/边一致性问题
+
+会话收尾要求：
+1. 运行当前文档校验（占位符、图表数量、语法）
+2. 更新 checklist 的 `passes` 字段
+3. 写入 progress/handoff，明确下一窗口优先任务
+
+### Done Gate
+
+`checklist.json` 全绿 + Phase 4 校验通过，才可输出成功报告。
+
 ## 执行流程
 
 ### Phase 1: Prerequisites Check
@@ -328,9 +358,9 @@ Else:
 无需单独运行 /core-architecture
 ```
 
-### 在 /flow-init 中的使用
+### 在 /flow:init 中的使用
 ```
-/flow-init 可以读取 ARCHITECTURE.md 获取上下文:
+/flow:init 可以读取 ARCHITECTURE.md 获取上下文:
   - 查看需求在架构中的位置
   - 了解相关模块和依赖
   - 参考 ADR 做技术决策

package/.claude/commands/core/guidelines.md

@@ -35,6 +35,31 @@ description: 'Generate project-specific development guidelines skills (frontend/
 /core-guidelines --dry-run
 ```
 
+## Harness Engineering 增强（Eval-Driven + Incremental）
+
+`/core-guidelines` 容易出现两类失败：一次生成过大导致中断、未验证触发规则就标记完成。为此引入双阶段协议。
+
+### Step 0: Initializer Session
+
+创建会话工件：
+- `devflow/.core-harness/guidelines/skill-checklist.json`
+  - Frontend/Backend 分别列出验收项：触发规则、关键资源文件、示例质量、约束合规，默认 `passes=false`
+- `devflow/.core-harness/guidelines/progress.md`
+- `devflow/.core-harness/guidelines/session-handoff.md`
+
+### Worker Session
+
+- 一次只处理一个 skill（frontend 或 backend），禁止同窗口双线并发重写
+- 每次只完成一个最小闭环：`生成/更新 → 触发验证 → 示例验证 → 勾选 passes`
+- 结束前必须写 handoff，明确下一窗口要做的单一目标
+
+### Eval Gate（禁止“看起来差不多”）
+
+只有当以下检查全部通过才标记对应 skill 完成：
+1. `skill-rules.json` 触发范围正确，且前后端互不污染
+2. SKILL + resources 无占位符/虚构路径
+3. 至少 1 个真实文件路径触发测试通过（frontend 与 backend 各自独立）
+
 ---
 
 ## Process
@@ -466,8 +491,8 @@ Choice: [user input]
 
 ## Related Commands
 
-- `/flow-init` - Initialize new requirement (can call /core-guidelines)
-- `/flow-tech` - Technical design (analyzes tech stack similarly)
+- `/flow:init` - Initialize new requirement (can call /core-guidelines)
+- `/flow:spec` - Unified specification and technical planning
 
 ---
 

package/.claude/commands/core/roadmap.md

@@ -102,6 +102,35 @@ guides:
 - **roadmap-planner (Agent)**: 根据上下文生成文档，无对话
 - **architecture-designer (Agent)**: 生成架构图，无对话
 
+## Harness Engineering 增强（OpenAI + Anthropic 实践融合）
+
+为避免长会话中的“半成品漂移 / 提前宣布完成 / 上下文断片”，`/core-roadmap` 强制采用双阶段执行。
+
+### Stage -1: Initializer Session（只做地基，不做全量生成）
+
+在首次运行或 `--regenerate` 时先建立可恢复工件：
+- `devflow/.core-harness/roadmap/feature-checklist.json`
+  - 结构化列出路线图必须产物（愿景、里程碑、依赖图、容量评估、季度分配等），默认 `passes=false`
+- `devflow/.core-harness/roadmap/progress.md`
+  - 记录每次会话完成内容、未决问题、下一步
+- `devflow/.core-harness/roadmap/session-handoff.md`
+  - 给下一窗口的启动指令（从哪个 Stage 继续、先做什么验证）
+
+### Worker Session（增量推进，每次只完成一个最小目标）
+
+每个窗口必须遵守：
+1. 启动先读状态：`pwd` → `progress.md` → `feature-checklist.json` → 最近 git log（若仓库可用）
+2. 先做冒烟检查：确认现有 `ROADMAP.md/BACKLOG.md/ARCHITECTURE.md` 不是损坏状态
+3. 只推进一个最小单元：
+   - 一个 Stage 的信息收集，或
+   - 一个 RM 依赖簇的整理，或
+   - 一次时间线冲突修复
+4. 结束前必须更新工件：勾选 `passes`、写入 progress/handoff、明确下一步
+
+### 完成判定（禁止“口头完成”）
+
+只有 `feature-checklist.json` 全部 `passes=true`，且 Stage 8 输出文件全部存在并通过校验，才允许宣告完成。
+
 ---
 
 ## 执行流程骨架
@@ -268,9 +297,9 @@ guides:
 
 下一步建议:
   1. 审查路线图
-  2. 开始首个需求: /flow-init "REQ-XXX|{RM-title}"
+  2. 开始首个需求: /flow:init "REQ-XXX|{RM-title}"
   3. 定期更新: /core-roadmap --regenerate
-  4. 监控进度: /flow-status --all
+  4. 监控进度: /flow:status --all
 
 → 详见 {TEMPLATE:dialogue} Stage 8
 ```
@@ -425,10 +454,10 @@ grep "Status: Completed" devflow/ROADMAP.md | wc -l
 
 ```
 # 选择当前季度的第一个 RM-ID
-/flow-init "REQ-XXX|{RM-title}"
+/flow:init "REQ-XXX|{RM-title}"
 
 # 或查看所有状态
-/flow-status --all
+/flow:status --all
 ```
 
 ---

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

@@ -5,289 +5,79 @@ scripts:
   validate_constitution: .claude/scripts/validate-constitution.sh
 ---
 
-# Flow-Style - 设计风格指南生成命令
+# /core-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 合并）
-```
+## 目标
+生成或更新 `devflow/STYLE.md`，作为项目设计 SSOT，供 `/flow:spec`、`/flow:dev`、`/flow:verify` 全链路复用。
 
-### 阶段 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 生成风格分析
+## 命令
+```text
+/core-style            # 新建风格指南
+/core-style --update   # 更新已有风格指南
 ```
 
-### 阶段 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 + 最新代码分析
-      • 保留现有定义，补充新发现的模式
+## Harness Engineering 增强（多窗口稳定执行）
 
-2. 生成风格分析文档
-   → 创建 devflow/research/style_analysis.md
-   → 结构:
-     ```
-     # 设计风格分析
+为避免风格文档在多轮会话中变成“补丁堆”，执行采用 initializer + incremental worker。
 
-     ## 分析来源
-     - 参考设计: reference-final.html (新项目)
-     - 代码分析: src/components/**, styles/** (现有项目)
-     - 分析时间: YYYY-MM-DD 北京时间
+### 0. Initializer Session
+- 建立 `devflow/.core-harness/style/` 工件：
+  - `checklist.json`: token 体系、组件约束、可访问性、响应式、动效、禁用项等验收项（默认 `passes=false`）
+  - `progress.md`: 本轮修改与未决项
+  - `session-handoff.md`: 下一轮优先任务与验证命令
 
-     ## 颜色提取
-     - 主色: #XXXXXX (使用频率: XX%)
-     - 辅色: #XXXXXX (使用频率: XX%)
-     - 成功色: #XXXXXX
-     - 警告色: #XXXXXX
-     - 错误色: #XXXXXX
-     - 中性色: #XXXXXX, #XXXXXX, ...
+### 1. Worker Session
+- 每轮只处理一个最小块（例如颜色 token、排版 token、某一类组件约束）
+- 修改后立即做局部验证，不通过则回滚该块后重试
+- 收尾必须同步 checklist/progress/handoff，保持可恢复
 
-     ## 字体分析
-     - 标题字体: Font Family, Weight, Size
-     - 正文字体: Font Family, Weight, Size
-     - 代码字体: Font Family (如有)
-     - 字体组合规律
+### 2. Done Gate
+- 只有 checklist 全部 `passes=true` 且第 4 步校验通过，才允许输出“STYLE 生成完成”
 
-     ## 间距系统
-     - 基础单位: 4px / 8px / 16px
-     - 组件间距: 8px, 16px, 24px, 32px
-     - 布局间距: 48px, 64px, 96px
+## 执行步骤
 
-     ## 组件样式模式
-     - 按钮: 圆角、阴影、hover 效果、padding
-     - 卡片: 圆角、阴影、边框、padding
-     - 输入框: 圆角、边框、focus 效果、padding
-     - ...
+### 1. 入口检查
+- 检查 `devflow/STYLE.md` 是否存在。
+- 无 `--update` 且文件已存在时，要求用户确认是否覆盖。
+- 记录执行开始到 `EXECUTION_LOG.md`。
 
-     ## 其他设计元素
-     - 阴影 & 层级: box-shadow 定义
-     - 动画 & 过渡: transition, animation 定义
-     - 圆角: border-radius 规律
-     - 透明度: opacity 使用场景
-     ```
-   → EXECUTION_LOG.md 记录分析完成
+### 2. 采集输入
+- 新项目：引导用户提供参考 URL / 截图 / HTML+CSS。
+- 现有项目：扫描前端代码提取颜色、排版、间距、组件模式。
+- 输出分析材料到 `devflow/research/style_analysis.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 和语义化命名
-        - 所有示例代码必须可直接复用
+### 3. 生成 STYLE
+- 使用 `.claude/docs/templates/STYLE_TEMPLATE.md` 生成 `devflow/STYLE.md`。
+- 必须包含语义化 token 与组件级约束。
+- 避免页面级“临时补丁式”描述。
 
-4. 生成 STYLE.md
-   → Agent 输出 devflow/STYLE.md
-   → 确保文档包含所有必需部分
-   → 确保示例代码完整可执行
-```
+### 4. 校验与落盘
+- 校验文件存在：
+  - `devflow/STYLE.md`
+  - `devflow/research/style_analysis.md`
+- 运行宪法检查：
+  - `{SCRIPT:validate_constitution} --type style --severity warning`
+- 更新 `devflow/project_status.json` 与 `EXECUTION_LOG.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 生成产品路线图"
-```
+## 与主链集成
+- `/flow:spec`：将 STYLE 约束写入需求验收标准。
+- `/flow:dev`：实现阶段必须遵循 STYLE token/组件规范。
+- `/flow:verify`：质量闸检查样式一致性并产出 gate 结果。
 
 ## 输出
+```text
+✅ devflow/STYLE.md
+✅ devflow/research/style_analysis.md
+✅ devflow/project_status.json (updated)
+✅ EXECUTION_LOG.md (updated)
 ```
-✅ 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 记录每次更新的原因和变更内容
+## 异常处理
+- STYLE 已存在且用户拒绝覆盖：直接退出，不改动。
+- 输入不足：提示补充参考设计，不进入生成阶段。
+- 生成失败：保留 `style_analysis.md`，提示修正后重试。

package/.claude/commands/flow/CLAUDE.md

@@ -0,0 +1,28 @@
+# flow/
+> L2 | 父级: /Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/.claude/CLAUDE.md
+
+成员清单
+archive.md: 归档需求命令。
+checklist.md: 已废弃命令，统一迁移到 /flow:verify。
+clarify.md: 已废弃命令，默认主链移除独立澄清阶段。
+constitution.md: 宪法规则管理命令。
+context.md: 上下文资产管理命令。
+delta.md: 需求增量变更命令。
+dev.md: 主链开发阶段命令，触发 harness dispatch/resume。
+fix.md: Bug 修复命令。
+ideate.md: 想法到需求命令。
+init.md: 主链初始化命令，触发 harness init/pack。
+new.md: 已废弃命令，迁移到 /flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release。
+quality.md: 已废弃命令，统一迁移到 /flow:verify。
+release.md: 主链发布命令，触发 harness release/janitor。
+restart.md: 旧中断恢复命令（迁移过渡保留）。
+spec.md: 主链规格命令，触发 harness plan。
+status.md: 状态查询命令。
+update.md: 任务状态更新命令。
+upgrade.md: 升级分析命令。
+verify.md: 主链验证命令，触发 harness verify。
+workspace.md: 工作区记录命令。
+
+法则: 成员完整·一行一文件·父级链接·技术词前置
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

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

@@ -207,7 +207,7 @@ ERROR: 无效的归档原因: cancelled
 ## 最佳实践
 
 ### 何时归档
-- ✅ 需求已完成并成功发布 (`/flow-release` 后)
+- ✅ 需求已完成并成功发布 (`/flow:release` 后)
 - ✅ 需求被明确取消或废弃
 - ✅ 需求被新需求完全取代
 
@@ -224,7 +224,7 @@ ERROR: 无效的归档原因: cancelled
 ## 与其他命令的关系
 
 ```text
-/flow:init → /flow:spec → /flow:dev → /flow:quality → /flow:release
+/flow:init → /flow:spec → /flow:dev → /flow:verify → /flow:release
                                                             ↓
                                                     /flow:archive ← 工作流终点
                                                             ↓