create-vibe-workflow 0.1.0 → 0.2.0

package/dist/templates/commands/gstack/review.md.ejs

@@ -0,0 +1,192 @@
+---
+name: "Review"
+description: "Pre-landing PR 代码审查 — 分析 git diff 的结构性问题。源自 gstack /review"
+category: "Quality"
+tags: ["审查", "代码质量", "PR", "gstack"]
+---
+
+# Review
+
+## 职责
+
+在 PR 合并前对代码变更进行结构化审查。分析 git diff 中的结构性问题、安全风险、性能隐患，并分类定级。
+
+## 工作模式
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### 面向非专业编程人员（Vibe Coder）
+
+审查就是"找人帮你检查代码有没有问题"：
+- 每个问题会用通俗语言解释
+- 同时展示"有问题的代码"和"修改后的代码"——对比看
+- 告诉你问题严重程度：红色的要必须修，黄色的最好修，蓝色的可修可不修
+- 不要觉得被批评——审查是为了保护你的代码质量
+- 如果看不懂某个问题，直接问，我会解释
+` : `
+### 面向专业开发者
+
+- 关注结构性问题和业务逻辑正确性
+- 按 CRITICAL / HIGH / MEDIUM / LOW 定级
+- 只阻断 CRITICAL 和 HIGH 级别问题
+- 提供具体的行级反馈
+` %>
+
+## 步骤
+
+### 步骤 1：获取变更范围
+
+确定要审查的 diff：
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### 获取变更内容
+
+运行以下命令获取所有变更：
+
+\`\`\`bash
+git diff main...HEAD
+\`\`\`
+
+（如果用的是 master 分支，把 main 换成 master）
+` : `
+\`\`\`bash
+git diff <base-branch>...HEAD
+\`\`\`
+
+自动检测 base branch（master/main），如果检测失败，让用户指定。
+` %>
+
+同时获取变更列表：
+
+```bash
+git diff --name-only <base-branch>...HEAD
+git diff --stat <base-branch>...HEAD
+```
+
+### 步骤 2：结构化分析
+
+从以下维度分析每次变更：
+
+#### 1. SQL 安全（如有数据库变更）
+
+```
+□ 缺少索引：WHERE/ORDER BY/JOIN 列是否已有索引？
+□ N+1 查询：是否有循环中查询数据库？
+□ 迁移风险：数据迁移是否可回滚？
+□ SQL 注入：是否使用了参数化查询？
+```
+
+#### 2. LLM 信任边界违规
+
+```
+□ 用户输入直接拼接到 prompt/系统指令中？
+□ 是否有 prompt injection 风险？
+□ LLM 输出是否经过验证再使用？
+□ 敏感数据是否可能通过 prompt 泄露？
+```
+
+#### 3. 条件副作用
+
+```
+□ 条件判断中是否有副作用（赋值、API 调用）？
+□ 短路求值是否可能导致意外的跳过？
+□ if/else 分支是否覆盖了所有可能？
+```
+
+#### 4. 错误处理
+
+```
+□ 所有可能失败的操作都有 try-catch？
+□ 错误信息是否泄露了敏感信息？
+□ 失败路径是否会导致资源泄漏（连接未关闭、文件句柄未释放）？
+□ 是否有静默吞错误（空的 catch 块）？
+```
+
+#### 5. 安全
+
+```
+□ 认证：新的 API 端点是否有权限检查？
+□ 输入验证：用户输入是否经过验证？
+□ 敏感数据：日志中是否记录了密码/token？
+□ XSS/CSRF：前端是否做了输出转义？
+```
+
+### 步骤 3：问题分类定级
+
+每个问题按以下标准分类：
+
+| 级别 | 含义 | 动作 | 颜色 |
+|------|------|------|------|
+| **CRITICAL** | 必须修复 — 会导致数据丢失/安全漏洞/生产故障 | 阻断合并 | 🔴 |
+| **HIGH** | 强烈建议修复 — 大概率引发 bug | 建议修复 | 🟠 |
+| **MEDIUM** | 值得修复 — 未来可能出问题 | 考虑修复 | 🟡 |
+| **LOW** | 风格偏好 — 不影响功能 | 可忽略 | 🔵 |
+
+**问题报告格式：**
+
+```
+### [CRITICAL] <问题简述>
+- **文件**: `path/to/file.ts:L42-L48`
+- **问题**: <详细说明>
+- **风险**: 如果不修复会导致...
+- **修复建议**:
+
+  ```diff
+  - // 有问题的代码
+  + // 修复后的代码
+  ```
+
+---
+
+### [HIGH] <问题简述>
+- **文件**: `path/to/file.ts:L100`
+- **问题**: <详细说明>
+- **修复建议**: <具体建议>
+---
+```
+
+### 步骤 4：生成审查报告
+
+```
+## Review 报告
+
+分支：feature/xxx → <base-branch>
+变更文件：N 个 | 新增：+N | 删除：-N
+
+### 摘要
+
+- CRITICAL：N 个（必须修复）
+- HIGH：N 个（建议修复）
+- MEDIUM：N 个（考虑修复）
+- LOW：N 个（风格偏好）
+
+### 详细问题
+
+[CRITICAL] ...
+[HIGH] ...
+[MEDIUM] ...
+[LOW] ...
+
+### 总体评价
+
+<简短评价代码质量，建议接收/条件接收/拒绝>
+```
+
+### 步骤 5：重新审查
+
+用户修复问题后，再次运行 `/review` 确认所有 CRITICAL/HIGH 问题已修复。重复直到通过。
+
+## 阻断规则
+
+**以下情况必须标记为 CRITICAL：**
+- 密码/token/密钥硬编码
+- SQL 注入漏洞
+- 认证绕过（无权限检查的 API）
+- 可能导致数据丢失的变更
+- 严重 N+1 查询（循环中查询数据库）
+
+## 提示
+
+- 保持审查客观、专业。不评价编码风格偏好，除非项目有明确规范
+- 对于误报，在报告中说明"已确认为误报"
+- 如果 diff 很大（>500 行），聚焦在关键逻辑变更上
+- `/ship` 命令会自动调用 `/review`，并在有 CRITICAL 问题时中止

