sillyspec 2.4.1 → 2.4.3

package/package.json

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

package/templates/brainstorm.md

@@ -3,14 +3,95 @@
 ## 用户想法
 $ARGUMENTS
 
+## 流程总览
+
+```
+┌─────────────────────────────────────────────────┐
+│                  BRAINSTORM 流程                  │
+├─────────────────────────────────────────────────┤
+│                                                  │
+│  ┌─── Step 0: 状态检查 ───┐                      │
+│  └────────────┬───────────┘                      │
+│               ▼                                   │
+│  ┌─── Step 1: 加载项目上下文 ──┐                  │
+│  └────────────┬───────────────┘                   │
+│               ▼                                    │
+│  ┌─── Step 1.5: 协作与复用检查 ─┐                 │
+│  └────────────┬────────────────┘                  │
+│               ▼                                    │
+│  ┌─── Step 2: 原型/设计图分析 ─┐ ← 如有原型      │
+│  └────────────┬────────────────┘                  │
+│               ▼                                    │
+│  ┌─── Step 3: 对话式探索 ──┐                      │
+│  │  (一次一个问题，2-3轮)  │                      │
+│  └────────────┬───────────┘                       │
+│               ▼                                    │
+│  ┌─── Step 4: 提出 2-3 种方案 ─┐                  │
+│  └────────────┬───────────────┘                   │
+│               ▼                                    │
+│  ┌─── Step 5: 分段展示设计 ──┐                    │
+│  │  (逐段确认)               │                    │
+│  └────────────┬─────────────┘                     │
+│               ▼                                    │
+│  ┌─── Step 6: 写设计文档 ────┐                    │
+│  └────────────┬─────────────┘                     │
+│               ▼                                    │
+│  ┌─── Step 7: AI 自审 ──────┐                     │
+│  └────────────┬─────────────┘                     │
+│               ▼                                    │
+│  ┌─── Step 8: 用户确认 ────┐                      │
+│  │  ⛔ 必须等用户明确确认  │                      │
+│  └────────────┬───────────┘                       │
+│               ▼                                    │
+│         /sillyspec:propose                         │
+│         (唯一出口 ✅)                               │
+│                                                  │
+│  ❌ 禁止跳转：propose → execute（无此路径）        │
+│  ❌ 禁止跳转：brainstorm → 任何代码操作            │
+└─────────────────────────────────────────────────┘
+```
+
+**终态明确：** brainstorm 完成后，必须且只能调用 `/sillyspec:propose` 进入下一阶段。不允许直接进入 execute、plan 或任何代码操作。
+
+## 结构化 Checklist（必须按顺序完成）
+
+> ⚠️ AI 必须逐项完成以下清单，每步有明确产出后再进入下一步。
+> 不允许跳步。不允许并行。不允许在完成当前步骤前开始下一步。
+
+- [ ] **Step 0** — 检查 CLI 状态，确认当前处于 brainstorm 阶段
+- [ ] **Step 1** — 加载项目上下文，理解现有代码结构和约定
+- [ ] **Step 1.5** — 检查同名变更和全局模板，避免重复劳动
+- [ ] **Step 2** — 分析原型/设计图（如有），提取页面结构和字段
+- [ ] **Step 2b** — 评估需求范围，复杂需求先拆分子项目/阶段，生成 MASTER.md
+- [ ] **Step 3** — 对话式探索需求，一次一个问题，2-3 轮内完成
+- [ ] **Step 4** — 提出 2-3 个方案并给出推荐
+- [ ] **Step 5** — 分段展示设计，逐段用户确认
+- [ ] **Step 6** — 撰写 design 文档并保存
+- [ ] **Step 7** — AI 自审 design 文档（对照约束检查）
+- [ ] **Step 8** — 用户确认设计 → 调用 `/sillyspec:propose`
+
 ## 核心原则
 
 **创建性工作前必须经过此流程。** 不管需求多简单，都必须先探索再动手。
 
 <HARD-GATE>
 在用户确认设计之前，不得调用任何实现技能、不写任何代码、不做任何脚手架、不安装任何依赖。
+brainstorm 的唯一出口是 /sillyspec:propose。没有其他路径可以离开 brainstorm。
 </HARD-GATE>
 
