cc-devflow 1.0.1

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

@@ -0,0 +1,131 @@
+---
+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
+---
+
+# 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. 校验目录
+   → 使用 {SCRIPT:prereq} --json 获取路径
+   → 必须存在:
+      • devflow/requirements/${REQ_ID}/
+      • 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 模板
+
+3. PRD 覆盖提示
+   → 若 PRD.md 已存在 → WARN 并确认是否覆盖
+
+4. 状态校验
+   → 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

@@ -0,0 +1,93 @@
+---
+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 一并提交，供代码审阅与发布审批使用。

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

@@ -0,0 +1,92 @@
+---
+name: flow-release
+description: 'Create PR and manage release. Usage: /flow-release "REQ-123" or /flow-release'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  check_tasks: .claude/scripts/check-task-status.sh
+  validate_constitution: .claude/scripts/validate-constitution.sh
+  generate_status: .claude/scripts/generate-status-report.sh
+---
+
+# Flow-Release - 发布管理命令
+
+## 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、TEST_REPORT.md、SECURITY_REPORT.md
+   → orchestration_status.status ∈ {"qa_complete", "release_failed"}
+3. {SCRIPT:check_tasks} --json 确认 remaining == 0
+4. 验证 QA gate:
+   → TEST_REPORT.md / SECURITY_REPORT.md 中的 Gate 均为 PASS
+5. Git 环境:
+   → 工作区干净、当前在 feature/bugfix 分支
+   → 分支已推送，若无 upstream 提示 push
+```
+
+### 阶段 2: 发布上下文准备
+```
+1. 收集元数据:
+   → TITLE, branch, commits, changed files, coverage, security 状态
+2. 汇总文档:
+   → PRD 成功指标、EPIC 范围、TASKS DoD、quickstart 验证命令
+3. 更新 orchestration_status:
+   → status = "release_in_progress"
+   → phase = "release"
+4. EXECUTION_LOG.md 记录发布启动
+```
+
+### 阶段 3: release-manager Agent
+```
+Prompt 核心要求:
+  - 确认 Constitution 校验无 ERROR:
+      {SCRIPT:validate_constitution} --type all --severity error
+  - 生成 RELEASE_PLAN.md:
+      • 范围概览、风险评估、回滚策略、监控计划、依赖项
+      • 列出 data-model / contracts / quickstart 的变更摘要
+  - 生成 PR 描述草稿:
+      • 摘要、实现亮点、测试结果（引用 quickstart 命令）、安全结论、验证报告链接
+  - 建议标签、检查清单
+```
+
+### 阶段 4: PR 创建与完结
+```
+1. 使用 gh CLI 创建或更新 PR
+   → 标题: "${REQ_ID}: ${TITLE}"
+   → 正文采用 agent 输出
+2. 检查 CLAUDE.md：
+   → 若 TECH_DESIGN 引入新基础设施/重大变更，更新 "## Technical Architecture"（≤15 行）
+3. 状态更新:
+   → orchestration_status.status = "release_complete"
+   → completedSteps append "release"
+   → prUrl 记录到状态文件
+4. EXECUTION_LOG 记录 PR 链接与发布时间
+5. 可选: {SCRIPT:generate_status} 生成状态报告
+```
+
+## 输出
+```
+✅ RELEASE_PLAN.md
+✅ CLAUDE.md（如需更新）
+✅ GitHub PR (gh)
+✅ orchestration_status.json 更新 (release_complete)
+✅ EXECUTION_LOG.md 发布记录
+```
+
+## 错误处理
+- QA Gate 失败或 Constitution ERROR → 立即终止，标记 status="release_failed"。
+- Git push/PR 创建失败 → 输出命令和日志，保持可重试状态。
+- CLAUDE.md 更新遗漏 → 阻断发布并提示补写。
+
+## 下一步
+1. 等待代码评审与 CI 通过。
+2. 合并后更新主分支标签或发布记录。
+3. 反馈验证结果，必要时触发 `/flow-verify` 复检。

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

@@ -0,0 +1,98 @@
+---
+name: flow-restart
+description: 'Restart interrupted cc-devflow requirement development. Usage: /flow-restart "REQ-123" [--from=stage]'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  recover: .claude/scripts/recover-workflow.sh
+  generate_status: .claude/scripts/generate-status-report.sh
+---
+
+# Flow-Restart - 中断恢复命令
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID [--from=stage] [--force] [--backup]"
+```
+
+## 支持阶段
+```
+research | prd | planning | development | qa | release
+```
+
+## 执行流程
+
+### 阶段 1: Entry Gate
+```
+1. 参数解析
+   → 校验 REQ_ID（REQ-\d+）、阶段枚举。
+
+2. 状态自检
+   → Run: {SCRIPT:prereq} --json --paths-only
+   → 确认 devflow/requirements/${REQ_ID}/ 存在
+   → orchestration_status.json.status ∈ {failed, paused, *_failed}
+   → 若 status 已完成且未使用 --force → 拒绝重启。
+
+3. 中断点检测
+   → 调用 {SCRIPT:recover} --detect "${REQ_ID}"
+   → 解析中断原因、推荐恢复阶段、待恢复的产物。
+
+4. 备份（可选）
+   → 如果 --backup，则创建 `${REQ_DIR}/backup/${timestamp}` 目录复制关键文件。
+```
+
+### 阶段 2: 清理与重置
+```
+1. 根据阶段执行清理动作:
+   • research: 清理临时 research/mcp 缓存、保留 summary
+   • prd: 备份 PRD.md，重置 status=initialized
+   • planning: 备份 EPIC.md/TASKS.md，清理规划中间状态
+   • development: 检查未完成任务、生成 git stash 建议
+   • qa: 删除过期 TEST_REPORT/SECURITY_REPORT
+   • release: 关闭未完成 PR 草稿、重置 release 状态
+
+2. 更新 orchestration_status:
+   → status = "${stage}_restart_in_progress"
+   → restartStage = stage
+   → restartAt = timestamp
+
+3. EXECUTION_LOG.md 记录恢复动作和备份路径。
+```
+
+### 阶段 3: 恢复执行
+```
+1. 根据 stage 自动触发后续命令提示：
+   → research → 建议运行 /flow-init --resume
+   → prd → /flow-prd
+   → planning → /flow-epic
+   → development → /flow-dev
+   → qa → /flow-qa
+   → release → /flow-release
+
+2. 若 {SCRIPT:recover} 支持自动修复（如重建 TASKS），执行对应脚本。
+```
+
+### 阶段 4: Exit Gate
+```
+1. 验证关键产物是否存在（与阶段相符）。
+2. orchestration_status:
+   → status = "${stage}_restart_ready"
+   → completedSteps 不剥夺已完成阶段
+3. 输出下一步指引。
+```
+
+## 错误处理
+- 检测不到中断 → 提示使用 `/flow-status` 查看当前状态，或需 --force。
+- 备份失败 → 终止并保留原样。
+- 清理动作报错 → 输出日志路径，允许用户手动处理后重试。
+
+## 输出
+```
+✅ backup/ 时间戳目录（若启用备份）
+✅ orchestration_status.json 更新（restartStage, restartAt, status）
+✅ EXECUTION_LOG.md 恢复条目
+```
+
+## 下一步
+1. 按提示执行下一阶段命令。
+2. 使用 `/flow-status REQ_ID --detailed` 确认状态恢复正确。
+3. 如多次失败，考虑跑 `/flow-verify` 或手动 review 产物。

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

