sillyspec 2.4.0

package/.claude/commands/sillyspec/plan.md

@@ -0,0 +1,238 @@
+---
+description: 编写实现计划 — 2-5 分钟粒度，精确到文件路径和代码
+argument-hint: "[计划名]"
+---
+
+你现在是 SillySpec 的计划编写器。
+
+## 流程
+
+### 0. 检查状态（必须先执行）
+
+**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
+
+```bash
+sillyspec status --json
+```
+
+**根据 CLI 返回的 phase 决定是否允许执行 plan：**
+- `phase: "plan"` → ✅ 可以继续
+- 其他 phase → ❌ 不允许跳步，提示用户运行 `sillyspec next` 获取正确步骤
+
+**不要跳过状态检查。不要自己推断阶段。以 CLI 为准。**
+
+### 1. 加载所有上下文
+
+首先检查工作区配置：
+
+```bash
+cat .sillyspec/config.yaml 2>/dev/null
+```
+
+**如果是工作区模式：**
+
+```bash
+# 工作区概览（了解所有子项目）
+cat .sillyspec/workspace/CODEBASE-OVERVIEW.md 2>/dev/null
+
+# 共享规范
+cat .sillyspec/shared/*.md 2>/dev/null
+
+# 规范（最近非归档变更）
+LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
+cat "$LATEST/proposal.md"
+cat "$LATEST/design.md"
+cat "$LATEST/tasks.md"
+cat "$LATEST/specs/requirements.md" 2>/dev/null
+
+# 各子项目的代码库上下文
+# 从 config.yaml 读取项目列表，对每个子项目：
+cat <子项目路径>/.sillyspec/codebase/CONVENTIONS.md 2>/dev/null
+cat <子项目路径>/.sillyspec/codebase/ARCHITECTURE.md 2>/dev/null
+cat <子项目路径>/.sillyspec/codebase/STACK.md 2>/dev/null
+
+# 项目需求
+cat <子项目路径>/.sillyspec/REQUIREMENTS.md 2>/dev/null
+```
+
+**如果不是工作区模式：**
+
+```bash
+# 规范（最近非归档变更）
+LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
+cat "$LATEST/proposal.md"
+cat "$LATEST/design.md"
+cat "$LATEST/tasks.md"
+cat "$LATEST/specs/requirements.md" 2>/dev/null
+
+# 代码库上下文（棕地）
+cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
+cat .sillyspec/codebase/ARCHITECTURE.md 2>/dev/null
+cat .sillyspec/codebase/STACK.md 2>/dev/null
+
+# 项目需求
+cat .sillyspec/REQUIREMENTS.md 2>/dev/null
+```
+
+### 1.5 锚定确认（必须完成）
+
+读取相关规范文件。对于存在的文件，确认理解；对于不存在的文件，标注跳过：
+
+```
+已读取并理解：
+- [x] proposal.md — 变更动机和范围
+- [x] design.md — 技术方案和文件变更（如果存在）
+- [x] tasks.md — 实现清单
+- [x] specs/requirements.md — 需求和场景（如果存在）
+
+所有可用上下文已加载，开始执行。
+```
+
+**文件不存在不是错误**。只确认实际存在的文件。不准跳过此步骤。
+
+### 2. 逐任务展开
+
+把 tasks.md 中每个 checkbox 展开为详细步骤。
+
+**工作区模式下，每个 Task 必须标注所属项目：**
+
+```markdown
+### Task 1: [frontend] 数据库 User 模型
+
+**项目：** frontend
+**文件：**
+```
+
+如果不是工作区模式，保持原有 Task 格式不变。
+
+**非工作区模式示例：**
+
+```markdown
+### Task 1: 数据库 User 模型
+
+**文件：**
+- 修改：`prisma/schema.prisma`
+- 新建：`prisma/migrations/xxx/migration.sql`
+- 测试：`tests/models/user.test.ts`
+
+**步骤：**
+- [ ] 写失败测试：
+  ```typescript
+  // tests/models/user.test.ts
+  import { prisma } from '@/lib/db'
+
+  describe('User model', () => {
+    it('should create user with hashed password', async () => {
+      const user = await prisma.user.create({
+        data: { email: 'test@test.com', passwordHash: 'hashed' }
+      })
+      expect(user.id).toBeDefined()
+      expect(user.passwordHash).toBe('hashed')
+    })
+  })
+  ```
+  运行：`pnpm test tests/models/user.test.ts` → 预期 FAIL（模型不存在）
+
+- [ ] 写最少代码让测试通过：
+  ```prisma
+  // prisma/schema.prisma
+  model User {
+    id           String   @id @default(cuid())
+    email        String   @unique
+    passwordHash String
+    createdAt    DateTime @default(now())
+  }
+  ```
+  运行：`npx prisma migrate dev --name add-user-model`
+  运行：`pnpm test tests/models/user.test.ts` → 预期 PASS
+
+- [ ] 运行全量测试 → 预期 ALL GREEN
+- [ ] git commit -m "feat: add User model"
+
+**验证命令：**
+`pnpm test tests/models/user.test.ts -v`
+```
+
+### 3. 标注执行顺序
+
+```markdown
+## 执行顺序
+
+**Wave 1**（并行，无依赖）：
+- Task 1: 数据库模型
+- Task 2: 邮件服务（独立模块）
+
+**Wave 2**（依赖 Wave 1）：
+- Task 3: 注册 API（需要 User 模型）
+
+**Wave 3**（依赖 Wave 2）：
+- Task 4: 验证流程（需要注册完成）
+```
+
+### 4. 计划原则
+
+**假设执行者是：** 熟练开发者，但对你项目零上下文、品味存疑、讨厌写测试。
+
+- 每个步骤 2-5 分钟可完成
+- 包含完整可运行的代码（不要写"添加验证逻辑"）
+- 包含精确文件路径（不要写"在适当位置"）
+- 包含运行命令和预期输出
+- 频繁 commit，每个任务独立提交
+- 如果发现设计有矛盾 → 停下来告诉用户
+
+### 5. 保存
+
+保存到 `.sillyspec/plans/YYYY-MM-DD-<change-name>.md`
+
+### 6. 自检门控（Hard Gate）
+
+- [ ] 每个 task 是否包含具体文件路径？
+- [ ] 每个 task 是否包含验证命令和预期输出？
+- [ ] 是否标注了 Wave 和执行顺序？
+- [ ] plan 是否与 design.md 的文件变更清单一致？
+
+**任何一项不通过 → 修正后重新检查。**
+
+### 脚本校验（硬验证）
+
+Hard Gate 自检通过后，运行校验脚本：
+
+```bash
+bash scripts/validate-plan.sh .sillyspec/changes/<当前变更目录>
+```
+
+- 脚本返回 0 → 自检通过，继续
+- 脚本返回非 0 → 根据提示修正后重新运行
+
+### 8. 最后说：
+
+**用 CLI 验证并获取下一步：**
+
+```bash
+sillyspec status --json
+```
+
+展示给用户：
+> 计划已保存到 `.sillyspec/plans/xxx.md`。
+> 下一步：
+
+```bash
+sillyspec next
+```
+
+将 CLI 返回的命令推荐给用户。**不要自己编建议。**
+
+### 9. 更新 STATE.md
+
+plan 完成后，**必须自动更新** `.sillyspec/STATE.md`：
+
+- 当前阶段改为 `plan ✅`
+- 下一步改为 `/sillyspec:execute`
+- 历史记录追加时间 + plan 完成
+- 追加 Wave 数量信息
+
+## 绝对规则
+- 不写实现代码（只写计划中的代码示例）
+- 每个步骤必须有验证命令和预期输出
+- 不要遗漏边界情况
+- **计划中引用的表名、字段名必须来自 ARCHITECTURE.md 数据模型或 design.md 中声明的新增表。禁止编造。**

