sillyspec 2.5.0 → 2.6.0

package/.claude/commands/sillyspec/archive.md

@@ -3,7 +3,9 @@
 
 ## 核心约束（必须遵守）
 - ❌ 未经验证就归档（必须先确认验证通过）
+- ❌ 未勾选的 checkbox 未告知用户就归档
 - ❌ 归档后留下活跃变更的残留状态
+- ❌ 覆盖已存在的归档目录
 
 ## 变更名称
 $ARGUMENTS
@@ -12,16 +14,49 @@ $ARGUMENTS
 
 ## 流程
 
-1. **确认验证通过：** 检查是否执行过 verify，没有则提示 `/sillyspec:verify`
-2. **展示归档内容：** 变更目录名、文件列表、生成总结
-3. **用户确认：** AskUserQuestion 确认归档或取消
-4. **执行归档：** 移动到 `.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/`
-5. **更新 tasks.md：** 确保所有 checkbox 勾选
-6. **更新 ROADMAP.md**（如存在）：标记对应 Phase 已完成
-7. **Git 提交：** `git add .sillyspec/ && git commit -m "docs: archive sillyspec change <change-name>"`
+### 1. 前置检查（门禁）
 
-### 最后说：
+读取 `.sillyspec/changes/<change-name>/` 下所有必要文件，逐项检查：
+
+- [ ] **verify 状态：** 检查是否有验证记录，无则提示先执行 `/sillyspec:verify`
+- [ ] **文件完整性：** 检查 `proposal.md` 和 `design.md` 是否存在，缺失则警告
+- [ ] **任务完成度：** 读取 `tasks.md`，统计已完成/未完成任务数。**有未完成的 → 用 AskUserQuestion 询问：**
+  - ① 继续归档（未完成任务将被标记完成）
+  - ② 取消，回去完成任务
+
+> 任一门禁不通过且用户选择取消 → 终止流程。
+
+### 2. 展示归档清单
+
+展示即将归档的内容摘要：
+- 变更目录名
+- 包含的文件列表
+- 任务完成统计（✅ 已完成 / ⬜ 未完成）
+- 一句话总结本次变更
+
+### 3. Spec 沉淀
+
+将 `.sillyspec/changes/<change-name>/specs/` 下的设计文档**复制到 `.sillyspec/specs/` 主目录**，确保已完成的设计规范可被后续变更参考。如目标已存在同名文件则跳过并提示。
 
-> ✅ 变更 `<change-name>` 已归档。继续：`/sillyspec:brainstorm "新想法"`
+### 4. 用户确认
+
+用 AskUserQuestion 让用户确认：
+- ① 确认归档
+- ② 取消
+
+### 5. 执行归档
+
+- 目标路径：`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/`
+- **检查目标路径是否已存在**，存在则中止并报错，防止覆盖
+- 移动变更目录到归档路径
+
+### 6. 归档后更新
+
+- **tasks.md：** 确保所有 checkbox 都已勾选 `[x]`
+- **ROADMAP.md**（如存在）：标记对应 Phase 已完成
+- **STATE.md：** 清除当前变更信息，历史记录追加归档完成
+- **Git 提交：** `git add .sillyspec/ && git commit -m "docs: archive sillyspec change <change-name>"`
+
+### 最后说：
 
-更新 `.sillyspec/STATE.md`：清除当前变更信息，历史记录追加归档完成。
+> ✅ 变更 `<change-name>` 已归档到 `archive/YYYY-MM-DD-<change-name>/`。继续：`/sillyspec:brainstorm "新想法"`

package/.claude/commands/sillyspec/brainstorm.md

@@ -1,3 +1,8 @@
+---
+description: 需求探索 — 结构化头脑风暴，生成设计文档（创建性工作前必用）
+argument-hint: "[需求或想法描述]"
+---
+
 ## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 

package/.claude/commands/sillyspec/continue.md

@@ -1,3 +1,8 @@
+---
+description: 自动判断并执行下一步
+argument-hint: ""
+---
+
 ## 核心约束（必须遵守）
 - ❌ 跳过自动判断，直接执行某个阶段
 

package/.claude/commands/sillyspec/execute.md