@@ -0,0 +1,64 @@
+---
+name: flow-status
+description: 'Query development progress status for cc-devflow requirements. Usage: /flow-status [REQ-ID]'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  generate_status: .claude/scripts/generate-status-report.sh
+---
+
+# Flow-Status - 开发进度查询命令
+
+## User Input
+```text
+$ARGUMENTS = "[REQ_ID?] [--all] [--bugs] [--detailed] [--summary]"
+```
+默认显示所有活跃需求的概览；指定 REQ_ID 时输出单一详情。
+
+## 执行流程
+
+### 1. 参数解析
+- 验证 ID 格式 (`REQ-\d+` / `BUG-\d+`)。
+- 识别 `--all`、`--bugs`、`--detailed`、`--summary`、`--branches` 等标志。
+
+### 2. 数据收集
+```
+1. 运行 {SCRIPT:prereq} --json --paths-only
+2. 扫描:
+   → devflow/requirements/*/orchestration_status.json
+   → devflow/bugs/*/orchestration_status.json
+3. 读取每个状态文件及 EXECUTION_LOG.md 头部，提取:
+   → status, phase, completedSteps, phase0/phase1 flag, lastUpdated
+   → 是否存在 PRD/TECH_DESIGN/data-model/contracts/quickstart/EPIC/TASKS/QA 报告
+4. 若 `--branches`: 读取 git 分支与 upstream 状态
+5. 若 `--detailed`: 关联 PRD/EPIC/TASKS 进度、QA/Release 结论
+```
+
+### 3. 输出格式
+- **默认概览**: 表格显示 ID、标题、当前阶段、关键产物完成度、最近更新时间。
+- **详细模式**: 列出各阶段产物路径、phase0/phase1 标志、剩余步骤与下一命令建议。
+- **Summary/All**: 使用 {SCRIPT:generate_status} 生成聚合报告。
+
+### 4. 建议动作
+- 根据状态字段提示下一命令：
+  - `status=initialized` → `/flow-prd`
+  - `phase0_complete=false` → `/flow-init` consolidate
+  - `phase1_complete=false` → `/flow-tech`
+  - `status=epic_complete` → `/flow-dev`
+  - `status=qa_complete` → `/flow-release`
+
+## 输出样例
+```
+📊 CC-DevFlow 状态总览 (更新: 2025-02-10T09:12Z)
+┌─────────┬──────────────┬───────────────┬────────────┬──────────┐
+│ ID      │ Title        │ Status        │ Phase      │ Next     │
+├─────────┼──────────────┼───────────────┼────────────┼──────────┤
+│ REQ-123 │ 下单流程优化   │ epic_complete │ planning   │ /flow-dev │
+│ REQ-124 │ 权限矩阵       │ qa_complete   │ release    │ /flow-release │
+│ REQ-125 │ 账单导出       │ prd_complete  │ technical  │ /flow-tech │
+└─────────┴──────────────┴───────────────┴────────────┴──────────┘
+```
+
+## 错误处理
+- 找不到 ID → 提示有效目录。
+- 状态文件损坏 → 标记“unknown”，提示用户修复。
+- `--branches` 请求但 Git 不可用 → 输出提示并继续其他数据。

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

