sillyspec 2.4.4 → 2.6.0

package/.claude/commands/sillyspec/init.md

@@ -1,20 +1,23 @@
-## 交互规范
+---
+description: 绿地项目初始化 — 深度提问、调研、需求文档、路线图
+argument-hint: "[项目名]"
+---
 
+## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 
-不要用编号列表让用户手动输入数字。
-如果需要自由输入，在 AskUserQuestion 的选项中加入"Other（自定义输入）"。
-
----
-
-你现在是 SillySpec 的项目初始化器。
+## 核心约束（必须遵守）
+- ❌ 写任何实现代码
+- ❌ 安装任何依赖
+- ❌ 一次问多个问题
+- ❌ 接受模糊需求（❌"好用" → ✅"首屏加载 < 2 秒"）
 
 ## 用户输入
 $ARGUMENTS
 
-## 核心流程
+---
 
-这是一个从零开始创建新项目的完整流程。你的目标是：**在开始写任何代码之前，把需求彻底搞清楚。**
+## 流程
 
 ### Step 1: 检查工作区模式
 
@@ -22,16 +25,7 @@ $ARGUMENTS
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-如果 config.yaml 存在且包含 `projects` → 工作区模式：
-1. 列出所有子项目：
-   检测到工作区模式，请选择要初始化的子项目：
-   > 1. frontend — 前端 - Vue3 + TypeScript
-   > 2. backend — 后端 - Node.js + PostgreSQL
-   > 3. 新建子项目（先运行 /sillyspec:workspace add）
-2. 用户选择后，**切换到该子项目目录**执行后续所有步骤
-3. 后续步骤中的所有文件路径相对于子项目目录
-
-否则 → 单项目模式，继续。
+有 `projects` → 工作区模式：AskUserQuestion 选子项目，切换到子项目目录执行。
 
 ### Step 2: 检查项目状态
 
@@ -39,128 +33,32 @@ cat .sillyspec/config.yaml 2>/dev/null
 ls -la
 ```
 
-如果目录已经有代码/配置文件 → 提示用 `/sillyspec:scan` 代替。
-如果是空目录 → 继续。
-
-### Step 3: 深度提问
+已有代码/配置 → 提示用 `/sillyspec:scan`。空目录 → 继续。
 
-**一次只问一个问题**，按以下顺序探索：
+### Step 3: 深度提问（一次一个问题）
 
-1. **项目本质** — 这个项目要解决什么问题？给谁用？
-2. **核心功能** — 用户能做的最重要的事情是什么？
-3. **技术偏好** — 有偏好的语言/框架吗？还是让我建议？
-4. **非功能需求** — 性能要求？安全要求？离线支持？多语言？
-5. **设计偏好** — 有参考产品吗？喜欢什么风格？
-6. **约束** — 预算？时间？团队规模？
-7. **不在范围内** — 明确什么不做
+按需探索（不是每个都要）：项目本质 → 核心功能 → 技术偏好 → 非功能需求 → 设计偏好 → 约束 → 不在范围内。
 
 ### Step 4: 技术选型（如需要）
 
-如果用户没有明确偏好，基于项目需求推荐 2-3 套技术栈，列出优劣：
-- 语言 + 框架 + 数据库 + 部署方案
-- 给出推荐和理由
-
-### Step 5: 可选调研
-
-如果用户同意，对关键技术选型做快速调研：
-- 选定框架的当前版本和生态状态
-- 已知的坑和替代方案
-- 依赖的第三方服务的稳定性
-
-### Step 6: 生成需求文档
-
-保存到 `.sillyspec/REQUIREMENTS.md`：
-
-```markdown
-# 需求文档
-
-## 项目概述
-[一句话描述]
+用户无明确偏好时，推荐 2-3 套技术栈并列优劣和推荐理由。可选快速调研选定框架的版本、生态、已知坑。
 
-## 目标用户
-[谁在用、在什么场景下用]
+### Step 5: 生成文档
 
-## 功能需求
-### P0 — 必须有
-- [ ] 需求 1
-- [ ] 需求 2
+**`REQUIREMENTS.md`：** 概述、目标用户、功能需求（P0/P1/P2）、非功能需求、不在范围内、技术选型表。
 
-### P1 — 应该有
-- [ ] 需求 3
+**`ROADMAP.md`：** Phase 分阶段路线图（目标 + 交付物）。
 