package/dist/templates/commands/gstack/ship.md.ejs

@@ -0,0 +1,256 @@
+---
+name: "Ship"
+description: "准备并创建 Pull Request — merge base、测试、审查、版本号、changelog、PR。源自 gstack /ship"
+category: "Release"
+tags: ["发布", "PR", "ship", "gstack"]
+---
+
+# Ship
+
+## 职责
+
+将当前分支的变更通过 Pull Request 发布。涵盖从合并 base 分支到创建 PR 的完整流程。
+
+**这是开发工作流的第 9 步（最终步）**——其他步骤未完成时不应运行此命令。
+
+## 工作模式
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### 面向非专业编程人员（Vibe Coder）
+
+Ship 就是"把你的代码变化打包提交"的过程：
+- 每一步会解释"现在在做什么"
+- git 操作会翻译成通俗语言
+- 如果出错，会明确告诉你哪里有问题、怎么修
+- 最后会生成一个 PR——就像"提交作业给老师检查"
+- 常见的术语解释：
+  - "merge" = "把最新代码合并进来"
+  - "branch" = "你的工作副本"
+  - "PR" = "请求把你的代码合并到主分支"
+` : `
+### 面向专业开发者
+
+- 自动检测 base branch（master/main）
+- 自动处理版本号和 changelog
+- 内部调用 /review 和 /verify
+- 输出符合项目规范的 PR
+` %>
+
+## 前提条件
+
+在运行 `/ship` 前，确认以下条件已满足：
+
+- [ ] 当前分支有未推送的 commit
+- [ ] 所有 P0 任务已完成（检查 `todolist.md`）
+- [ ] 没有未提交的变更（`git status` 干净，或已 stage）
+- [ ] base branch (master/main) 可访问
+
+如果条件不满足，向用户报告并等待修复。
+
+## 步骤
+
+### 步骤 1：检测并合并 base branch
+
+自动检测 base branch（master 或 main）：
+
+```bash
+# 检测 base branch
+BASE_BRANCH=$(git branch -l master main | head -1 | tr -d '* ')
+echo "Base branch: $BASE_BRANCH"
+
+# 获取最新
+git fetch origin $BASE_BRANCH
+
+# 合并
+git merge origin/$BASE_BRANCH --no-edit
+```
+
+**如果合并冲突**：
+<%= USER_LEVEL === 'vibe-coder' ? `
+- 告诉你哪些文件有冲突
+- 这是正常情况——说明你和别人改了同一个文件
+- 帮你解决冲突（保留双方的修改）
+- 解决后继续流程
+` : `
+- 列出冲突文件
+- 提示手动解决或协助解决
+- 解决后继续
+` %>
+
+### 步骤 2：运行 /verify
+
+自动调用 `/verify` 进行完整性检查：
+
+- 编译检查
+- 类型检查
+- Lint 检查
+- 测试套件（全部测试通过 + 覆盖率 ≥ 80%）
+- 安全扫描
+- Diff 审查
+
+如果验证失败，**中止流程**：
+
+```
+❌ Verification 失败！
+
+原因：<具体失败阶段和信息>
+
+请修复后重新运行 /ship。
+```
+
+### 步骤 3：运行 /review
+
+自动调用 `/review` 进行代码审查。
+
+如果存在 CRITICAL 问题：
+
+```
+❌ 代码审查发现 CRITICAL 问题！
+
+CRITICAL 问题列表：
+1. <问题 1>
+2. <问题 2>
+
+请修复 CRITICAL 问题后重新运行 /ship。
+```
+
+**HIGH 及以下级别问题**：记录但不阻断。
+
+### 步骤 4：版本号（如适用）
+
+如果项目根目录存在 `VERSION` 文件，根据 semver 规范自动递增：
+
+```bash
+# 读取当前版本
+VERSION=$(cat VERSION)
+
+# 根据 commit 类型决定递增方式
+# feat → minor, fix → patch, breaking → major
+# 更新 VERSION 文件
+echo "<new-version>" > VERSION
+```
+
+**不自动提交 VERSION 变更**——让用户确认：
+
+```
+当前版本：v1.2.3
+建议版本：v1.3.0（根据 feat 提交自动推断）
+确认更新？[Y/n]
+```
+
+### 步骤 5：更新 CHANGELOG（如适用）
+
+如果存在 `CHANGELOG.md` 或 `CHANGELOG.md`，追加变更记录：
+
+```
+## [1.3.0] - <YYYY-MM-DD>
+
+### Added
+- <新功能描述>
+
+### Fixed
+- <Bug 修复描述>
+
+### Changed
+- <重构/优化描述>
+```
+
+根据 git log 自动生成变更内容：
+
+```bash
+git log <base-branch>..HEAD --oneline --no-decorate
+```
+
+### 步骤 6：提交变更
+
+如果存在 VERSION 和 CHANGELOG 的修改，提交它们：
+
+```bash
+git add VERSION CHANGELOG.md
+git commit -m "chore: bump version to v<新版本>"
+```
+
+### 步骤 7：推送并创建 PR
+
+```bash
+# 获取当前分支名
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# 推送
+git push -u origin $BRANCH
+
+# 创建 PR
+gh pr create \
+  --title "<70 字符以内的 PR 标题>" \
+  --body "<PR 描述>"
+```
+
+**PR 标题格式**：`<type>: <简短描述>`（不超过 70 字符）
+
+**PR 描述格式**：
+
+```
+## Summary
+
+- <1-3 点说明变更内容>
+- <按重要性排序>
+
+## Test Plan
+
+- [ ] 单元测试通过
+- [ ] 集成测试通过
+- [ ] 手动测试关键路径
+- [ ] 检查无回归
+
+Closes #<issue-number>（如有）
+```
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### PR 描述示例
+
+PR 标题和描述会自动生成。标题简短说明"做了什么"，描述里详细列出"改了哪些"和"怎么验证"。
+` : '' %>
+
+### 步骤 8：输出摘要
+
+```
+## Ship 完成 🚢
+
+分支：<branch-name> → <base-branch>
+PR：<PR URL>
+
+### 变更统计
+- 文件变更：<N> 个
+- 新增行：+<N>
+- 删除行：-<N>
+
+### 提交列表
+1. <commit-hash> <commit-message>
+2. <commit-hash> <commit-message>
+
+### 验证结果
+- /verify：✅ 通过
+- /review：✅ 通过
+
+### 版本：v<新版本>（如有）
+```
+
+## 错误处理
+
+| 错误场景 | 处理方式 |
+|---------|---------|
+| 合并冲突 | 报告冲突文件，协助解决后重试 |
+| 测试失败 | 报告失败项，等待修复后重试 |
+| Verify 失败 | 中止流程，报告失败详情 |
+| Review CRITICAL | 中止流程，要求修复 CRITICAL |
+| Push 失败 | 检查远程权限，重试 |
+| PR 创建失败 | 检查 gh 认证，重试 |
+
+## 提示
+
+- `/ship` 应该在所有 P0 任务完成后运行
+- 如果当前分支还没有 push 过，会自动处理
+- 如果项目没有 VERSION 文件，跳过版本号步骤
+- 如果项目没有 CHANGELOG，跳过 changelog 步骤
+- 保持 PR 标题简短（< 70 字符）——标题太长会被截断
+- PR 描述包含测试计划——方便 reviewer 验证