@@ -36,7 +36,7 @@ cat .sillyspec/config.yaml 2>/dev/null
 
 **单项目模式：**
 ```bash
-PLAN=$(ls -t .sillyspec/plans/*.md | head -1); cat "$PLAN"
+PLAN=$(ls -t .sillyspec/changes/*/plan.md 2>/dev/null | head -1); cat "$PLAN"
 LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
 cat "$LATEST"/{tasks,design}.md 2>/dev/null
 cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
@@ -59,13 +59,17 @@ cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
 
 ## 执行策略
 
-### 有 subagent 能力时（推荐）
+用 AskUserQuestion 询问用户选择执行模式：
+1. 串行执行 — 当前会话逐任务执行，适合简单变更
+2. 子代理并行 — 每个 Task 启动独立子代理，适合多任务独立变更（需要 subagent 能力）
+
+选择子代理模式时：
 1. 按计划的 Wave 分组
 2. 每个 Task 启动独立子代理（不继承主 session 历史）
-3. 子代理上下文：任务描述 + TDD 纪律 + 精确文件路径 + 相关约定
+3. 子代理上下文：任务描述 + TDD 纪律 + 精确文件路径 + 相关约定 + **要修改文件的当前源码** + **被调用类的源码**
 
-### 无 subagent 时
-当前会话逐任务串行执行。
+选择串行模式时：
+当前会话逐任务串行执行，每完成一个任务展示结果并等待用户确认。
 
 ## 每个任务的 TDD 铁律
 
@@ -80,7 +84,12 @@ cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
 
 **违反 TDD → 删掉代码从测试重新开始。例外（需人工确认）：** 抛弃型原型、生成代码、配置文件。
 
-## 写代码前必须读取现有源码（防幻觉）
+## 写代码前必须读取现有源码（先读后写）
+
+**⛔ 铁律：**
+- 没有读过相关源文件，不允许写任何代码
+- 方法签名必须来自已有代码或 plan 中的明确定义，禁止凭空编造
+- 调用已有方法时，必须先 `cat` 源文件确认方法签名（参数、返回值、异常）
 
 ```bash
 cat .sillyspec/codebase/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null

package/.claude/commands/sillyspec/explore.md

@@ -1,3 +1,8 @@
+---
+description: 自由思考模式 — 讨论、画图、调研，不写代码
+argument-hint: "[探索主题]"
+---
+
 ## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 

package/.claude/commands/sillyspec/export.md

@@ -1,3 +1,8 @@
+---
+description: 导出成功方案为可复用模板
+argument-hint: "<change-name> [--to <path>]"
+---
+
 ## 核心约束（必须遵守）
 - ❌ 修改任何文件（只读）
 

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

@@ -1,3 +1,8 @@
+---
+description: 绿地项目初始化 — 深度提问、调研、需求文档、路线图
+argument-hint: "[项目名]"
+---
+
 ## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 

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

@@ -46,7 +46,10 @@ cat .sillyspec/REQUIREMENTS.md 2>/dev/null
 
 **每个 Task 必须包含：**
 - 精确文件路径
+- **精确方法签名**（参数类型、返回值类型、注解）— ❌ "实现用户创建接口" → ✅ `public Result<UserVO> createUser(@RequestBody @Valid UserDTO dto)`，参考 `RoleController.createRole`
 - 完整可运行的代码示例（不写"添加验证逻辑"这种模糊描述）
+- 涉及已有类调用时，标注"参考 `XxxService.java` 的 `xxx` 方法"
+- 新增方法必须列出方法签名，方法签名必须来自已有代码风格或 design.md
 - 运行命令和预期输出
 - TDD 步骤：🔴 写失败测试 → 🟢 写最少代码 → 🔵 重构 → ✅ commit
 
@@ -60,7 +63,7 @@ cat .sillyspec/REQUIREMENTS.md 2>/dev/null
 
 ### 4. 保存
 
-保存到 `.sillyspec/plans/YYYY-MM-DD-<change-name>.md`
+保存到 `.sillyspec/changes/<变更名>/plan.md`
 
 ### 5. 自检门控
 

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

@@ -51,7 +51,7 @@ ls .sillyspec/changes/ | grep -v archive
 
 **`specs/requirements.md`：** 功能需求（REQ-001 格式）、Given/When/Then 用户场景、非功能需求
 
-**`design.md`：** 架构决策及理由、文件变更清单表格、数据模型、API 设计
+**`design.md`：** 架构决策及理由、文件变更清单表格、数据模型、API 设计、**代码风格参照**（参考已有的 Controller/Service/Entity 源文件，标注返回值类型、异常类型、注解风格）
 
 **`tasks.md`：** 准备 → 实现 → 收尾的任务列表（每个 task 标注文件路径）
 

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

