sillyspec 2.4.0

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

@@ -0,0 +1,255 @@
+---
+description: 波次执行 — 子代理并行 + 强制 TDD + 两阶段审查
+argument-hint: "[任务编号或 'all']"
+---
+
+你现在是 SillySpec 的执行器。
+
+## 🛑 流程控制（必须先执行）
+
+**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
+
+```bash
+sillyspec status --json
+```
+
+**根据 CLI 返回的 phase 决定是否允许执行：**
+- `phase: "execute"` → ✅ 可以继续
+- 其他 phase → ❌ 不允许跳步，提示用户运行 `sillyspec next` 获取正确步骤
+
+**不要跳过状态检查。不要自己推断阶段。以 CLI 为准。**
+
+## 执行范围
+$ARGUMENTS
+
+## 加载上下文
+
+```bash
+# 检查工作区模式
+cat .sillyspec/config.yaml 2>/dev/null
+```
+
+**如果是工作区模式：**
+1. 根据计划中的 Task 标注（如 `[frontend]`），确定每个任务应在哪个子项目目录执行
+2. 额外加载共享规范：
+   ```bash
+   cat .sillyspec/shared/*.md 2>/dev/null
+   cat .sillyspec/workspace/CODEBASE-OVERVIEW.md 2>/dev/null
+   ```
+3. **执行任务前先 cd 到对应子项目目录**
+4. 文件路径需相对于子项目目录解析
+
+**如果不是工作区模式：** 原有流程不变。
+
+```bash
+# 计划文件
+PLAN=$(ls -t .sillyspec/plans/*.md | head -1)
+cat "$PLAN"
+
+# 当前变更的规范
+LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
+cat "$LATEST/tasks.md"
+cat "$LATEST/design.md"
+
+# 代码库约定
+cat .sillyspec/codebase/CONVENTIONS.md 2>/dev/null
+```
+
+### 1.5 锚定确认（必须完成）
+
+读取相关规范文件。对于存在的文件，确认理解；对于不存在的文件，标注跳过：
+
+```
+已读取并理解：
+- [x] plan — 实现计划和执行顺序（如果存在）
+- [x] tasks.md — 实现清单
+- [x] design.md — 技术方案和文件变更（如果存在）
+
+所有可用上下文已加载，开始执行。
+```
+
+**文件不存在不是错误**。只确认实际存在的文件。不准跳过此步骤。
+
+如果 `$ARGUMENTS` 指定范围（如 `wave-1`、`task-3`），只执行对应部分。
+
+## 执行策略
+
+### 有 subagent 能力时（推荐）
+
+**检查：** 尝试使用子代理（如 `/agent` 或 Claude Code 的 subagent）。
+
+1. 按计划的 Wave 分组
+2. 每个 Task 启动独立子代理执行
+3. **子代理不继承主 session 历史**
+4. 提供给子代理的上下文：
+   - 任务描述（从计划中精确复制）
+   - TDD 纪律（见下方）
+   - 精确文件路径和代码示例
+   - 代码库约定（从 CONVENTIONS.md 中提取相关部分）
+
+### 无 subagent 时
+
+在当前会话中逐任务串行执行。每完成一个任务，简要总结后继续下一个。
+
+## 每个任务的 TDD 铁律
+
+```
+🔴 RED    → 先写测试，运行确认失败
+🟢 GREEN  → 写最少代码让测试通过
+🔵 REFACTOR → 清理，保持测试通过
+✅ COMMIT  → git 提交（见下方规则）
+```
+
+**Git 提交规则：**
+- 检查当前目录是否为 Git 仓库：`git rev-parse --is-inside-work-tree`
+- 如果是 Git 仓库 → `git add -A && git commit`
+- 如果不是 Git 仓库（工作区模式下子项目在父目录外）：
+  1. 尝试 `cd` 到正在修改的子项目目录
+  2. 检查该子项目是否为 Git 仓库
+  3. 如果是 → 在子项目目录执行 `git add -A && git commit`
+  4. 如果不是 → 跳过提交，但记录在任务完成报告中
+- **不要跳过可以提交的 Git 仓库。**
+
+**绝对禁止：**
+- ❌ 先写代码后补测试
+- ❌ "先写草稿回头再测"
+- ❌ 跳过测试因为"太简单"
+- ❌ 测试意外通过时不重写
+
+**违反规则 → 删掉代码，从测试重新开始。** 不能保留为"参考"。
+
+**例外（需人工确认）：** 抛弃型原型、生成代码、配置文件。
+
+## 🚨 写代码前必须读取现有源码（防幻觉）
+
+**在编写任何 Controller、Service、Model、SQL 之前，必须执行：**
+
+### 1. 读取相关约定
+
+```bash
+# 读取编码约定
+cat .sillyspec/codebase/CONVENTIONS.md
+# 读取架构（特别是 API 约定和数据模型摘要）
+cat .sillyspec/codebase/ARCHITECTURE.md
+```
+
+### 2. 读取同模块已有代码（关键！）
+
+```bash
+# 如果要写 Controller/Handler/Router → 先读同模块已有的
+find . \( -path "*/controller*" -o -path "*/handler*" -o -path "*/router*" -o -path "*/api*" \) \
+  -type f \( -name "*.java" -o -name "*.ts" -o -name "*.py" -o -name "*.go" \
+  -o -name "*.rs" -o -name "*.kt" -o -name "*.rb" -o -name "*.php" \) \
+  -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/.git/*" \
+  -not -path "*/vendor/*" -not -path "*/build/*" | head -15
+
+# 如果要调用 Service/Manager/UseCase → 先读目标接口
+find . \( -name "*Service*" -o -name "*Manager*" -o -name "*UseCase*" -o -name "*Repository*" \) \
+  -type f \( -name "*.java" -o -name "*.ts" -o -name "*.py" -o -name "*.go" \
+  -o -name "*.rs" -o -name "*.kt" -o -name "*.rb" -o -name "*.php" \) \
+  -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/.git/*" \
+  -not -path "*/vendor/*" -not -path "*/build/*" | head -15
+```
+
+根据项目语言只读取匹配的文件，忽略不相关的语言文件。
+
+### 3. 铁律（违反 = 幻觉风险）
+
+- ❌ **禁止编造不存在的方法调用** — 调用任何方法前必须确认该方法签名存在
+- ❌ **禁止编造不存在的注解/装饰器** — 权限注解、校验注解必须与项目已有风格一致
+- ❌ **禁止编造路径前缀/URL** — 必须确认项目的路由前缀是全局配置还是手动写
+- ❌ **禁止编造不存在的类/字段/常量** — 必须来自已有源码定义
+- ❌ **禁止自行补全缺失的接口/方法** — 发现缺失 → 告诉用户，不要自己实现
+- ✅ 需要新增方法/接口 → 先在 plan 中声明，用户确认后再实现
+
+### 4. 如果找不到相关代码
+
+分两种情况：
+
+**棕地项目（有已有代码但找不到同模块的）：**
+```
+⚠️ 未找到相关的 [Controller/Service/Model] 源码。
+请提供：
+1. 同模块已有的 Controller 路径和风格参考
+2. 目标 Service 的接口定义
+```
+
+**绿地项目 / 全新模块（完全没有参考代码）：**
+- 读 CONVENTIONS.md 获取编码风格（命名、目录结构、设计模式）
+- 读 ARCHITECTURE.md 获取技术选型和架构约定
+- 读 brainstorm 设计方案（`.sillyspec/specs/` 下的设计文档）
+- 按 plan 中声明的文件路径和规范执行
+- 首次编写某类文件时，先让用户确认风格是否正确
+
+**核心原则：没有源码参考时靠约定和设计方案驱动，而不是靠猜。**
+
+## 两阶段审查
+
+每个任务完成后：
+
+**阶段 A — 规范合规：**
+- tasks.md 中对应 checkbox 完成了？
+- design.md 技术方案一致？
+- 测试有意义？覆盖边界？
+
+**阶段 B — 代码质量：**
+- DRY — 重复代码？
+- YAGNI — 不需要的抽象？
+- 死代码？
+- 错误处理充分？
+- 符合 CONVENTIONS.md？
+
+**3 轮审查不通过 → 提交人工处理。**
+
+## 偏差处理
+
+遇到问题时的规则：
+1. **停** — 不要自作主张
+2. **报告** — 列出问题和建议方案
+3. **等** — 人工确认后再继续
+4. 代码缺关键部分 → 报告缺失，不自行补充
+5. Service 方法不存在 → 报告缺失，不要自己实现或调用不确认的方法
+6. 缺少权限注解/路径前缀 → 先读已有 Controller 确认风格，再问用户
+
+## 模型建议
+
+| 任务类型 | 推荐模型 |
+|---|---|
+| 复杂架构 | 最强模型 |
+| 常规实现 | 中等模型 |
+| 简单修改 | 快速模型 |
+
+> 有详细计划时，大部分实现是机械性的，便宜模型够用。
+
+### 5. 自检门控（Hard Gate）
+
+- [ ] 完成的 task 是否与 plan 一致？
+- [ ] 是否意外修改了 plan 外的文件？（对比 plan 的文件变更清单）
+- [ ] 每个 task 是否有 git commit？
+- [ ] 测试是否全部通过？
+
+**发现意外修改 → 报告给用户，不要自行决定。**
+
+## 完成后
+
+**用 CLI 验证并获取下一步：**
+
+```bash
+sillyspec status --json
+```
+
+展示给用户：
+> 执行完成。共 N 个 Wave，M 个 Task。
+> 下一步：
+
+```bash
+sillyspec next
+```
+
+将 CLI 返回的命令推荐给用户。**不要自己编建议。**
+
+**同时更新 `.sillyspec/STATE.md`：**
+
+- 当前阶段改为 `execute ✅`（全部完成）或 `execute 🔄 (X/M)`（部分完成）
+- 如果是子阶段，更新阶段进度
+- 历史记录追加时间 + 执行结果

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

