create-vibe-workflow 0.1.0 → 0.2.0

package/templates/commands/superpowers/brainstorm.md.ejs

@@ -0,0 +1,240 @@
+---
+name: "Brainstorm"
+description: "将模糊想法转化为具体设计文档，在写任何代码前执行。源自 Superpowers brainstorming"
+category: "Planning"
+tags: ["设计", "规划", "头脑风暴", "Superpowers"]
+---
+
+# Brainstorm
+
+## 职责
+
+将用户的一个模糊想法或需求，通过结构化思考转化为具体设计文档。**禁止编写任何实现代码**——本命令的唯一产出是一份设计文档。
+
+## HARD GATE（硬性约束）
+
+> **禁止：**
+> - 编写任何实现代码
+> - 创建任何项目脚手架
+> - 修改任何源代码文件
+> - 生成代码片段（除设计文档中的伪代码示例外）
+>
+> **唯一允许的产出：**
+> - `docs/designs/YYYY-MM-DD-<topic>.md` 设计文档
+> - 相关 git commit（仅包含设计文档）
+
+## 工作模式
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### 面向非专业编程人员（Vibe Coder）
+
+用户可能没有技术背景。你的职责是翻译器和引导者：
+- **用自然语言交流**：避免技术术语，或用通俗比喻解释
+- **帮用户理清想法**：用户可能只有一个模糊的需求，通过提问帮他们聚焦
+- **翻译技术概念**：把用户的"我想要一个类似淘宝的页面"翻译为功能模块
+- **给出简单选项**：设计方案时给 2-3 个选项，用日常语言说明优劣
+- **逐步确认**：每完成一个设计部分就询问"这个部分你觉得对吗？"
+- **控制范围**：提醒用户不要一次做太多，聚焦最小可行方案
+` : `
+### 面向专业开发者
+
+- 可以直接讨论技术方案、架构模式、设计模式
+- 关注实现效率、可维护性、技术合理性
+- 可以复用项目已有的模式和约定
+- 使用适当的抽象层级讨论（领域层、应用层、基础设施层）
+- 关注可测试性、可扩展性、性能边界
+` %>
+
+## 步骤
+
+### 步骤 1：探索项目上下文
+
+在开始设计前，了解当前项目：
+
+1. 读取 `docs/` 目录下已有的设计文档和 PRD
+2. 检查项目结构（`src/`、`packages/` 等）了解已有约定
+3. 查看最近的 git commit 了解开发节奏
+4. 如果项目有 `CLAUDE.md`，阅读项目说明
+5. 如果项目有 `openspec/` 目录，阅读最近的提案
+
+**目的**：确保新设计不重复已有功能，符合项目既有模式。
+
+### 步骤 2：逐一问 clarifying questions
+
+一次只问 **一个问题**，等待用户回答后再问下一个。
+
+**必须先澄清的问题：**
+
+| 问题 | 目的 |
+|------|------|
+| "这个功能解决谁的什么问题？" | 确定用户和目标 |
+| "你觉得什么样的输出算做完了？" | 确定验收标准 |
+| "有没有类似的参考（网站、应用、截图）？" | 对齐视觉/功能预期 |
+| "这个功能影响现有功能吗？" | 确定影响范围 |
+| "你希望什么时候能用上？" | 确定时间约束 |
+
+**约束确认：**
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+- "你希望用户登录后才能用，还是所有人能用？"
+- "数据存哪里方便？电脑本地还是服务器？"
+- "多少人会用这个功能？"
+` : `
+- "认证方案用什么？JWT / Session / OAuth？"
+- "数据存储用现有 DB 还是引入新的存储？"
+- "预期并发量级？这可能影响架构选择。"
+` %>
+
+### 步骤 3：提出 2-3 个方案
+
+针对需求，提出 2-3 个可行方案，每个方案包括：
+
+```
+## 方案 A：<名称>
+- **做法**：简短的实现描述
+- **优点**：2-3 个优点
+- **缺点**：1-2 个缺点
+- **复杂度**：低/中/高
+- **预估工时**：<时间估算>
+
+## 方案 B：<名称>
+...
+
+## 方案 C（可选）：<名称>
+...
+```
+
+**提出推荐方案**并说明理由：
+
+```
+## 推荐：方案 <X>
+理由：<1-2 句话说明为什么推荐该方案>
+```
+
+用户确认方案后再进入下一步。
+
+### 步骤 4：分部分设计，逐部分确认
+
+将设计拆分为以下部分，**每完成一部分就向用户确认**：
+
+#### 第一部分：功能范围
+
+```
+## 功能范围
+
+### 在范围内（本次做）
+- 功能 A
+- 功能 B
+
+### 不在范围内（明确排除）
+- 功能 C（后续迭代）
+- 功能 D（不相关）
+```
+
+#### 第二部分：数据模型（如有）
+
+```
+## 数据模型
+
+### 实体
+- **User**：id, name, email, role, createdAt
+- **Order**：id, userId, status, total, createdAt
+
+### 关系
+- User 1:N Order
+```
+
+#### 第三部分：用户界面 / API
+
+```
+## 界面 / API
+
+### 页面/端点
+1. `/login` — 登录页面（邮箱 + 密码）
+2. `/register` — 注册页面
+...
+```
+
+#### 第四部分：数据流
+
+```
+## 数据流
+
+### 核心流程
+1. 用户访问页面 →
+2. 系统检查认证状态 →
+3. 未认证用户重定向到登录页 →
+4. ...
+```
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+每次确认时用通俗语言："这个部分你看对不对？有需要调整的地方吗？"
+` : `
+每次确认："这个设计部分是否符合预期？有没有需要补充的技术细节？"
+` %>
+
+### 步骤 5：编写设计文档
+
+写入 `docs/designs/YYYY-MM-DD-<topic>.md`，格式：
+
+```markdown
+# 设计：<项目名称>
+
+## 概述
+<1-3 句话说明这个设计要做什么>
+
+## 背景
+<为什么需要这个功能，解决什么问题>
+
+## 方案选择
+<选中的方案和理由>
+
+## 功能范围
+### 范围内
+### 范围外
+
+## 数据模型
+...
+
+## 界面 / API
+...
+
+## 数据流
+...
+
+## 影响分析
+<会影响哪些已有模块，是否需要迁移>
+
+## 验收标准
+- [ ] P0: ...
+- [ ] P1: ...
+
+## 设计日期
+<%= GENERATED_AT.split('T')[0] %>
+
+## 设计者
+create-vibe-workflow / Brainstorm command
+```
+
+> 如果 `docs/designs/` 目录不存在，先创建。
+
+### 步骤 6：提交设计文档
+
+```bash
+git add docs/designs/YYYY-MM-DD-<topic>.md
+git commit -m "docs: 添加 <topic> 设计文档"
+```
+
+## 设计原则
+
+- **先理解再设计**：没有理解需求之前不要急于给方案
+- **保持聚焦**：控制范围，避免功能蔓延
+- **逐部分确认**：不要在全部完成后才让用户反馈
+- **记录决策**：设计文档要记录"为什么选 A 不选 B"
+- **足够就好**：设计文档不是详细规格，够下一步规划用即可
+
+## 下一步
+
+设计文档提交后，建议用户运行：
+- `/plan` — 将设计拆解为 commit 级任务
+- 然后进入开发阶段

package/templates/commands/superpowers/tdd.md.ejs

@@ -0,0 +1,230 @@
+---
+name: "TDD"
+description: "强制执行测试驱动开发纪律 — RED → GREEN → REFACTOR 循环，覆盖率 ≥80%"
+category: "Development"
+tags: ["TDD", "测试", "开发", "Superpowers"]
+---
+
+# TDD
+
+## 职责
+
+强制执行 Test-Driven Development（测试驱动开发）纪律：**先写测试，再写实现**。
+
+## TDD 铁律
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  ① RED     ── 写一个失败的测试（先写！）                   │
+│  ② GREEN   ── 写最简实现让测试通过                        │
+│  ③ REFACTOR ── 重构代码，保持测试通过                     │
+│  ④ LOOP    ── 回到 ①，直到功能完成                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+**不可跳过的阶段：RED → GREEN → REFACTOR 必须严格按顺序执行。**
+
+## 工作模式
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### 面向非专业编程人员（Vibe Coder）
+
+- TDD 的核心理念是"先想清楚怎么验证，再动手做"——就像组装家具前先检查零件清单
+- 测试就是"验证清单"——确认每个功能按预期工作
+- 如果测试失败，不要慌——这恰恰说明测试在保护你
+- 红 -> 绿 -> 重构，可以先不纠结完美，先确保功能跑通，再回来打磨
+- 会使用通俗语言解释测试结果：红色 = 有问题需要修，绿色 = 一切正常
+` : `
+### 面向专业开发者
+
+- 测试行为而非实现细节
+- 避免 over-mocking——只在系统边界使用 mock
+- 关注测试的可维护性和可读性
+- 覆盖率指标是手段不是目的
+- 每个 RED 阶段验证测试本身会失败（确认测试有效）
+` %>
+
+## 步骤
+
+### 步骤 0：准备
+
+1. 读取 `todolist.md`，找到当前待完成的第一个 P0 任务
+2. 理解任务描述、涉及文件、验收标准
+3. 确定当前要实现的函数/组件/端点
+
+```
+正在实现：<commit-message>
+涉及文件：<files>
+当前阶段：准备就绪，等待 RED 阶段
+```
+
+### 步骤 1：RED — 先写测试
+
+**必须**：在写任何实现代码之前，先写测试。
+
+**写测试指南：**
+
+```
+### RED 阶段
+
+测试目标：<要测试的函数/组件>
+测试文件：<test-file-path>
+
+测试用例：
+1. <场景 1> — 期望结果
+2. <场景 2> — 期望结果
+...
+```
+
+**测试命名规范**：`{被测单元} — {场景} — {期望结果}`
+
+```
+示例：
+- createUser — with valid data — returns user object with ID
+- createUser — with duplicate email — throws ValidationError
+- UserAvatar — when image fails to load — shows fallback initials
+```
+
+**测试类型选择**（按优先级）：
+
+| 要验证什么 | 测试类型 | 速度 | 数量 |
+|-----------|---------|------|------|
+| 工具函数/纯逻辑 | 单元测试 | 毫秒级 | 边界全覆盖 |
+| 组件渲染 | 单元测试 | 毫秒级 | happy path |
+| API 端点 | 集成测试 | 秒级 | happy + error |
+| 数据库操作 | 集成测试 | 秒级 | CRUD + 约束 |
+
+**写完后运行测试**，确认测试**失败**：
+
+```bash
+npm test 2>&1 | head -30
+# 或
+npm run test -- --run 2>&1 | head -30
+```
+
+> 确认测试失败证明：① 测试写对了 ② 功能确实还没实现
+
+### 步骤 2：GREEN — 最简实现
+
+**写最简代码让测试通过**：
+
+- 写刚好够让测试通过的代码
+- **不要优化**，**不要抽象**，**不要加未来功能**
+- 可以硬编码返回值——后续测试会迫使你泛化
+- 本阶段目标是**通过测试**，不是"写好代码"
+
+```
+### GREEN 阶段
+
+实现方案：<简短的实现描述>
+变更文件：<files to modify>
+```
+
+**写完后运行测试**，确认全部通过：
+
+```bash
+npm test 2>&1 | head -30
+```
+
+### 步骤 3：REFACTOR — 重构
+
+**测试通过后才能重构**：
+
+- 提取重复代码
+- 优化命名
+- 简化逻辑
+- 遵循项目代码风格
+
+**重构不改变行为**：
+- 不改测试
+- 不改 API 签名
+- 不改业务逻辑
+
+**每步修改后跑测试**确认没有破坏：
+
+```bash
+npm test 2>&1 | head -10
+```
+
+```
+### REFACTOR 阶段
+
+重构内容：
+1. <重构了什么> — <理由>
+2. <重构了什么> — <理由>
+```
+
+### 步骤 4：验证覆盖率
+
+```bash
+npm run test -- --coverage 2>&1 | tail -30
+```
+
+覆盖率要求：
+- 纯逻辑层 ≥ 95%
+- 组件层 ≥ 80%
+- API 端点 ≥ 80%
+- **总覆盖率 ≥ 80%**
+
+如果覆盖率不达标，补充测试或标记为已知低覆盖区域。
+
+### 步骤 5：标记任务完成
+
+在 `todolist.md` 中将当前任务标记为 `[x]`：
+
+```
+- [x] <commit-message> — <任务描述>
+```
+
+并提交当前进度：
+
+```bash
+git add -A
+git commit -m "<commit-message>"
+```
+
+### 步骤 6：进入下一个任务
+
+如果还有未完成的 P0 任务，回到步骤 0（RED 阶段）。
+
+如果所有 P0 完成，输出完成摘要：
+
+```
+✅ 所有 P0 任务已完成！
+
+完成情况：
+- [x] 任务 1
+- [x] 任务 2
+
+覆盖率：<X>%（≥80% ✅）
+
+建议：运行 /verify 进行完整性检查
+```
+
+## 反模式（必须避免）
+
+| 反模式 | 问题 | 正确做法 |
+|--------|------|---------|
+| 先写实现再补测试 | 测试只是验证而非驱动 | 先写测试 |
+| 测试依赖实现细节 | 重构时大面积测试失败 | 测试行为而非实现 |
+| 一个测试测多个东西 | 失败时不知道问题在哪 | 一个测试一个断言 |
+| mock 过多 | 测试与实现强耦合 | 只在边界层用 mock |
+| 忽略 RED 阶段 | 无法确认测试有效性 | RED 阶段验证测试本身 |
+| 覆盖率 100% 强迫症 | 耗费精力在 trivial 代码上 | 按决策矩阵分配精力 |
+
+## CI 集成
+
+```
+每次 push / PR 自动运行：
+[lint] → [type-check] → [unit-test] → [build] → [integration-test]
+
+门禁规则：
+- 单元测试失败 → 阻断合并
+- 覆盖率低于阈值 → 警告
+```
+
+## 下一步
+
+实现完成后，运行：
+- `/verify` — 完整性检查（编译、测试、lint、安全）
+- 然后准备提交 PR