@@ -1,3 +1,8 @@
+---
+description: 快速任务 — 跳过完整流程，直接做
+argument-hint: "[任务描述]"
+---
+
 ## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 

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

@@ -23,7 +23,7 @@ cat .sillyspec/STATE.md 2>/dev/null
 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 .sillyspec/plans/*.md .sillyspec/{REQUIREMENTS,ROADMAP}.md 2>/dev/null
+ls .sillyspec/codebase/*.md .sillyspec/changes/*/plan.md .sillyspec/{REQUIREMENTS,ROADMAP}.md 2>/dev/null
 ```
 
 **探测结果推断：**

package/.claude/commands/sillyspec/scan.md

@@ -163,6 +163,19 @@ find . -name "*.java" -not -path "*/{node_modules,.git}/*" | xargs grep -l "@Map
 
 无基类 → 写"本项目没有实体基类"。
 
+### D. 代码风格深度提取
+
+读取 2-3 个典型的 Controller、Service、ServiceImpl、Entity 源文件，提取具体风格（从源码提取，禁止编造）：
+
+1. **注解风格**：Controller 用 `@RestController` 还是 `@Controller`？方法用什么映射注解？参数校验方式？
+2. **返回值约定**：统一返回 `Result<T>` / `ResponseEntity<T>` / 其他？
+3. **异常处理**：用什么异常类？有没有全局异常处理器？
+4. **Service 层约定**：实现类命名、是否继承基类、基类通用方法、事务注解用法
+5. **实体/POJO 风格**：是否继承基类、Lombok 用法、ID 生成策略、`@TableId`
+6. **Mapper/DAO 风格**：XML Mapper 还是注解？有没有通用 Mapper 基类？
+
+将以上信息写入 CONVENTIONS.md「代码风格」章节。非 Java 项目参考同等概念提取。前端-only 项目写"不适用"。
+
 ---
 
 ## 深度扫描

package/.claude/commands/sillyspec/status.md

@@ -1,3 +1,8 @@
+---
+description: 查看项目进度和状态
+argument-hint: ""
+---
+
 ## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 

package/.claude/commands/sillyspec/verify.md

@@ -1,3 +1,8 @@
+---
+description: 验证实现 — 对照规范检查 + 测试套件
+argument-hint: "[可选：指定验证范围]"
+---
+
 ## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 

package/.claude/commands/sillyspec/workspace.md

@@ -1,3 +1,8 @@
+---
+description: 工作区管理 — 初始化、管理多项目工作区，查看子项目状态
+argument-hint: "[可选：add/remove/status/info]"
+---
+
 ## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "type": "module",
   "bin": {

package/src/init.js

@@ -175,20 +175,16 @@ function isTTY() {
 
 async function doInstall(projectDir, tools, isWorkspace, subprojects = []) {
   // 创建基础目录
-  const dirs = [
-    '.sillyspec/codebase',
-    '.sillyspec/changes/archive',
-    '.sillyspec/plans',
-    '.sillyspec/specs',
-    '.sillyspec/phases',
-  ];
+  // 不预创建子目录，由各命令按需创建
+  // .sillyspec/codebase/    → scan
+  // .sillyspec/changes/     → brainstorm/propose
+  // .sillyspec/changes/archive/ → archive
+  // .sillyspec/plans/        → plan
+  // .sillyspec/specs/        → propose
   if (isWorkspace) {
-    dirs.push('.sillyspec/shared', '.sillyspec/workspace');
+    mkdirSync(join(projectDir, '.sillyspec', 'shared'), { recursive: true });
+    mkdirSync(join(projectDir, '.sillyspec', 'workspace'), { recursive: true });
   }
-  for (const d of dirs) {
-    mkdirSync(join(projectDir, d), { recursive: true });
-  }
-  mkdirSync(join(homedir(), '.sillyspec', 'templates'), { recursive: true });
 
   // .gitignore
   const gitignorePath = join(projectDir, '.gitignore');

package/templates/archive.md

@@ -3,7 +3,9 @@
 
 ## 核心约束（必须遵守）
 - ❌ 未经验证就归档（必须先确认验证通过）
+- ❌ 未勾选的 checkbox 未告知用户就归档
 - ❌ 归档后留下活跃变更的残留状态
+- ❌ 覆盖已存在的归档目录
 
 ## 变更名称
 $ARGUMENTS
@@ -12,16 +14,49 @@ $ARGUMENTS
 
 ## 流程
 
-1. **确认验证通过：** 检查是否执行过 verify，没有则提示 `/sillyspec:verify`
-2. **展示归档内容：** 变更目录名、文件列表、生成总结
-3. **用户确认：** AskUserQuestion 确认归档或取消
-4. **执行归档：** 移动到 `.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/`
-5. **更新 tasks.md：** 确保所有 checkbox 勾选
-6. **更新 ROADMAP.md**（如存在）：标记对应 Phase 已完成
-7. **Git 提交：** `git add .sillyspec/ && git commit -m "docs: archive sillyspec change <change-name>"`
+### 1. 前置检查（门禁）
 
-### 最后说：
+读取 `.sillyspec/changes/<change-name>/` 下所有必要文件，逐项检查：
+
+- [ ] **verify 状态：** 检查是否有验证记录，无则提示先执行 `/sillyspec:verify`
+- [ ] **文件完整性：** 检查 `proposal.md` 和 `design.md` 是否存在，缺失则警告
+- [ ] **任务完成度：** 读取 `tasks.md`，统计已完成/未完成任务数。**有未完成的 → 用 AskUserQuestion 询问：**
+  - ① 继续归档（未完成任务将被标记完成）
+  - ② 取消，回去完成任务
+
+> 任一门禁不通过且用户选择取消 → 终止流程。
+
+### 2. 展示归档清单
+
+展示即将归档的内容摘要：
+- 变更目录名
+- 包含的文件列表
+- 任务完成统计（✅ 已完成 / ⬜ 未完成）
+- 一句话总结本次变更
+
+### 3. Spec 沉淀
+
+将 `.sillyspec/changes/<change-name>/specs/` 下的设计文档**复制到 `.sillyspec/specs/` 主目录**，确保已完成的设计规范可被后续变更参考。如目标已存在同名文件则跳过并提示。
 
-> ✅ 变更 `<change-name>` 已归档。继续：`/sillyspec:brainstorm "新想法"`
+### 4. 用户确认
+
+用 AskUserQuestion 让用户确认：
+- ① 确认归档
+- ② 取消
+
+### 5. 执行归档
+
+- 目标路径：`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/`
+- **检查目标路径是否已存在**，存在则中止并报错，防止覆盖
+- 移动变更目录到归档路径
+
+### 6. 归档后更新
+
+- **tasks.md：** 确保所有 checkbox 都已勾选 `[x]`
+- **ROADMAP.md**（如存在）：标记对应 Phase 已完成
+- **STATE.md：** 清除当前变更信息，历史记录追加归档完成
+- **Git 提交：** `git add .sillyspec/ && git commit -m "docs: archive sillyspec change <change-name>"`
+
+### 最后说：
 
-更新 `.sillyspec/STATE.md`：清除当前变更信息，历史记录追加归档完成。
+> ✅ 变更 `<change-name>` 已归档到 `archive/YYYY-MM-DD-<change-name>/`。继续：`/sillyspec:brainstorm "新想法"`

package/templates/execute.md

@@ -36,7 +36,7 @@ cat .sillyspec/config.yaml 2>/dev/null
 
 **单项目模式：**
 ```bash