package/dist/templates/commands/opsx/apply.md.ejs

@@ -0,0 +1,106 @@
+---
+name: "OPSX: Apply"
+description: "按 OpenSpec 提案的任务清单逐项实现代码变更"
+category: "Workflow"
+tags: ["实现", "开发", "OpenSpec"]
+---
+
+# OPSX: Apply
+
+## 职责
+
+按照 `openspec/changes/<change-name>/tasks.md` 中的任务清单，逐项实现代码变更。每个任务完成后标记 `[x]`，直到所有 P0 任务完成。
+
+## 前提条件
+
+- `openspec/changes/<change-name>/` 下必须有 `tasks.md`
+- 如果不存在，提示用户先运行 `/opsx:propose`
+- 如果存在 `proposal.md` 和 `design.md`，在实现前先阅读它们
+
+## 步骤
+
+### 步骤 1：选择变更
+
+如果用户在命令中指定了变更名称（如 `/opsx:apply add-user-login`），直接使用。
+
+否则，列出 `openspec/changes/` 下的所有变更（排除 `archive/`），让用户选择：
+
+```
+可用的提案：
+1. add-user-login (3/5 任务完成)
+2. fix-order-pagination (0/2 任务完成)
+请选择 (1-2)：
+```
+
+### 步骤 2：阅读上下文
+
+实现前先阅读：
+1. `tasks.md` — 了解完整任务清单
+2. `design.md` — 了解设计方案
+3. `proposal.md` — 了解业务背景和验收标准
+
+如果有共同依赖的上下文（相邻模块代码、现有接口定义等），一并阅读。
+
+### 步骤 3：逐项实现任务
+
+对 tasks.md 中的每个 **未完成** 的 P0 任务：
+
+```
+### 正在实现：<任务描述>
+
+当前任务：<commit-message>
+涉及文件：<files>
+```
+
+1. **理解任务**：确保清楚这个任务要改什么
+2. **做出修改**：只做最少修改，完成当前任务
+3. **验证**：确保代码编译通过、相关测试通过
+4. **标记完成**：将 `[ ]` 改为 `[x]`
+5. **文档反写**：如果修改涉及文档（API、schema 等），同步更新
+6. **进入下一个任务**
+
+#### 实现原则
+
+- **保持聚焦**: 一个任务只做一件事，不做未来优化
+- **最小变更**: 能改一行不改两行，能不改就不改
+- **遵循现有模式**: 和已有代码风格一致，不发明新写法
+- **编译通过**: 每个任务完成后确保 `tsc` / `npm run build` 通过
+- **跳过 TDD**: Apply 模式下不再强制 RED-GREEN-REFACTOR，但需要确保修改的正确性
+
+### 步骤 4：暂停条件
+
+在以下情况下停止执行，并向用户报告：
+
+| 情况 | 动作 |
+|------|------|
+| **任务描述不清晰** | 暂停，向用户确认具体要怎么改 |
+| **设计问题暴露** | 暂停，建议先更新 design.md 再继续 |
+| **遇到编译/测试错误** | 暂停，排查根因，修复后继续 |
+| **依赖的外部条件不满足** | 暂停，告知用户需要的外部依赖 |
+| **用户中途打断** | 暂停，记录当前进度，下次可继续 |
+
+### 步骤 5：完成
+
+所有 P0 任务标记完成后：
+
+```
+✅ 变更 <change-name> 的 P0 任务已全部完成！
+
+完成情况：
+- [x] 任务 1
+- [x] 任务 2
+- [ ] 任务 3 (P1，后续迭代)
+
+P1 待办（共 N 项）：
+- 任务 3
+- 任务 4
+
+建议运行测试确认无回归。
+```
+
+## 提示
+
+- 如果用户是 Vibe Coder，在暂停时用通俗语言解释问题，不要说技术术语
+- 每个任务完成后如果有必要，运行 `npm test` / `npm run build` 确保没有 break
+- 如果编码过程中发现 tasks.md 有遗漏的任务，先暂停并询问用户是否补充
+- 不要一次性修改所有文件再逐一验证，应该做一点验证一点