package/.claude/commands/sillyspec/propose.md

@@ -0,0 +1,234 @@
+---
+description: 生成结构化规范 — proposal + design + tasks
+argument-hint: "[变更名]"
+---
+
+你现在是 SillySpec 的规范生成器。
+
+## 变更名称
+$ARGUMENTS
+
+## 流程
+
+### 0. 检查状态（必须先执行）
+
+**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
+
+```bash
+sillyspec status --json
+```
+
+**根据 CLI 返回的 phase 决定是否允许执行 propose：**
+- `phase: "propose"` → ✅ 可以继续
+- 其他 phase → ❌ 不允许跳步，提示用户运行 `sillyspec next` 获取正确步骤
+
+**不要跳过状态检查。不要自己推断阶段。以 CLI 为准。**
+
+### 1. 加载上下文
+
+读取相关文档：
+
+```bash
+# 检测是否是子阶段变更
+if [[ "$ARGUMENTS" == */stage-* ]]; then
+  MASTER_NAME="${ARGUMENTS%%/*}"
+  STAGE_NAME="${ARGUMENTS#*/}"
+  MASTER_DIR=".sillyspec/changes/$MASTER_NAME"
+  CHANGE_DIR="$MASTER_DIR/stages/$STAGE_NAME"
+else
+  CHANGE_DIR=".sillyspec/changes/$ARGUMENTS"
+fi
+
+# 如果存在 MASTER.md，读取主变更上下文
+cat .sillyspec/changes/*/MASTER.md 2>/dev/null
+
+# 最新设计文档
+ls -t .sillyspec/specs/*.md | head -1
+# 需求
+cat .sillyspec/REQUIREMENTS.md 2>/dev/null
+# 代码库约定（棕地）
+cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
+cat .sillyspec/codebase/ARCHITECTURE.md 2>/dev/null
+# 已有变更（排除子阶段）
+ls .sillyspec/changes/ | grep -v archive
+```
+
+如果是子阶段变更（如 `reward-punishment/stage-1`）：
+- 读取 MASTER.md 获取整体方向和技术决策
+- 读取 MASTER.md 中"经验记录"章节（前面阶段的踩坑经验）
+- 读取前面已完成阶段的设计文件（保持一致性）
+- 读取该阶段对应的原型分析结果
+- 规范文件保存到 `changes/<变更名>/stages/<stage-N>/`
+
+如果是普通变更，照原流程执行。
+
+如果没有设计文档 → 提示先运行 `/sillyspec:brainstorm`
+
+### 1.5 锚定确认（必须完成）
+
+读取相关规范文件。对于存在的文件，确认理解；对于不存在的文件，标注跳过：
+
+```
+已读取并理解：
+- [x] proposal.md — 变更动机和范围（如果存在）
+- [ ] design.md — 不存在（正常，将在本阶段生成）
+- [ ] specs/requirements.md — 不存在（正常，将在本阶段生成）
+
+所有可用上下文已加载，开始执行。
+```
+
+**文件不存在不是错误**。只确认实际存在的文件。不准跳过此步骤。
+
+### 2. 探索现有代码
+
+理解相关模块的当前实现，识别影响范围。
+
+### 3. 生成规范文件
+
+创建 `.sillyspec/changes/$ARGUMENTS/`，生成以下文件：
+
+**`proposal.md`** — 变更提案：
+```markdown
+# [change-name]
+
+## 动机
+为什么做这件事
+
+## 变更范围
+受影响的核心区域
+
+## 不在范围内
+明确排除的内容
+
+## 成功标准
+- [ ] 可量化的标准 1
+- [ ] 可量化的标准 2
+```
+
+**`specs/requirements.md`** — 需求清单：
+```markdown
+# 需求
+
+## 功能需求
+- [ ] REQ-001: 用户可以用邮箱注册
+- [ ] REQ-002: 注册后自动发送验证邮件
+
+## 用户场景
+### 场景 1: 新用户注册
+Given: 用户在注册页面
+When: 填写邮箱和密码并提交
+Then: 收到验证邮件，账户处于待验证状态
+
+### 场景 2: 邮箱验证
+Given: 用户收到验证邮件
+When: 点击验证链接
+Then: 账户激活，跳转到登录页
+
+## 非功能需求
+- 注册接口响应 < 500ms
+- 密码使用 bcrypt 哈希
+```
+
+**`design.md`** — 技术方案：
+```markdown
+# 技术设计
+
+## 架构决策
+- 使用 JWT 存储 session（而非 server-side session）
+- 理由：支持未来微服务拆分
+
+## 文件变更清单
+| 操作 | 文件 | 说明 |
+|---|---|---|
+| 新建 | `src/lib/auth.ts` | 认证核心逻辑 |
+| 新建 | `src/app/api/auth/register/route.ts` | 注册接口 |
+| 修改 | `prisma/schema.prisma` | 添加 User 模型 |
+
+## 数据模型
+[Prisma schema 或数据库表设计]
+
+## API 设计
+POST /api/auth/register
+Request: { email: string, password: string }
+Response: { userId: string, message: "verification email sent" }
+```
+
+**`tasks.md`** — 实现清单：
+```markdown
+# 实现清单
+
+## 准备
+- [ ] Task 0: 配置开发环境（依赖、环境变量）
+
+## 实现
+- [ ] Task 1: 数据库模型（User 表）
+- [ ] Task 2: 注册 API
+- [ ] Task 3: 邮件发送服务
+- [ ] Task 4: 邮箱验证流程
+
+## 收尾
+- [ ] Task 5: 错误处理和边界情况
+- [ ] Task 6: 集成测试
+```
+
+### 4. 展示关键文件
+
+展示 proposal.md 和 design.md 给用户审阅。tasks.md 只展示任务列表（细节在 plan 阶段展开）。
+
+### 5. 自检门控（Hard Gate）
+
+在展示文件给用户之前，**必须自检**：
+
+- [ ] proposal.md 是否包含"动机"、"变更范围"、"不在范围内"、"成功标准"四个章节？
+- [ ] design.md 是否包含"文件变更清单"表格？
+- [ ] specs/requirements.md 是否包含 Given/When/Then 格式的用户场景？
+- [ ] tasks.md 是否每个 task 都有文件路径？
+
+**任何一项不通过 → 修正后重新检查，不准跳过。**
+
+### 脚本校验（硬验证）
+
+Hard Gate 自检通过后，运行校验脚本：
+
+```bash
+bash scripts/validate-proposal.sh .sillyspec/changes/$ARGUMENTS
+```
+
+- 脚本返回 0 → 自检通过，继续展示文件
+- 脚本返回非 0 → 根据错误提示修正文件，重新运行脚本
+
+### 7. 最后说：
+
+**用 CLI 验证并获取下一步：**
+
+```bash
+sillyspec status --json
+```
+
+展示给用户：
+> 规范已生成到 `.sillyspec/changes/$ARGUMENTS/`。
+> 
+> 审阅 `proposal.md`（为什么做）和 `design.md`（怎么做）。
+> 下一步：
+
+```bash
+sillyspec next
+```
+
+将 CLI 返回的命令推荐给用户。**不要自己编建议。**
+
+### 8. 更新 STATE.md
+
+propose 完成后，**必须自动更新** `.sillyspec/STATE.md`：
+
+- 当前阶段改为 `propose ✅`
+- 下一步改为 `/sillyspec:plan`
+- 历史记录追加时间 + propose 完成
+- 如果是子阶段（stages/ 下），更新阶段进度
+
+## 绝对规则
+- 不写实现代码
+- tasks.md 只列任务名，不写具体步骤
+- 必须包含可量化的成功标准
+- 用户场景用 Given/When/Then 格式
+- **禁止编造不存在的表名、字段名、API 端点。** design.md 中引用的数据库对象必须来自 ARCHITECTURE.md 的数据模型章节，或明确标注为"新增"