package/templates/commands/superpowers/verify.md.ejs

@@ -0,0 +1,211 @@
+---
+name: "Verify"
+description: "预完成验证 — 在声明工作完成前运行所有检查。源自 Superpowers verification-before-completion"
+category: "Quality"
+tags: ["验证", "质量", "检查", "Superpowers"]
+---
+
+# Verify
+
+## 职责
+
+在声明"功能完成"或"问题已修复"之前，运行所有检查。**没有验证过的完成声明不可信。**
+
+## CRITICAL RULE（硬性规则）
+
+> **禁止在未运行此命令的情况下声明"已完成"、"已修复"、"功能正确"。**
+>
+> 证据必须优先于断言。每次你认为"搞定了"时，先运行 `/verify`。
+
+## 工作模式
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### 面向非专业编程人员（Vibe Coder）
+
+验证就是"最后的检查清单"——就像出门前检查：钥匙、手机、钱包。
+- 每个检查步骤会用通俗语言解释在做什么
+- 失败了会告诉你"哪里有问题"和"怎么修"
+- 不要担心看不懂，我会解释每个错误
+- 修复建议是可操作的（"在第 42 行删掉这个 console.log"）
+` : `
+### 面向专业开发者
+
+- 只报告具体失败信息，不做不必要的解释
+- 关注 CI 一致性——确保本地检查与 CI 检查一致
+- 支持逐项跳过（用 --skip-lint 等参数）
+` %>
+
+## 6 阶段验证
+
+### 阶段 1：编译检查
+
+确保代码可以编译。执行项目对应的编译命令：
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+运行构建命令，检查有没有"红色的错误"——如果有，说明代码还不完整。
+
+\`\`\`bash
+npm run build 2>&1
+\`\`\`
+` : `
+\`\`\`bash
+# TypeScript 项目
+npm run build 2>&1
+# 或
+tsc --noEmit 2>&1
+
+# 其他语言根据项目配置
+\`\`\`
+` %>
+
+**通过条件**：编译/构建成功，无错误退出。
+
+### 阶段 2：类型检查
+
+确保类型系统没有错误：
+
+```bash
+# TypeScript
+npx tsc --noEmit 2>&1
+# 或使用项目配置的 type-check 脚本
+npm run type-check 2>&1
+```
+
+**通过条件**：类型检查通过，无类型错误。
+
+### 阶段 3：Lint 检查
+
+确保代码风格和规范没有问题：
+
+```bash
+# 根据项目配置
+npm run lint 2>&1
+# 或
+npx eslint . 2>&1
+npx prettier --check . 2>&1
+```
+
+**通过条件**：无新的 lint 错误或警告。如果项目本身有未修复的历史 lint 问题，只检查本次修改的文件。
+
+### 阶段 4：测试套件
+
+运行所有测试并检查覆盖率：
+
+```bash
+npm test 2>&1
+npm run test -- --coverage 2>&1 | tail -20
+```
+
+**检查项：**
+
+| 检查 | 通过条件 |
+|------|---------|
+| 所有测试通过 | 0 failures |
+| 覆盖率 ≥ 80% | 全局与单文件覆盖率均达标 |
+| 无 flaky 测试 | 重复运行 3 次均通过（如适用） |
+
+**通过条件**：所有测试通过 + 覆盖率 ≥ 80%。
+
+**如果测试失败：**
+<%= USER_LEVEL === 'vibe-coder' ? `
+- 我会告诉你哪个测试失败了
+- 解释这个测试在测什么
+- 给出可能的修复方向
+- 修复完成后重新运行测试
+` : `
+- 分析失败根因（实现错误 / 测试问题 / 环境问题）
+- 检查测试隔离性
+- 验证 mock 是正确的
+- 修复后重新运行
+` %>
+
+### 阶段 5：安全扫描
+
+检查代码中的安全问题：
+
+```
+### 安全检查清单
+
+□ 无硬编码密钥（API Key、密码、token）
+  搜索模式：/(?:sk-|api[-_]?key|password|secret|token)[:=]["']\w/
+
+□ 无 console.log 残留
+  搜索模式：console\.(log|debug|warn|error)
+
+□ 无 TODO / FIXME 在生产代码中
+  搜索模式：TODO|FIXME|HACK|XXX
+
+□ 无暴露的注释掉的代码块
+
+□ 用户输入已做验证（如果涉及新 API 端点）
+```
+
+> 扫描范围为本次修改的所有文件（用 `git diff --name-only` 获取）。
+
+**通过条件**：无高安全性问题（CRITICAL/HIGH 级别）。
+
+### 阶段 6：Diff 审查
+
+审查所有变更，检查：
+
+```
+### Diff 审查清单
+
+□ 变更与需求相关（无无关修改）
+□ 无调试代码残留
+□ 文档已同步更新
+□ 错误处理完整（无静默吞错误）
+□ 命名一致（与项目现有模式一致）
+□ 无重复代码或不必要的抽象
+□ 未引入新的循环依赖
+```
+
+**通过条件**：所有检查项通过。如果有问题，列出具体位置。
+
+## 输出报告
+
+验证完成后，生成以下报告：
+
+```
+## Verify 报告
+
+### 编译检查    ✅ 通过
+### 类型检查    ✅ 通过
+### Lint 检查    ✅ 通过
+### 测试套件    ✅ 通过（共 N 个测试，覆盖率 X%）
+### 安全扫描    ✅ 通过
+### Diff 审查   ✅ 通过
+
+结果：✅ 全部通过！可以准备提交。
+```
+
+如果有失败项：
+
+```
+## Verify 报告
+
+### 编译检查    ❌ 失败
+  - 错误信息：<具体信息>
+  - 修复建议：<具体建议>
+
+### 类型检查    ✅ 通过
+
+结果：❌ 1/6 阶段失败。请修复后再运行 /verify。
+
+下一个动作：<具体的下一步操作>
+```
+
+## 跳过选项
+
+- `--skip-build` / `--skip-type` / `--skip-lint` / `--skip-tests` / `--skip-security` / `--skip-diff`
+- 跳过时需说明理由
+
+## 与 /ship 的关联
+
+`/ship` 命令会在创建 PR 前**自动调用 `/verify`**。如果验证失败，ship 流程会中止并报告失败原因。
+
+## 下一步
+
+验证通过后：
+- 运行 `/plan` 标记下一个任务
+- 或运行 `/ship` 创建 PR