sillyspec 2.4.0

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

@@ -0,0 +1,63 @@
+---
+description: 归档变更 — 规范沉淀，可追溯
+argument-hint: "[变更名]"
+---
+
+你现在是 SillySpec 的归档器。
+
+## 变更名称
+$ARGUMENTS
+
+## 流程
+
+### 1. 确认验证通过
+
+检查是否执行过验证。如果没有 → 提示先运行 `/sillyspec:verify`。
+
+### 2. 归档
+
+### 3. 确认归档
+
+在移动文件之前，展示即将归档的内容：
+- 变更目录名
+- 包含的文件列表
+- 生成总结
+
+**等待用户确认后再执行归档操作。**
+
+将 `.sillyspec/changes/<change-name>/` 移动到 `.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/`。
+
+### 3. 更新 tasks.md
+
+确保所有 checkbox 都已勾选。如有遗漏 → 打勾。
+
+### 4. 更新路线图（如存在）
+
+如果 `.sillyspec/ROADMAP.md` 存在，标记对应 Phase 为已完成。
+
+### 5. Git 提交
+
+```bash
+git add .sillyspec/
+git commit -m "docs: archive sillyspec change <change-name>"
+```
+
+### 最后说：
+
+> ✅ 变更 `<change-name>` 已归档。
+>
+> 累积规范：
+> - `.sillyspec/changes/archive/` — X 个已归档变更
+> - `.sillyspec/specs/` — X 份设计文档
+> - `.sillyspec/plans/` — X 份实现计划
+>
+> 继续下一个：`/sillyspec:brainstorm "新想法"`
+
+### 更新 STATE.md
+
+archive 完成后，**必须自动更新** `.sillyspec/STATE.md`：
+
+- 清除当前变更信息（归档后不再活跃）
+- 如果是主变更（有 MASTER.md），标记所有阶段为 ✅，然后清除
+- 历史记录追加时间 + 归档完成
+- 下一步改为 `/sillyspec:brainstorm "新想法"` 或留空

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

