create-vibe-workflow 0.1.0 → 0.2.0

package/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 顺序实现

package/templates/hooks/check-deps.mjs

@@ -1,65 +1,66 @@
-#!/usr/bin/env node
-
-// 依赖检测 — Claude Code PreToolUse hook
-// 检查外部依赖组件是否已安装，缺失时打印中文安装指引
-
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-
-const homeDir = homedir();
-const skillsDir = join(homeDir, '.claude', 'skills');
-
-const REQUIRED = [
-  { name: 'gstack', dir: 'gstack', install: 'cd ~/.claude/skills && git clone https://github.com/garrytan/gstack.git gstack' },
-  { name: 'superpowers', dir: 'superpowers', install: 'https://github.com/anthropics/claude-code-superpowers' },
-];
-
-const OPTIONAL = [
-  { name: 'openspec', dir: 'openspec', install: 'npm install -g @anthropic/openspec' },
-];
-
-const missing = [];
-const missingOptional = [];
-
-for (const dep of REQUIRED) {
-  if (!existsSync(join(skillsDir, dep.dir))) {
-    missing.push(dep);
-  }
-}
-
-for (const dep of OPTIONAL) {
-  if (!existsSync(join(skillsDir, dep.dir))) {
-    missingOptional.push(dep);
-  }
-}
-
-if (missing.length === 0 && missingOptional.length === 0) {
-  process.exit(0);
-}
-
-console.log('');
-console.log('══════════════════════════════════════════');
-console.log('  ⚠️  工作流依赖检查');
-console.log('══════════════════════════════════════════');
-
-if (missing.length > 0) {
-  console.log('');
-  console.log('❌ 缺少必要组件（工作流核心功能将不可用）：');
-  for (const dep of missing) {
-    console.log(`  • ${dep.name} — 安装: ${dep.install}`);
-  }
-}
-
-if (missingOptional.length > 0) {
-  console.log('');
-  console.log('⚠️  缺少可选组件（部分高级功能不可用）：');
-  for (const dep of missingOptional) {
-    console.log(`  • ${dep.name} — 安装: ${dep.install}`);
-  }
-}
-
-console.log('');
-console.log('安装后可重启 Claude Code 以启用完整工作流。');
-console.log('══════════════════════════════════════════');
-console.log('');
+#!/usr/bin/env node
+
+// 依赖检测 — Claude Code PreToolUse hook
+// 检查外部依赖组件是否已安装，缺失时打印中文安装指引
+
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const homeDir = homedir();
+const skillsDir = join(homeDir, '.claude', 'skills');
+
+const REQUIRED = [
+  { name: 'gstack', dir: 'gstack', install: 'https://github.com/garrytan/gstack' },
+  { name: 'superpowers', dir: 'superpowers', install: 'https://github.com/obra/superpowers' },
+];
+
+const OPTIONAL = [
+  { name: 'openspec', dir: 'openspec', install: 'https://github.com/Fission-AI/OpenSpec' },
+  { name: 'everything-claude-code', dir: 'everything-claude-code', install: 'https://github.com/affaan-m/everything-claude-code' },
+];
+
+const missing = [];
+const missingOptional = [];
+
+for (const dep of REQUIRED) {
+  if (!existsSync(join(skillsDir, dep.dir))) {
+    missing.push(dep);
+  }
+}
+
+for (const dep of OPTIONAL) {
+  if (!existsSync(join(skillsDir, dep.dir))) {
+    missingOptional.push(dep);
+  }
+}
+
+if (missing.length === 0 && missingOptional.length === 0) {
+  process.exit(0);
+}
+
+console.log('');
+console.log('══════════════════════════════════════════');
+console.log('  ⚠️  工作流依赖检查');
+console.log('══════════════════════════════════════════');
+
+if (missing.length > 0) {
+  console.log('');
+  console.log('❌ 缺少必要组件（工作流核心功能将不可用）：');
+  for (const dep of missing) {
+    console.log(`  • ${dep.name} — 安装: ${dep.install}`);
+  }
+}
+
+if (missingOptional.length > 0) {
+  console.log('');
+  console.log('⚠️  缺少可选组件（部分高级功能不可用）：');
+  for (const dep of missingOptional) {
+    console.log(`  • ${dep.name} — 安装: ${dep.install}`);
+  }
+}
+
+console.log('');
+console.log('安装后可重启 Claude Code 以启用完整工作流。');
+console.log('══════════════════════════════════════════');
+console.log('');

package/templates/memory/MEMORY.md.ejs

