sillyspec 3.7.13 → 3.7.15

package/.claude/skills/sillyspec-continue/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: sillyspec:continue
+description: 自动判断并执行下一步
+---
+
+---
+
+你现在是 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. 有 docs/*/scan/ 但没有进行中的工作？
+   → 提示运行 /sillyspec:brainstorm "你的想法"
+
+5. 什么都没有？
+   → 提示运行 /sillyspec:init（新项目）或 /sillyspec:scan（棕地项目）
+```
+
+## 输出
+
+先报告检测结果，再执行：
+
+> 🤖 SillySpec 自动检测
+> 
+> 当前状态：[描述]
+> 下一步：[执行的命令]
+> 
+> [开始执行...]

package/.claude/skills/sillyspec-execute/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: sillyspec:execute
+description: 波次执行 — 子代理并行 + 强制 TDD + 两阶段审查
+---
+
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 跳过状态检查，自行推断阶段
+- ❌ 跳步执行（不允许跳过 plan 直接 execute）
+- ❌ 先写代码后补测试
+- ❌ 编造不存在的方法/注解/路径/类/字段
+- ❌ 自行补全缺失的接口/方法（应报告 BLOCKED）
+- ❌ 意外修改了计划外的文件却不报告
+
+## 状态检查（必须先执行）
+
+```bash
+sillyspec progress show 2>/dev/null
+```
+
+检查 progress.json 中 currentStage 是否为 execute。如果不是 → 检查是否有未完成的 tasks.md：
+
+```bash
+ls .sillyspec/changes/*/tasks.md 2>/dev/null | xargs grep -l '\- \[ \]' 2>/dev/null
+```
+
+有未完成的 tasks.md → 继续。没有 → 提示 `/sillyspec:continue`。
+
+## 执行范围
+$ARGUMENTS
+
+---
+
+## 加载上下文
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .
+```
+
+**工作区模式：** 根据计划 Task 标注确定子项目，额外加载共享规范 + CODEBASE-OVERVIEW.md。所有代码修改、测试运行在子项目目录中执行。
+
+**加载以下文件（主代理读取，后续注入子代理）：**
+```bash
+PLAN=$(ls -t .sillyspec/changes/*/tasks.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
+PROJECT=$(python3 -c "import sys,json; print(json.load(open('.sillyspec/.runtime/progress.json')).get('project',''))" 2>/dev/null || basename "$(pwd)")
+cat docs/${PROJECT}/scan/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null
+cat .sillyspec/local.yaml 2>/dev/null
+```
+
+**知识库查询（强制步骤）：**
+主代理在 dispatch 每个子代理前，必须执行：
+```bash
+cat .sillyspec/knowledge/INDEX.md 2>/dev/null
+```
+根据当前 task 描述中的关键词（技术名词、模块名、文件路径等）匹配 INDEX.md 条目。命中时读取对应 knowledge 文件，将内容注入子代理 prompt 的「相关知识」段。未命中则跳过，不注入空段。
+
+如果 `$ARGUMENTS` 指定范围（如 `wave-1`、`task-3`），只执行对应部分。
+
+---
+
+## 任务分类→模型路由（强制）
+
+主代理在 dispatch 子代理前，根据任务特征选择模型：
+
+| 分类 | 触发条件 | 推荐模型 |
+|------|---------|---------|
+| **架构/复杂推理** | 任务含"设计"、"架构"、"重构"、"性能优化"、"算法" | 最强模型（如 Claude Sonnet 4 / Hunter Alpha） |
+| **常规实现** | 一般 CRUD、业务逻辑、接口开发 | 中等模型（如 GPT-4o / GLM-5） |
+| **简单修改** | 改配置、改文案、改样式、修 bug | 快速模型（如 DeepSeek / Llama） |
+| **文档/写作** | 写文档、写注释、写 README | 写作模型（如 GPT-4o / DeepSeek） |
+
+**默认模型**：如无法判断，使用当前默认模型。
+
+**用户覆盖**：用户可在 tasks.md 中用标签指定模型，如：
+```markdown
+- [ ] [model:openrouter/anthropic/claude-sonnet-4] 实现支付模块架构设计
+```
+
+主代理读取标签后覆盖自动分类。
+
+---
+
+## 确认频率
+
+用 AskUserQuestion 询问用户选择：
+- **每个 Wave 确认** — 每个 Wave 完成后展示结果，等用户确认后继续下一 Wave
+- **AI 自主判断** — AI 在遇到 BLOCKED 或计划外变更时才询问，其余自动推进
+- **全自动** — 全部自动执行，不在中途打断用户
+
+---
+
+## 子代理执行（强制模式）
+
+**所有任务通过子代理执行，主代理负责调度和记录。**
+
+### 执行流程
+
+1. 解析 tasks.md，按 Wave 分组
+2. 根据「任务分类→模型路由」规则为每个任务选择模型
+3. 同一 Wave 内的任务**并行启动**子代理，不同 Wave **串行等待**
+4. 每个 Wave 完成后，根据用户选择的确认频率决定是否暂停
+5. 子代理返回结果后，主代理勾选 tasks.md、更新 progress.json（`sillyspec progress update-step`）
+
+**dispatch 时指定 model 参数：**
+```bash
+# 根据任务分类选择模型
+if [[ "$TASK_LABEL" =~ model: ]]; then
+  MODEL=$(echo "$TASK_LABEL" | grep -oP 'model:\S+')
+elif [[ "$TASK_DESC" =~ 设计|架构|重构|性能优化|算法 ]]; then
+  MODEL="openrouter/anthropic/claude-sonnet-4"  # 最强模型
+elif [[ "$TASK_DESC" =~ 配置|文案|样式|修.?bug ]]; then
+  MODEL="zai/glm-5-turbo"  # 快速模型
+else
+  MODEL="openrouter/openai/gpt-4o"  # 中等模型
+fi
+```
+
+### 子代理 Prompt 模板
+
+主代理在 dispatch 子代理前，根据「任务分类→模型路由」选择模型，然后准备以下 prompt（所有内容**内联**，不让子代理自己读文件）：
+
+**模型选择示例：**
+```
+# 架构任务 → dispatch 时指定 model=openrouter/anthropic/claude-sonnet-4
+# 普通实现 → dispatch 时指定 model=openrouter/openai/gpt-4o
+# 简单修改 → dispatch 时指定 model=zai/glm-5-turbo
+```
+
+```
+你正在执行任务：
+
+## 任务描述
+{tasks.md 中当前 task 的完整内容，包括步骤字段}
+
+## 项目约定
+{CONVENTIONS.md 全文}
+
+## 项目架构
+{ARCHITECTURE.md 全文}
+
+## 构建命令
+{local.yaml 中的 build 命令，如无则给默认命令}
+
+## 工作目录
+{子项目目录路径，工作区模式需要 cd 到此目录}
+
+## 相关知识（如有）
+{主代理从 knowledge/ 中按任务关键词匹配到的内容，未命中则删除此段}
+
+## 文档/代码查询（强制步骤）
+
+**在写代码前，如果涉及不熟悉的库/框架/API，必须先查询：**
+
+```bash
+# 1. 查官方文档（Context7 MCP）
+# 用法：在 prompt 中说明需要查询的库名
+# 主代理会在 dispatch 前通过 MCP 查询并注入结果
+
+# 2. 查开源实现（grep.app MCP）  
+# 用法：如果文档不够，搜 GitHub 上的真实实现
+# 主代理会在 dispatch 前通过 MCP 查询并注入结果
+```
+
+**主代理 dispatch 前的查询流程：**
+1. 读取当前 task 描述
+2. 提取涉及的库/框架/技术关键词
+3. 通过 Context7 MCP 查询官方文档
+4. 如果文档不足以解决问题，通过 grep.app MCP 搜索开源代码
+5. 将查询结果注入子代理 prompt 的「相关知识」段
+
+## 铁律（必须遵守）
+1. **先读后写：** 先 cat 要修改的文件和参考文件，确认风格和方法签名后再写
+2. **grep 确认：** 调用已有方法前必须 grep 确认存在，grep 不到 → 报告 BLOCKED
+3. **不编造：** 不编造不存在的方法/注解/类/字段
+4. **不自行补全：** 发现缺失接口/方法，不自己写，报告 BLOCKED
+5. **TDD 不跳步：** 按任务步骤逐步执行，每步必须运行测试命令并确认结果
+6. **测试直接通过 = 测了已有行为，重写测试**
+7. **暂存：** 完成后在工作目录执行 git add -A（不要 commit，由用户通过 /sillyspec:commit 统一提交）
+8. **不修改计划外的文件**，如必须修改则在报告中说明
+
+## 完成后报告（严格按此格式）
+
+- **Status:** DONE / DONE_WITH_CONCERNS / BLOCKED
+- **改动文件：** {列表}
+- **测试结果：** {通过/失败/跳过及原因}
+- **Commit:** {hash 或 "无"}
+- **问题：** {BLOCKED 原因 / DONE_WITH_CONCERNS 描述 / 无}
+- **发现的坑：** {执行过程中发现的项目特有规律/陷阱/约定，如无则写"无"。示例："XxxMapper.selectPage() 第一个参数必须是 IPage 对象，传 null 会 NPE 而非返回全部"}
+```
+
+### 子代理结果处理
+
+子代理返回后，主代理：
+
+1. **DONE** → 勾选 tasks.md，记录精确到秒的时间戳
+2. **DONE_WITH_CONCERNS** → 勾选 tasks.md，记录问题到报告
+3. **BLOCKED** → 不勾选，报告给用户，AskUserQuestion 三选一：
+   - 重试（重新 dispatch 同一任务）
+   - 跳过（勾选并标注 SKIPPED）
+   - 停止（暂停执行，用户处理后继续）
+
+**知识库写入：** 如果子代理报告中「发现的坑」不为"无"，主代理将内容追加到 `.sillyspec/knowledge/uncategorized.md`，格式：
+```markdown
+### [待确认] {简短标题}
+> 来源：{变更名} / {task 编号} | {时间戳}
+
+{坑的具体描述}
+```
+
+---
+
+## 完成后
+
+**知识库审阅：** 检查是否有待确认的知识条目：
+```bash
+grep -c '^\### \[待确认\]' .sillyspec/knowledge/uncategorized.md 2>/dev/null
+```
+如果有待确认条目，提示用户：
+> 📚 本轮执行发现了 N 条新知识，请审阅：`cat .sillyspec/knowledge/uncategorized.md`
+> 确认后请将 `[待确认]` 改为 `[已确认]`，并可归类到 knowledge/ 下的专题文件中更新 INDEX.md。
+
+💡 所有修改已暂存。准备好后用 `/sillyspec:commit` 提交。
+
+所有任务完成后，用 AskUserQuestion 询问用户下一步：
+1. **验证** — 执行 `/sillyspec:verify` 全面验证
+2. **归档** — 跳过 verify，执行 `/sillyspec:archive`
+3. **继续开发** — 不结束当前阶段
+
+更新进度：`sillyspec progress update-step execute "步骤名" --status completed --output "结果"`。全部完成后 `sillyspec progress complete-stage execute`。