package/.claude/commands/sillyspec/quick.md

@@ -0,0 +1,62 @@
+---
+description: 快速任务 — 跳过完整流程，直接做
+argument-hint: "[任务描述]"
+---
+
+---
+
+你现在是 SillySpec 快速模式。
+
+## 任务
+$ARGUMENTS
+
+## 适用场景
+- bug 修复
+- 改颜色、改文案、调样式
+- 加一行日志
+- 不需要规范管理的零碎任务
+
+## 流程
+
+### 1. 理解任务
+如果描述模糊 → 问一个问题确认。
+
+### 2. 加载最小上下文
+
+```bash
+cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
+cat .sillyspec/codebase/ARCHITECTURE.md 2>/dev/null
+```
+
+### 3. TDD 执行
+
+- 写失败测试 → 确认失败
+- 写最少代码 → 确认通过
+- 重构（如需要）
+
+### 4. 运行相关测试
+
+```bash
+pnpm test 2>/dev/null || npm test 2>/dev/null || pytest 2>/dev/null
+```
+
+确保没有引入回归。
+
+### 5. Git commit
+
+```bash
+git add -A
+git commit -m "fix: $ARGUMENTS"
+```
+
+### 最后说：
+
+> ✅ 完成：$ARGUMENTS
+> 修改文件：xxx, yyy
+> 新增测试：zzz
+> 提交：abc1234
+
+## 绝对规则
+- 仍然要写测试（这是底线）
+- 如果任务比预期复杂 → 停下来建议用完整流程
+- 不修改无关文件

