cc-devflow 1.0.1

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

@@ -0,0 +1,260 @@
+---
+name: flow-checklist
+description: 'Generate requirement quality checklist. Usage: /flow-checklist [OPTIONS]'
+---
+
+# /flow-checklist - 需求质量检查命令
+
+## Usage
+```
+/flow-checklist [OPTIONS]
+```
+
+## Purpose
+生成和管理需求质量检查清单 - "Unit Tests for English"。
+对需求文档进行质量测试，确保需求完整性、清晰性、一致性、可测量性和场景覆盖。
+
+## Options
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--type` | string | `general` | Checklist 类型，支持逗号分隔多类型 |
+| `--status` | flag | - | 显示完成度统计 |
+| `--mark` | string | - | 批量标记检查项为完成 (CHK001,CHK002) |
+| `--mark-all` | flag | - | 标记所有检查项为完成 |
+| `--file` | string | - | 指定操作的 Checklist 文件 |
+| `--help` | flag | - | 显示帮助信息 |
+
+## Valid Types
+- `ux`: UX/UI 需求检查
+- `api`: API 需求检查
+- `security`: 安全需求检查
+- `performance`: 性能需求检查
+- `data`: 数据需求检查
+- `general`: 通用需求检查 (默认)
+
+## Entry Gate
+1. 验证 `PRD.md` 存在
+2. 验证 `orchestration_status.json.prd_complete == true`
+3. 创建 `checklists/` 目录 (如不存在)
+
+## Execution Flow
+
+### Generate Checklist (--type)
+
+```
+1. Parse --type parameter
+   → Split by comma if multiple types
+   → Validate each type against valid_types
+
+2. For each type:
+   a. Read PRD.md content
+   b. Invoke checklist-agent.md with:
+      - prd_content: PRD.md 内容
+      - type: Checklist 类型
+      - config: quality-rules.yml 配置
+   c. Agent generates checklist items (15-30 items)
+   d. Write to checklists/{type}.md
+   e. If file exists: Append mode (继续编号)
+
+3. Output summary:
+   → Items generated per type
+   → Dimension coverage (5/5)
+   → Traceability percentage
+
+4. Update orchestration_status.json:
+   → checklist.generated_types[]
+   → checklist.total_items
+   → checklist.generated_at
+```
+
+### Check Status (--status)
+
+```
+1. Run calculate-checklist-completion.sh --json
+   → Scan checklists/*.md
+   → Count [x] and [ ] items
+
+2. Display completion table:
+   | Checklist | Complete | Total | Percentage |
+   |-----------|----------|-------|------------|
+   | ux.md     | 16       | 20    | 80%        |
+   | OVERALL   | 46       | 57    | 81%        |
+
+3. Compare to threshold (from quality-rules.yml)
+   → PASS: completion >= threshold
+   → FAIL: completion < threshold
+
+4. Update orchestration_status.json:
+   → checklist.checked_items
+   → checklist.completion_percentage
+   → checklist.last_check_at
+```
+
+### Mark Items (--mark)
+
+```
+1. Parse --mark parameter
+   → Split by comma
+   → Validate each ID format (CHK + 3 digits)
+
+2. For each ID:
+   a. Search checklists/*.md for CHK{NNN}
+   b. If found: Replace "- [ ]" with "- [x]"
+   c. If not found: Output warning
+
+3. Output:
+   → "Updated completion: N items marked"
+   → "Run /flow-checklist --status to see updated completion"
+```
+
+### Mark All (--mark-all --file)
+
+```
+1. Validate --file parameter exists
+2. Read specified file
+3. Replace all "- [ ]" with "- [x]"
+4. Output item count
+```
+
+## Exit Gate
+1. 如果生成了新 Checklist:
+   - 更新 `orchestration_status.json.checklist`
+   - 追加事件到 `EXECUTION_LOG.md`
+2. 输出下一步提示
+
+## Output Examples
+
+### Generate Single Type
+```
+Generating UX Checklist...
+Reading PRD.md...
+Analyzing UX requirements...
+Applying Anti-Example rules...
+
+✅ Generated: checklists/ux.md
+   Items: 18
+   Dimensions: 5/5 (Completeness, Clarity, Consistency, Measurability, Coverage)
+   Traceability: 85% (>=80% required)
+
+Next: Review and check items, then run /flow-checklist --status
+```
+
+### Generate Multiple Types
+```
+Generating multiple Checklists...
+
+[1/3] UX Checklist...
+✅ Generated: checklists/ux.md (18 items)
+
+[2/3] API Checklist...
+✅ Generated: checklists/api.md (22 items)
+
+[3/3] Security Checklist...
+✅ Generated: checklists/security.md (15 items)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Summary:
+| Type     | Items Generated | Coverage |
+|----------|-----------------|----------|
+| ux       | 18              | 5/5      |
+| api      | 22              | 5/5      |
+| security | 15              | 4/5      |
+| TOTAL    | 55              | -        |
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next: Review and check items, then run /flow-checklist --status
+```
+
+### Check Status
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Checklist Completion Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+| Checklist | Complete | Total | Percentage |
+|-----------|----------|-------|------------|
+| ux.md     | 16       | 20    | 80%        |
+| api.md    | 18       | 22    | 82%        |
+| security  | 12       | 15    | 80%        |
+|-----------|----------|-------|------------|
+| OVERALL   | 46       | 57    | 81%        |
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Gate Threshold: 80%
+Status: ✅ PASS (81% >= 80%)
+
+Ready for: /flow-epic
+```
+
+## Error Handling
+
+### MISSING_PRD
+```
+ERROR: MISSING_PRD
+PRD.md not found in requirement directory.
+
+Run /flow-prd first.
+```
+
+### INVALID_TYPE
+```
+ERROR: INVALID_TYPE
+Invalid checklist type: {type}
+
+Valid types: ux, api, security, performance, data, general
+```
+
+### NO_CHECKLISTS
+```
+ERROR: NO_CHECKLISTS
+No checklists found in checklists/ directory.
+
+Run /flow-checklist --type <type> first.
+```
+
+## Append Mode (T011)
+
+When running `--type {type}` and `checklists/{type}.md` already exists:
+
+1. Read existing file
+2. Find highest CHK number (e.g., CHK018)
+3. Generate new items starting from next number (CHK019)
+4. Append new items to existing file
+5. Preserve existing structure and checked items
+
+## EXECUTION_LOG Events (T012)
+
+### Checklist Generated
+```markdown
+### 2025-12-15 23:55:00 (周日)
+**Event**: Checklist Generated
+**Type**: ux
+**Items**: 18
+**Dimensions**: 5/5
+**Traceability**: 85%
+```
+
+### Status Checked
+```markdown
+### 2025-12-15 23:58:00 (周日)
+**Event**: Checklist Status Checked
+**Completion**: 81%
+**Threshold**: 80%
+**Status**: PASS
+```
+
+## Related Commands
+
+| Command | Relationship |
+|---------|--------------|
+| `/flow-prd` | Prerequisite (generates PRD.md) |
+| `/flow-epic` | Consumer (uses checklist gate) |
+| `/flow-status` | Reader (displays checklist status) |
+
+## Configuration
+
+Config file: `config/quality-rules.yml`
+
+Key settings:
+- `gate.threshold`: Minimum completion % (default: 80)
+- `types.{type}.min_items`: Minimum items per type (default: 15)
+- `types.{type}.max_items`: Maximum items per type (default: 30)

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

@@ -0,0 +1,136 @@
+---
+name: flow-clarify
+description: 'Requirement clarification with 11-dimension ambiguity scan. Usage: /flow-clarify [REQ-XXX] [--skip] [--history]'
+---
+
+# /flow-clarify - 需求澄清命令
+
+## Usage
+```
+/flow-clarify [REQ-XXX] [--skip] [--history]
+```
+
+## Purpose
+在 PRD 生成前通过 11 维度歧义扫描系统化消除需求模糊性。
+
+## Arguments
+- `REQ-XXX`: 需求编号（可选，默认从分支推断）
+- `--skip`: 跳过澄清，直接进入下一阶段
+- `--history`: 查看历史澄清记录
+
+## Entry Gate
+1. 验证 `research/research.md` 存在
+2. 验证 `orchestration_status.json.phase0_complete == true`
+3. 检查 `.session.json` 是否有未完成会话（断点恢复）
+
+## Execution Flow
+
+### Phase 1: Scan (自动执行)
+```bash
+# 调用 run-clarify-scan.sh 执行 11 维度并行扫描
+.claude/scripts/run-clarify-scan.sh REQ-XXX --parallel
+```
+
+输出: scan_result.json (内存)
+
+### Phase 2: Question Generation (自动执行)
+```bash
+# 基于扫描结果生成 ≤5 个优先级排序问题
+.claude/scripts/generate-clarification-questions.sh --input scan_result.json --max 5
+```
+
+输出: questions[] with AI recommendations
+
+### Phase 3: Interactive Q&A (用户交互)
+For each question:
+1. Display question + options + AI recommendation (⭐ RECOMMENDED)
+2. Read user input
+3. Validate answer (A-E or ≤5 words)
+4. Generate rationale (Claude Haiku)
+5. Save to .session.json (incremental)
+
+### Phase 4: Report Generation (自动执行)
+```bash
+# 生成澄清报告
+.claude/scripts/generate-clarification-report.sh --session .session.json
+```
+
+输出: research/clarifications/[timestamp]-flow-clarify.md
+
+## Exit Gate
+1. 验证报告完整性
+2. 更新 `orchestration_status.json`:
+   - `clarify_complete = true`
+   - `clarify_session_id = [sessionId]`
+3. 删除 `.session.json`
+4. 输出: "✅ Ready for /flow-prd"
+
+## Session Recovery
+如果检测到 `.session.json`:
+1. 显示恢复提示
+2. 从 `currentQuestionIndex` 继续
+3. 不重复已回答的问题
+
+## User Abort (Ctrl+C)
+1. 捕获 SIGINT
+2. 保存当前进度到 `.session.json`
+3. 输出恢复命令: `/flow-clarify REQ-XXX`
+
+## Output Format
+
+### Question Display
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📝 Q1: 关于 Functional Scope
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+用户权限应如何划分？
+
+  A) RBAC 角色模型 - 基于角色的访问控制
+  B) ABAC 属性模型 - 基于属性的访问控制
+  C) 简单二元权限 - admin/user 两级
+
+  ⭐ RECOMMENDED: A (RBAC 是企业级应用最常见模式)
+
+Your choice (A-C, or press Enter for recommended):
+```
+
+### Report Structure
+```markdown
+# Clarification Report: REQ-XXX
+
+## Metadata
+- Session ID: 20251215-143000-REQ-001
+- Date: 2025-12-15
+- Questions: 3 / 5
+
+## Scan Summary
+| Dimension | Status | Issues |
+|-----------|--------|--------|
+| Functional Scope | ambiguous | 2 |
+| ...
+
+## Clarification Session
+### Q1: Functional Scope
+**Question**: 用户权限应如何划分？
+**Answer**: A (RBAC 角色模型)
+**Rationale**: RBAC 提供灵活的权限管理...
+
+## Next Command
+✅ Run `/flow-prd` to generate PRD
+```
+
+## Error Handling
+- `MISSING_RESEARCH`: research.md 不存在 → 提示先运行 `/flow-init`
+- `INVALID_PHASE`: phase0_complete != true → 提示完成研究阶段
+- `API_ERROR`: Claude API 错误 → 降级到规则引擎
+- `SESSION_CORRUPT`: .session.json 损坏 → 提示删除重试
+
+## Related Commands
+- **前置**: `/flow-init` (生成 research.md)
+- **后续**: `/flow-prd` (生成 PRD)
+- **可选**: `/flow-clarify --history` (查看历史)
+
+## Constitution Compliance
+- **Article I**: 完整实现，无 TODO
+- **Article III**: API Key 使用环境变量
+- **Article VI**: TDD 顺序正确

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

@@ -0,0 +1,82 @@
+---
+name: flow-constitution
+description: 'Manage CC-DevFlow Constitution. Usage: /flow-constitution [--article I] [--amend --proposal file] [--apply --version TYPE]'
+scripts:
+  manage: .claude/scripts/manage-constitution.sh
+---
+
+# Flow-Constitution - 宪法管理命令
+
+## User Input
+```text
+$ARGUMENTS = "[--article I] [--verify] [--impact-report] [--amend --proposal path] [--apply --version TYPE] [--history]"
+```
+
+## 执行原则
+- 所有功能均由 `{SCRIPT:manage}` 执行；此文档仅说明入口与参数。
+- Article 编号遵循罗马数字 I-X。
+- 版本类型：MAJOR / MINOR / PATCH（SemVer 语义）。
+
+## 常用命令
+```text
+/flow-constitution                      → show 当前版本
+/flow-constitution --article IV         → show 指定 Article
+/flow-constitution --verify             → verify 全局一致性
+/flow-constitution --impact-report      → impact 分析
+/flow-constitution --history            → 历史
+/flow-constitution --amend --proposal amendments/2025-01-10-observability.md
+/flow-constitution --apply --version MINOR
+/flow-constitution --apply --version PATCH --force
+```
+
+## 执行流程（由脚本实现）
+
+### 1. Show / Article
+```
+→ {SCRIPT:manage} show [ARTICLE]
+→ 输出当前版本、修订日期、指定 Article 内容
+```
+
+### 2. Verify
+```
+→ {SCRIPT:manage} verify
+→ 检查所有模板/代理/脚本的 Constitution 版本号一致
+→ 调用 validate-constitution hooks，如有违规列出文件
+```
+
+### 3. Impact Report
+```
+→ {SCRIPT:manage} impact
+→ 汇总即将应用的修正案对模板/代理/脚本的影响
+→ 生成报告 (amendments/impact_*.md)
+```
+
+### 4. Amend
+```
+→ {SCRIPT:manage} amend <proposal>
+→ 校验提案格式（版本建议、动机、影响、迁移策略）
+→ 输出预览并提示下一步（apply 之前需人工 review）
+```
+
+### 5. Apply
+```
+→ {SCRIPT:manage} apply <TYPE>
+→ 更新 .claude/constitution/project-constitution.md 版本号
+→ 触发模板/代理/脚本同步
+→ 生成 Sync Report
+```
+
+### 6. History
+```
+→ {SCRIPT:manage} history
+→ 列出版本历史与修订摘要
+```
+
+## 错误处理
+- 未提供必要参数（如 --proposal）→ 脚本返回错误提示。
+- Invalid version bump → 阻断，要求遵循 MAJOR/MINOR/PATCH。
+- 验证失败（如模板未同步）→ 返回违规清单，用户需手动修复。
+
+## 下一步
+- 需要向项目传播修订时，先运行 `--impact-report`，与团队确认后再 `--apply`。
+- 应用后建议运行 `/flow-verify --all` 确认所有需求遵循最新宪法。

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

@@ -0,0 +1,134 @@
+---
+name: flow-dev
+description: 'Execute development tasks following TDD order. Usage: /flow-dev "REQ-123" or /flow-dev'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  check_tasks: .claude/scripts/check-task-status.sh
+  mark_task: .claude/scripts/mark-task-complete.sh
+  validate_constitution: .claude/scripts/validate-constitution.sh
+---
+
+# Flow-Dev - 开发执行命令
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID? [--task T###]"
+```
+未提供 REQ_ID 时从当前分支或 `DEVFLOW_REQ_ID` 推断；`--task` 用于指定起始任务。
+
+## 执行流程
+
+### 阶段 1: Entry Gate
+```
+1. 解析 REQ_ID 与 --task
+   → If argument provided: split
+   → Else: run {SCRIPT:prereq} --json --paths-only
+
+2. 校验资产
+   → 必须存在（/flow-tech 产物）:
+      • TECH_DESIGN.md (技术方案总纲)
+      • research/codebase-tech-analysis.md (代码库技术分析)
+      • data-model.md (数据模型定义)
+      • contracts/ (API 契约目录，至少 1 个文件)
+      • quickstart.md (快速启动指南)
+   → 必须存在（/flow-epic 产物）:
+      • EPIC.md (Epic 规划文档)
+      • TASKS.md (任务分解清单)
+   → 状态校验:
+      • orchestration_status.status ∈ {"epic_complete", "development_in_progress"}
+      • phase0_complete == true (研究阶段完成)
+      • phase1_complete == true (技术设计完成)
+
+3. TASKS 结构校验
+   → Phase 顺序: Setup → Foundational → Phase 2 Tests First → ⚠️ Test Verification → Phase 3 Core Implementation → ...
+   → 任务格式 `- [ ] T### [P?] [US?] Description (path)`
+
+4. 起始任务
+   → Run: {SCRIPT:check_tasks} --json
+   → 若指定 --task，验证任务存在且未完成
+   → 记录下一任务 ID
+```
+
+### 阶段 2: Quickstart 与风格指南加载
+```
+1. 读取 quickstart.md
+   → 获取环境变量、依赖安装、测试命令
+
+2. 读取 STYLE.md（如存在）
+   → 检查 devflow/STYLE.md 文件
+   → 如存在:
+      • 加载设计风格指南（颜色、字体、间距、组件样式等）
+      • 所有前端代码生成必须遵循 STYLE.md 定义的风格
+      • 特别注意:
+        - 颜色使用（使用 CSS Variables 或 Tailwind classes 引用 STYLE.md 定义）
+        - 字体使用（字体族、字阶、行高、字重等必须符合 STYLE.md）
+        - 间距使用（padding, margin, gap 必须使用 STYLE.md 的间距系统）
+        - 组件结构（Button, Card, Input 等必须遵循 STYLE.md 的组件规范）
+        - 阴影、圆角、动画、透明度等（必须遵循 STYLE.md）
+      • 在 EXECUTION_LOG.md 记录 STYLE.md 版本和使用情况
+   → 如不存在:
+      • 使用项目现有的样式约定（如有）
+      • 建议用户运行 /flow-style 建立项目设计标准
+
+3. 如果首次运行:
+   → 执行 quickstart 中的 setup 命令
+
+4. 在 EXECUTION_LOG.md 记录 quickstart 版本 + STYLE.md 版本（如有）
+```
+
+### 阶段 3: TDD 循环
+```
+For each remaining task (顺序严格遵循 TASKS.md):
+
+1. 读取任务定义
+   → 提取 task id、phase、文件路径、是否 [P]
+
+2. 执行策略
+   - Phase 2 (测试任务):
+       • 根据 contracts/ 生成 contract/integration tests
+       • 每个测试必须 FAIL (使用 quickstart 的 test 命令)
+   - Phase 3 (实现任务):
+       • 依据 data-model.md、TECH_DESIGN.md、contracts/ 实现代码
+       • 运行相关测试 (quickstart) 确认 PASS
+   - 后续 Phase:
+       • 按任务描述（安全、性能、文档等）完成
+
+3. 验证 DoD
+   → 测试失败/成功状态符合阶段要求
+   → 文件路径与任务描述一致
+
+4. 标记完成
+   → Run: {SCRIPT:mark_task} T###
+   → Git 提交 (一任务一提交)
+```
+
+### 阶段 4: Exit Gate
+```
+1. 所有任务完成?
+   → {SCRIPT:check_tasks} --json 确认 remaining=0
+
+2. 代码质量
+   → 运行 quickstart 中全量测试命令
+   → 可选: {SCRIPT:validate_constitution} --type dev --severity warning
+
+3. 状态更新
+   → orchestration_status:
+        status = "development_complete"
+        completedSteps append "dev"
+   → EXECUTION_LOG.md 记录完成
+```
+
+## 运行提示
+- 始终使用 quickstart 中提供的命令（测试、lint、db migrate 等）。
+- Phase 2 的所有测试必须在实现前失败；若某测试直接通过，回滚并修正。
+- 遵循 TASKS.md 标注的 `[P]` 仅表示逻辑上可并行，实际执行依旧串行。
+- 如需恢复，可使用 `/flow-dev --task TXYZ` 指向首个未完成任务。
+
+## 错误处理
+- 缺少资产 → 引导用户先运行 `/flow-tech` 或 `/flow-epic`。
+- quickstart 命令失败 → 输出日志路径，要求修复环境后重试。
+- 任务执行失败 → 保留当前状态，不自动跳过。
+
+## 下一步
+1. 完成所有任务后运行 `/flow-qa` 进入测试与安全审查。
+2. 若有新技术引入，回到 `research/tasks.json` 补记并通知 planner。