sillyspec 3.8.5 → 3.8.7

package/templates/explore.md

@@ -0,0 +1,59 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 写实现代码
+- ❌ 安装依赖
+- ❌ 修改文件（除非用户明确要求保存发现）
+- ❌ 强行下结论或强行结构化
+
+## 话题
+$ARGUMENTS
+
+---
+
+## 这是什么模式
+
+**探索模式用于思考，不用于实现。** 读文件、搜代码、调查代码库，但绝对不能写代码。没有固定步骤、没有必需的输出。
+
+## 姿态
+
+- **好奇不说教** — 问自然产生的问题
+- **开放式线程** — 展示多个有趣方向
+- **可视化** — 大量使用 ASCII 图表
+- **自适应** — 追随有趣线索随时转向
+- **务实** — 探索实际代码库，不只纸上谈兵
+
+## 上下文感知
+
+```bash
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+cat .sillyspec/{REQUIREMENTS,ROADMAP}.md 2>/dev/null
+cat .sillyspec/docs/*/scan/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null
+cat .sillyspec/knowledge/INDEX.md 2>/dev/null
+```
+
+有进行中变更时读取其 design/tasks，自然引用。发现重要决策时可提议保存（不自动保存）。
+
+## MCP 能力（按需使用）
+
+检查当前可用工具列表中是否存在 MCP 工具（Context7/浏览器/数据库/搜索等），不依赖配置文件路径。
+
+- 有 Context7 → 探索时查询最新文档，验证技术方案的可行性
+- 有浏览器 MCP → 可浏览相关网站、查竞品实现
+- 有搜索 MCP → 搜索技术方案、最佳实践
+- 无 MCP → 使用 web search
+
+## 话题升级提示
+
+探索过程中，当对话达到一定深度时（讨论了 5+ 轮、或涉及具体实现方案、或用户表达"试试看"/"能不能做"/"怎么搞"），主动用 AskUserQuestion 提示用户：
+
+1. **🧠 头脑风暴** — `/sillyspec:brainstorm` 深度探索需求和方案
+2. **⚡ 快速执行** — `/sillyspec:quick` 直接动手做
+4. **🔍 继续探索** — 还没聊透，继续
+
+不需要每次都提示，只在对话**明显转向执行意图**时触发。纯讨论、提问、查资料时不要打断。
+
+## 没有必需的结束
+
+探索可以创建变更提案、产出文档、继续探索或结束。

package/templates/export.md

@@ -0,0 +1,21 @@
+## 核心约束（必须遵守）
+- ❌ 修改任何文件（只读）
+
+## 参数解析
+`$ARGUMENTS`：变更名 + 可选 `--to` 输出路径（默认 `~/.sillyspec/templates/<change-name>/`）
+
+---
+
+## 流程
+
+1. **读取变更文件：** 
+   - 先检查根目录：`cat .sillyspec/changes/$ARGUMENTS/{design}.md 2>/dev/null`
+   - 根目录没有 → 检查子项目：遍历 `projects/*.yaml` 中的子项目路径，查找 `$ARGUMENTS`
+2. **清理为通用模板：** 移除项目特定信息，保留通用设计方案，添加 `notes.md` 使用建议。
+3. **导出：** `mkdir -p ~/.sillyspec/templates/<change-name>` 并复制文件。
+4. **确认：** 展示摘要和模板路径。
+
+### 最后说：
+
+> ✅ 已导出到 `~/.sillyspec/templates/<change-name>/`
+> 其他项目使用：`/sillyspec:brainstorm` → AI 自动发现并建议复用

package/templates/init.md

