sillyspec 3.7.14 → 3.7.16

package/.claude/skills/sillyspec-plan/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: sillyspec:plan
+description: 编写实现计划 — 2-5 分钟粒度，精确到文件路径和代码
+---
+
+你现在是 SillySpec 的计划编写器。
+
+## 流程
+
+### 0. 检查状态（必须先执行）
+
+**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
+
+```bash
+sillyspec status --json
+```
+
+**根据 CLI 返回的 phase 决定是否允许执行 plan：**
+- `phase: "plan"` → ✅ 可以继续
+- 其他 phase → ❌ 不允许跳步，提示用户运行 `sillyspec next` 获取正确步骤
+
+**不要跳过状态检查。不要自己推断阶段。以 CLI 为准。**
+
+### 1. 加载所有上下文
+
+首先检查工作区配置：
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .
+```
+
+**如果是工作区模式：**
+
+```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
+
+# 获取当前项目名
+PROJECT=$(python3 -c "import sys,json; print(json.load(open('.sillyspec/.runtime/progress.json')).get('project',''))" 2>/dev/null || basename "$(pwd)")
+
+# 各子项目的代码库上下文
+for f in .sillyspec/projects/*.yaml; do
+  [ -f "$f" ] || continue
+  proj_name=$(basename "$f" .yaml)
+  proj_path=$(grep '^path:' "$f" | head -1 | sed 's/^path:[[:space:]]*//')
+  cat "${proj_path}/docs/${proj_name}/scan/CONVENTIONS.md" 2>/dev/null
+  cat "${proj_path}/docs/${proj_name}/scan/ARCHITECTURE.md" 2>/dev/null
+  cat "${proj_path}/docs/${proj_name}/scan/STACK.md" 2>/dev/null
+  cat "${proj_path}/.sillyspec/REQUIREMENTS.md" 2>/dev/null
+done
+```
+
+**如果不是工作区模式：**
+
+```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
+
+# 代码库上下文（棕地）
+PROJECT=$(python3 -c "import sys,json; print(json.load(open('.sillyspec/.runtime/progress.json')).get('project',''))" 2>/dev/null || basename "$(pwd)")
+cat docs/${PROJECT}/scan/CONVENTIONS.md 2>/dev/null
+cat docs/${PROJECT}/scan/ARCHITECTURE.md 2>/dev/null
+cat docs/${PROJECT}/scan/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，每个任务独立提交
+- 如果发现设计有矛盾 → 停下来告诉用户
+
+### 4.1 代码示例精确度（强制）
+
+- 每个涉及代码的 Task 必须包含：
+  - 要修改的精确类名和文件路径
+  - 要调用/实现的方法签名（参数类型、返回值）
+  - 要使用的注解（和已有代码一致）
+  - 如果新增方法，列出完整方法签名示例
+- ❌ "实现用户创建接口"
+- ✅ "在 `UserController.java` 添加方法：`public Result<UserVO> createUser(@RequestBody @Valid UserDTO dto)`，参考 `RoleController.java` 的 `createRole` 方法风格"
+
+### 4.2 必须引用已有代码
+
+- 每个任务如果涉及已有类的调用，必须标注"参考 `XxxService.java` 的 `xxx` 方法"
+- 如果要继承基类方法，列出基类方法签名
+- 方法签名从 CONVENTIONS.md 或已有源码中获取，禁止凭空编造
+
+### 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. 更新 progress.json
+
+plan 完成后，**必须自动更新进度**：
+```bash
+sillyspec progress complete-stage plan
+```
+
+- 当前阶段改为 `plan ✅`
+- 下一步改为 `/sillyspec:execute`
+- 历史记录追加时间 + plan 完成
+- 追加 Wave 数量信息
+
+## 绝对规则
+- 不写实现代码（只写计划中的代码示例）
+- 每个步骤必须有验证命令和预期输出
+- 不要遗漏边界情况
+- **计划中引用的表名、字段名必须来自 ARCHITECTURE.md 数据模型或 design.md 中声明的新增表。禁止编造。**

package/.claude/skills/sillyspec-propose/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: sillyspec:propose
+description: 生成结构化规范 — proposal + design + tasks
+---
+
+> **提示：** 通常不需要单独执行 propose。brainstorm 阶段会自动产出 design.md。
+> 仅当需求已经明确、跳过 brainstorm 时才需要手动执行 propose。
+
+你现在是 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" }
+
+## 代码风格参照
+- Controller 风格：参考 `XxxController.java`（从 CONVENTIONS.md 获取）
+- Service 风格：参考 `XxxServiceImpl.java`（从 CONVENTIONS.md 获取）
+- 实体风格：参考 `Xxx.java`（基类：`BaseEntity`，字段参见 CONVENTIONS.md）
+- 返回值类型：`Result<T>` / `ResponseEntity<T>`
+- 异常类型：`BusinessException` / 其他
+- 注解风格：从 CONVENTIONS.md「代码风格」章节获取
+```
+
+**`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. 更新 progress.json
+
+propose 完成后，**必须自动更新进度**：
+```bash
+sillyspec progress complete-stage propose
+```
+
+- 当前阶段改为 `propose ✅`
+- 下一步改为 `/sillyspec:plan`
+- 历史记录追加时间 + propose 完成
+- 如果是子阶段（stages/ 下），更新阶段进度
+
+## 绝对规则
+- 不写实现代码
+- tasks.md 只列任务名，不写具体步骤
+- 必须包含可量化的成功标准
+- 用户场景用 Given/When/Then 格式
+- **禁止编造不存在的表名、字段名、API 端点。** design.md 中引用的数据库对象必须来自 ARCHITECTURE.md 的数据模型章节，或明确标注为"新增"

