sillyspec 3.7.13 → 3.7.15

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

@@ -0,0 +1,111 @@
+---
+name: sillyspec:resume
+description: 恢复工作 — 从中断处继续
+---
+
+## 交互规范
+
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+不要用编号列表让用户手动输入数字。
+如果需要自由输入，在 AskUserQuestion 的选项中加入"Other（自定义输入）"。
+
+你现在是 SillySpec 的恢复管理器。
+
+## 流程
+
+### 1. 读取 progress.json
+
+```bash
+sillyspec progress show 2>/dev/null
+```
+
+### 2. 如果有 progress.json
+
+直接从 progress.json 中提取并展示：
+
+> 🔄 工作状态恢复
+>
+> **当前变更**：<名称>
+> **当前阶段**：<阶段名> <状态>
+> **下一步**：<命令>
+>
+> **阶段进度**（大模块）：
+> | 阶段 | 状态 |
+> |---|---|
+> | stage-1 列表页 | ✅ |
+> | stage-2 表单页 | 🔄 execute (2/6) |
+> | stage-3 详情页 | ⬜ |
+>
+> **关键决策**：
+> - xxx
+>
+> **下一步命令**：
+> `/sillyspec:execute reward-punishment/stage-2`
+
+**不需要执行 Git 操作或文件探测。** progress.json 已经包含所有信息。
+
+使用 `sillyspec progress show` 查看。
+
+然后问用户：
+   1. 直接继续执行下一步
+   2. 查看更多细节
+
+### 3. 如果没有 progress.json
+
+**不要直接说"没有记录"。** 自动探测项目状态：
+
+```bash
+# 检查主变更
+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 2>/dev/null
+
+# 检查计划文件
+ls -t .sillyspec/plans/*.md | head -1 2>/dev/null
+
+# 检查需求/路线图
+cat .sillyspec/REQUIREMENTS.md 2>/dev/null
+cat .sillyspec/ROADMAP.md 2>/dev/null
+```
+
+#### 如果检测到 MASTER.md（大模块）
+
+检查各阶段状态并输出阶段进度表（同步骤 2 格式）。
+
+同时**运行 `sillyspec progress init`**，将探测到的信息写入 progress.json，后续命令执行时会自动更新。
+
+#### 如果是普通变更（无 MASTER.md）
+
+根据探测结果推断：
+
+| 探测到的文件 | 推断阶段 | 建议操作 |
+|---|---|---|
+| 无任何 .sillyspec/ 内容 | 未开始 | `/sillyspec:init` 或 `/sillyspec:scan` |
+| 有 SCAN-RAW.md 但缺失文档 | 扫描中断 | `/sillyspec:scan --deep`（断点续扫） |
+| 有 codebase/ 但文档不全（快扫 3 份缺失） | 快扫中断 | `/sillyspec:scan`（补全缺失文档） |
+| 有 codebase/ 7 份齐全但无 changes/ | 已扫描，未开始需求 | `/sillyspec:brainstorm "想法"` |
+| 有 REQUIREMENTS.md 但无 changes/ | 绿地项目，已有需求 | `/sillyspec:brainstorm "想法"` |
+| changes/ 下有 proposal，无 tasks | 已有规范，待计划 | `/sillyspec:plan` |
+| changes/ 下有 tasks，有未完成 checkbox | 执行中 | `/sillyspec:execute` |
+| tasks.md 全部完成 | 待验证 | `/sillyspec:verify` |
+
+**扫描中断检测逻辑：**
+- 有 `SCAN-RAW.md` → 说明深度扫描预处理已完成，检查 7 份文档缺哪些
+- 有部分 codebase 文档（如只有 STACK 和 STRUCTURE）→ 说明快扫或深扫中断
+- 缺失的文档列表直接展示给用户，告知 `/sillyspec:scan` 会自动跳过已存在的文档
+
+**同时运行 `sillyspec progress init`** 记录推断的状态。
+
+### 4. 关键原则
+
+- **不需要 HANDOFF.json**。progress.json 是唯一的恢复数据源。
+- **progress.json 不需要 Git 提交**（已在 .runtime/ 下，被 .gitignore 忽略）。
+- **每次命令执行完自动更新 progress.json**（通过 `sillyspec progress` CLI），不需要用户手动保存。