@@ -0,0 +1,61 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 写任何实现代码
+- ❌ 安装任何依赖
+- ❌ 一次问多个问题
+- ❌ 接受模糊需求（❌"好用" → ✅"首屏加载 < 2 秒"）
+
+## 用户输入
+$ARGUMENTS
+
+---
+
+## 流程
+
+### Step 1: 检查工作区模式
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .
+```
+
+有 `projects` → 工作区模式：AskUserQuestion 选子项目，切换到子项目目录执行。
+
+### Step 2: 检查项目状态
+
+```bash
+ls -la
+```
+
+已有代码/配置 → 提示用 `/sillyspec:scan`。空目录 → 继续。
+
+### Step 3: 深度提问（一次一个问题）
+
+按需探索（不是每个都要）：项目本质 → 核心功能 → 技术偏好 → 非功能需求 → 设计偏好 → 约束 → 不在范围内。
+
+### Step 4: 技术选型（如需要）
+
+用户无明确偏好时，推荐 2-3 套技术栈并列优劣和推荐理由。可选快速调研选定框架的版本、生态、已知坑。
+
+### Step 5: 生成文档
+
+**`REQUIREMENTS.md`：** 概述、目标用户、功能需求（P0/P1/P2）、非功能需求、不在范围内、技术选型表。
+
+**`ROADMAP.md`：** Phase 分阶段路线图（目标 + 交付物）。
+
+**`PROJECT.md`：** 项目名、一句话描述、状态。
+
+### Step 6: Git 初始化
+
+```bash
+git init && git add .
+```
+
+💡 项目已初始化并暂存。准备好后用 `/sillyspec:commit` 提交。
+
+### 最后说：
+
+> ✅ 项目初始化完成！
+> 生成文件：PROJECT.md、REQUIREMENTS.md、ROADMAP.md
+> 下一步：`/sillyspec:brainstorm "Phase 1: xxx"` 或直接告诉我改什么

package/templates/plan.md

@@ -0,0 +1,146 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 写实现代码（只写计划中的代码示例）
+- ❌ 每个步骤缺验证命令和预期输出
+- ❌ 编造表名、字段名（必须来自 ARCHITECTURE.md 或 design.md）
+
+
+
+## 流程
+
+### 1. 加载上下文
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .
+```
+
+**工作区模式：** 加载 CODEBASE-OVERVIEW.md + 共享规范 + 子项目的 CONVENTIONS/ARCHITECTURE/STACK + REQUIREMENTS.md。
+
+**单项目模式：**
+```bash
+LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
+cat "$LATEST"/{design,tasks}.md 2>/dev/null
+cat .sillyspec/docs/<project>/scan/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null
+cat .sillyspec/REQUIREMENTS.md 2>/dev/null
+```
+
+### 1.5 锚定确认（必须完成）
+
+确认实际存在的文件（design / tasks），不存在的标注跳过。
+
+### 2. 逐任务展开
+
+把 tasks.md 每个 checkbox **保留 `- [ ]` 格式**并展开为任务描述，按 Wave 分组组织。工作区模式下每个 Task 标注所属项目。
+
+**输出格式要求（必须严格遵守）：**
+
+```markdown
+### Wave 1（并行，无依赖）
+- [ ] 添加用户创建接口
+  - 修改: `UserController.java`、`UserService.java`
+  - 参考: `RoleController.createRole`
+  - 步骤:
+    1. 写测试 UserControllerTest.testCreateUser
+    2. 运行测试确认失败
+    3. 写 UserController.createUser
+    4. 运行测试确认通过
+
+- [ ] 添加角色创建接口
+  - ...
+```
+
+**每个 Task 必须保留 `- [ ]` checkbox，这是 execute 阶段勾选完成状态的依据。** 禁止写成纯文本列表。
+
+**每个 Task 必须包含「步骤」字段，列出 TDD 执行顺序：**
+- 1. 写测试 → 2. 运行确认失败 → 3. 写代码 → 4. 运行确认通过
+
+**纯配置/数据/文档类任务可跳过 TDD，步骤简化为：1. 实现 → 2. 验证**
+
+**注意：不需要写精确方法签名和代码示例。** 方法签名和代码风格由 execute 阶段先读后写确认。plan 专注"做什么"和"执行顺序"。
+
+**每个 Task 包含：**
+- 精确文件路径（修改哪个文件）
+- 任务描述（做什么，一两句话说清楚）
+- 涉及已有类调用时，标注参考文件（如"参考 `RoleController.createRole`）
+- 依赖关系
+
+**注意：不需要写精确方法签名和代码示例。** 方法签名和代码风格由 execute 阶段先读后写确认。plan 专注"做什么"，execute 负责"怎么做"。
+
+### 3. 标注执行顺序
+
+按 Wave 分组，标注依赖关系：
+```markdown
+### Wave 1（并行，无依赖）
+- [ ] 添加用户创建接口
+  - 修改: `UserController.java`、`UserService.java`
+  - 参考: `RoleController.createRole`
+
+- [ ] 添加角色创建接口
+  - ...
+
+### Wave 2（依赖 Wave 1）
+- [ ] 添加用户列表查询（依赖用户创建完成）
+  - ...
+```
+
+### 4. 保存
+
+**直接覆盖** `.sillyspec/changes/<变更名>/tasks.md`。不再生成单独的 plan.md 文件。
+
+### 5. E2E 测试规划
+
+识别 design.md 中是否有 UI 交互功能（页面跳转、表单提交、按钮操作等），如有则：
+
+**检测测试能力（按优先级）：**
+```bash
+# 优先级 1：专业 E2E 框架
+cat package.json 2>/dev/null | grep -E "playwright|cypress" ; ls node_modules/playwright node_modules/cypress 2>/dev/null
+# 优先级 2：通用测试框架
+cat package.json 2>/dev/null | grep -E "jest|vitest|mocha" ; ls node_modules/jest node_modules/vitest 2>/dev/null
+# 优先级 3：浏览器 MCP
+cat .claude/mcp.json .cursor/mcp.json 2>/dev/null | grep -i "browser\|chrome\|devtools"
+```
+
+- **有 E2E/测试框架** → tasks.md 中添加 E2E 测试任务（同波次，编码后编写）
+- **无框架但有浏览器 MCP** → tasks.md 中添加"编写 e2e-steps.md 测试步骤"任务
+- **什么都没有** → 提示用户运行 `sillyspec setup` 安装 MCP 工具，或手动安装测试框架
+
+纯后端/无 UI 的变更跳过此步骤。
+
+### 6. 自检门控
+
+- [ ] 每个 task 有具体文件路径？
+- [ ] 标注了 Wave 和依赖关系？
+- [ ] 涉及 UI 的任务是否有对应的 E2E 测试任务？
+- [ ] **design.md 中的每个功能点是否都在 tasks.md 中有对应任务？**
+
+### 6.5 设计完整性对照（必须完成）
+
+逐条检查 design.md 中的功能描述，确保每个功能点都有对应的 task。特别关注：
+
+1. **逐功能点扫描：** 将 design.md 中描述的每个功能点（含子功能）列出，与 tasks.md 逐条对照
+2. **前后端覆盖检查：** 涉及前后端协作的功能，确认前端和后端各有独立 task
+3. **遗漏项处理：** 发现未覆盖的功能点 → 追加 task 到对应 Wave，并提示用户确认
+
+**执行方式：**
+```
+从 design.md 提取功能点清单：
+  功能 A（后端接口）
+  功能 B（前端页面）
+  功能 C（前后端联动）
+
+与 tasks.md 对照：
+  ✅ 功能 A → task-3
+  ❌ 功能 B → 无对应 task → 追加
+  ⚠️ 功能 C → 只有后端 task，缺少前端 task → 追加
+```
+
+发现遗漏时用 AskUserQuestion 确认追加内容，用户确认后再写入 tasks.md。
+
+### 7. 完成
+
+```bash
+cat .sillyspec/STATE.md 2>/dev/null
+```