+## 🚫 禁止事项
+
+- ❌ 写实现代码（Java/JS/Python/任何语言）
+- ❌ 修改任何源代码文件
+- ❌ 安装依赖或执行构建命令
+- ❌ 创建数据库迁移脚本
+- ❌ 直接实现功能而不是先讨论设计
+- ❌ 跳过 brainstorm 直接进入 execute 或 plan
+- ❌ 在 checklist 未完成前开始写设计文档
+- ❌ 编造不存在的表名、字段名、API 端点
+
+如果用户在头脑风暴阶段要求写代码，提醒他们：先完成 brainstorm 确认设计方案，再进入 propose → plan → execute 流程写代码。
+
 ## 反模式："这个太简单了不需要设计"
 
 每个项目都走这个流程。Todo 列表、单函数工具、配置修改——都一样。"简单"的项目才是未检视的假设造成最大浪费的地方。设计可以很短，但必须呈现并获批准。
@@ -42,9 +123,9 @@ cat .sillyspec/config.yaml 2>/dev/null
 
 **如果是工作区模式：**
 1. 询问本次需求属于哪个子项目：
-   检测到工作区模式，请选择需求所属的子项目：
-   > 1. frontend — 前端 - Vue3 + TypeScript
-   > 2. backend — 后端 - Node.js + PostgreSQL
+   请选择需求所属的子项目：
+   1. frontend — 前端 - Vue3 + TypeScript
+   2. backend — 后端 - Node.js + PostgreSQL
 2. 加载该子项目的上下文 + 工作区共享规范：
 
 ```bash
@@ -190,11 +271,11 @@ ls ~/.sillyspec/templates/ 2>/dev/null
 将以上分析结果展示给用户，补充遗漏：
 
 > 📐 原型分析完成。提取到 3 个页面、15 个字段、4 个交互流程。
->
-> 请确认：
-> 1. 有没有漏掉的字段或功能？
-> 2. 图中的流程线我理解得对吗？
-> 3. 有没有业务规则只在口头说、没画在原型里的？
+
+请确认：
+1. 有没有漏掉的字段或功能？
+2. 图中的流程线我理解得对吗？
+3. 有没有业务规则只在口头说、没画在原型里的？
 
 **2f. 如果原型页面太多**
 
@@ -384,14 +465,34 @@ git commit -m "docs: master change plan for <变更名>"
 - [ ] 标准 2
 ```
 
-### 7. 提交 Git
+### 7. AI 自审
+
+写完设计文档后，**立即进行自审**，不要等用户来挑问题。
+
+自审检查项：
+
+1. **需求覆盖**：design 是否完整覆盖了用户在 Step 3 中确认的所有需求点？
+2. **约束一致性**：design 中的技术方案是否与 ARCHITECTURE.md、CONVENTIONS.md 一致？
+3. **表名/字段真实性**：是否所有引用的表名和字段都来自真实 schema？新增的是否明确标注？
+4. **范围控制**：是否包含了不必要的功能（违反 YAGNI）？
+5. **验收标准**：验收标准是否具体、可测试？
+6. **与已有变更冲突**：是否与 Step 1.5 中检测到的已有变更冲突？
+
+**自审结果处理：**
+- 全部通过 → 进入 Step 8
+- 发现问题 → 修改 design 文档，重新自审，全部通过后再进入 Step 8
+- 不确定的问题 → 在 Step 8 展示给用户时标注「⚠️ 自审存疑」，请用户判断
+
+**不要跳过自审。** 这是保证设计质量的关键环节。
+
+### 8. 提交 Git
 
 ```bash
 git add .sillyspec/specs/
 git commit -m "docs: design for <topic>"
 ```
 
-### 8. 用户确认
+### 9. 用户确认（⛔ 门禁）
 
 **设计保存后，用 CLI 验证状态：**
 
@@ -401,10 +502,15 @@ sillyspec status --json
 
 CLI 应返回 `phase: "propose"`。
 
