Initial commit: VibeEngineering V2

- 两阶段分离：设计阶段人工确认，执行阶段全自动化 - 子代理驱动：Implementer → Spec Reviewer → Quality Reviewer - 原生 Task 系统：使用 Claude Code Task 替代自定义状态管理 - 跨 Compact 恢复：PreCompact + SessionStart Hook（内联命令实现） Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-04 18:00:55 +08:00
commit c484cafb45
15 changed files with 2906 additions and 0 deletions
--- a/.claude/skills/brainstorming/SKILL.md
+++ b/.claude/skills/brainstorming/SKILL.md
@ -0,0 +1,128 @@
+---
+name: brainstorming
+description: 在任何创造性工作之前必须使用 - 创建功能、构建组件、添加功能或修改行为时。探索用户意图、需求和设计，然后再实现。
+---
+
+# 头脑风暴：将想法转化为设计
+
+## 概述
+
+通过自然的协作对话，帮助将想法转化为完整的设计和规格。
+
+首先了解当前项目上下文，然后**每次只问一个问题**来细化想法。一旦你理解了要构建什么，以小节（200-300 字）呈现设计，每节之后确认是否正确。
+
+## 流程
+
+### 理解想法
+
+- 首先查看当前项目状态（文件、文档、最近的提交）
+- **每次只问一个问题**来细化想法
+- 尽可能使用多选题，但开放式问题也可以
+- 每条消息只问一个问题 - 如果一个主题需要更多探索，拆分成多个问题
+- 关注理解：目的、约束、成功标准
+
+### 探索方案
+
+- 提出 2-3 种不同的方案及其权衡
+- 以对话方式呈现选项，并给出你的推荐和理由
+- 先说推荐的选项并解释原因
+
+### 呈现设计
+
+- 一旦你认为理解了要构建什么，呈现设计
+- 将设计分成 200-300 字的小节
+- 每节之后询问是否正确
+- 涵盖：架构、组件、数据流、错误处理、测试
+- 如果有不清楚的地方，准备返回澄清
+
+## 设计完成后
+
+### 文档
+
+- 将验证过的设计写入 `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- 提交设计文档到 git
+
+### 输出
+
+完成后输出：
+
+```
+设计文档已完成并保存到 docs/plans/YYYY-MM-DD-<topic>-design.md
+
+下一步：执行 /vibe-plan 创建实现计划。
+```
+
+## 核心原则
+
+- **每次只问一个问题** - 不要用多个问题淹没用户
+- **多选题优先** - 在可能时比开放式问题更容易回答
+- **严格遵循 YAGNI** - 从所有设计中移除不必要的功能
+- **探索替代方案** - 在确定之前总是提出 2-3 种方案
+- **增量验证** - 分节呈现设计，验证每一节
+- **保持灵活** - 当某些内容不清楚时返回澄清
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|----------|
+| 一次问多个问题 | 每条消息只问一个问题 |
+| 假设用户意图 | 询问澄清 |
+| 跳过方案探索 | 总是提出 2-3 种方案 |
+| 设计完直接开始编码 | 等待用户确认设计 |
+| 添加"可能有用"的功能 | 严格遵循 YAGNI |
+
+## 危险信号 - 停下来
+
+如果你发现自己想：
+- "用户可能想要这个功能"
+- "我先开始编码，边做边设计"
+- "这个设计很明显，不需要确认"
+- "我可以跳过方案探索"
+
+**所有这些都意味着：停下来。遵循流程。**
+
+## 示例工作流
+
+```
+用户: 我想添加一个用户认证功能
+
+你: 让我先了解一下项目情况...
+[查看项目文件和结构]
+
+你: 关于认证方式，你倾向于哪种？
+1. 用户名/密码（传统方式）
+2. OAuth（第三方登录，如 Google、GitHub）
+3. 两者都支持
+
+用户: 先支持用户名/密码
+
+你: 关于密码存储，你有特定的安全要求吗？
+1. 使用 bcrypt 哈希（推荐，安全性高）
+2. 使用 SHA-256（较快，安全性中等）
+3. 有其他要求请说明
+
+用户: 用 bcrypt
+
+你: 好的，让我呈现设计的第一部分...
+
+## 1. 用户模型设计
+
+用户表结构：
+- id: UUID
+- username: 唯一字符串
+- password_hash: bcrypt 哈希
+- created_at: 时间戳
+- updated_at: 时间戳
+
+这部分设计是否正确？
+
+用户: 是的
+
+你: [继续下一部分...]
+
+[设计完成后]
+
+你: 设计文档已保存到 docs/plans/2026-01-19-user-auth-design.md
+
+请审查设计，确认后我将创建实现计划。
+```
--- a/.claude/skills/subagent-driven-development/SKILL.md
+++ b/.claude/skills/subagent-driven-development/SKILL.md
@ -0,0 +1,274 @@
+---
+name: subagent-driven-development
+description: 在当前会话中执行有独立任务的实现计划时使用
+---
+
+# 子代理驱动开发
+
+通过为每个任务派发新的子代理来执行计划，每个任务完成后进行两阶段审查：先规格符合性审查，再代码质量审查。
+
+**核心原则：** 每个任务新子代理 + 两阶段审查（规格然后质量）= 高质量，快速迭代
+
+## 何时使用
+
+```
+有实现计划?
+    ↓ 是
+任务大多独立?
+    ↓ 是
+→ 子代理驱动开发
+
+否则 → 手动执行或先头脑风暴
+```
+
+**优势：**
+- 同一会话（无上下文切换）
+- 每个任务新子代理（无上下文污染）
+- 每个任务后两阶段审查：先规格符合性，再代码质量
+- 快速迭代（任务之间无人工等待）
+
+## 流程
+
+```
+读取计划，使用 Task 系统创建任务
+    ↓
+每个业务 Task:
+    ├── 派发 Implementer 子代理
+    │         ├── 阅读任务需求
+    │         ├── 遵循 TDD
+    │         ├── 实现功能
+    │         ├── Git commit
+    │         └── 更新 Task metadata
+    │
+    ├── 派发 Spec Reviewer 子代理
+    │         ├── 独立阅读代码
+    │         ├── 逐条验证需求
+    │         └── 检查遗漏或多余功能
+    │         ↓ 问题? → Implementer 修复 → 重新审查
+    │
+    ├── 派发 Code Quality Reviewer 子代理
+    │         ├── 审查代码质量
+    │         └── 分类问题：关键/重要/次要
+    │         ↓ 问题? → Implementer 修复 → 重新审查
+    │
+    └── 主窗口：TaskUpdate status=completed
+    ↓
+还有更多任务?
+    ↓ 是 → 下一个 Task
+    ↓ 否 → 校验 Task 执行
+```
+
+## 子代理派发模板
+
+### Implementer 子代理
+
+```
+Task tool (general-purpose):
+  description: "实现 Task N: {Task标题}"
+  prompt: |
+    你正在实现一个具体的开发任务。
+
+    ## 任务信息
+
+    {Task JSON 的完整 description 内容}
+
+    ## Task metadata 更新规范（必须遵守）
+
+    在执行过程中，你必须持续通过 TaskUpdate 更新 metadata：
+
+    1. 开始任务时：
+       TaskUpdate taskId={id} metadata={"started_at": "{当前时间}"}
+
+    2. 每次修改文件后：
+       TaskUpdate taskId={id} metadata={"files_modified": ["file1.py", "file2.py"]}
+
+    3. 遇到错误时（必须记录，包含解决方案）：
+       TaskUpdate taskId={id} metadata={"errors_encountered": ["错误描述 - 解决方案"]}
+       ⚠️ 如果你无法解决某个问题而选择跳过或简化，必须如实记录
+
+    4. 运行测试后：
+       TaskUpdate taskId={id} metadata={"test_results": "5/5 passed"}
+
+    5. 提交代码后：
+       TaskUpdate taskId={id} metadata={"git_commit": "{hash}", "commit_message": "{msg}"}
+
+    ## 执行要求
+
+    - 遵循 TDD：先写测试，再实现
+    - 每个有意义的变更都要提交
+    - 自审：完成后检查实现是否完整
+    - 如实记录：不要隐瞒错误或跳过的内容
+```
+
+### Spec Reviewer 子代理
+
+```
+Task tool (general-purpose):
+  description: "审查 Task N 的规格符合性"
+  prompt: |
+    你正在审查一个实现是否符合其规格。
+
+    ## 被请求的内容
+
+    {Task JSON 的完整 description 内容}
+
+    ## 实现者声称构建的内容
+
+    {Implementer 子代理的返回报告}
+
+    ## 关键：不要信任报告
+
+    实现者的报告可能不完整、不准确或过于乐观。你必须独立验证。
+
+    **要：** 阅读实际代码，逐行比较，检查声称但未实现的部分
+    **不要：** 相信报告，信任完整性声明
+
+    ## 输出格式
+
+    - ✅ 符合规格
+    - ❌ 发现问题：[具体列出，带 file:line 引用]
+```
+
+### Code Quality Reviewer 子代理
+
+```
+Task tool (general-purpose):
+  description: "审查 Task N 的代码质量"
+  prompt: |
+    你正在审查代码更改的生产就绪性。
+
+    ## 实现内容
+
+    {Implementer 报告}
+
+    ## 需求/计划
+
+    {Task description}
+
+    ## 审查清单
+
+    - 代码质量：关注点分离、错误处理、类型安全、DRY
+    - 架构：设计决策、可扩展性、性能、安全
+    - 测试：测试真实逻辑、边界覆盖、集成测试
+    - 生产就绪：向后兼容、文档、无明显bug
+
+    ## 输出格式
+
+    ### 优点
+    [具体说明做得好的地方]
+
+    ### 问题
+    - 关键（必须修复）：[Bug、安全问题]
+    - 重要（应该修复）：[架构问题、测试缺口]
+    - 次要（可以改进）：[代码风格]
+
+    ### 评估
+    可以合并？[是/否/修复后可以]
+```
+
+## 示例工作流
+
+```
+你: 我正在使用子代理驱动开发执行此计划。
+
+[调用 TaskList 获取所有任务]
+[找到第一个 pending Task]
+
+Task 1: Hook 安装脚本
+
+[派发 Implementer 子代理，包含完整任务 description]
+
+Implementer: "开始之前 - hook 应该安装在用户级还是系统级？"
+
+你: "用户级 (~/.config/vibe/hooks/)"
+
+Implementer: "好的。现在开始实现..."
+[稍后] Implementer:
+  - 实现了 install-hook 命令
+  - 添加了测试，5/5 通过
+  - 自审：发现遗漏了 --force 标志，已添加
+  - 已提交
+  - metadata 已更新
+
+[派发 Spec Reviewer]
+Spec Reviewer: ✅ 符合规格 - 所有需求满足
+
+[派发 Code Quality Reviewer]
+Code Reviewer: 优点：测试覆盖好。问题：无。通过。
+
+[TaskUpdate taskId=1 status=completed]
+
+Task 2: 恢复模式
+
+[派发 Implementer 子代理]
+
+Implementer:
+  - 添加了 verify/repair 模式
+  - 8/8 测试通过
+  - 已提交
+
+[派发 Spec Reviewer]
+Spec Reviewer: ❌ 问题：
+  - 遗漏：进度报告（规格说"每 100 项报告一次"）
+  - 多余：添加了 --json 标志（未请求）
+
+[Implementer 修复问题]
+Implementer: 移除了 --json 标志，添加了进度报告
+
+[Spec Reviewer 再次审查]
+Spec Reviewer: ✅ 现在符合规格
+
+[派发 Code Quality Reviewer]
+Code Reviewer: 问题（重要）：魔法数字（100）
+
+[Implementer 修复]
+Implementer: 提取了 PROGRESS_INTERVAL 常量
+
+[Code Reviewer 再次审查]
+Code Reviewer: ✅ 通过
+
+[TaskUpdate taskId=2 status=completed]
+
+...
+
+[所有业务 Task 完成后]
+[校验 Task 自动执行]
+[验证 design.md + metadata → 生成快照 → 标记完成]
+```
+
+## 危险信号
+
+**永远不要：**
+- 跳过审查（规格符合性或代码质量）
+- 带着未修复的问题继续
+- 并行派发多个实现子代理（冲突）
+- 让子代理读取计划文件（提供完整 description 代替）
+- 跳过 metadata 更新（校验 Task 需要这些信息）
+- 忽略子代理问题（在让他们继续之前回答）
+- 接受规格符合性的"差不多"（审查者发现问题 = 未完成）
+- **在规格符合性 ✅ 之前开始代码质量审查**（顺序错误）
+- 在任一审查有未解决问题时进入下一个任务
+
+**如果子代理提问：**
+- 清晰完整地回答
+- 如需要提供额外上下文
+- 不要催他们进入实现
+
+**如果审查者发现问题：**
+- Implementer（同一子代理）修复
+- 审查者再次审查
+- 重复直到通过
+- 不要跳过重新审查
+
+**如果子代理任务失败：**
+- 派发修复子代理，带具体指示
+- 不要手动修复（上下文污染）
+
+## 集成
+
+**必需的工作流 skills：**
+- **brainstorming** - 创建设计文档（design.md）
+- **writing-plans** - 创建此 skill 执行的计划（plan.md）
+
+**子代理应使用：**
+- **test-driven-development** - 子代理为每个任务遵循 TDD
--- a/.claude/skills/test-driven-development/SKILL.md
+++ b/.claude/skills/test-driven-development/SKILL.md
@ -0,0 +1,255 @@
+---
+name: test-driven-development
+description: 在实现任何功能或修复 bug 时使用，在写实现代码之前
+---
+
+# 测试驱动开发 (TDD)
+
+## 概述
+
+先写测试。看它失败。写最小代码通过测试。
+
+**核心原则：** 如果你没有看到测试失败，你就不知道它是否测试了正确的东西。
+
+**违反规则的字面意思就是违反规则的精神。**
+
+## 何时使用
+
+**总是：**
+- 新功能
+- Bug 修复
+- 重构
+- 行为变更
+
+**例外（需要用户确认）：**
+- 一次性原型
+- 生成的代码
+- 配置文件
+
+想着"就这一次跳过 TDD"？停下来。那是在找借口。
+
+## 铁律
+
+```
+没有失败的测试，就不能写生产代码
+```
+
+先写代码再写测试？删除它。重新开始。
+
+**没有例外：**
+- 不要把它作为"参考"保留
+- 不要在写测试时"调整"它
+- 不要看它
+- 删除就是删除
+
+从测试重新实现。就这样。
+
+## RED-GREEN-REFACTOR
+
+```
+RED（写失败测试）
+    ↓ 验证失败正确
+GREEN（最小代码）
+    ↓ 验证通过全绿
+REFACTOR（清理）
+    ↓ 保持绿色
+→ 下一个 → RED
+```
+
+### RED - 写失败的测试
+
+写一个最小的测试，展示应该发生什么。
+
+**好的示例：**
+```typescript
+test('重试失败操作 3 次', async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+  const result = await retryOperation(operation);
+
+  expect(result).toBe('success');
+  expect(attempts).toBe(3);
+});
+```
+清晰的名称，测试真实行为，只测一件事
+
+**坏的示例：**
+```typescript
+test('retry works', async () => {
+  const mock = jest.fn()
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce('success');
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(2);
+});
+```
+模糊的名称，测试 mock 而不是代码
+
+**要求：**
+- 一个行为
+- 清晰的名称
+- 真实代码（除非不可避免，否则不用 mock）
+
+### 验证 RED - 看它失败
+
+**强制执行。永远不要跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试失败（不是报错）
+- 失败消息是预期的
+- 因为功能缺失而失败（不是拼写错误）
+
+**测试通过了？** 你在测试已有行为。修复测试。
+
+**测试报错了？** 修复错误，重新运行直到它正确失败。
+
+### GREEN - 最小代码
+
+写最简单的代码通过测试。
+
+**好的示例：**
+```typescript
+async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (i === 2) throw e;
+    }
+  }
+  throw new Error('unreachable');
+}
+```
+刚好够通过
+
+**坏的示例：**
+```typescript
+async function retryOperation<T>(
+  fn: () => Promise<T>,
+  options?: {
+    maxRetries?: number;
+    backoff?: 'linear' | 'exponential';
+    onRetry?: (attempt: number) => void;
+  }
+): Promise<T> {
+  // YAGNI - 过度设计
+}
+```
+
+不要添加功能、重构其他代码，或"改进"超出测试范围的内容。
+
+### 验证 GREEN - 看它通过
+
+**强制执行。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试通过
+- 其他测试仍然通过
+- 输出干净（没有错误、警告）
+
+**测试失败？** 修复代码，不是测试。
+
+**其他测试失败？** 现在修复。
+
+### REFACTOR - 清理
+
+只有在绿色之后：
+- 移除重复
+- 改进名称
+- 提取辅助函数
+
+保持测试绿色。不要添加行为。
+
+### 重复
+
+下一个失败测试，测试下一个功能。
+
+## 好的测试
+
+| 质量 | 好 | 坏 |
+|------|----|----|
+| **最小** | 一件事。名称中有"和"？拆分它。 | `test('验证邮箱和域名和空格')` |
+| **清晰** | 名称描述行为 | `test('test1')` |
+| **展示意图** | 展示期望的 API | 隐藏代码应该做什么 |
+
+## 为什么顺序很重要
+
+**"我之后写测试来验证它能工作"**
+
+事后写的测试立即通过。立即通过什么都证明不了：
+- 可能测试了错误的东西
+- 可能测试的是实现，不是行为
+- 可能遗漏了你忘记的边界情况
+- 你从未看到它捕获 bug
+
+先测试强迫你看到测试失败，证明它确实在测试什么。
+
+## 常见借口
+
+| 借口 | 现实 |
+|------|------|
+| "太简单不需要测试" | 简单代码也会出错。测试只需 30 秒。 |
+| "我之后再测试" | 测试立即通过什么都证明不了。 |
+| "已经手动测试过了" | 临时 ≠ 系统化。没有记录，无法重新运行。 |
+| "删除 X 小时的工作太浪费" | 沉没成本谬误。保留不可信的代码才是浪费。 |
+| "TDD 太教条了，务实意味着灵活" | TDD 就是务实的：更快发现 bug，防止回归。 |
+| "事后测试能达到相同目的" | 不。事后测试回答"这做了什么？"先测试回答"这应该做什么？" |
+
+## 危险信号 - 停下来重新开始
+
+- 先写代码再写测试
+- 实现后才写测试
+- 测试立即通过
+- 无法解释测试为什么失败
+- 测试是"之后"添加的
+- 合理化"就这一次"
+- "我已经手动测试过了"
+- "保留作为参考"或"调整现有代码"
+
+**所有这些意味着：删除代码。用 TDD 重新开始。**
+
+## 验证清单
+
+完成工作前：
+
+- [ ] 每个新函数/方法都有测试
+- [ ] 在实现之前看到每个测试失败
+- [ ] 每个测试失败的原因是预期的（功能缺失，不是拼写错误）
+- [ ] 为每个测试写了最小代码通过
+- [ ] 所有测试通过
+- [ ] 输出干净（没有错误、警告）
+- [ ] 测试使用真实代码（mock 只在不可避免时使用）
+- [ ] 边界情况和错误都有覆盖
+
+无法勾选所有项？你跳过了 TDD。重新开始。
+
+## 卡住时
+
+| 问题 | 解决方案 |
+|------|----------|
+| 不知道如何测试 | 先写期望的 API。先写断言。问用户。 |
+| 测试太复杂 | 设计太复杂。简化接口。 |
+| 必须 mock 所有东西 | 代码耦合太紧。使用依赖注入。 |
+| 测试设置太大 | 提取辅助函数。仍然复杂？简化设计。 |
+
+## 最终规则
+
+```
+生产代码 → 测试存在并且先失败了
+否则 → 不是 TDD
+```
+
+没有用户许可不能有例外。
--- a/.claude/skills/writing-plans/SKILL.md
+++ b/.claude/skills/writing-plans/SKILL.md
@ -0,0 +1,143 @@
+---
+name: writing-plans
+description: 当有规格或需求的多步骤任务时使用，在接触代码之前
+---
+
+# 编写实现计划
+
+## 概述
+
+编写全面的实现计划，假设执行者对代码库零上下文且判断力有限。记录他们需要知道的一切：每个任务要接触哪些文件、代码、测试、可能需要检查的文档、如何测试。将整个计划作为小任务交付。DRY。YAGNI。TDD。频繁提交。
+
+假设执行者是技术熟练的开发者，但对我们的工具或问题领域几乎一无所知。假设他们不太擅长测试设计。
+
+**开始时宣布：** "我正在使用 writing-plans skill 创建实现计划。"
+
+**保存计划到：** `docs/plans/YYYY-MM-DD-<feature-name>-plan.md`
+
+## 小粒度任务
+
+**每个步骤是一个动作（2-5 分钟）：**
+- "写失败的测试" - 一步
+- "运行它确保它失败" - 一步
+- "实现最小代码使测试通过" - 一步
+- "运行测试确保它们通过" - 一步
+- "提交" - 一步
+
+## 计划文档头部
+
+**每个计划必须以此头部开始：**
+
+```markdown
+# [功能名称] 实现计划
+
+> **执行指令**：使用 `/vibe-execute` 命令启动自动执行流程。
+> 执行过程中会自动创建 Task 系统，派发子代理，执行校验。
+
+**目标**：[一句话描述要构建什么]
+
+**架构**：[2-3 句话描述方案]
+
+**技术栈**：[关键技术/库]
+
+---
+```
+
+## 任务结构
+
+```markdown
+### Task N: [组件名称]
+
+**文件：**
+- 创建: `exact/path/to/file.py`
+- 修改: `exact/path/to/existing.py:123-145`
+- 测试: `tests/exact/path/to/test.py`
+
+**Step 1: 写失败测试**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+**Step 2: 运行测试验证失败**
+
+运行: `pytest tests/path/test.py::test_name -v`
+预期: FAIL，提示 "function not defined"
+
+**Step 3: 写最小实现**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: 运行测试验证通过**
+
+运行: `pytest tests/path/test.py::test_name -v`
+预期: PASS
+
+**Step 5: 提交**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+
+---
+```
+
+## 关键原则
+
+- 始终使用精确的文件路径
+- 计划中包含完整代码（不是"添加验证逻辑"）
+- 精确的命令和预期输出
+- 引用相关 skills
+- DRY, YAGNI, TDD, 频繁提交
+
+## 执行交接
+
+保存计划后输出：
+
+```
+计划已完成并保存到 docs/plans/YYYY-MM-DD-<feature>-plan.md
+
+下一步：执行 /vibe-execute 开始子代理驱动执行。
+```
+
+## 完成标准
+
+```markdown
+## 完成标准
+
+1. 所有 Task 验收标准满足
+2. 所有测试通过
+3. 对照用户需求确认功能完整
+
+## 校验
+
+执行完成后，校验 Task 会自动：
+1. 对比 design.md 和所有 Task metadata
+2. 检测降级实现
+3. 运行完整测试套件
+4. 生成 Task 快照
+```
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|----------|
+| 模糊的文件路径 | 使用精确路径 `src/auth/login.py` |
+| "添加验证逻辑" | 提供完整的验证代码 |
+| 任务太大（>5 分钟） | 拆分成更小的步骤 |
+| 跳过测试验证步骤 | 每个 Step 都要验证 |
+
+## 危险信号 - 停下来
+
+- 任务描述超过一屏
+- 需要"理解"才能完成的任务
+- 没有明确的验证命令
+- 任务之间有隐含依赖
+
+**这些都意味着：任务需要进一步拆分。**