package/templates/quick.md

@@ -0,0 +1,135 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 不写测试（底线是仍然要写测试）
+- ❌ 修改无关文件
+- ❌ 跳过测试因为"任务太简单"
+
+## 用法
+
+- `/sillyspec:quick "修复用户创建接口漏了手机号校验"` — 独立记录到按用户名隔离的 QUICKLOG
+- `/sillyspec:quick --change user-module "修复用户创建接口漏了手机号校验"` — 追加到 user-module 变更的 tasks.md
+
+## 任务
+$ARGUMENTS
+
+---
+
+## 流程
+
+1. **解析参数：** 检查是否携带 `--change <变更名>`，确定记录方式
+1.5 **归属检查：** 如果没有 `--change` 参数，检查 `.sillyspec/changes/` 下是否有非 archive 的活跃变更目录：
+   ```bash
+   ls -d .sillyspec/changes/*/ 2>/dev/null | grep -v archive
+   ```
+   - 有活跃变更 → AskUserQuestion 询问本次 quick 归属哪个变更，默认选当前活跃的
+   - 用户选择后将日志写入 `.sillyspec/changes/<变更名>/quicklog/` 而非独立 QUICKLOG
+   - 用户选择"无归属" → 走原有的独立 QUICKLOG 流程
+   - 无活跃变更 → 走原有的独立 QUICKLOG 流程
+2. **理解任务：** 模糊则问一个问题确认
+3. **加载上下文：** `cat .sillyspec/docs/<project>/scan/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null`
+3b. **编码规范扫描：** 检测项目中的编码规范配置文件（`.eslintrc*`、`.prettierrc*`、`tsconfig.json`、`.editorconfig`、`tailwind.config.*`、`CONTRIBUTING.md`），提取关键规则生成摘要。写作代码时必须严格遵守这些规则（分号/引号/缩进/命名风格等），如不确定优先遵守规范约束。
+4. **知识库查询（强制步骤）：**
+   ```bash
+   cat .sillyspec/knowledge/INDEX.md 2>/dev/null
+   ```
+   根据当前任务描述中的关键词匹配 INDEX.md 条目，命中时 `cat` 对应知识文件，将内容纳入后续开发考量。未命中则跳过。
+   **MCP 检测：** 检查当前可用工具列表中是否存在 MCP 工具（Context7/浏览器/数据库/搜索等），根据检测结果动态利用：
+   - 有 Context7 → 查询不熟悉库/API 的最新文档
+   - 有浏览器 MCP → 验证页面改动效果
+   - 有数据库 MCP → 查询表结构和数据验证（只读）
+   - 有搜索 MCP → 搜索最佳实践和解决方案
+   - 有其他 MCP → 按任务需要灵活使用
+   - 无 MCP → 使用 web search
+5. **先读后写：** 调用已有方法前 `cat` 源文件确认签名，`grep` 确认方法存在
+6. **数据操作安全：** 任何改变现有数据的操作（非 SELECT 的数据库操作）必须暂停并报告给用户确认，不得自动执行。新建表不受此限制
+6. **TDD 执行：**
+   ```
+   🔴 RED    → 先写测试，运行确认失败
+   🟢 GREEN  → 写最少代码让测试通过
+   🔵 REFACTOR → 清理，保持测试通过
+   ✅ STAGE   → git add 暂存（测试文件必须包含在暂存中）
+   ```
+   测试文件必须保留在项目中，不能删除。违反 TDD → 删掉代码从测试重新开始。
+   - 纯配置/数据/文档可跳过 TDD
+   - 其他情况一律走 TDD
+7. **运行测试：** 先检查 local.yaml 构建命令配置：
+```bash
+cat .sillyspec/local.yaml 2>/dev/null
+```
+如果有则使用 local.yaml 中的命令；否则使用默认命令：
+```bash
+mvn test -pl <模块> -Dtest=<测试类> 2>/dev/null || ./gradlew test --tests <测试类> 2>/dev/null || pnpm test 2>/dev/null || npm test 2>/dev/null || pytest <测试文件> 2>/dev/null
+```
+8. **Lint 校验（如项目配置了）：** 写完代码后、暂存前，运行项目的 lint 工具验证代码质量：
+   ```bash
+   # 检测并运行可用的 lint 工具
+   npx eslint <修改的文件> 2>/dev/null || \
+   npx prettier --check <修改的文件> 2>/dev/null || \
+   npx tsc --noEmit 2>/dev/null || \
+   true  # 没有 lint 工具则跳过
+   ```
+   - **有报错 → 自动修复：** `npx eslint --fix <修改的文件>` / `npx prettier --write <修改的文件>`
+   - **修复后仍有报错 → 在 QUICKLOG 中标注，提醒用户手动处理**
+   - **工作区模式下，在子项目目录中执行，不要在主项目目录执行**
+9. **Git 暂存：** `git add -A`。**不要 commit**，由用户通过 `/sillyspec:commit` 统一提交。**工作区模式下，确认当前在正确的子项目目录中执行暂存。**
+10. **记录：**
+   - **有 `--change`：** 在 `.sillyspec/changes/<变更名>/tasks.md` 追加 task 并勾选，**记录精确到秒的时间戳**：
+
+```
+- [x] [YYYY-MM-DD HH:MM:SS] 任务描述
+```
+   - **无 `--change` 但步骤 1.5 确认了归属变更：** 记录到 `.sillyspec/changes/<变更名>/quicklog/YYYY-MM-DD-HHMMSS-任务简述.md`，格式：
+
+```markdown
+# quick: 任务描述
+
+- 时间：YYYY-MM-DD HH:MM:SS
+- 关联变更：<变更名>
+- 修改文件：
+  - `path/to/file1`
+  - `path/to/file2`
+- 改动说明：（2-3 句描述做了什么）
+- 发现的坑：（如有，简要记录）
+```
+
+   - **无 `--change` 且无归属：** 记录到 `.sillyspec/quicklog/QUICKLOG-<git用户名>.md`（见下方规则）
+10. **检查复杂度：** 任务比预期复杂 → 建议用完整流程
+
+11. **记录发现的坑：** 执行过程中如果发现项目特有的规律、陷阱或约定（如"某方法参数顺序容易搞反"、"某表有隐藏软删除字段"），追加到 `.sillyspec/knowledge/uncategorized.md`，格式：
+
+```markdown
+### [待确认] {简短标题}
+> 来源：quick / {时间戳}
+
+{坑的具体描述}
+```
+
+**工作区模式下：** 只影响当前子项目 → 写入当前子项目 `.sillyspec/knowledge/uncategorized.md`；影响多个子项目 → 写入工作区根目录 `.sillyspec/knowledge/uncategorized.md`。
+
+12. **知识库审阅提示：** 如果本次执行向 knowledge/ 写入了新条目，提示用户：
+> 📚 本次 quick 发现了新知识，请审阅：`cat .sillyspec/knowledge/uncategorized.md`
+> 确认后请将 `[待确认]` 改为 `[已确认]`，并可归类到 knowledge/ 下的专题文件中更新 INDEX.md。
+
+### QUICKLOG 规则
+
+**按 git 用户名隔离，避免多人同时操作冲突：**
+
+```bash
+USER=$(git config user.name 2>/dev/null || echo "default")
+LOG_FILE=".sillyspec/quicklog/QUICKLOG-${USER}.md"
+```
+
+文件路径：`$LOG_FILE`
+
+**追加记录格式（时间精确到秒）：**
+```markdown
+## YYYY-MM-DD HH:MM:SS | fix: 任务描述
+- 文件：`修改的文件列表`
+- 关联归档：`相关的已归档变更名`（如有）
+```
+
+**文件轮转：** 追加前检查文件大小，超过 500 行则：
+1. 将当前文件重命名为 `QUICKLOG-${USER}-YYYY-MM-DD.md`
+2. 创建新的空 `QUICKLOG-${USER}.md`