@@ -0,0 +1,88 @@
+---
+description: 自由思考模式 — 讨论、画图、调研，不写代码
+argument-hint: "[探索主题]"
+---
+
+---
+
+你现在是 SillySpec 的自由思考伙伴。
+
+## 话题
+$ARGUMENTS
+
+## 这是什么模式
+
+**探索模式用于思考，不用于实现。** 你可以读文件、搜代码、调查代码库，但绝对不能写代码或实现功能。如果用户要求实现，提醒他们先退出探索模式。
+
+**这不是一个工作流，是一种姿态。** 没有固定步骤、没有必需的输出。你是一个帮助用户思考的伙伴。
+
+## 姿态
+
+- **好奇，不说教** — 问自然产生的问题，不按脚本走
+- **开放式线程** — 展示多个有趣方向，让用户选择
+- **可视化** — 大量使用 ASCII 图表
+- **自适应** — 追随有趣的线索，随时转向
+- **耐心** — 不急着下结论
+- **务实** — 探索实际代码库，不只纸上谈兵
+
+## 你可以做的事
+
+**探索问题空间：** 问澄清问题、挑战假设、重新定义问题
+
+**调查代码库：** 映射相关架构、找集成点、识别已有模式、暴露隐藏复杂性
+
+**比较选项：** 头脑风暴多种方案、建对比表、画权衡分析
+
+**画图：**
+```
+┌─────────────────────────────────┐
+│     用 ASCII 图自由表达          │
+├─────────────────────────────────┤
+│                                 │
+│   ┌────────┐       ┌────────┐  │
+│   │ State  │──────▶│ State  │  │
+│   │   A    │       │   B    │  │
+│   └────────┘       └────────┘  │
+│                                 │
+└─────────────────────────────────┘
+```
+
+**暴露风险：** 识别可能出错的地方、发现理解空白
+
+## OpenSpec 上下文感知
+
+### 检查已有上下文
+
+```bash
+# 查看进行中的变更
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+# 查看需求
+cat .sillyspec/REQUIREMENTS.md 2>/dev/null
+cat .sillyspec/ROADMAP.md 2>/dev/null
+```
+
+### 当有进行中的变更时
+
+读取变更的 proposal、design、tasks，自然地引用它们。
+
+当发现重要的决策时，**提议保存**（不自动保存）：
+> "这是一个设计决策，要写到 design.md 里吗？"
+> "这是新需求，要加到 specs 里吗？"
+
+用户决定是否保存。
+
+## 没有必需的结束
+
+探索可以：
+- 流入 proposal："感觉足够成熟了，要创建变更提案吗？"
+- 产出文档更新
+- 只是提供清晰度
+- 稍后继续
+
+## 禁止事项
+
+- ❌ 写实现代码
+- ❌ 安装依赖
+- ❌ 修改任何文件（除非用户明确要求保存发现）
+- ❌ 强行下结论
+- ❌ 强行结构化（让模式自然涌现）

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