package/.claude/commands/sillyspec/resume.md

@@ -0,0 +1,100 @@
+---
+description: 恢复工作 — 从中断处继续
+argument-hint: ""
+---
+
+你现在是 SillySpec 的恢复管理器。
+
+## 流程
+
+### 1. 读取 STATE.md
+
+```bash
+cat .sillyspec/STATE.md 2>/dev/null
+```
+
+### 2. 如果有 STATE.md
+
+直接从 STATE.md 中提取并展示：
+
+> 🔄 工作状态恢复
+>
+> **当前变更**：<名称>
+> **当前阶段**：<阶段名> <状态>
+> **下一步**：<命令>
+>
+> **阶段进度**（大模块）：
+> | 阶段 | 状态 |
+> |---|---|
+> | stage-1 列表页 | ✅ |
+> | stage-2 表单页 | 🔄 execute (2/6) |
+> | stage-3 详情页 | ⬜ |
+>
+> **关键决策**：
+> - xxx
+>
+> **下一步命令**：
+> `/sillyspec:execute reward-punishment/stage-2`
+
+**不需要执行 Git 操作或文件探测。** STATE.md 已经包含所有信息。
+
+然后问用户：直接继续，还是需要了解更多细节？
+
+### 3. 如果没有 STATE.md
+
+**不要直接说"没有记录"。** 自动探测项目状态：
+
+```bash
+# 检查主变更
+ls .sillyspec/changes/*/MASTER.md 2>/dev/null
+
+# 检查活跃变更
+ls .d .sillyspec/changes/*/ | grep -v archive | grep -v stages | tail -1 2>/dev/null
+
+# 检查子阶段
+ls .sillyspec/changes/*/stages/*/proposal.md 2>/dev/null
+
+# 检查代码库文档
+ls .sillyspec/codebase/*.md 2>/dev/null
+
+# 检查计划文件
+ls -t .sillyspec/plans/*.md | head -1 2>/dev/null
+
+# 检查需求/路线图
+cat .sillyspec/REQUIREMENTS.md 2>/dev/null
+cat .sillyspec/ROADMAP.md 2>/dev/null
+```
+
+#### 如果检测到 MASTER.md（大模块）
+
+检查各阶段状态并输出阶段进度表（同步骤 2 格式）。
+
+同时**创建 STATE.md**，将探测到的信息写入，后续命令执行时会自动更新。
+
+#### 如果是普通变更（无 MASTER.md）
+
+根据探测结果推断：
+
+| 探测到的文件 | 推断阶段 | 建议操作 |
+|---|---|---|
+| 无任何 .sillyspec/ 内容 | 未开始 | `/sillyspec:init` 或 `/sillyspec:scan` |
+| 有 SCAN-RAW.md 但缺失文档 | 扫描中断 | `/sillyspec:scan --deep`（断点续扫） |
+| 有 codebase/ 但文档不全（快扫 3 份缺失） | 快扫中断 | `/sillyspec:scan`（补全缺失文档） |
+| 有 codebase/ 7 份齐全但无 changes/ | 已扫描，未开始需求 | `/sillyspec:brainstorm "想法"` |
+| 有 REQUIREMENTS.md 但无 changes/ | 绿地项目，已有需求 | `/sillyspec:propose 变更名` |
+| changes/ 下有 proposal，无 tasks | 已有规范，待计划 | `/sillyspec:plan` |
+| changes/ 下有 tasks，有未完成 checkbox | 执行中 | `/sillyspec:execute` |
+| tasks.md 全部完成 | 待验证 | `/sillyspec:verify` |
+
+**扫描中断检测逻辑：**
+- 有 `SCAN-RAW.md` → 说明深度扫描预处理已完成，检查 7 份文档缺哪些
+- 有部分 codebase 文档（如只有 STACK 和 STRUCTURE）→ 说明快扫或深扫中断
+- 缺失的文档列表直接展示给用户，告知 `/sillyspec:scan` 会自动跳过已存在的文档
+
+**同时创建 STATE.md** 记录推断的状态。
+
+### 4. 关键原则
+
+- **不需要 HANDOFF.json**。STATE.md 是唯一的恢复数据源。
+- **STATE.md 不需要 Git 提交**。它是工作状态文件，可以加入 `.gitignore`。
+- **每次命令执行完自动更新 STATE.md**，不需要用户手动保存。