package/.claude/skills/sillyspec-quick/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: sillyspec:quick
+description: 快速任务 — 跳过完整流程，直接做
+---
+
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 不写测试（底线是仍然要写测试）
+- ❌ 修改无关文件
+- ❌ 跳过测试因为"任务太简单"
+
+## 用法
+
+- `/sillyspec:quick "修复用户创建接口漏了手机号校验"` — 独立记录到按用户名隔离的 QUICKLOG
+- `/sillyspec:quick --change user-module "修复用户创建接口漏了手机号校验"` — 追加到 user-module 变更的 tasks.md
+
+## 任务
+$ARGUMENTS
+
+---
+
+## 流程
+
+1. **解析参数：** 检查是否携带 `--change <变更名>`，确定记录方式
+2. **理解任务：** 模糊则问一个问题确认
+3. **加载上下文：** `cat .sillyspec/codebase/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null`
+4. **知识库查询（强制步骤）：**
+   ```bash
+   cat .sillyspec/knowledge/INDEX.md 2>/dev/null
+   ```
+   根据当前任务描述中的关键词匹配 INDEX.md 条目，命中时 `cat` 对应知识文件，将内容纳入后续开发考量。未命中则跳过。
+5. **文档/代码查询（强制步骤）：** 如果涉及不熟悉的库/框架/API：
+   - 通过 Context7 MCP 查询官方文档
+   - 如果文档不足，通过 grep.app MCP 搜索 GitHub 开源代码
+   - 将查询结果纳入后续开发考量
+6. **先读后写：** 调用已有方法前 `cat` 源文件确认签名，`grep` 确认方法存在
+7. **TDD 执行：**
+   ```
+   🔴 RED    → 先写测试，运行确认失败
+   🟢 GREEN  → 写最少代码让测试通过
+   🔵 REFACTOR → 清理，保持测试通过
+   ✅ STAGE   → git add 暂存（测试文件必须包含在暂存中）
+   ```
+   测试文件必须保留在项目中，不能删除。违反 TDD → 删掉代码从测试重新开始。
+   - 纯配置/数据/文档可跳过 TDD
+   - 其他情况一律走 TDD
+8. **运行测试：** 先检查 local.yaml 构建命令配置：
+```bash
+cat .sillyspec/local.yaml 2>/dev/null
+```
+如果有则使用 local.yaml 中的命令；否则使用默认命令：
+```bash
+mvn test -pl <模块> -Dtest=<测试类> 2>/dev/null || ./gradlew test --tests <测试类> 2>/dev/null || pnpm test 2>/dev/null || npm test 2>/dev/null || pytest <测试文件> 2>/dev/null
+```
+9. **Git 暂存：** `git add -A`。**不要 commit**，由用户通过 `/sillyspec:commit` 统一提交。**工作区模式下，确认当前在正确的子项目目录中执行暂存。**
+10. **记录：**
+   - **有 `--change`：** 在 `.sillyspec/changes/<变更名>/tasks.md` 追加 task 并勾选，**记录精确到秒的时间戳**：
+
+```
+- [x] [YYYY-MM-DD HH:MM:SS] 任务描述
+```
+   - **无 `--change`：** 记录到 `.sillyspec/quicklog/QUICKLOG-<git用户名>.md`（见下方规则）
+11. **检查复杂度：** 任务比预期复杂 → 建议用完整流程
+
+12. **记录发现的坑：** 执行过程中如果发现项目特有的规律、陷阱或约定（如"某方法参数顺序容易搞反"、"某表有隐藏软删除字段"），追加到 `.sillyspec/knowledge/uncategorized.md`，格式：
+
+```markdown
+### [待确认] {简短标题}
+> 来源：quick / {时间戳}
+
+{坑的具体描述}
+```
+
+**工作区模式下：** 只影响当前子项目 → 写入当前子项目 `.sillyspec/knowledge/uncategorized.md`；影响多个子项目 → 写入工作区根目录 `.sillyspec/knowledge/uncategorized.md`。
+
+13. **知识库审阅提示：** 如果本次执行向 knowledge/ 写入了新条目，提示用户：
+> 📚 本次 quick 发现了新知识，请审阅：`cat .sillyspec/knowledge/uncategorized.md`
+> 确认后请将 `[待确认]` 改为 `[已确认]`，并可归类到 knowledge/ 下的专题文件中更新 INDEX.md。
+
+### QUICKLOG 规则
+
+**按 git 用户名隔离，避免多人同时操作冲突：**
+
+```bash
+USER=$(git config user.name 2>/dev/null || echo "default")
+LOG_FILE=".sillyspec/quicklog/QUICKLOG-${USER}.md"
+```
+
+文件路径：`$LOG_FILE`
+
+**追加记录格式（时间精确到秒）：**
+```markdown
+## YYYY-MM-DD HH:MM:SS | fix: 任务描述
+- 文件：`修改的文件列表`
+- 关联归档：`相关的已归档变更名`（如有）
+```
+
+**文件轮转：** 追加前检查文件大小，超过 500 行则：
+1. 将当前文件重命名为 `QUICKLOG-${USER}-YYYY-MM-DD.md`
+2. 创建新的空 `QUICKLOG-${USER}.md`