create-vibe-workflow 0.1.0 → 0.2.0

package/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/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/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` 等后缀

package/templates/commands/opsx/explore.md.ejs

@@ -0,0 +1,84 @@
+---
+name: "OPSX: Explore"
+description: "以探索模式分析问题、研究代码、比较方案，不修改任何代码"
+category: "Workflow"
+tags: ["探索", "分析", "研究", "OpenSpec"]
+---
+
+# OPSX: Explore
+
+## 职责
+
+这是一个 **探索姿态**，不是固定工作流。当用户对某个问题还没有清晰想法时，用这个命令自由探索。**禁止修改任何代码或文件**。
+
+## 你可以做
+
+- ✅ **阅读代码**：理解现有实现、接口定义、模块结构
+- ✅ **搜索查询**：用 Grep / Glob 查找相关代码
+- ✅ **分析问题**：定位 Bug 根因、性能瓶颈、设计缺陷
+- ✅ **画图说明**：用 ASCII 图表（流程图、架构图、时序图）帮助理解
+- ✅ **提问澄清**：向用户询问更多细节
+- ✅ **方案对比**：列出多个方案的优劣，辅助决策
+- ✅ **技术调研**：分析某个库 / API / 模式的适用性
+- ✅ **风险评估**：识别实现某个功能可能的风险点
+- ✅ **阅读文档**：查看项目的文档、设计文档、PRD 等
+
+## 你不能做
+
+- ❌ **修改任何代码文件**
+- ❌ **创建新文件**
+- ❌ **运行修改文件的命令**（如代码生成器 scaffold）
+- ❌ **标记任务为完成**
+- ❌ **做出设计决策**（只能提供分析供用户决策）
+
+## 常见场景
+
+### 场景 1：模糊的想法
+
+用户说"我想要一个登录功能"，但不确定具体要什么。你可以：
+1. 检查项目是否有已有的认证方案
+2. 分析常见的登录方案（邮箱密码 / OAuth / 手机号）
+3. 列出每种方案的优劣
+4. 询问用户的具体需求
+
+### 场景 2：问题调查
+
+用户说"列表页面很慢"。你可以：
+1. 查看列表页面代码
+2. 分析数据查询、渲染逻辑
+3. 查找潜在性能瓶颈
+4. 给出优化建议（不实现）
+
+### 场景 3：方案比较
+
+用户说"用 Prisma 还是 Drizzle？"。你可以：
+1. 阅读项目现有数据库代码
+2. 对比两个 ORM 的特性和项目适配度
+3. 给出推荐和理由
+4. 让用户决策
+
+### 场景 4：代码理解
+
+用户说"这个模块怎么工作的？"你可以：
+1. 阅读模块代码
+2. 绘制数据流图
+3. 解释关键逻辑
+
+## 结束方式
+
+探索没有强制产出，可以自然结束：
+
+| 情况 | 做法 |
+|------|------|
+| 用户明确了想法 | 建议下一步运行 `/opsx:propose` |
+| 用户要做决策 | 提供分析摘要，让用户决策 |
+| 用户没有进一步问题 | 询问"还有什么需要探索的吗？" |
+| 用户决定实现 | 建议 `/opsx:propose` → `/opsx:apply` |
+
+## 提示
+
+- 探索时不预设结论，保持开放心态
+- 多问"为什么"，帮用户理清真实需求
+- 画 ASCII 图表非常有价值，比文字描述高效得多
+- 如果发现明显的问题（如安全漏洞），可以指出但 **不要修复**
+- 探索过程中如果用户提出"能不能帮我改一下"，提醒用户切换到 apply 模式

package/templates/commands/opsx/propose.md.ejs

@@ -0,0 +1,185 @@
+---
+name: "OPSX: Propose"
+description: "将需求想法转化为结构化规格文档（提案 + 设计 + 任务拆解），项目根目录下的 openspec/changes/ 中"
+category: "Workflow"
+tags: ["需求", "规划", "规格", "OpenSpec"]
+---
+
+# OPSX: Propose
+
+## 职责
+
+将用户的一个需求想法（自然语言描述）转化为可执行的结构化规格文档。产出三个文件到 `openspec/changes/<change-name>/` 目录：
+
+| 文件 | 内容 |
+|------|------|
+| `proposal.md` | 做什么 & 为什么做、范围界定、P0/P1 优先级划分 |
+| `design.md` | 怎么做、架构方案、关键决策 |
+| `tasks.md` | 可检查的任务清单（每个任务 = 一个独立 commit） |
+
+## 工作模式
+
+<%= USER_LEVEL === 'vibe-coder' ? `
+### 面向非专业编程人员（Vibe Coder）
+
+用户可能没有技术背景。你的任务是：
+- **引导式提问**：用自然语言追问，帮用户理清需求
+- **翻译成技术语言**：把用户的"我想要一个登录页面"翻译为功能规格
+- **不做假设**：不清楚的地方用 AskUserQuestion 确认
+- **给出选项**：设计方案时给 2-3 个选项，说明各自优劣
+` : `
+### 面向专业开发者
+
+- 可以直接讨论技术方案、架构选型
+- 关注实现效率和技术合理性
+- 可以复用项目已有的模式和约定
+` %>
+
+## 步骤
+
+### 步骤 1：理解需求
+
+- 接收用户自然语言描述的需求
+- 如果描述模糊，用 **AskUserQuestion** 追问澄清：
+  - "这个功能解决谁的什么问题？"
+  - "你觉得什么样的输出算做完了？"
+  - "有没有类似的参考？"
+- 提炼出核心目标和验收标准（1-3 条）
+
+### 步骤 2：确定变更名称
+
+- 从需求描述中提取关键词，推导 kebab-case 的变更名称
+- 示例："添加用户登录功能" → `add-user-login`
+- 示例："修复订单列表分页问题" → `fix-order-pagination`
+- 如不确定，向用户确认名称
+
+### 步骤 3：创建目录结构
+
+创建 `openspec/changes/<change-name>/` 目录，包含三个文件：
+- `proposal.md`
+- `design.md`
+- `tasks.md`
+
+> 如果 `openspec/` 目录不存在，先创建它并添加 `.gitkeep`。
+
+### 步骤 4：编写 proposal.md
+
+**做什么 & 为什么做**
+```
+# 提案：<变更名称>
+
+## 概述
+用 1-3 句话说明要做什么，为什么做。
+
+## 用户故事
+作为 <角色>，
+我想要 <功能/能力>，
+以便 <业务价值>。
+
+## 验收标准
+- [ ] P0: ...
+- [ ] P0: ...
+- [ ] P1: ...
+
+## 范围界定
+
+### 在范围内
+- 功能 A
+- 功能 B
+
+### 不在范围内（明确排除）
+- 功能 X（后续迭代）
+- 功能 Y（不相关）
+
+## 优先级
+
+### P0（本次必须完成）
+- ...
+
+### P1（设计时考虑，本次不实现）
+- ...
+```
+
+- P0 是必须完成的核心功能，P1 是后续迭代
+- 验收标准要可检查（能用 yes/no 回答）
+
+### 步骤 5：编写 design.md
+
+**怎么做**
+```
+# 设计：<变更名称>
+
+## 架构方案
+<描述整体方案，含组件/模块交互>
+
+## 关键决策
+
+### 决策 1：<标题>
+- **选项**: A / B / C
+- **选择**: A
+- **理由**: ...
+- **影响**: ...
+
+## 数据流
+<数据如何流转，核心流程>
+
+## 接口/API（如适用）
+<接口定义、参数、返回值>
+
+## 影响分析
+<会影响哪些已有模块，是否需要迁移>
+```
+
+- 保持简洁，重点在关键决策和数据流
+- 不需要过度设计，够下一个步骤的任务拆解用即可
+
+### 步骤 6：编写 tasks.md
+
+**任务清单**
+```
+# 任务：<变更名称>
+
+## P0 任务（本次实现）
+
+- [ ] `<commit-message>` — <描述>（~<估算行数> 行）
+  涉及文件：<file1>, <file2>
+
+## P1 任务（后续迭代）
+
+- [ ] `<commit-message>` — <描述>
+```
+
+- 每个任务对应一个独立 commit
+- 每个任务 50-300 行变更
+- 按照实现顺序排列（依赖前置）
+- 对每个任务标注涉及的文件（方便 AI 定位上下文）
+
+### 步骤 7：展示摘要
+
+生成完成后，用简洁格式向用户展示摘要：
+
+```
+## 摘要
+
+变更：<change-name>
+
+### 做什么
+<一句话说明>
+
+### P0 任务
+1. ...
+2. ...
+
+### P1（后续）
+- ...
+- ...
+
+已生成：openspec/changes/<change-name>/
+```
+
+## 提示
+
+- 如果项目已有其他 `openspec/changes/` 中的提案，先阅读它们以保持一致风格
+- 如果项目有既定的架构约定（如 NestJS 模块结构），在 design.md 中遵循
+- Proposal.md 保持业务语言，design.md 可以进入技术细节
+- 不确定的技术方案，**先研究再决定**，而不是猜测