@@ -0,0 +1,88 @@
+<!--
+  ============================================================
+  项目记忆索引文件
+  ============================================================
+  这是索引文件，不是记忆本身。每行指向一条记忆文件。
+  AI 会在每次对话开始时读取此文件，快速了解项目状态。
+  新增记忆后，记得在这里加一行索引。
+
+  格式：
+  - [Title](file.md) — 一句话钩子（让 AI 快速判断是否需要读这篇）
+
+  更新规则：
+  - 新增记忆后立即更新此文件
+  - 记忆已过期？保留索引但标注 (archived)
+  - 不要删除索引，保留历史轨迹
+  ============================================================
+-->
+
+# 记忆索引
+
+> 最后更新：<%= GENERATED_AT.split('T')[0] %>
+> 总记忆数：N 条（其中活跃 M 条，已归档 K 条）
+
+---
+
+## 👤 用户 & 团队
+
+<!-- 格式示例（使用时取消注释并替换）：
+### 当前成员
+- [team-member.md](team-member.md) — 团队角色和分工
+
+### 用户偏好
+- [preferences.md](preferences.md) — 编码风格偏好、命名习惯、常用工具
+-->
+
+_暂无记录_
+
+---
+
+## 💬 反馈 & 经验
+
+<!-- 格式示例（使用时取消注释并替换）：
+### 用户反馈
+- [feedback-2025-06-01.md](feedback-2025-06-01.md) — 用户对列表页性能不满意，希望优化加载速度
+
+### 经验教训
+- [lessons-auth.md](lessons-auth.md) — 认证模块踩坑记录：refresh token 轮换策略选型
+-->
+
+_暂无记录_
+
+---
+
+## 📋 项目状态
+
+<!-- 格式示例（使用时取消注释并替换）：
+### 里程碑
+- [milestone-v1.md](milestone-v1.md) — v1.0 发布: 2025-05-15，核心功能完成
+
+### 活跃模块
+- [module-auth.md](module-auth.md) — 认证模块：JWT + OAuth2，已稳定运行
+- [module-order.md](module-order.md) — 订单模块：开发中，预计下周完成
+
+### TODOs
+- [todo-refactor.md](todo-refactor.md) — 计划重构支付模块，拆分过大的 PaymentService
+
+### 技术债务
+- [tech-debt.md](tech-debt.md) — 当前已知的技术债务清单
+-->
+
+_暂无记录_
+
+---
+
+## 📚 参考 & 外部
+
+<!-- 格式示例（使用时取消注释并替换）：
+### 技术参考
+- [architecture-decisions.md](architecture-decisions.md) — 关键架构决策记录（ADR）
+
+### 外部资源
+- [external-apis.md](external-apis.md) — 集成的外部服务 API 文档和凭据指引
+
+### 术语表
+- [glossary.md](glossary.md) — 项目专用术语和缩写解释
+-->
+
+_暂无记录_

package/templates/memory/dev-notes.md.ejs

@@ -0,0 +1,61 @@
+<!--
+  ============================================================
+  开发笔记
+  ============================================================
+  目的：记录项目开发过程中发现的模式、踩坑记录、好用做法。
+  这些是经验性的东西，不是正式文档，但非常有用。
+
+  说明：
+  - 每条记录以日期开头：YYYY-MM-DD 内容描述
+  - 按时间倒序排列（最新的在最上面）
+  - 保持简洁，每条 1-5 行
+  - 如果某条经验后来被证伪，不要删除，追加说明 (deprecated)
+  ============================================================
+-->
+
+# 开发笔记
+
+> 项目：<%= PROJECT_NAME %>
+> 最后更新：<%= GENERATED_AT.split('T')[0] %>
+
+---
+
+## 模式发现
+
+<!-- 记录项目中发现的重复模式和约定 -->
+
+<!-- 示例：
+### 2025-06-01 Service 层统一返回 Result 对象
+所有 Service 方法都返回 { success, data, error } 结构，Controller 层不再 try-catch。
+这样可以统一错误处理，前端也方便判断。
+-->
+
+_暂无记录_
+
+---
+
+## 踩坑记录
+
+<!-- 记录解决过的坑，避免重复踩 -->
+
+<!-- 示例：
+### 2025-06-01 Drizzle 迁移文件命名冲突
+同时运行两个迁移时，由于文件名按时间戳排序，可能导致外键引用顺序错误。
+解决：手动指定迁移顺序，在文件名前加序号前缀如 001_、002_。
+-->
+
+_暂无记录_
+
+---
+
+## 好用做法
+
+<!-- 记录团队发现的高效做法 -->
+
+<!-- 示例：
+### 2025-06-01 使用 Zod 推断类型代替手写接口
+先在 schema.ts 定义 Zod schema，再用 z.infer 推断类型。
+这样 schema 和类型永远一致，不需要手动同步。
+-->
+
+_暂无记录_

package/templates/memory/troubleshooting.md.ejs