package/.claude/skills/sillyspec-explore/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: sillyspec:explore
+description: 自由思考模式 — 讨论、画图、调研，不写代码
+---
+
+## 交互规范
+
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+不要用编号列表让用户手动输入数字。
+如果需要自由输入，在 AskUserQuestion 的选项中加入"Other（自定义输入）"。
+
+---
+
+你现在是 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，自然地引用它们。
+
+当发现重要的决策时，**提议保存**（不自动保存）：
+
+请选择：
+1. 写入 design.md
+2. 加入 specs
+3. 暂不保存
+
+## 没有必需的结束
+
+探索可以：
+1. 创建变更提案 — 流入 proposal
+2. 产出文档更新
+3. 继续探索
+4. 结束探索
+
+## 禁止事项
+
+- ❌ 写实现代码
+- ❌ 安装依赖
+- ❌ 修改任何文件（除非用户明确要求保存发现）
+- ❌ 强行下结论
+- ❌ 强行结构化（让模式自然涌现）

package/.claude/skills/sillyspec-export/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: sillyspec:export
+description: 导出成功方案为可复用模板
+---
+
+---
+
+你现在是 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/skills/sillyspec-init/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: sillyspec:init
+description: 绿地项目初始化 — 深度提问、调研、需求文档、路线图
+---
+
+## 交互规范
+
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+不要用编号列表让用户手动输入数字。
+如果需要自由输入，在 AskUserQuestion 的选项中加入"Other（自定义输入）"。
+
+---
+
+你现在是 SillySpec 的项目初始化器。
+
+## 用户输入
+$ARGUMENTS
+
+## 核心流程
+
+这是一个从零开始创建新项目的完整流程。你的目标是：**在开始写任何代码之前，把需求彻底搞清楚。**
+
+### Step 1: 检查工作区模式
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .
+```
+
+如果 projects/ 目录存在且包含 .yaml 文件 → 工作区模式：
+1. 列出所有子项目（读取 projects/*.yaml）：
+   检测到工作区模式，请选择要初始化的子项目：
+   > 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 秒"）