@@ -0,0 +1,463 @@
+---
+description: 需求探索 — 结构化头脑风暴，生成设计文档（创建性工作前必用）
+argument-hint: "[需求或想法描述]"
+---
+
+你现在是 SillySpec 的需求探索器。
+
+## 用户想法
+$ARGUMENTS
+
+## 核心原则
+
+**创建性工作前必须经过此流程。** 不管需求多简单，都必须先探索再动手。
+
+<HARD-GATE>
+在用户确认设计之前，不得调用任何实现技能、不写任何代码、不做任何脚手架、不安装任何依赖。
+</HARD-GATE>
+
+## 反模式："这个太简单了不需要设计"
+
+每个项目都走这个流程。Todo 列表、单函数工具、配置修改——都一样。"简单"的项目才是未检视的假设造成最大浪费的地方。设计可以很短，但必须呈现并获批准。
+
+## 流程
+
+### 0. 检查状态（必须先执行）
+
+**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
+
+```bash
+sillyspec status --json
+```
+
+**根据 CLI 返回的 phase 决定是否允许执行 brainstorm：**
+- `phase: "brainstorm"` → ✅ 可以继续
+- `phase: "init"` → ❌ 还没扫描，提示 `sillyspec next` 获取正确的下一步
+- 其他 phase → ⚠️ 提示用户当前阶段，建议先完成当前阶段
+
+**不要跳过状态检查。不要自己推断阶段。以 CLI 为准。**
+
+### 1. 加载项目上下文
+
+首先检查是否在工作区中：
+
+```bash
+cat .sillyspec/config.yaml 2>/dev/null
+```
+
+**如果是工作区模式：**
+1. 询问本次需求属于哪个子项目：
+   ```
+   检测到工作区模式，请选择需求所属的子项目：
+     1) frontend — 前端 - Vue3 + TypeScript
+     2) backend — 后端 - Node.js + PostgreSQL
+   ```
+2. 加载该子项目的上下文 + 工作区共享规范：
+
+```bash
+# 工作区共享规范
+ls .sillyspec/shared/ 2>/dev/null
+cat .sillyspec/shared/*.md 2>/dev/null
+
+# 子项目上下文
+cat <子项目路径>/.sillyspec/PROJECT.md 2>/dev/null
+cat <子项目路径>/.sillyspec/REQUIREMENTS.md 2>/dev/null
+cat <子项目路径>/.sillyspec/ROADMAP.md 2>/dev/null
+cat <子项目路径>/.sillyspec/codebase/STRUCTURE.md 2>/dev/null
+cat <子项目路径>/.sillyspec/codebase/CONVENTIONS.md 2>/dev/null
+# 工作区概览（了解其他子项目）
+cat .sillyspec/workspace/CODEBASE-OVERVIEW.md 2>/dev/null
+```
+
+3. 后续设计文档保存到子项目目录下的 `.sillyspec/specs/`
+4. 提问时考虑跨项目影响（如：这个需求是否需要其他子项目配合？）
+
+**如果不是工作区模式：** 加载原有上下文：
+
+```bash
+# 项目概述
+cat .sillyspec/PROJECT.md 2>/dev/null
+# 需求
+cat .sillyspec/REQUIREMENTS.md 2>/dev/null
+# 路线图
+cat .sillyspec/ROADMAP.md 2>/dev/null
+# 代码库结构（棕地项目）
+cat .sillyspec/codebase/STRUCTURE.md 2>/dev/null
+cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
+# 进行中的变更
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+# 已有设计
+ls .sillyspec/specs/ 2>/dev/null
+```
+
+理解项目现状、已有约定、进行中的工作。
+
+### 1.5 协作与复用检查
+
+在开始提问前，执行以下两项检查：
+
+**检查 A：同名变更检查**
+
+```bash
+ls .sillyspec/changes/ | grep -v archive
+```
+
+如果发现有与当前想法相关的变更，输出：
+```
+⚠️ 检测到已有相关变更：
+- user-auth（3 天前）— 用户认证功能
+
+如果这是不同功能，请在 propose 时使用不同的变更名。
+如果是同一功能，请先查看已有变更：cat .sillyspec/changes/user-auth/proposal.md
+多人协作时，建议使用带人名的变更名（如 user-auth-zhangsan）避免冲突。
+```
+
+没有相关变更则跳过，不输出任何内容。
+
+**检查 B：全局模板检查**
+
+```bash
+ls ~/.sillyspec/templates/ 2>/dev/null
+```
+
+如果有匹配的模板，输出：
+```
+📚 发现可复用模板：
+- ~/.sillyspec/templates/user-auth/ — 用户认证方案
+
+是否基于此模板开始？读取模板内容，结合当前项目上下文适配。
+如果从零开始，请告知。
+```
+
+没有模板则跳过，不输出任何内容。
+
+### 2. 原型/设计图分析（如有）
+
+如果用户在想法描述中提供了截图、图片文件、或 HTML 原型：
+
+**不要跳过这一步，不要只看描述文字。** 图片中包含布局、字段、流程线、交互关系等视觉信息，纯文字无法完整传达。
+
+#### 分析步骤
+
+**2a. 提取页面结构**
+
+从图片中识别并列出：
+
+```
+页面结构分析：
+
+页面 1：台账列表（/rp/rpLedger）
+├── 搜索区
+│   ├── 奖惩类型（下拉：奖励/处罚）
+│   ├── 状态（下拉：待审核/已通过）
+│   └── 查询/重置按钮
+├── 操作栏
+│   ├── 新建、批量删除、导出
+│   └── 权限按钮（编辑/删除/详情）
+└── 数据表格
+    ├── 姓名、部门、奖惩类型、金额、状态、操作时间
+    └── 分页
+```
+
+**2b. 提取表单字段**
+
+对每个表单/编辑页面，提取字段定义：
+
+```
+表单字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| 姓名 | 文本输入 | ✅ | |
+| 奖惩类型 | 下拉选择 | ✅ | 选项：奖励/处罚 |
+| 金额 | 数字输入 | ✅ | |
+| 原因 | 文本域 | ❌ | 多行文本 |
+| 附件 | 文件上传 | ❌ | 支持多文件 |
+```
+
+**2c. 提取交互流程**
+
+识别页面间的跳转关系、流程线、按钮行为：
+
+```
+交互流程：
+
+列表页 → [新建] → 新建表单 → [提交] → 审核页 → [通过] → 回到列表
+列表页 → [详情] → 详情页（只读）
+列表页 → [编辑] → 编辑表单（预填数据）→ [保存] → 回到列表
+列表页 → [删除] → 确认弹窗 → [确定] → 列表刷新
+```
+
+**2d. 识别图中标注和备注**
+
+原型图中可能有用文字标注的业务规则、状态说明、权限说明，全部提取。
+
+**2e. 展示分析结果，请用户确认**
+
+将以上分析结果展示给用户，补充遗漏：
+
+> 📐 原型分析完成。提取到 3 个页面、15 个字段、4 个交互流程。
+>
+> 请确认：
+> 1. 有没有漏掉的字段或功能？
+> 2. 图中的流程线我理解得对吗？
+> 3. 有没有业务规则只在口头说、没画在原型里的？
+
+**2f. 如果原型页面太多**
+
+原型包含多个页面时：
+- 逐页分析，不要一次全部输出
+- 先分析列表页和表单页，再分析详情页和流程页
+- 每页分析完后问用户"下一页？"
+
+**多张图片时**，按页面逻辑顺序分析（先主页面后子页面）。
+
+#### 分析完成后
+
+将原型分析结果保存为 Brainstorm 的参考上下文，后续提问时基于这个分析结果来问，而不是问用户"页面长什么样"这类图片里已经回答了的问题。
+
+#### 大模块：建议拆分执行
+
+如果分析发现原型内容复杂，应该建议用户拆分为多个阶段。判断标准不是页面数量，而是**内容复杂度**：
+
+**满足以下任意 2 条就建议拆分：**
+- 包含 3+ 个可独立交付的功能模块（如列表 + 审批 + 权限管理 + 报表）
+- 涉及 3+ 种角色有不同的操作权限和视图
+- 有跨页面的状态流转（审批流、多步表单、级联操作）
+- 有图时：分析完内容后发现模块间耦合度低，可以独立开发和验证
+- 无图时：brainstorm 提问阶段发现需求范围过大，无法在一次 execute 中高质量完成
+
+**示例：**
+- 5 张简单 CRUD 列表页 → 不拆
+- 2 张带审批流 + 4 种角色的页面 → 拆
+- 无图，"做一个完整 ERP" → 拆
+- 1 张复杂表单 + 10+ 字段联动 + 多条件校验 → 可能不拆（内容集中）
+
+```
+📐 原型分析完成。提取到 15 个页面，功能模块较多，建议拆分执行：
+
+阶段 1：列表页 + 搜索（4 张图）
+  - 台账列表、搜索表单、批量操作、分页
+
+阶段 2：新建/编辑表单（4 张图）
+  - 新建表单、编辑表单、字段校验、附件上传
+
+阶段 3：详情页 + 审核流程（4 张图）
+  - 详情查看、审核页、审批流程、状态流转
+
+阶段 4：导出 + 其他（3 张图）
+  - 数据导出、权限配置、操作日志
+
+建议每个阶段独立 brainstorm → propose → plan → execute → verify。
+全部完成后统一归档。
+```
+
+**请用户确认拆分方案：**
+- 拆分逻辑是否合理？
+- 各阶段范围是否正确？
+- 阶段顺序是否需要调整？
+- 有没有遗漏的功能？
+
+用户确认后，生成 **MASTER.md**（主变更文件），然后进入阶段 1。
+
+#### 生成 MASTER.md
+
+如果用户确认了拆分方案，生成主变更文件：
+
+```bash
+mkdir -p .sillyspec/changes/<变更名>/stages
+```
+
+**`.sillyspec/changes/<变更名>/MASTER.md`：**
+
+```markdown
+# <变更名> — 主变更
+
+## 概述
+[一句话描述整个模块的目标]
+
+## 拆分计划
+
+| 阶段 | 范围 | 页面数 | 状态 |
+|---|---|---|---|
+| 阶段 1 | 列表页 + 搜索 | 4 | ⬜ 待开始 |
+| 阶段 2 | 新建/编辑表单 | 4 | ⬜ 待开始 |
+| 阶段 3 | 详情页 + 审核流程 | 4 | ⬜ 待开始 |
+| 阶段 4 | 导出 + 其他 | 3 | ⬜ 待开始 |
+
+## 整体技术方向
+- 基于现有 ARCHITECTURE.md 的架构风格
+- 复用现有 CONVENTIONS.md 的编码规范
+- 统一使用 [xxx] 组件库
+
+## 阶段间依赖
+- 阶段 2 依赖阶段 1（表单提交后回到列表）
+- 阶段 3 依赖阶段 2（审核需要表单数据）
+- 阶段 4 无强依赖，可并行
+
+## 原型分析摘要
+[各页面的简要描述，每个阶段用几句话概括]
+
+## 经验记录
+（每个阶段完成后在此记录踩坑和经验，供后续阶段参考）
+```
+
+**同时提交 Git：**
+
+```bash
+git add .sillyspec/changes/<变更名>/MASTER.md
+git commit -m "docs: master change plan for <变更名>"
+```
+
+**然后提示用户：**
+
+> ✅ 主变更已创建：`.sillyspec/changes/<变更名>/MASTER.md`
+>
+> 现在进入阶段 1。请运行：
+> `/sillyspec:brainstorm <变更名>/stage-1`
+>
+> 阶段 1 的 brainstorm 会自动读取 MASTER.md，基于整体方向进行设计。
+> 完成后依次：propose → plan → execute → verify。
+> 阶段 1 完成后，进入阶段 2，以此类推。
+> 全部阶段完成后，运行 `/sillyspec:archive <变更名>` 统一归档。
+
+#### 如果是子阶段 brainstorm
+
+如果 `$ARGUMENTS` 包含 `<变更名>/stage-N` 格式（如 `reward-punishment/stage-1`），说明这是大模块的子阶段：
+
+1. 读取主变更：`cat .sillyspec/changes/<变更名>/MASTER.md`
+2. 读取经验记录：MASTER.md 中的"经验记录"章节
+3. 加载该阶段对应的原型图片（如果用户提供了）
+4. 基于 MASTER.md 的整体方向 + 本阶段范围，进行设计
+5. 设计文档保存到 `.sillyspec/changes/<变更名>/stages/<stage-N>/`
+6. 读取前面已完成的阶段的设计（如果有），保持一致性
+
+### 3. 对话式探索（不是问卷）
+
+**🛑 绝对禁止一次性抛出多个问题。**
+
+不要预先准备问题清单。不要想"我需要先搞清楚 A、B、C、D、E 再给方案"。
+
+正确做法：
+1. 从**最核心的一个问题**开始（通常是：你到底想做什么？）
+2. **等待用户回答**
+3. 根据回答判断下一步：
+   - 信息够了 → 直接进入方案讨论，不再问更多问题
+   - 需要追问 → 只追问**一个**相关的问题
+   - 方向有歧义 → 提出 2-3 个选项让用户选
+
+探索顺序（按需，不是每次都要走到最后）：
+1. **目的** — 用户想要什么？（不要问"怎么做"）
+2. **约束** — 技术限制、时间、兼容性要求
+3. **边界** — 什么不在范围内
+4. **成功标准** — 怎么算做好了？
+
+**目标：用最少的轮次搞清楚需求。** 大多数 brainstorm 2-3 轮问答就应该能进入方案讨论了。如果你发现自己列出了超过 2 个问题还没开始，说明你问错方向了——回到用户的核心需求，重新提问。
+
+### 4. 提出 2-3 种方案
+
+每种方案列出优劣，给出推荐和理由。
+
+### 5. 分段展示设计
+
+按复杂度分段展示：
+- 简单项目：几句话就行
+- 复杂项目：每段 200-300 字，逐段确认
+
+### 6. 写设计文档
+
+保存到 `.sillyspec/specs/YYYY-MM-DD-<topic>-design.md`
+
+```markdown
+# [Feature Name] 设计
+
+## 概述
+[一句话描述]
+
+## 功能描述
+[详细描述用户交互流程]
+
+## 技术方案
+[架构决策和关键选择]
+
+## 约束和假设
+[已知的限制条件]
+
+## 不在范围内
+[明确排除的内容]
+
+## 验收标准
+- [ ] 标准 1
+- [ ] 标准 2
+```
+
+### 7. 提交 Git
+
+```bash
+git add .sillyspec/specs/
+git commit -m "docs: design for <topic>"
+```
+
+### 8. 用户确认
+
+**设计保存后，用 CLI 验证状态：**
+
+```bash
+sillyspec status --json
+```
+
+CLI 应返回 `phase: "propose"`。
+
+展示给用户：
+> 设计已保存到 `.sillyspec/specs/xxx-design.md`。
+> 
+> 下一步：
+
+```bash
+sillyspec next
+```
+
+将 CLI 返回的命令推荐给用户。**不要自己编建议。**
+
+### 9. 更新 STATE.md
+
+每次 brainstorm 完成后，**必须自动更新** `.sillyspec/STATE.md`。
+
+**如果 STATE.md 不存在则创建。** 追加或更新以下内容：
+
+```markdown
+# 项目状态
+
+## 当前变更
+- 名称：<变更名>
+- 当前阶段：brainstorm ✅
+- 下一步：/sillyspec:propose <变更名>
+
+## 阶段进度（大模块）
+（如果有 MASTER.md，列出各阶段状态）
+
+## 关键决策
+- （brainstorm 中确定的关键技术决策）
+
+## 历史记录
+- <时间> brainstorm 完成：<主题>
+```
+
+**不需要 Git 提交 STATE.md。** 这是工作状态文件，随时变化，不需要版本控制（可以加入 `.gitignore`）。
+
+## 关键原则
+- 🛑 **一次只问一个问题，等用户回答后再决定下一步**（这是铁律，违反等于 brainstorm 失败）
+- 多选题优于开放式问题
+- YAGNI — 无情砍掉不需要的功能
+- 总是探索替代方案
+- 设计可以很短，但必须存在
+- **2-3 轮问答就应该进入方案讨论**，不要变成问答马拉松
+
+### 注意
+
+在开始生成设计之前，必须先读取相关上下文：
+- `.sillyspec/codebase/ARCHITECTURE.md` — 如果是棕地项目，**必须读取数据模型章节**，设计中引用的表名必须来自真实 schema
+- `.sillyspec/codebase/` 下的其他文档
+- 如果没有上下文文档，先询问用户是否有现有设计或需求文档
+
+**禁止编造不存在的表名、字段名、API 端点。** 如果需要新建表/字段，明确标注为"新增"。

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