package/dist/templates/commands/opsx/archive.md.ejs

@@ -0,0 +1,88 @@
+---
+name: "OPSX: Archive"
+description: "将已完成的变更归档到 openspec/changes/archive/ 中"
+category: "Workflow"
+tags: ["归档", "清理", "OpenSpec"]
+---
+
+# OPSX: Archive
+
+## 职责
+
+将已完成（或决定暂停）的变更从 `openspec/changes/<change-name>/` 移入 `openspec/changes/archive/YYYY-MM-DD-<name>/`，保持工作区整洁。
+
+## 步骤
+
+### 步骤 1：选择要归档的变更
+
+如果用户在命令中指定了变更名称（如 `/opsx:archive add-user-login`），直接使用。
+
+否则，列出 `openspec/changes/` 下所有 **未被归档** 的变更（排除 `archive/` 目录）：
+
+```
+可归档的变更：
+1. add-user-login ✅ 5/5 任务完成
+2. fix-order-pagination ⚠️ 1/2 任务完成
+3. abandon-idea         ⚠️ 0/2 任务完成
+请选择 (1-3)：
+```
+
+### 步骤 2：检查制品完整性
+
+读取变更目录下的所有文件，检查核心制品是否存在：
+
+- `proposal.md` — 是否存在
+- `design.md` — 是否存在（可选）
+- `tasks.md` — 是否存在，P0 任务是否全部完成
+
+### 步骤 3：警告未完成任务
+
+如果存在未完成的 P0 任务，显示警告但 **不阻止归档**：
+
+```
+⚠️  警告：以下 P0 任务尚未完成：
+  - 实现用户注册接口
+  - 添加注册表单页面
+
+确认归档？[y/N]
+```
+
+如果用户确认（y），继续归档。
+
+### 步骤 4：执行归档
+
+1. 创建 `openspec/changes/archive/` 目录（如不存在）
+2. 以日期前导命名归档目录：`archive/YYYY-MM-DD-<change-name>/`
+   - 示例：`archive/2025-06-15-add-user-login/`
+3. 将整个变更目录移动到归档位置
+
+```
+📦 正在归档：add-user-login
+   → openspec/changes/archive/2025-06-15-add-user-login/
+```
+
+### 步骤 5：展示摘要
+
+```
+✅ 归档完成！
+
+变更：add-user-login
+归档位置：openspec/changes/archive/2025-06-15-add-user-login/
+完成状态：5/5 P0 任务已完成
+归档日期：<%= GENERATED_AT.split('T')[0] %>
+```
+
+如果存在未完成任务，在后面追加：
+
+```
+⚠️  注意：归档时有 1 个 P0 任务未完成。
+  如需继续，运行 /opsx:apply 然后输入变更名，AI 会从存档中读取任务清单。
+```
+
+## 提示
+
+- 归档是不可逆操作（但可以手动移回），归档前询问确认
+- 即使是未完成的提案也建议归档，而不是直接删除——归档保留了决策记录
+- 对于放弃的提案，可以在归档目录中补充一个 `ABANDONED.md` 说明放弃原因
+- 归档后不需要修改任何代码或文档，只移动文件
+- 如果 archive/ 目录中有同名变更，在名称后追加 `-v2`、`-v3` 等后缀