-### P2 — 有了更好
-- [ ] 需求 4
-
-## 非功能需求
-- 性能：xxx
-- 安全：xxx
-- 部署：xxx
-
-## 不在范围内
-- xxx
-- xxx
-
-## 技术选型
-| 层 | 选择 | 理由 |
-|---|---|---|
-| 前端 | React + TypeScript | xxx |
-| 后端 | xxx | xxx |
-| 数据库 | xxx | xxx |
-```
-
-### Step 7: 生成路线图：
-
-```markdown
-# 项目路线图
-
-## Phase 1: 基础骨架
-- 目标：可运行的最小版本
-- 交付物：项目结构 + 基础配置 + 首个可运行页面/接口
-
-## Phase 2: 核心功能
-- 目标：P0 功能全部可用
-- 交付物：xxx
-
-## Phase 3: 完善
-- 目标：P1 + 测试 + 打磨
-- 交付物：xxx
-```
-
-### Step 8: 生成 PROJECT.md
-
-保存到 `.sillyspec/PROJECT.md`：
-
-```markdown
-# PROJECT.md
-
-## 项目名：xxx
-## 一句话：xxx
-## 状态：已初始化，等待规划
-```
+**`PROJECT.md`：** 项目名、一句话描述、状态。
 
-### Step 9: Git 初始化
+### Step 6: Git 初始化
 
 ```bash
-git init
-git add .
-git commit -m "chore: sillyspec init - project initialized"
+git init && git add . && git commit -m "chore: sillyspec init - project initialized"
 ```
 
 ### 最后说：
 
 > ✅ 项目初始化完成！
->
-> 生成文件：
-> - `.sillyspec/PROJECT.md` — 项目概述
-> - `.sillyspec/REQUIREMENTS.md` — 需求文档
-> - `.sillyspec/ROADMAP.md` — 路线图
->
-> 下一步：
-> - 开始第一个功能：`/sillyspec:brainstorm "Phase 1: xxx"`
-> - 或修改需求：直接告诉我改什么
-
-## 绝对规则
-- 不写任何实现代码
-- 不安装任何依赖
-- 提问阶段一次一个问题
-- 需求必须具体，不能模糊（❌"好用" → ✅"首屏加载 < 2 秒"）
+> 生成文件：PROJECT.md、REQUIREMENTS.md、ROADMAP.md
+> 下一步：`/sillyspec:brainstorm "Phase 1: xxx"` 或直接告诉我改什么

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

@@ -1,233 +1,85 @@
-你现在是 SillySpec 的计划编写器。
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 
-## 流程
-
-### 0. 检查状态（必须先执行）
+## 核心约束（必须遵守）
+- ❌ 写实现代码（只写计划中的代码示例）
+- ❌ 每个步骤缺验证命令和预期输出
+- ❌ 编造表名、字段名（必须来自 ARCHITECTURE.md 或 design.md）
 
-**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
+## 状态检查（必须先执行）
 
 ```bash
 sillyspec status --json
 ```
 
-**根据 CLI 返回的 phase 决定是否允许执行 plan：**
-- `phase: "plan"` → ✅ 可以继续
-- 其他 phase → ❌ 不允许跳步，提示用户运行 `sillyspec next` 获取正确步骤
+- `phase: "plan"` → ✅ 继续
+- 其他 phase → 提示 `sillyspec next`
 
-**不要跳过状态检查。不要自己推断阶段。以 CLI 为准。**
+---
 
-### 1. 加载所有上下文
+## 流程
 
-首先检查工作区配置：
+### 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
-```
-
-**如果不是工作区模式：**
+**工作区模式：** 加载 CODEBASE-OVERVIEW.md + 共享规范 + 子项目的 CONVENTIONS/ARCHITECTURE/STACK + REQUIREMENTS.md。
 
+**单项目模式：**
 ```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"/{proposal,design,tasks}.md 2>/dev/null
 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/codebase/{CONVENTIONS,ARCHITECTURE,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 — 需求和场景（如果存在）
-
-所有可用上下文已加载，开始执行。
-```
-
-**文件不存在不是错误**。只确认实际存在的文件。不准跳过此步骤。
+确认实际存在的文件（proposal / design / tasks / requirements），不存在的标注跳过。
 
 ### 2. 逐任务展开
 
-把 tasks.md 中每个 checkbox 展开为详细步骤。
-
-**工作区模式下，每个 Task 必须标注所属项目：**
-
-```markdown
-### Task 1: [frontend] 数据库 User 模型
-
-**项目：** frontend
-**文件：**
-```
+把 tasks.md 每个 checkbox 展开为详细步骤。工作区模式下每个 Task 标注所属项目。
 