@@ -0,0 +1,30 @@
+<!--
+  ============================================================
+  排错日志
+  ============================================================
+  目的：记录开发中遇到的错误、根因和解决方案。
+  每次遇到报错并解决后，在这里追加一条记录。
+
+  说明：
+  - 每条记录一行表格式，使用 | 分隔
+  - 按日期倒序排列（最新的在最上面）
+  - 根因要写到具体的技术原因，不要只写"配置错了"
+  - 如果同一个问题反复出现，说明根因没找对
+  ============================================================
+-->
+
+# 排错日志
+
+> 项目：<%= PROJECT_NAME %>
+> 最后更新：<%= GENERATED_AT.split('T')[0] %>
+
+| 日期 | 现象 | 根因 | 解决 |
+|------|------|------|------|
+<!--
+| 2025-06-01 | `Cannot find module` 构建报错 | tsconfig.json 中 paths 配置与 ts-node 的路径解析不一致 | 在 tsconfig.json 中配置 `tsconfig-paths` 插件，并安装 `tsconfig-paths` 依赖 |
+| 2025-06-02 | 列表页首次加载白屏 3 秒 | 服务端渲染时未使用流式渲染，所有数据加载完才返回 | 改用 `React.lazy` + `Suspense` 实现流式加载 |
+
+注意：日期列使用 YYYY-MM-DD 格式，按日期倒序排列。
+-->
+
+_暂无记录_

package/templates/rules/agents.md

@@ -1,49 +1,49 @@
-# Agent Orchestration
-
-## Available Agents
-
-Located in `~/.claude/agents/`:
-
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| planner | Implementation planning | Complex features, refactoring |
-| architect | System design | Architectural decisions |
-| tdd-guide | Test-driven development | New features, bug fixes |
-| code-reviewer | Code review | After writing code |
-| security-reviewer | Security analysis | Before commits |
-| build-error-resolver | Fix build errors | When build fails |
-| e2e-runner | E2E testing | Critical user flows |
-| refactor-cleaner | Dead code cleanup | Code maintenance |
-| doc-updater | Documentation | Updating docs |
-
-## Immediate Agent Usage
-
-No user prompt needed:
-1. Complex feature requests - Use **planner** agent
-2. Code just written/modified - Use **code-reviewer** agent
-3. Bug fix or new feature - Use **tdd-guide** agent
-4. Architectural decision - Use **architect** agent
-
-## Parallel Task Execution
-
-ALWAYS use parallel Task execution for independent operations:
-
-```markdown
-# GOOD: Parallel execution
-Launch 3 agents in parallel:
-1. Agent 1: Security analysis of auth module
-2. Agent 2: Performance review of cache system
-3. Agent 3: Type checking of utilities
-
-# BAD: Sequential when unnecessary
-First agent 1, then agent 2, then agent 3
-```
-
-## Multi-Perspective Analysis
-
-For complex problems, use split role sub-agents:
-- Factual reviewer
-- Senior engineer
-- Security expert
-- Consistency reviewer
-- Redundancy checker
+# Agent 编排（Agent Orchestration）
+
+## 可用 Agent
+
+位于 `~/.claude/agents/`：
+
+| Agent | 用途 | 使用场景 |
+|-------|------|----------|
+| planner | 实现计划制定 | 复杂功能、重构方案 |
+| architect | 系统设计 | 架构决策、技术选型 |
+| tdd-guide | 测试驱动开发指导 | 新功能、Bug 修复 |
+| code-reviewer | 代码审查 | 写完代码后执行 |
+| security-reviewer | 安全分析 | 提交前检查 |
+| build-error-resolver | 构建错误修复 | 编译/构建失败时 |
+| e2e-runner | E2E 测试 | 关键用户流程验证 |
+| refactor-cleaner | 死代码清理 | 代码维护、优化 |
+| doc-updater | 文档更新 | 同步文档变更 |
+
+## 即时使用规则
+
+无需用户额外提示，以下场景自动触发：
+1. **复杂功能请求** → 使用 **planner** agent
+2. **代码刚写完/修改后** → 使用 **code-reviewer** agent
+3. **Bug 修复或新功能** → 使用 **tdd-guide** agent
+4. **架构决策** → 使用 **architect** agent
+
+## 并行任务执行
+
+**始终**对独立操作使用并行 Task 执行：
+
+```markdown
+# ✅ 推荐：并行执行
+同时启动 3 个 agent：
+1. Agent 1: 安全审查（auth 模块）
+2. Agent 2: 性能审查（缓存系统）
+3. Agent 3: 类型检查（工具函数）
+
+# ❌ 不推荐：不必要的串行
+先等 agent 1，再 agent 2，再 agent 3
+```
+
+## 多视角分析
+
+对于复杂问题，使用分角色子 agent：
+- 事实核查者（Factual reviewer）
+- 高级工程师（Senior engineer）
+- 安全专家（Security expert）
+- 一致性检查员（Consistency reviewer）
+- 冗余检测器（Redundancy checker）