-PLAN=$(ls -t .sillyspec/plans/*.md | head -1); cat "$PLAN"
+PLAN=$(ls -t .sillyspec/changes/*/plan.md 2>/dev/null | head -1); cat "$PLAN"
 LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
 cat "$LATEST"/{tasks,design}.md 2>/dev/null
 cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
@@ -59,13 +59,17 @@ cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
 
 ## 执行策略
 
-### 有 subagent 能力时（推荐）
+用 AskUserQuestion 询问用户选择执行模式：
+1. 串行执行 — 当前会话逐任务执行，适合简单变更
+2. 子代理并行 — 每个 Task 启动独立子代理，适合多任务独立变更（需要 subagent 能力）
+
+选择子代理模式时：
 1. 按计划的 Wave 分组
 2. 每个 Task 启动独立子代理（不继承主 session 历史）
-3. 子代理上下文：任务描述 + TDD 纪律 + 精确文件路径 + 相关约定
+3. 子代理上下文：任务描述 + TDD 纪律 + 精确文件路径 + 相关约定 + **要修改文件的当前源码** + **被调用类的源码**
 
-### 无 subagent 时
-当前会话逐任务串行执行。
+选择串行模式时：
+当前会话逐任务串行执行，每完成一个任务展示结果并等待用户确认。
 
 ## 每个任务的 TDD 铁律
 