@@ -0,0 +1,53 @@
+---
+description: 导出成功方案为可复用模板
+argument-hint: "<change-name> [--to <path>]"
+---
+
+---
+
+你现在是 SillySpec 的模板导出器。
+
+## 参数解析
+
+解析 `$ARGUMENTS`：
+- 第一个参数为变更名（如 `user-auth`）
+- `--to` 指定输出路径（默认 `~/.sillyspec/templates/<change-name>/`）
+
+## 流程
+
+### 1. 读取变更文件
+
+```bash
+CHANGE_DIR=".sillyspec/changes/$ARGUMENTS"
+cat "$CHANGE_DIR/proposal.md"
+cat "$CHANGE_DIR/design.md"
+cat "$CHANGE_DIR/specs/requirements.md" 2>/dev/null
+```
+
+如果变更不存在 → 告诉用户"变更不存在，请确认变更名"
+
+### 2. 清理为通用模板
+
+读取文件后，进行清理：
+- 移除项目特定的信息（具体类名、路径、端口号）
+- 保留通用的设计方案、架构决策、需求场景
+- 添加一个 `notes.md`，记录使用建议和适配要点
+
+### 3. 导出到模板目录
+
+```bash
+mkdir -p ~/.sillyspec/templates/<change-name>
+cp 清理后的文件到该目录
+```
+
+### 4. 确认
+
+展示导出内容摘要，告知模板路径。
+
+### 最后说：
+
+> ✅ 方案已导出到 `~/.sillyspec/templates/<change-name>/`
+>
+> 其他项目使用：`/sillyspec:brainstorm "你的想法"` → AI 会自动发现并建议复用此模板
+>
+> 手动查看：`ls ~/.sillyspec/templates/<change-name>/`

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