-展示给用户：
-> 设计已保存到 `.sillyspec/specs/xxx-design.md`。
-> 
-> 下一步：
+**⛔ 必须等待用户明确确认后才能进入下一阶段。** 展示给用户：
+
+
+请确认设计方案：
+1. ✅ 确认，进入 propose
+2. ✏️ 需要修改（请说明要改什么）
+3. ❌ 推翻重来
+
+**用户选择 1** → 推荐下一步命令：
 
 ```bash
 sillyspec next
@@ -412,7 +518,12 @@ sillyspec next
 
 将 CLI 返回的命令推荐给用户。**不要自己编建议。**
 
-### 9. 更新 STATE.md
+**用户选择 2** → 修改 design 文档，重新自审，再次进入确认门禁。
+**用户选择 3** → 回到 Step 3 或 Step 4 重新探索。
+
+**不允许在用户确认前自行推进到 propose 或任何后续阶段。**
+
+### 10. 更新 STATE.md
 
 每次 brainstorm 完成后，**必须自动更新** `.sillyspec/STATE.md`。
 

package/templates/resume.md

@@ -34,8 +34,8 @@ cat .sillyspec/STATE.md 2>/dev/null
 **不需要执行 Git 操作或文件探测。** STATE.md 已经包含所有信息。
 
 然后问用户：
-> 1. 直接继续执行下一步
-> 2. 查看更多细节
+   1. 直接继续执行下一步
+   2. 查看更多细节
 
 ### 3. 如果没有 STATE.md
 

package/templates/scan.md

@@ -43,9 +43,9 @@ cat .sillyspec/config.yaml 2>/dev/null
 
 询问用户：
 > 检测到工作区模式，请选择扫描范围：
-> 1. 全部子项目（逐个扫描后生成汇总）
-> 2. 指定某个子项目
-> 3. 取消
+   1. 全部子项目（逐个扫描后生成汇总）
+   2. 指定某个子项目
+   3. 取消
 
 根据选择：
 - 选 1 → 逐个扫描，最后生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`
@@ -68,9 +68,9 @@ wc -l .sillyspec/codebase/*.md 2>/dev/null
 
 **已有 3 份（STACK + STRUCTURE + PROJECT）：**
 > 检测到上次的快速扫描结果。
-> 1. 升级为完整扫描（补充 4 份文档）
-> 2. 重新快速扫描（覆盖现有文档）
-> 3. 跳过，直接开始开发
+   1. 升级为完整扫描（补充 4 份文档）
+   2. 重新快速扫描（覆盖现有文档）
+   3. 跳过，直接开始开发
 
 **已有 7 份完整文档：**
 先检查距上次扫描过了多久：
@@ -80,8 +80,8 @@ git log --oneline --since="上次扫描时间" | wc -l
 ```
 
 > 上次扫描距今 X 天，期间有 Y 个新提交。
-> 1. 刷新（重新扫描全部）
-> 2. 跳过，直接开始开发
+   1. 刷新（重新扫描全部）
+   2. 跳过，直接开始开发
 
 **用户选跳过** → 输出"可以开始开发了。建议下一步：`/sillyspec:brainstorm '你的需求'`"然后结束。
 
@@ -89,13 +89,13 @@ git log --oneline --since="上次扫描时间" | wc -l
 
 请选择扫描模式：
 
-> 1. 快速扫描 ⚡
+   1. 快速扫描 ⚡
 >    读取配置文件和目录结构，约 30 秒
 >    生成 3 份文档：技术栈 + 目录结构 + 项目概览
-> 2. 深度扫描 🔍
+   2. 深度扫描 🔍
 >    读取全部源代码并分析，约 2-3 分钟
 >    生成 7 份文档：技术栈 + 架构 + 目录结构 + 编码约定 + 集成 + 测试 + 技术债务
-> 3. 取消
+   3. 取消
 
 根据选择进入对应的扫描流程。
 
@@ -131,8 +131,8 @@ git log --oneline --since="上次扫描时间" | wc -l
 把以上选择汇总，让用户最后确认：
 
 开始扫描？
-> 1. 确认，开始扫描
-> 2. 修改选项
+   1. 确认，开始扫描
+   2. 修改选项
 
 用户确认 → 执行扫描。用户想改 → 回到对应步骤。
 

package/templates/workspace.md

@@ -14,8 +14,8 @@ cat .sillyspec/config.yaml 2>/dev/null
 ```
 
 如果不存在 → 这是一个尚未配置工作区的项目。询问用户：
-> 1. 初始化工作区
-> 2. 跳过
+   1. 初始化工作区
+   2. 跳过
 
 ### Step 2: 解析指令