package/templates/scan-quick.md

@@ -0,0 +1,49 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+> 本模板由 `/sillyspec:scan --quick` 触发。如需完整深度扫描，使用 `/sillyspec:scan`。
+
+## 核心约束（必须遵守）
+- ❌ 修改任何代码
+- ❌ 编造文件路径或代码模式（必须包含真实路径）
+- ❌ 读源码文件（快扫只读配置和目录）
+
+## 快速扫描流程
+
+### Step 1: 检查工作区模式
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .
+```
+
+有 `projects` 字段 → 工作区模式：逐个子项目快扫。
+
+### Step 2: 读配置文件
+
+```bash
+cat package.json tsconfig.json requirements.txt Cargo.toml go.mod pom.xml build.gradle 2>/dev/null
+find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null
+```
+
+### Step 3: 生成文档
+
+`mkdir -p .sillyspec/codebase`，生成 4 份文档：
+
+1. **ARCHITECTURE.md** — 架构 + 技术栈（合并原 STACK.md）
+2. **STRUCTURE.md** — 目录结构（`find . -type f | head -200`）
+3. **CONVENTIONS.md** — 空骨架文件，含章节标题（注意事项、代码风格等），供后续 quick/execute 追加
+4. **PROJECT.md** — 项目概览
+
+### Step 4: 暂存修改
+
+```bash
+git add .sillyspec/
+```
+
+工作区模式在每个子项目分别暂存。
+
+💡 扫描产出已暂存。准备好后用 `/sillyspec:commit` 提交。
+
+### 完成
+
+提示用户：快扫只提取基础信息。如需完整代码规范（框架规则、实体继承、代码风格），执行 `/sillyspec:scan` 进行深度扫描。

package/templates/scan.md

@@ -0,0 +1,156 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+你现在是 SillySpec 代码库扫描器（编排器）。**你不读源码，只编排子代理或串行执行。**
+
+## 参数处理
+- 空白 → 交互式引导（逐步询问）
+- `--deep` → 直接深度扫描
+- 其他 → 快速扫描该区域
+
+
+
+## 交互式引导（参数为空时）
+
+### 检查工作区 & 已有文档
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .   # 有子项目配置 → 工作区模式
+ls .sillyspec/docs/<project>/scan/ 2>/dev/null       # 检查已有文档
+wc -l .sillyspec/docs/<project>/scan/*.md 2>/dev/null
+```
+
+- 已有 3 份 → 建议升级深度扫描
+- 已有 7 份 → 建议刷新或跳过
+- 工作区 → 逐个扫描 / 选子项目 / 退出
+
+### 选择扫描模式、范围、排除目录、确认
+按原流程交互，确认后进入扫描。
+
+---
+
+## 构建环境探测（主代理执行）
+
+```bash
+cat package.json pom.xml build.gradle go.mod Cargo.toml requirements.txt pyproject.toml Gemfile composer.json 2>/dev/null
+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`（临时文件，扫描完删除）。
+
+---
+
+## 深度扫描
+
+`mkdir -p .sillyspec/codebase`
+
+### 断点续扫
+
+```bash
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/docs/<project>/scan/${f}.md" ] && echo "✅ ${f}.md" || echo "⬜ ${f}.md"
+done
+```
+
+只生成缺失的文档。
+
+### 检测子代理可用性
+检查是否有 Task/Spawn 工具。有 → 子代理模式，无 → 串行模式。
+
+---
+
+### 子代理模式（4 个并行）
+
+#### Agent 1: tech → ARCHITECTURE.md
+扫描技术栈 + 数据库 Schema + 架构模式。参考 `_env-detect.md`。
+用 grep/rg 搜索（`@Entity`、`schema.prisma`、`models.py` 等），**禁止读源码全文**。
+Schema 只记表名+说明+字段数。含 `## 技术栈` `## 架构概览` `## 数据模型（摘要）`。路径用反引号，不编造。
+
+#### Agent 2: conventions → CONVENTIONS.md
+扫描框架隐形规则 + 实体继承 + 代码风格。参考 `_env-detect.md`。
+用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**。
+根据检测到的语言/框架自行决定搜索什么模式，提取 3-5 个典型示例。
+含 `## 框架隐形规则` `## 实体继承规范` `## 代码风格`。路径用反引号，不编造。
+
+#### Agent 3: structure → STRUCTURE.md + INTEGRATIONS.md
+扫描目录结构 + 外部集成。参考 `_env-detect.md`。
+用 find/ls/tree 和 grep，**禁止读源码全文**。
+搜索 API 调用、MQ 配置、缓存、第三方 SDK。STRUCTURE.md 含目录树+模块说明。INTEGRATIONS.md 按类型分组。路径用反引号，不编造。
+
+#### Agent 4: quality → TESTING.md + CONCERNS.md + PROJECT.md
+扫描测试现状 + 技术债务 + 项目概览。参考 `_env-detect.md`。
+用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**。
+TESTING.md 含测试结构。CONCERNS.md 按严重程度分组。PROJECT.md 含项目信息。路径用反引号，不编造。
+
+---
+
+### 串行模式（降级）
+无子代理时，按 tech → conventions → structure → quality 顺序执行。
+每个 area 完成后**立即写文件**，下一个 area 开始前清除源码上下文。
+
+---
+
+## 工作区模式
+对每个子项目：cd → 环境探测 → 扫描 → cd 回工作区。
+全部完成后汇总 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`（只读各子项目的 ARCHITECTURE.md + CONVENTIONS.md）。
+
+---
+
+## 扫描完成
+
+```bash
+# 路径校验
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/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'
+# 未分类知识
+
+> execute/quick 执行中发现的坑暂存于此，用户审阅后归类到对应文件并更新 INDEX.md。
+
+EOF
+fi
+
+# 记录状态
+cat > .sillyspec/STATE.md << 'EOF'
+# 项目状态
+
+## 最近活动
+- $(date '+%Y-%m-%d %H:%M:%S') scan 完成
+EOF
+
+# 清理
+rm -f .sillyspec/docs/<project>/scan/_env-detect.md
+git add .sillyspec/
+```
+
+💡 扫描产出已暂存。准备好后用 `/sillyspec:commit` 提交。
+
+### 自检门控
+- [ ] ARCHITECTURE.md：技术栈 + Schema 摘要？
+- [ ] CONVENTIONS.md：隐形规则 + 代码风格？
+- [ ] STRUCTURE.md：目录结构？
+- [ ] INTEGRATIONS.md：外部依赖？
+- [ ] TESTING.md：测试现状？
+- [ ] CONCERNS.md：技术债务？
+- [ ] PROJECT.md：项目概览？
+
+## 绝对规则
+- ❌ 修改代码 / 编造路径 / 主代理读源码全文
+- ✅ 交互模式每步等用户 / 文档只写 `.sillyspec/docs/<project>/scan/`