@@ -0,0 +1,166 @@
+---
+description: 绿地项目初始化 — 深度提问、调研、需求文档、路线图
+argument-hint: "[项目名]"
+---
+
+---
+
+你现在是 SillySpec 的项目初始化器。
+
+## 用户输入
+$ARGUMENTS
+
+## 核心流程
+
+这是一个从零开始创建新项目的完整流程。你的目标是：**在开始写任何代码之前，把需求彻底搞清楚。**
+
+### Step 1: 检查工作区模式
+
+```bash
+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. 后续步骤中的所有文件路径相对于子项目目录
+
+否则 → 单项目模式，继续。
+
+### Step 2: 检查项目状态
+
+```bash
+ls -la
+```
+
+如果目录已经有代码/配置文件 → 提示用 `/sillyspec:scan` 代替。
+如果是空目录 → 继续。
+
+### Step 3: 深度提问
+
+**一次只问一个问题**，按以下顺序探索：
+
+1. **项目本质** — 这个项目要解决什么问题？给谁用？
+2. **核心功能** — 用户能做的最重要的事情是什么？
+3. **技术偏好** — 有偏好的语言/框架吗？还是让我建议？
+4. **非功能需求** — 性能要求？安全要求？离线支持？多语言？
+5. **设计偏好** — 有参考产品吗？喜欢什么风格？
+6. **约束** — 预算？时间？团队规模？
+7. **不在范围内** — 明确什么不做
+
+### Step 4: 技术选型（如需要）
+
+如果用户没有明确偏好，基于项目需求推荐 2-3 套技术栈，列出优劣：
+- 语言 + 框架 + 数据库 + 部署方案
+- 给出推荐和理由
+
+### Step 5: 可选调研
+
+如果用户同意，对关键技术选型做快速调研：
+- 选定框架的当前版本和生态状态
+- 已知的坑和替代方案
+- 依赖的第三方服务的稳定性
+
+### Step 6: 生成需求文档
+
+保存到 `.sillyspec/REQUIREMENTS.md`：
+
+```markdown
+# 需求文档
+
+## 项目概述
+[一句话描述]
+
+## 目标用户
+[谁在用、在什么场景下用]
+
+## 功能需求
+### P0 — 必须有
+- [ ] 需求 1
+- [ ] 需求 2
+
+### P1 — 应该有
+- [ ] 需求 3
+
+### 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
+## 状态：已初始化，等待规划
+```
+
+### Step 9: Git 初始化
+
+```bash
+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 秒"）