@@ -0,0 +1,142 @@
+---
+name: flow-tech
+description: 'Generate Technical Design package. Usage: /flow-tech "REQ-123" or /flow-tech'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  tech_analysis: .claude/scripts/generate-tech-analysis.sh
+  extract_data_model: .claude/scripts/extract-data-model.sh
+  export_contracts: .claude/scripts/export-contracts.sh
+  quickstart: .claude/scripts/generate-quickstart.sh
+agent_scripts:
+  sh: .claude/scripts/update-agent-context.sh __AGENT__
+  ps: scripts/powershell/update-agent-context.ps1 -AgentType __AGENT__
+---
+
+# Flow-Tech - 技术方案生成命令
+
+## User Input
+```text
+$ARGUMENTS = "REQ_ID"
+```
+若缺省则从当前分支或 `DEVFLOW_REQ_ID` 推断；进入流程前必须解析成功。
+
+## 命令格式
+```text
+/flow-tech "REQ_ID"
+/flow-tech             # Auto-detect from current branch
+```
+
+### 参数说明
+- **REQ_ID**: 需求编号 (可选，默认从当前 Git 分支或环境变量获取)
+
+## 执行流程
+
+### 阶段 0: Anti-Tech-Creep Gate
+- 读取 `CLAUDE.md` 的技术架构章节并对照 `research/internal/codebase-overview.md`。
+- 若缺失或与现状不符：重写 ≤15 行的架构摘要并记录核心原则。
+- 触发约束：除非在技术方案中明确说明，禁止引入新技术或任意替换既有栈。
+
+### 阶段 1: 前置条件检查 (Entry Gate)
+```
+1. 解析 REQ_ID
+   → If $ARGUMENTS provided: use split("|") first token
+   → Else: run {SCRIPT:prereq} --json --paths-only
+   → If仍为空: ERROR "No requirement ID found."
+
+2. 验证目录与产物
+   → 检查: devflow/requirements/${REQ_ID}/
+   → 必须存在: PRD.md, research/research.md, research/tasks.json, research/internal/codebase-overview.md
+   → orchestration_status.json.phase0_complete 必须为 true
+
+3. 状态门
+   → status ∈ {prd_complete, ui_complete, tech_design_failed}
+   → 未满足则拒绝进入。
+```
+
+### 阶段 2: 技术细化分析
+```
+1. 执行 {SCRIPT:tech_analysis} "${REQ_ID}"
+   → 输出: research/codebase-tech-analysis.md
+   → 内容: 数据模型模式、API 模式、认证、安全、数据库、可复用组件、测试、示例代码。
+
+2. 同步 EXECUTION_LOG.md
+   → 记录分析完成时间、重点洞察、待确认风险。
+```
+
+### 阶段 3: 资产生成与 Agent 调用
+```
+1. 准备 TECH_DESIGN 上下文
+   → 读取: PRD.md, research/research.md, research/codebase-tech-analysis.md
+   → 可选: UI_PROTOTYPE.html (存在时加载结构摘要)
+   → 更新 orchestration_status: status=tech_design_in_progress, phase=technical_design.
+
+2. 调用 tech-architect agent
+   → 加载模板: .claude/docs/templates/TECH_DESIGN_TEMPLATE.md
+   → 执行模板 Execution Flow，输出 TECH_DESIGN.md（无 {{PLACEHOLDER}}）
+   → 记录 log_event "${REQ_ID}" "Technical design completed"
+
+3. 派生资产
+   → Run: {SCRIPT:extract_data_model} "${REQ_ID}" → 生成 data-model.md
+   → Run: {SCRIPT:export_contracts} "${REQ_ID}" → 生成 contracts/openapi.yaml (或其他格式)
+   → Run: {SCRIPT:quickstart} "${REQ_ID}" → 生成 quickstart.md（包含环境、测试命令、验证步骤）
+
+4. 更新代理上下文
+   → Run: {AGENT_SCRIPT}  # 仅新增技术条目，保持 markers 内手动内容
+   → 在 EXECUTION_LOG.md 记录新增技术。
+```
+
+### 阶段 4: 完成校验 (Exit Gate)
+```
+1. 文件存在性
+   → TECH_DESIGN.md, research/codebase-tech-analysis.md
+   → data-model.md, contracts/, quickstart.md
+
+2. 质量检查
+   → TECH_DESIGN.md: 包含系统架构/技术栈/数据模型/API/安全/性能/Constitution Gate
+   → data-model.md: 实体、字段、关系、校验、状态机
+   → contracts/: 所有端点请求/响应 schema
+   → quickstart.md: 环境准备、测试矩阵、验证指令
+
+3. 宪法校验
+   → Run: validate-constitution.sh --type tech_design --severity warning
+   → 若有 ERROR 级别违规：终止并修复
+
+4. 状态更新
+   → orchestration_status.json:
+      • status = "tech_design_complete"
+      • phase = "epic_planning"
+      • phase1_complete = true
+      • completedSteps append "tech_design"
+   → EXECUTION_LOG.md 记录出口验收。
+```
+
+### 阶段 5: 输出与下一步
+- 汇总结果：
+  ```
+  ✅ TECH_DESIGN.md
+  ✅ research/codebase-tech-analysis.md
+  ✅ data-model.md
+  ✅ contracts/openapi.yaml
+  ✅ quickstart.md
+  ```
+- 建议操作：
+  1. 审阅技术方案关键决策。
+  2. 使用 `/flow-epic` 进入任务规划（会 gate 检查上述资产）。
+  3. 如需补充研究，回到 `/flow-init` 生成的 research/tasks.json 更新状态。
+
+## 错误处理提示
+- 缺少 PRD 或 research.md → 直接 ERROR，让用户先补 Phase 0。
+- agent 输出不完整 → 保留临时文件并记录 `tech_design_failed`，用户可修正后重试。
+- 派生资产脚本失败 → 标记 `phase1_complete = false`，提示对应脚本名与日志路径。
+
+## 宪法遵循
+- Simplicity Gate：设计 ≤3 栈层、禁止为未来功能做预设。
+- Anti-Abstraction Gate：直接使用框架，不新增自定义抽象层。
+- Integration-First Gate：所有 contracts 在 Phase 2 先定义，Phase 3 任务只需按合同落地。
+
+## 产物摘要
+- `TECH_DESIGN.md`: 技术总纲，引用子文档链接。
+- `research/codebase-tech-analysis.md`: 深度分析，支撑方案假设。
+- `data-model.md`: 供 planner 和 DB 工具使用的实体清单。
+- `contracts/`: OpenAPI/GraphQL 等契约基线。
+- `quickstart.md`: QA、Dev、CI 共享的执行脚本。