create-vibe-workflow 0.1.0 → 0.2.0

package/dist/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/dist/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

package/dist/templates/commands/workflow/plan.md.ejs

@@ -0,0 +1,219 @@
+---
+name: "Plan"
+description: "将设计/规格拆解为独立、可提交的子任务，每个子任务 = 1 个 commit（50-300 行，1-8 个文件）"
+category: "Planning"
+tags: ["规划", "任务拆解", "commit", "P0/P1"]
+---
+
+# Plan
+
+## 职责
+
+将设计文档或功能描述拆解为 **commit 粒度**的子任务。每个子任务必须是独立的、可测试的增量。产出写入 `todolist.md`。
+
+## 跳过条件
+
+- 单文件修改，变更量 < 50 行 → 不需要 plan，直接实现
+- 纯配置修改（环境变量、CI 配置）→ 不需要 plan
+
+## 工作模式
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### 面向非专业编程人员（Vibe Coder）
+
+- 用通俗语言解释每个任务要做什么
+- 避免 git/commit 术语，或简单解释"每完成一个任务就保存一次进度"
+- 任务按"从简单到复杂"的顺序排列
+- 帮用户理解为什么先做某些任务
+- 示例："先做数据存储（就像先搭好货架），再做页面展示（把货品摆上去）"
+` : `
+### 面向专业开发者
+
+- 关注模块划分和依赖关系
+- 任务粒度符合 git commit 规范
+- 每个任务可独立编译 + 独立测试
+- 关注接口定义先于实现
+` %>
+
+## 步骤
+
+### 步骤 1：阅读设计文档
+
+读取以下内容来理解要做什么：
+
+1. **设计文档** — 检查 `docs/designs/` 下是否有相关文档
+2. **PRD / 需求文档** — 检查 `docs/PRD.md` 或 `openspec/` 目录
+3. **用户描述** — 如果用户没有设计文档，直接根据描述拆解
+
+输出理解摘要：
+
+```
+## 理解确认
+
+功能：<功能名称>
+核心目标：<一句话说明>
+涉及模块：<涉及的模块列表>
+```
+
+### 步骤 2：识别独立工作单元
+
+将功能拆解为独立的、可逐步交付的工作单元。
+
+**拆分原则：**
+
+| 原则 | 说明 |
+|------|------|
+| **独立可测试** | 每个任务完成后可以独立验证 |
+| **依赖有序** | 前置任务的产出是后置任务的输入 |
+| **适当粒度** | 50-300 行变更，1-8 个文件 |
+| **单一职责** | 一个任务只做一件事 |
+
+**典型拆分模式：**
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### 后端模块示例
+1. 定义数据结构（Schema）
+2. 写操作数据的代码（Service）
+3. 写接收请求的接口（API）
+4. 把模块注册到系统
+
+### 前端页面示例
+1. 创建页面骨架
+2. 添加页面内容
+3. 连接后端数据
+4. 添加交互效果
+` : `
+### 后端模块
+1. feat: 添加 {Module} schema（shared/types）
+2. feat: 实现 {Module}Service（业务逻辑）
+3. feat: 实现 {Module}Controller（API 端点）
+4. feat: 注册 {Module}Module（DI 容器）
+5. test: 添加 {Module} 测试
+
+### 前端页面
+1. feat: 实现 {Page} 列表页（UI + 状态）
+2. feat: 实现 {Page} 详情页
+3. feat: 实现 {Page} 表单（创建/编辑）
+4. test: 添加 {Page} E2E 测试
+` %>
+
+### 步骤 3：编写/更新 todolist.md
+
+将任务写入 `todolist.md`（如果已有，在末尾追加；否则创建）。
+
+**格式：**
+
+```markdown
+# TodoList
+
+## <功能名称> — <日期>
+
+### P0（本次必须完成）
+
+- [ ] `<commit-message>` — <任务描述>
+  - 涉及文件：<file1>, <file2>
+  - 预估变更：~<N> 行
+  - 验收：<如何验证这个任务完成>
+
+- [ ] `<commit-message>` — <任务描述>
+  ...
+
+### P1（后续迭代）
+
+- [ ] `<commit-message>` — <任务描述>
+  ...
+
+### 未来（待定）
+
+- <任务描述>
+...
+```
+
+**P0-first 策略**：
+- 新功能只实现 P0 任务
+- P1 任务完整列出，标记为"后续迭代"
+- P0 必须是交付的最小可行功能
+
+### 步骤 4：标记优先级
+
+**P0 判定标准**（满足任一即为 P0）：
+- 核心功能，不做等于功能不可用
+- 其他 P0 任务的依赖
+- 用户明确要求的必须功能
+- 安全/合规相关
+
+**P1 判定标准**：
+- 增强功能，没有也能用
+- 性能优化
+- 边缘 case 处理
+- 管理后台功能
+
+### 步骤 5：展示摘要
+
+生成完成后，向用户展示摘要：
+
+```
+## Plan 摘要
+
+功能：<功能名称>
+P0 任务：<N> 个 | P1 任务：<M> 个
+
+### P0 执行顺序
+1. <任务 1> — <简述>
+2. <任务 2> — <简述>
+...
+
+### P1 待后续
+- <任务 3>
+- <任务 4>
+
+总计预估：~<N> 行变更
+
+todolist.md 已更新。
+```
+
+## 任务编写规则
+
+- commit-message 遵循 `<type>: <description>` 格式（type: feat/fix/refactor/docs/test/chore）
+- 涉及文件标注完整路径，方便 AI 定位
+- 验收标准要可检查（能用 yes/no 回答）
+- 标注任务间的依赖关系（如"依赖任务 3 完成"）
+- 每个任务标注预估变更行数
+
+## 常用任务序列
+
+### 后端新模块
+
+```
+1. feat: 添加 {Module} Zod schema
+2. feat: 实现 {Module}Service
+3. feat: 实现 {Module}Controller / 路由
+4. feat: 注册 {Module} 到模块系统
+5. test: 添加 {Module} 单元/集成测试
+6. docs: 同步 {Module} 文档
+```
+
+### 前端新页面
+
+```
+1. feat: 实现 {Page} 列表页
+2. feat: 实现 {Page} 详情页
+3. feat: 实现 {Page} 创建/编辑表单
+4. test: 添加 {Page} E2E 测试
+5. docs: 同步页面文档
+```
+
+### API 端点
+
+```
+1. feat: 添加 {Resource} CRUD 接口定义
+2. feat: 实现 {Resource} 数据访问层
+3. feat: 实现 {Resource} 业务逻辑
+4. test: 添加 {Resource} API 测试
+```
+
+## 下一步
+
+Plan 完成后，建议用户运行：
+- `/tdd` — 按 TDD 流程实现第一个任务
+- 或手动按 todolist.md 顺序实现