@@ -0,0 +1,44 @@
+---
+description: 自动判断并执行下一步
+argument-hint: ""
+---
+
+---
+
+你现在是 SillySpec 的自动推进器。
+
+## 判断逻辑
+
+按顺序检查，第一个未完成的就执行：
+
+```
+1. 有 HANDOFF.json？→ 执行 /sillyspec:resume
+
+2. .sillyspec/changes/ 有进行中的变更？
+   2a. 没有任何文件 → 提示检查 proposal 是否需要完善
+   2b. 没有 design.md → 提示补充 design
+   2c. 没有 tasks.md → 执行 /sillyspec:propose（补全规范）
+   2d. tasks.md 有未完成项 + 有计划文件 → 执行 /sillyspec:execute
+   2e. tasks.md 全完成 + 没验证 → 执行 /sillyspec:verify
+   2f. 已验证通过 → 执行 /sillyspec:archive
+
+3. 有设计文档但没有对应变更？
+   → 提示运行 /sillyspec:propose <name>
+
+4. 有 .sillyspec/codebase/ 但没有进行中的工作？
+   → 提示运行 /sillyspec:brainstorm "你的想法"
+
+5. 什么都没有？
+   → 提示运行 /sillyspec:init（新项目）或 /sillyspec:scan（棕地项目）
+```
+
+## 输出
+
+先报告检测结果，再执行：
+
+> 🤖 SillySpec 自动检测
+> 
+> 当前状态：[描述]
+> 下一步：[执行的命令]
+> 
+> [开始执行...]