package/{templates/scan.md → .claude/skills/sillyspec-scan/SKILL.md}

@@ -8,20 +8,13 @@
 - `--deep` → 直接深度扫描
 - 其他 → 快速扫描该区域
 
-## 状态检查（必须先执行）
+## 流程控制（必须先执行）
 
 ```bash
-cat .sillyspec/STATE.md 2>/dev/null
+sillyspec status --json
 ```
 
-**确定当前项目名：**
-```bash
-basename $(cat .sillyspec/projects/*.yaml 2>/dev/null | head -1) .yaml || basename $(pwd)
-```
-从 STATE.md 或 `projects/` 目录确定当前项目名，后续路径为 `.sillyspec/docs/<project>/`。
-
-有 STATE.md 且 phase 为 `scan` 或未记录 → 继续。
-其他 phase → STATE.md 中记录的下一步命令为准。
+非 `init` phase → 以 CLI 返回为准决定下一步。
 
 ---
 
@@ -30,9 +23,9 @@ basename $(cat .sillyspec/projects/*.yaml 2>/dev/null | head -1) .yaml || basena
 ### 检查工作区 & 已有文档
 
 ```bash
-cat .sillyspec/config.yaml 2>/dev/null   # 有 projects → 工作区模式
-ls .sillyspec/docs/<project>/scan/ 2>/dev/null       # 检查已有文档
-wc -l .sillyspec/docs/<project>/scan/*.md 2>/dev/null
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .   # 有 .yaml → 工作区模式
+ls docs/*/scan/ 2>/dev/null       # 检查已有文档
+wc -l docs/*/scan/*.md 2>/dev/null
 ```
 
 - 已有 3 份 → 建议升级深度扫描
@@ -51,19 +44,23 @@ cat package.json pom.xml build.gradle go.mod Cargo.toml requirements.txt pyproje
 find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null
 ```
 
-结果保存到 `.sillyspec/docs/<project>/scan/_env-detect.md`（临时文件，扫描完删除）。
+结果保存到 `docs/<project>/scan/_env-detect.md`（临时文件，扫描完删除）。
 
 ---
 
 ## 深度扫描
 
-`mkdir -p .sillyspec/codebase`
+```bash
+PROJECT=$(python3 -c "import sys,json; print(json.load(open('.sillyspec/.runtime/progress.json')).get('project',''))" 2>/dev/null || basename "$(pwd)")
+mkdir -p docs/${PROJECT}/scan
+```
 
 ### 断点续扫
 
 ```bash
+PROJECT=$(python3 -c "import sys,json; print(json.load(open('.sillyspec/.runtime/progress.json')).get('project',''))" 2>/dev/null || basename "$(pwd)")
 for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
-  [ -f ".sillyspec/docs/<project>/scan/${f}.md" ] && echo "✅ ${f}.md" || echo "⬜ ${f}.md"
+  [ -f "docs/${PROJECT}/scan/${f}.md" ] && echo "✅ ${f}.md" || echo "⬜ ${f}.md"
 done
 ```
 
@@ -115,55 +112,20 @@ TESTING.md 含测试结构。CONCERNS.md 按严重程度分组。PROJECT.md 含
 
 ```bash
 # 路径校验
+PROJECT=$(python3 -c "import sys,json; print(json.load(open('.sillyspec/.runtime/progress.json')).get('project',''))" 2>/dev/null || basename "$(pwd)")
 for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
-  [ -f ".sillyspec/docs/<project>/scan/${f}.md" ] && echo "✅ ${f}.md"
+  [ -f "docs/${PROJECT}/scan/${f}.md" ] && echo "✅ ${f}.md"
 done
 
-# 生成知识库骨架
-mkdir -p .sillyspec/knowledge
-if [ ! -f ".sillyspec/knowledge/INDEX.md" ]; then
-  cat > .sillyspec/knowledge/INDEX.md << 'EOF'
-# Knowledge Index
-
-> 子代理任务开始前查询此文件，按关键词匹配，只读命中的知识文件。
-> execute/quick 执行中发现的坑自动追加到 uncategorized.md，经用户确认后归类到对应文件。
-
-<!-- 格式：关键词1|关键词2|关键词3 → 文件路径 -->
-<!-- 示例：mybatis-plus|分页|Page → pagination.md -->
-<!-- 示例：跨域|CORS|preflight → cors.md -->
-EOF
-fi
-if [ ! -f ".sillyspec/knowledge/uncategorized.md" ]; then
-  cat > .sillyspec/knowledge/uncategorized.md << 'EOF'
-# 未分类知识
+# 验证 CLI
+sillyspec status --json   # 应返回 phase: "brainstorm"
+sillyspec next            # 推荐给用户
 
-> execute/quick 执行中发现的坑暂存于此，用户审阅后归类到对应文件并更新 INDEX.md。
-
-EOF
-fi
-
-# 更新状态
-cat > .sillyspec/STATE.md << 'EOF'
-# 项目状态
-
-## 当前阶段
-- 阶段：scan ✅
-- 下一步：/sillyspec:brainstorm
-
-## 关键决策
-- （扫描中发现的技术决策）
-
-## 历史记录
-- $(date '+%Y-%m-%d %H:%M:%S') scan 完成
-EOF
-
-# 清理
-rm -f .sillyspec/docs/<project>/scan/_env-detect.md
-git add .sillyspec/
+# 清理 + 提交
+rm -f docs/${PROJECT}/scan/_env-detect.md
+git add . && git commit -m "chore: sillyspec scan - codebase mapped"
 ```
 
-💡 扫描产出已暂存。准备好后用 `/sillyspec:commit` 提交。
-
 ### 自检门控
 - [ ] ARCHITECTURE.md：技术栈 + Schema 摘要？
 - [ ] CONVENTIONS.md：隐形规则 + 代码风格？
@@ -175,4 +137,4 @@ git add .sillyspec/
 
 ## 绝对规则
 - ❌ 修改代码 / 编造路径 / 主代理读源码全文
-- ✅ 交互模式每步等用户 / 文档只写 `.sillyspec/docs/<project>/scan/`
+- ✅ 交互模式每步等用户 / 文档只写 `docs/<project>/scan/`

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

@@ -0,0 +1,54 @@
+---
+name: sillyspec:state
+description: 查看当前工作状态 — 显示 progress.json 内容
+---
+
+你现在是 SillySpec 的状态查看器。
+
+## 流程
+
+### 1. 读取 progress.json
+
+```bash
+sillyspec progress show 2>/dev/null
+```
+
+### 2. 如果有 progress.json
+
+格式化展示当前状态：
+
+> 📊 当前状态
+>
+> **变更**：<名称>
+> **阶段**：<当前阶段>
+> **进度**：<具体进度>
+> **下一步**：<命令>
+>
+> **阶段进度**（大模块）：
+> （显示各阶段状态表）
+>
+> **关键决策**：
+> - xxx
+>
+> **阻塞项**：
+> - xxx（如无则省略）
+
+### 3. 如果没有 progress.json
+
+提示用户项目还没有开始，或 progress.json 尚未生成：
+
+> 📊 还没有工作记录。
+>
+> 开始使用：
+> - 新项目：`/sillyspec:init`
+> - 已有项目：`/sillyspec:scan`
+> - 恢复中断的工作：`/sillyspec:resume`
+>
+> progress.json 会在 `sillyspec init` 时自动创建。
+
+### 注意
+
+- 这是只读命令，**不修改任何文件**
+- `/sillyspec:status` 查看项目整体进度（change 文件级别）
+- `/sillyspec:state` 查看当前工作状态（progress.json 级别）
+- 两者互补：status 看"有什么"，state 看"在做什么"

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

@@ -0,0 +1,131 @@
+---
+name: sillyspec:status
+description: 查看项目进度和状态
+---
+
+---
+
+你现在是 SillySpec 的状态检查器。
+
+## 流程
+
+### 0: 检查工作区模式
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .
+```
+
+**如果是工作区模式：**
+
+1. 读取 projects/*.yaml 获取子项目列表：
+   ```bash
+   for f in .sillyspec/projects/*.yaml; do
+     [ -f "$f" ] || continue
+     proj_name=$(basename "$f" .yaml)
+     proj_path=$(grep '^path:' "$f" | head -1 | sed 's/^path:[[:space:]]*//')
+   done
+   ```
+2. 对每个子项目执行 Step 1-5 的检查（在子项目目录下）
+3. 检查共享规范：
+   ```bash
+   ls .sillyspec/shared/ 2>/dev/null
+   ```
+4. 检查工作区概览：
+   ```bash
+   ls .sillyspec/workspace/ 2>/dev/null
+   ```
+5. 输出汇总：
+
+```
+🏢 工作区状态
+
+📦 子项目：
+
+  ✅ frontend  ./frontend
+     📋 项目：已初始化
+     📂 代码库：已扫描（7 份文档）
+     🔄 进行中：1 个变更
+        - [user-auth] Phase 3 (Execute) — tasks 5/8
+     ✅ 已归档：3 个变更
+
+  ⚠️ backend   ./backend
+     📋 项目：已初始化
+     📂 代码库：未扫描
+     🔄 进行中：0 个变更
+
+📄 共享规范：2 份
+  - api-contract.md
+  - data-models.md
+
+💡 下一步：
+  - 扫描 backend：/sillyspec:scan backend
+  - 继续开发：/sillyspec:continue
+```
+
+然后结束，不执行下面的单项目流程。
+
+**如果不是工作区模式：** 继续下面的单项目流程。
+
+### 1. 项目基础
+
+```bash
+cat .sillyspec/PROJECT.md 2>/dev/null || echo "未初始化"
+PROJECT=$(python3 -c "import sys,json; print(json.load(open('.sillyspec/.runtime/progress.json')).get('project',''))" 2>/dev/null || basename "$(pwd)")
+ls docs/${PROJECT}/scan/ 2>/dev/null | head -10
+cat .sillyspec/REQUIREMENTS.md 2>/dev/null | head -20
+cat .sillyspec/ROADMAP.md 2>/dev/null
+```
+
+### 2. 进行中的变更
+
+```bash
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+```
+
+对每个进行中的变更，检查文件完成度：
+- proposal.md ✅/❌
+- design.md ✅/❌
+- specs/requirements.md ✅/❌
+- tasks.md — X/Y 完成
+- 对应计划 .sillyspec/plans/ ✅/❌
+
+### 3. 归档历史
+
+```bash
+ls .sillyspec/changes/archive/ 2>/dev/null | wc -l
+```
+
+### 4. 中断状态
+
+```bash
+cat .sillyspec/HANDOFF.json 2>/dev/null
+```
+
+### 5. 代码库文档
+
+```bash
+PROJECT=$(python3 -c "import sys,json; print(json.load(open('.sillyspec/.runtime/progress.json')).get('project',''))" 2>/dev/null || basename "$(pwd)")
+ls docs/${PROJECT}/scan/ 2>/dev/null
+```
+
+### 6. 输出
+
+```
+📊 SillySpec 状态
+
+📋 项目：xxx（已初始化 / 未初始化）
+📂 代码库：已扫描（7 份文档）/ 未扫描
+
+🔄 进行中：N 个变更
+  - [change-1] Phase 3 (Execute) — tasks 5/8
+  - [change-2] Phase 2 (Propose) — 缺少 design.md
+
+✅ 已归档：N 个变更
+📝 设计文档：N 份
+📝 实现计划：N 份
+
+💡 下一步：/sillyspec:continue
+```
+
+## 绝对规则
+- 不修改任何文件

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

@@ -0,0 +1,146 @@
+---
+name: sillyspec:verify
+description: 验证实现 — 对照规范检查 + 测试套件
+---
+
+> **可选阶段。** execute 完成后会询问是否需要 verify，也可以手动调用。
+
+你现在是 SillySpec 的验证器。
+
+## 🛑 流程控制（必须先执行）
+
+**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
+
+```bash
+sillyspec status --json
+```
+
+**根据 CLI 返回的 phase 决定是否允许执行 verify：**
+- `phase: "verify"` → ✅ 可以继续
+- 其他 phase → ❌ 不允许跳步，提示用户运行 `sillyspec next` 获取正确步骤
+
+**不要跳过状态检查。不要自己推断阶段。以 CLI 为准。**
+
+## 流程
+
+### 1. 加载规范
+
+```bash
+LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
+cat "$LATEST/proposal.md"
+cat "$LATEST/design.md"
+cat "$LATEST/tasks.md"
+cat "$LATEST/specs/requirements.md" 2>/dev/null
+```
+
+### 1.5 锚定确认（必须完成）
+
+读取相关规范文件。对于存在的文件，确认理解；对于不存在的文件，标注跳过：
+
+```
+已读取并理解：
+- [x] proposal.md — 变更动机和范围（如果存在）
+- [x] design.md — 技术方案和文件变更（如果存在）
+- [x] tasks.md — 实现清单（如果存在）
+- [x] specs/requirements.md — 需求和场景（如果存在）
+
+所有可用上下文已加载，开始验证。
+```
+
+**文件不存在不是错误**。只确认实际存在的文件。不准跳过此步骤。
+
+### 2. 逐项检查 tasks.md
+
+对每个 checkbox 报告状态：
+- ✅ 已完成 / ❌ 未完成 / ⚠️ 部分完成
+
+### 3. 对照 design.md
+
+- 架构决策是否遵循？
+- 文件变更清单是否一致？
+- 数据模型是否符合？
+- API 设计是否符合？
+
+### 4. 运行完整测试套件（fresh run）
+
+```bash
+# 根据项目技术栈运行
+pnpm test 2>/dev/null || npm test 2>/dev/null || pytest 2>/dev/null || go test ./... 2>/dev/null
+```
+
+记录通过/失败数量。如有失败，分析原因。
+
+### 5. 代码质量扫描
+
+```bash
+# 搜索技术债务标记
+grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.tsx" --include="*.py" --include="*.js" 2>/dev/null | head -20
+```
+
+### 6. 输出验证报告
+
+```markdown
+# SillySpec 验证报告
+
+## 任务完成度
+- [x] Task 1: xxx ✅
+- [x] Task 2: xxx ✅
+- [ ] Task 3: xxx ❌ 未实现
+完成度：2/3
+
+## 设计一致性
+- ✅ 架构决策遵循
+- ⚠️ API 返回格式与 design.md 略有差异（缺少 error 字段）
+
+## 测试结果
+- passed: 42, failed: 3
+
+## 技术债务标记
+- src/auth/login.ts:15 // TODO: add rate limiting
+- src/auth/login.ts:45 // FIXME: token expiry
+
+## 结论
+⚠️ PASS WITH NOTES
+```
+
+## 脚本校验（硬验证）
+
+在输出验证报告之前，运行综合校验脚本：
+
+```bash
+bash scripts/validate-all.sh
+```
+
+将脚本输出纳入验证报告中的"设计一致性"部分。
+
+### 7. 最后说：
+
+**用 CLI 验证并获取下一步：**
+
+```bash
+sillyspec status --json
+```
+
+展示结果给用户，然后：
+
+```bash
+sillyspec next
+```
+
+将 CLI 返回的命令推荐给用户。**不要自己编建议。**
+
+### 8. 更新 progress.json
+
+verify 完成后，**必须自动更新进度**：
+```bash
+sillyspec progress complete-stage verify
+```
+
+- 当前阶段改为 `verify ✅` 或 `verify ⚠️`
+- 下一步改为 `/sillyspec:archive`（PASS 时）或 `修复后重新 /sillyspec:verify`
+- 如果是子阶段，更新阶段进度；如果全部阶段完成，下一步改为 `/sillyspec:archive`
+- 历史记录追加时间 + 验证结果
+
+## 绝对规则
+- 不修改任何代码
+- 只做检查和报告