@@ -80,7 +84,12 @@ cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
 
 **违反 TDD → 删掉代码从测试重新开始。例外（需人工确认）：** 抛弃型原型、生成代码、配置文件。
 
-## 写代码前必须读取现有源码（防幻觉）
+## 写代码前必须读取现有源码（先读后写）
+
+**⛔ 铁律：**
+- 没有读过相关源文件，不允许写任何代码
+- 方法签名必须来自已有代码或 plan 中的明确定义，禁止凭空编造
+- 调用已有方法时，必须先 `cat` 源文件确认方法签名（参数、返回值、异常）
 
 ```bash
 cat .sillyspec/codebase/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null

package/templates/plan.md

@@ -46,7 +46,10 @@ cat .sillyspec/REQUIREMENTS.md 2>/dev/null
 
 **每个 Task 必须包含：**
 - 精确文件路径
+- **精确方法签名**（参数类型、返回值类型、注解）— ❌ "实现用户创建接口" → ✅ `public Result<UserVO> createUser(@RequestBody @Valid UserDTO dto)`，参考 `RoleController.createRole`
 - 完整可运行的代码示例（不写"添加验证逻辑"这种模糊描述）
+- 涉及已有类调用时，标注"参考 `XxxService.java` 的 `xxx` 方法"
+- 新增方法必须列出方法签名，方法签名必须来自已有代码风格或 design.md
 - 运行命令和预期输出
 - TDD 步骤：🔴 写失败测试 → 🟢 写最少代码 → 🔵 重构 → ✅ commit
 
@@ -60,7 +63,7 @@ cat .sillyspec/REQUIREMENTS.md 2>/dev/null
 
 ### 4. 保存
 
-保存到 `.sillyspec/plans/YYYY-MM-DD-<change-name>.md`
+保存到 `.sillyspec/changes/<变更名>/plan.md`
 
 ### 5. 自检门控
 

package/templates/propose.md

@@ -51,7 +51,7 @@ ls .sillyspec/changes/ | grep -v archive
 
 **`specs/requirements.md`：** 功能需求（REQ-001 格式）、Given/When/Then 用户场景、非功能需求
 
-**`design.md`：** 架构决策及理由、文件变更清单表格、数据模型、API 设计
+**`design.md`：** 架构决策及理由、文件变更清单表格、数据模型、API 设计、**代码风格参照**（参考已有的 Controller/Service/Entity 源文件，标注返回值类型、异常类型、注解风格）
 
 **`tasks.md`：** 准备 → 实现 → 收尾的任务列表（每个 task 标注文件路径）
 

package/templates/resume.md

@@ -23,7 +23,7 @@ cat .sillyspec/STATE.md 2>/dev/null
 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 .sillyspec/plans/*.md .sillyspec/{REQUIREMENTS,ROADMAP}.md 2>/dev/null
+ls .sillyspec/codebase/*.md .sillyspec/changes/*/plan.md .sillyspec/{REQUIREMENTS,ROADMAP}.md 2>/dev/null
 ```
 
 **探测结果推断：**

package/templates/scan.md

@@ -163,6 +163,19 @@ find . -name "*.java" -not -path "*/{node_modules,.git}/*" | xargs grep -l "@Map
 
 无基类 → 写"本项目没有实体基类"。
 
+### D. 代码风格深度提取
+
+读取 2-3 个典型的 Controller、Service、ServiceImpl、Entity 源文件，提取具体风格（从源码提取，禁止编造）：
+
+1. **注解风格**：Controller 用 `@RestController` 还是 `@Controller`？方法用什么映射注解？参数校验方式？
+2. **返回值约定**：统一返回 `Result<T>` / `ResponseEntity<T>` / 其他？
+3. **异常处理**：用什么异常类？有没有全局异常处理器？
+4. **Service 层约定**：实现类命名、是否继承基类、基类通用方法、事务注解用法
+5. **实体/POJO 风格**：是否继承基类、Lombok 用法、ID 生成策略、`@TableId`
+6. **Mapper/DAO 风格**：XML Mapper 还是注解？有没有通用 Mapper 基类？
+
+将以上信息写入 CONVENTIONS.md「代码风格」章节。非 Java 项目参考同等概念提取。前端-only 项目写"不适用"。
+
 ---
 
 ## 深度扫描