-如果不是工作区模式，保持原有 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`
-```
+**每个 Task 必须包含：**
+- 精确文件路径
+- **精确方法签名**（参数类型、返回值类型、注解）— ❌ "实现用户创建接口" → ✅ `public Result<UserVO> createUser(@RequestBody @Valid UserDTO dto)`，参考 `RoleController.createRole`
+- 完整可运行的代码示例（不写"添加验证逻辑"这种模糊描述）
+- 涉及已有类调用时，标注"参考 `XxxService.java` 的 `xxx` 方法"
+- 新增方法必须列出方法签名，方法签名必须来自已有代码风格或 design.md
+- 运行命令和预期输出
+- TDD 步骤：🔴 写失败测试 → 🟢 写最少代码 → 🔵 重构 → ✅ commit
 
 ### 3. 标注执行顺序
 
+按 Wave 分组，标注依赖关系：
 ```markdown
-## 执行顺序
-
-**Wave 1**（并行，无依赖）：
-- Task 1: 数据库模型
-- Task 2: 邮件服务（独立模块）
-
-**Wave 2**（依赖 Wave 1）：
-- Task 3: 注册 API（需要 User 模型）
-
-**Wave 3**（依赖 Wave 2）：
-- Task 4: 验证流程（需要注册完成）
+**Wave 1**（并行，无依赖）：Task 1, Task 2
+**Wave 2**（依赖 Wave 1）：Task 3
 ```
 
-### 4. 计划原则
-
-**假设执行者是：** 熟练开发者，但对你项目零上下文、品味存疑、讨厌写测试。
-
-- 每个步骤 2-5 分钟可完成
-- 包含完整可运行的代码（不要写"添加验证逻辑"）
-- 包含精确文件路径（不要写"在适当位置"）
-- 包含运行命令和预期输出
-- 频繁 commit，每个任务独立提交
-- 如果发现设计有矛盾 → 停下来告诉用户
-
-### 5. 保存
-
-保存到 `.sillyspec/plans/YYYY-MM-DD-<change-name>.md`
-
-### 6. 自检门控（Hard Gate）
+### 4. 保存
 
-- [ ] 每个 task 是否包含具体文件路径？
-- [ ] 每个 task 是否包含验证命令和预期输出？
-- [ ] 是否标注了 Wave 和执行顺序？
-- [ ] plan 是否与 design.md 的文件变更清单一致？
+保存到 `.sillyspec/changes/<变更名>/plan.md`
 
-**任何一项不通过 → 修正后重新检查。**
+### 5. 自检门控
 
-### 脚本校验（硬验证）
-
-Hard Gate 自检通过后，运行校验脚本：
-
-```bash
-bash scripts/validate-plan.sh .sillyspec/changes/<当前变更目录>
-```
-
-- 脚本返回 0 → 自检通过，继续
-- 脚本返回非 0 → 根据提示修正后重新运行
-
-### 8. 最后说：
-
-**用 CLI 验证并获取下一步：**
+- [ ] 每个 task 有具体文件路径？
+- [ ] 每个 task 有验证命令和预期输出？
+- [ ] 标注了 Wave 和执行顺序？
+- [ ] plan 与 design.md 文件变更清单一致？
 
 ```bash
-sillyspec status --json
+bash scripts/validate-plan.sh .sillyspec/changes/<当前变更目录> 2>/dev/null
 ```
 
-展示给用户：
-> 计划已保存到 `.sillyspec/plans/xxx.md`。
-> 下一步：
+### 6. 完成
 
 ```bash
-sillyspec next
+sillyspec status --json && sillyspec next
 ```
 
-将 CLI 返回的命令推荐给用户。**不要自己编建议。**
-
-### 9. 更新 STATE.md
-
-plan 完成后，**必须自动更新** `.sillyspec/STATE.md`：
-
-- 当前阶段改为 `plan ✅`
-- 下一步改为 `/sillyspec:execute`
-- 历史记录追加时间 + plan 完成
-- 追加 Wave 数量信息
-
-## 绝对规则
-- 不写实现代码（只写计划中的代码示例）
-- 每个步骤必须有验证命令和预期输出
-- 不要遗漏边界情况
-- **计划中引用的表名、字段名必须来自 ARCHITECTURE.md 数据模型或 design.md 中声明的新增表。禁止编造。**
+更新 `.sillyspec/STATE.md`：阶段改为 `plan ✅`，下一步 `/sillyspec:execute`。