sillyspec 3.1.0 → 3.2.1

package/.claude/commands/sillyspec/archive.md

@@ -56,6 +56,8 @@ $ARGUMENTS
 - **STATE.md：** 清除当前变更信息，历史记录追加归档完成
 - **Git 提交：** `git add .sillyspec/ && git commit -m "docs: archive sillyspec change <change-name>"`
 
+**工作区模式下：** 如果变更属于某个子项目，cd 到子项目目录执行 git commit。工作区根目录无 git 则跳过。
+
 ### 最后说：
 
 > ✅ 变更 `<change-name>` 已归档到 `archive/YYYY-MM-DD-<change-name>/`。继续：`/sillyspec:brainstorm "新想法"`

package/.claude/commands/sillyspec/brainstorm.md

@@ -53,7 +53,7 @@ $ARGUMENTS
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-**工作区模式：** AskUserQuestion 选子项目，加载子项目上下文 + 共享规范 + 工作区概览，设计文档保存到子项目 `.sillyspec/changes/`。
+**工作区模式：** AskUserQuestion 选子项目，**cd 到子项目目录执行**，加载子项目上下文 + 共享规范 + 工作区概览，设计文档保存到子项目 `.sillyspec/changes/`。git commit 在子项目目录执行。
 
 **单项目模式：**
 ```bash

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

@@ -29,7 +29,7 @@ $ARGUMENTS
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-**工作区模式：** 根据计划 Task 标注确定子项目，额外加载共享规范 + CODEBASE-OVERVIEW.md，执行前 cd 到对应子项目目录。
+**工作区模式：** 根据计划 Task 标注确定子项目，额外加载共享规范 + CODEBASE-OVERVIEW.md，**执行前必须 cd 到对应子项目目录**。所有代码修改、测试运行、git commit 都在子项目目录中执行。一个 Task 属于哪个子项目，就 cd 到哪个子项目。
 
 **单项目模式：**
 ```bash
@@ -84,17 +84,62 @@ grep -rn "public.*getById" --include="*.java" src/main/java/**/service/
 ```
 grep 不到 → 不许调用，先查清楚或报告给用户。
 
-### 2. TDD
+### 2. TDD（强制执行，不可跳过）
 
+#### 🔴 RED — 写失败测试
+
+先写测试文件，再写实现代码。写代码前测试必须先存在。
+
+**写完测试后，立即运行确认失败：**
+
+先检查 local.yaml 是否有构建命令配置：
+```bash
+cat .sillyspec/local.yaml 2>/dev/null 2>/dev/null
+```
+
+如果有，使用 local.yaml 中的命令（含 `-s` 等参数）；否则使用默认命令：
+
+```bash
+mvn test -pl <模块> -Dtest=<测试类> 2>/dev/null || ./gradlew test --tests <测试类> 2>/dev/null || npm test -- --testPathPattern=<测试文件> 2>/dev/null || pytest <测试文件> 2>/dev/null
+```
+
+确认：
+- 测试失败（不是编译错误）
+- 失败原因是功能未实现（不是语法错误）
+
+**测试直接通过？** 你在测试已有行为，重写测试。**测试编译报错？** 先修测试语法。
+
+#### 🟢 GREEN — 写最少代码
+
+写刚好让测试通过的最少代码。不加额外功能。
+
+**写完后立即运行确认通过：**
+
+先检查 local.yaml 是否有构建命令配置：
+```bash
+cat .sillyspec/local.yaml 2>/dev/null 2>/dev/null
 ```
-🔴 RED    → 写测试，运行确认失败
-🟢 GREEN  → 写最少代码让测试通过
-🔵 REFACTOR → 清理，保持测试通过
+
+如果有，使用 local.yaml 中的命令；否则使用默认命令：
+
+```bash
+mvn test -pl <模块> -Dtest=<测试类> 2>/dev/null || ./gradlew test --tests <测试类> 2>/dev/null || npm test -- --testPathPattern=<测试文件> 2>/dev/null || pytest <测试文件> 2>/dev/null
 ```
 
-TDD 中间步骤（RED→GREEN→REFACTOR）连续执行，不需要每步等用户确认。
+确认：
+- 测试通过
+- 其他已有测试没有因此失败
+- 无编译错误、无 warnings
+
+**编译不通过或测试失败？** 修代码，不是改测试。**其他测试被破坏？** 立即修复。
+
+#### 🔵 REFACTOR — 清理
 
-**测试文件必须保留**，随代码一起 commit。违反 TDD → 删代码重来。
+在测试全绿的前提下清理：提取重复、改善命名、简化逻辑。重构后重新运行测试确认仍然通过。
+
+**TDD 中间步骤（RED→GREEN→REFACTOR）连续执行，不需要每步等用户确认。但每一步都必须运行测试命令并确认结果，不可省略。**
+
+**测试文件必须保留**，随代码一起 commit。违反 TDD（先写代码后补测试）→ 删代码重来。
 
 **可跳过 TDD（不需要确认）：** 纯配置（YAML/properties）、纯数据（SQL seed）、纯文档（README/注释）。
 
@@ -104,8 +149,17 @@ TDD 中间步骤（RED→GREEN→REFACTOR）连续执行，不需要每步等用
 
 ### 4. Git commit
 
+**先确认当前在 git 仓库中：**
+```bash
+git rev-parse --is-inside-work-tree 2>/dev/null
+```
+
+如果不在 git 仓库中，提示用户当前目录没有 git 管理，跳过 commit 或让用户指定仓库路径。
+
 `git add -A` → 生成 commit message → **根据用户选择的确认频率决定是否立即确认或批量确认**。
 
+**工作区模式下，每个子项目的 commit 独立执行，不要跨子项目 commit。**
+
 ---
 
 ## 偏差处理

package/.claude/commands/sillyspec/quick.md

@@ -33,7 +33,7 @@ $ARGUMENTS
    - 纯配置/数据/文档可跳过 TDD
    - 其他情况一律走 TDD
 6. **运行相关测试：** `pnpm test 2>/dev/null || npm test 2>/dev/null || pytest 2>/dev/null`
-7. **Git commit：** 展示 commit message 给用户确认后提交
+7. **Git commit：** 展示 commit message 给用户确认后提交。**工作区模式下，确认当前在正确的子项目目录中执行 commit。**
 8. **记录：**
    - **有 `--change`：** 在 `.sillyspec/changes/<变更名>/tasks.md` 追加 task 并勾选 `[x]`
    - **无 `--change`：** 记录到 `.sillyspec/quicklog/QUICKLOG.md`（见下方规则）

package/.claude/commands/sillyspec/scan.md

@@ -55,6 +55,24 @@ AskUserQuestion 依次确认：快速⚡/深度🔍、扫描范围（留空全
 
 汇总选择，用户确认后执行。
 
+### 🚨 工作区扫描铁律（防止上下文爆炸）
+
+**工作区模式下，必须逐个子项目扫描并写入，禁止跨子项目累积上下文：**
+
+```
+子项目 A → 读取 → 写入文档 → 清理上下文
+子项目 B → 读取 → 写入文档 → 清理上下文
+...
+最后 → 生成 CODEBASE-OVERVIEW.md
+```
+
+- ✅ 每个子项目扫描完成后**立即写入** `.sillyspec/codebase/` 文件
+- ✅ 写入后**不再回头读**该子项目的源码
+- ❌ 禁止同时读取多个子项目的源码再一次性全部写入
+- ❌ 禁止在一个子项目扫描过程中去读另一个子项目的文件
+
+**CODEBASE-OVERVIEW.md** 只读各子项目已生成的 ARCHITECTURE.md + CONVENTIONS.md（不读源码），生成汇总。
+
 ---
 
 ## 快速扫描
@@ -76,9 +94,73 @@ find . -type f -not -path "*/node_modules/*" -not -path "*/{dist,.git,vendor,bui
 git log --oneline -20
 ```
 
-## 🚨 三项强制扫描（快速和深度都必须执行）
+## 🚨 四项强制扫描（快速和深度都必须执行）
+
+### A. 构建环境探测（IDE vs 终端差异修复）
+
+**目的：** 解决 IDEA 有私服配置但终端跑不了 `mvn test` / `npm test` 的问题。
+
+**探测步骤：**
+
+```bash
+# 检测项目使用的构建工具
+ls pom.xml build.gradle package.json requirements.txt go.mod Cargo.toml pyproject.toml 2>/dev/null
+# 检测是否有 wrapper
+ls mvnw gradlew package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null
+# 检测是否有 IDEA 特殊配置
+grep -r "mavenHome\|settings\.xml\|gradleHome\|nodeInterpreter" .idea/workspace.xml 2>/dev/null | head -5
+# 检测是否有本地配置文件
+cat .mvn/maven.config 2>/dev/null
+cat .mvn/jvm.config 2>/dev/null
+cat .npmrc 2>/dev/null
+cat pip.conf .pip/pip.conf ~/.pip/pip.conf 2>/dev/null
+cat ~/.gradle/gradle.properties 2>/dev/null
+```
+
+**AskUserQuestion 询问用户：**
+
+> "检测到本项目使用 [Maven/Gradle/npm/pip/Go]，终端执行构建命令时是否需要特殊配置？"
+> 选项：
+> - 不需要，默认配置就能跑
+> - 需要指定配置文件（如 Maven 的 settings.xml）→ 让用户输入路径
+> - 需要额外参数（如私服地址、代理等）→ 让用户输入
+> - 不确定，先试试默认命令
+
+**如果用户选择了需要配置，测试默认命令是否能跑通：**
+
+```bash
+# Maven
+mvn test -s <用户提供的路径> --fail-at-end 2>&1 | tail -5
+# Gradle
+./gradlew test 2>&1 | tail -5 || gradle test 2>&1 | tail -5
+# npm
+npm test 2>&1 | tail -5 || pnpm test 2>&1 | tail -5
+# pip
+pip install -e . 2>&1 | tail -5 && pytest --collect-only 2>&1 | tail -5
+# Go
+go test ./... 2>&1 | tail -5
+```
+
+**写入 `.sillyspec/local.yaml`（本地记忆文件，不提交到 git）：**
+
+此文件存储每个开发者独立的本地配置。如果文件已存在则追加，已有字段则跳过：
 
-### A. 数据库 Schema 扫描
+```yaml
+# .sillyspec/local.yaml — 本地记忆文件（已在 .gitignore 中，不提交）
+# 每个开发者独立配置，clone 后重新 scan 即可生成
+
+build:
+  tool: maven
+  test_cmd: 'mvn test -s "D:/software/maven/conf/settings.xml"'
+  compile_cmd: 'mvn compile -s "D:/software/maven/conf/settings.xml"'
+  single_test_cmd: 'mvn test -s "D:/software/maven/conf/settings.xml" -pl {module} -Dtest={test_class}'
+```
+
+**铁律：后续 execute / verify 阶段执行构建或测试命令时，必须先读取 `.sillyspec/local.yaml` 中的 build 配置，使用记录的命令执行。如果 local.yaml 不存在或无 build 配置，使用默认命令。**
+
+无构建工具 → 跳过此步骤。
+
+### B. 数据库 Schema 扫描
 
 **目的：** 防止后续阶段编造表名和字段名。
 
@@ -101,7 +183,7 @@ find . \( -name "schema.prisma" -o -name "*.model.ts" -o -name "*.entity.ts" -o
 
 无数据库 → 写"本项目无数据库"。**铁律：所有阶段引用的表名必须来自此摘要，或 design.md 中声明的新增表。**
 
-### B. 框架隐形规则扫描
+### C. 框架隐形规则扫描
 
 **目的：** 防止 AI 生成的 SQL/代码违反框架自动处理机制（如自动注入字段、逻辑删除拦截器）。
 
@@ -138,7 +220,7 @@ find . \( -name "*.java" -o -name "*.py" -o -name "*.go" -o -name "*.ts" -o -nam
 
 无发现 → 写"未发现框架级别的自动处理配置"。**铁律：后续阶段生成 SQL/数据操作代码必须遵守这些规则。**
 
-### C. 实体继承规范扫描
+### D. 实体继承规范扫描
 
 **目的：** 防止新建表时漏掉基类通用字段，导致 ORM 查询报 Unknown column。
 
@@ -163,7 +245,7 @@ find . -name "*.java" -not -path "*/{node_modules,.git}/*" | xargs grep -l "@Map
 
 无基类 → 写"本项目没有实体基类"。
 
-### D. 代码风格深度提取
+### E. 代码风格深度提取
 
 读取 2-3 个典型的 Controller、Service、ServiceImpl、Entity 源文件，提取具体风格（从源码提取，禁止编造）：
 
@@ -228,9 +310,16 @@ sillyspec next
 
 ### Git 提交
 
+**单项目模式：**
 ```bash
-git add .sillyspec/
-git commit -m "chore: sillyspec scan - codebase mapped"
+git add .sillyspec/ && git commit -m "chore: sillyspec scan - codebase mapped"
+```
+
+**工作区模式：** 在每个子项目目录分别 commit（主工作区无 git 则跳过）：
+```bash
+for proj in $(cat .sillyspec/config.yaml | grep -oP 'path:\s*\K.*'); do
+  cd "$proj" && git add .sillyspec/ 2>/dev/null && git commit -m "chore: sillyspec scan - codebase mapped" && cd - > /dev/null
+done
 ```
 
 ### 路径校验 + 自检门控

package/.claude/commands/sillyspec/status.md

@@ -1,8 +1,3 @@
----
-description: 查看项目进度和状态
-argument-hint: ""
----
-
 ## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 
@@ -19,7 +14,37 @@ argument-hint: ""
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-**工作区模式：** 读取 config.yaml 子项目列表，对每个子项目检查 PROJECT.md、codebase 文档数、进行中变更、归档数。检查共享规范和工作区概览。输出汇总后结束，不执行单项目流程。
+**工作区模式：** 读取 config.yaml 子项目列表，对每个子项目检查 PROJECT.md、codebase 文档数、进行中变更、归档数。**同时检查工作区根目录 `.sillyspec/changes/` 下的未归档变更。** 检查共享规范和工作区概览。输出汇总后结束，不执行单项目流程。
+
+工作区变更检查命令：
+```bash
+# 工作区根目录的变更
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+ls .sillyspec/changes/archive/ 2>/dev/null | wc -l
+
+# 每个子项目的变更
+for proj in $(cat .sillyspec/config.yaml | grep -oP 'path:\s*\K.*'); do
+  echo "=== $(basename $proj) changes ==="
+  ls "$proj/.sillyspec/changes/" 2>/dev/null | grep -v archive
+  ls "$proj/.sillyspec/changes/archive/" 2>/dev/null | wc -l
+done
+```
+
+**汇总输出格式：**
+```
+📊 SillySpec 状态
+📋 工作区模式 — N 个子项目
+
+工作区变更：
+  🔄 进行中：sec-bonus-penalty（tasks: 3/5）
+  ✅ 已归档：1 个
+
+┌───────────────────┬────────────┬────────────┬────────┬────────┐
+│ 子项目            │ PROJECT.md │ 代码库文档 │ 进行中 │ 已归档 │
+├───────────────────┼────────────┼────────────┼────────┼────────┤
+│ back-service      │ ✗          │ 7 份       │ 1      │ 0      │
+└───────────────────┴────────────┴────────────┴────────┴────────┘
+```
 
 **单项目模式：** 继续 Step 2。
 

package/.claude/commands/sillyspec/verify.md

@@ -11,11 +11,27 @@
 ## 状态检查（必须先执行）
 
 ```bash
-sillyspec status --json
+cat .sillyspec/STATE.md 2>/dev/null
 ```
 
-- `phase: "verify"` → ✅ 继续
-- 其他 phase → 提示 `sillyspec next`
+检查当前阶段。如果没有 STATE.md，检查是否有未归档变更：
+
+```bash
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+```
+
+无 STATE.md 且无未归档变更 → 提示用户先完成 execute 或用 `/sillyspec:status` 查看状态。
+
+---
+
+## 工作区模式处理
+
+如果 `.sillyspec/config.yaml` 包含 `projects` 字段：
+
+1. 检查工作区根目录 `.sillyspec/changes/` 下的未归档变更
+2. 检查每个子项目 `<子项目路径>/.sillyspec/changes/` 下的未归档变更
+3. 列出所有未归档变更，让用户选择要验证哪个
+4. 根据 $ARGUMENTS 或用户选择，cd 到对应目录执行验证
 
 ---
 
@@ -24,8 +40,13 @@ sillyspec status --json
 ### 1. 加载规范
 
 ```bash
-LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
-cat "$LATEST"/{design,tasks}.md 2>/dev/null
+# 确定变更目录
+if [ -n "$ARGUMENTS" ]; then
+  CHANGE_DIR=".sillyspec/changes/$ARGUMENTS"
+else
+  CHANGE_DIR=$(ls -d .sillyspec/changes/*/ 2>/dev/null | grep -v archive | tail -1)
+fi
+cat "$CHANGE_DIR"/{design,tasks}.md 2>/dev/null
 ```
 
 锚定确认实际存在的文件。
@@ -61,14 +82,6 @@ grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.ts
 ## 结论：✅ PASS / ⚠️ PASS WITH NOTES / ❌ FAIL
 ```
 
-```bash
-bash scripts/validate-all.sh 2>/dev/null
-```
-
 ### 7. 完成
 
-```bash
-sillyspec status --json && sillyspec next
-```
-
-更新 `.sillyspec/STATE.md`：阶段改为 `verify ✅` 或 `verify ⚠️`。
+更新 `.sillyspec/STATE.md`（如存在）：阶段改为 `verify ✅` 或 `verify ⚠️`。

package/package.json

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

package/src/init.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
 import { join, resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir } from 'os';
@@ -50,17 +50,45 @@ const ARG_HINTS = {
   export: '<change-name> [--to <path>]',
 };
 
-const VALID_TOOLS = ['claude', 'claude_skills', 'cursor', 'codex', 'opencode', 'openclaw'];
+const VALID_TOOLS = ['claude', 'claude_skills', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
 
 const TOOL_LABELS = {
   claude: 'Claude Code',
   claude_skills: 'Claude Skills',
   cursor: 'Cursor',
-  codex: 'Codex CLI',
-  opencode: 'OpenCode',
   openclaw: 'OpenClaw',
+  codex: 'OpenAI Codex (通过 AGENTS.md)',
+  gemini: 'Gemini CLI (通过 GEMINI.md)',
+  opencode: 'OpenCode (通过 INSTRUCTIONS.md)',
 };
 
+// Slash commands 工具：安装 markdown 模板命令
+const SLASH_COMMAND_TOOLS = ['claude', 'claude_skills', 'cursor', 'openclaw'];
+
+// 指令文件工具：注入规范引用到指令文件
+const INSTRUCTION_TOOLS = ['codex', 'gemini', 'opencode'];
+
+const INSTRUCTION_FILE_MAP = {
+  codex: 'AGENTS.md',
+  gemini: 'GEMINI.md',
+  opencode: 'INSTRUCTIONS.md',
+};
+
+const INJECTION_CONTENT = `## SillySpec — 规范驱动开发
+
+在执行开发任务时，遵循以下规范：
+
+### 代码规范
+- 写代码前先读取 \`.sillyspec/codebase/CONVENTIONS.md\`（代码风格）和 \`.sillyspec/codebase/ARCHITECTURE.md\`（架构）
+- 调用已有方法前，用 grep 确认方法存在，不许编造
+- 遵循 \`.sillyspec/codebase/CONVENTIONS.md\` 中的代码风格
+
+### 工作流程
+- 读取 \`.sillyspec/STATE.md\` 确认当前阶段
+- 各阶段产出文件位于 \`.sillyspec/changes/<变更名>/\` 下
+- 详细流程参考模板文件：\`.sillyspec/.templates/\`（brainstorm.md, plan.md, execute.md 等）
+`;
+
 // ── 适配器 ──
 
 function generateClaude(projectDir, name, desc, body, argHint) {
@@ -103,32 +131,6 @@ ${body}`
   );
 }
 
-function generateCodex(projectDir, name, desc, body, argHint) {
-  const outDir = join(homedir(), '.agents', 'skills', `sillyspec-${name}`);
-  mkdirSync(outDir, { recursive: true });
-  writeFileSync(join(outDir, 'SKILL.md'),
-`---
-name: sillyspec:${name}
-description: ${desc}
----
-
-${body}`
-  );
-}
-
-function generateOpencode(projectDir, name, desc, body, argHint) {
-  const outDir = join(projectDir, '.opencode', 'skills', `sillyspec-${name}`);
-  mkdirSync(outDir, { recursive: true });
-  writeFileSync(join(outDir, 'SKILL.md'),
-`---
-name: sillyspec:${name}
-description: ${desc}
----
-
-${body}`
-  );
-}
-
 function generateOpenclaw(projectDir, name, desc, body, argHint) {
   const outDir = join(projectDir, '.openclaw', 'skills', `sillyspec-${name}`);
   mkdirSync(outDir, { recursive: true });
@@ -146,11 +148,30 @@ const GENERATORS = {
   claude: generateClaude,
   claude_skills: generateClaudeSkills,
   cursor: generateCursor,
-  codex: generateCodex,
-  opencode: generateOpencode,
   openclaw: generateOpenclaw,
 };
 
+// ── 指令文件注入 ──
+
+function injectInstructions(tool, projectDir) {
+  const fileName = INSTRUCTION_FILE_MAP[tool];
+  if (!fileName) return;
+  const filePath = join(projectDir, fileName);
+
+  // 文件不存在则创建
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, INJECTION_CONTENT);
+    return;
+  }
+
+  // 已存在 SillySpec 标记则跳过
+  const content = readFileSync(filePath, 'utf8');
+  if (content.includes('## SillySpec')) return;
+
+  // 追加到末尾
+  writeFileSync(filePath, content.trimEnd() + '\n\n' + INJECTION_CONTENT);
+}
+
 // ── 检测工具 ──
 
 function detectTools(projectDir) {
@@ -158,9 +179,10 @@ function detectTools(projectDir) {
   if (existsSync(join(projectDir, '.claude'))) found.push('claude');
   if (existsSync(join(projectDir, '.claude', 'skills'))) found.push('claude_skills');
   if (existsSync(join(projectDir, '.cursor'))) found.push('cursor');
-  if (existsSync(join(projectDir, '.opencode'))) found.push('opencode');
   if (existsSync(join(projectDir, '.openclaw'))) found.push('openclaw');
-  if (existsSync(join(homedir(), '.agents', 'skills'))) found.push('codex');
+  if (existsSync(join(projectDir, 'AGENTS.md'))) found.push('codex');
+  if (existsSync(join(projectDir, 'GEMINI.md'))) found.push('gemini');
+  if (existsSync(join(projectDir, 'INSTRUCTIONS.md'))) found.push('opencode');
   if (found.length === 0) found.push('claude');
   return found;
 }
@@ -188,7 +210,7 @@ async function doInstall(projectDir, tools, isWorkspace, subprojects = []) {
   }
 
   const gitignorePath = join(projectDir, '.gitignore');
-  const ignoreRules = ['.sillyspec/STATE.md', '.sillyspec/codebase/SCAN-RAW.md'];
+  const ignoreRules = ['.sillyspec/STATE.md', '.sillyspec/codebase/SCAN-RAW.md', '.sillyspec/local.yaml'];
   if (existsSync(gitignorePath)) {
     const content = readFileSync(gitignorePath, 'utf8');
     let updated = content.trimEnd();
@@ -202,13 +224,38 @@ async function doInstall(projectDir, tools, isWorkspace, subprojects = []) {
     writeFileSync(gitignorePath, ignoreRules.join('\n') + '\n');
   }
 
-  // 生成文件
+  // 生成 slash command 文件
   const templateFiles = readdirSync(TEMPLATE_DIR).filter(f => f.endsWith('.md'));
   let count = 0;
 
   for (let i = 0; i < tools.length; i++) {
     const toolName = tools[i];
     const label = TOOL_LABELS[toolName] || toolName;
+
+    if (INSTRUCTION_TOOLS.includes(toolName)) {
+      const spinner = ora(`安装 ${label}... (${i + 1}/${tools.length})`).start();
+      try {
+        injectInstructions(toolName, projectDir);
+        // 复制模板文件到 .sillyspec/.templates/
+        const templatesSourceDir = join(TEMPLATE_DIR);
+        const templatesDir = join(projectDir, '.sillyspec', '.templates');
+        if (!existsSync(templatesDir)) {
+          mkdirSync(templatesDir, { recursive: true });
+          for (const file of readdirSync(templatesSourceDir)) {
+            if (file.endsWith('.md')) {
+              copyFileSync(join(templatesSourceDir, file), join(templatesDir, file));
+            }
+          }
+        }
+        spinner.succeed(`${label} 完成`);
+        count++;
+      } catch (err) {
+        spinner.fail(`${label} 失败: ${err.message}`);
+        throw err;
+      }
+      continue;
+    }
+
     const spinner = ora(`安装 ${label}... (${i + 1}/${tools.length})`).start();
     try {
       const gen = GENERATORS[toolName];
@@ -345,7 +392,7 @@ export async function cmdInit(projectDir, options = {}) {
   const detected = detectTools(projectDir);
 
   const toolChoices = VALID_TOOLS.map(v => ({
-    name: `${TOOL_LABELS[v]}${v === 'claude' ? ' (slash commands)' : v === 'claude_skills' ? ' (skills 目录)' : ''}`,
+    name: `${TOOL_LABELS[v]}${v === 'claude' ? ' (推荐)' : ''}`,
     value: v,
     checked: detected.includes(v),
   }));

package/templates/archive.md

@@ -56,6 +56,8 @@ $ARGUMENTS
 - **STATE.md：** 清除当前变更信息，历史记录追加归档完成
 - **Git 提交：** `git add .sillyspec/ && git commit -m "docs: archive sillyspec change <change-name>"`
 
+**工作区模式下：** 如果变更属于某个子项目，cd 到子项目目录执行 git commit。工作区根目录无 git 则跳过。
+
 ### 最后说：
 
 > ✅ 变更 `<change-name>` 已归档到 `archive/YYYY-MM-DD-<change-name>/`。继续：`/sillyspec:brainstorm "新想法"`

package/templates/brainstorm.md

@@ -53,7 +53,7 @@ $ARGUMENTS
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-**工作区模式：** AskUserQuestion 选子项目，加载子项目上下文 + 共享规范 + 工作区概览，设计文档保存到子项目 `.sillyspec/changes/`。
+**工作区模式：** AskUserQuestion 选子项目，**cd 到子项目目录执行**，加载子项目上下文 + 共享规范 + 工作区概览，设计文档保存到子项目 `.sillyspec/changes/`。git commit 在子项目目录执行。
 
 **单项目模式：**
 ```bash

package/templates/execute.md

@@ -29,7 +29,7 @@ $ARGUMENTS
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-**工作区模式：** 根据计划 Task 标注确定子项目，额外加载共享规范 + CODEBASE-OVERVIEW.md，执行前 cd 到对应子项目目录。
+**工作区模式：** 根据计划 Task 标注确定子项目，额外加载共享规范 + CODEBASE-OVERVIEW.md，**执行前必须 cd 到对应子项目目录**。所有代码修改、测试运行、git commit 都在子项目目录中执行。一个 Task 属于哪个子项目，就 cd 到哪个子项目。
 
 **单项目模式：**
 ```bash
@@ -84,17 +84,62 @@ grep -rn "public.*getById" --include="*.java" src/main/java/**/service/
 ```
 grep 不到 → 不许调用，先查清楚或报告给用户。
 
-### 2. TDD
+### 2. TDD（强制执行，不可跳过）
 
+#### 🔴 RED — 写失败测试
+
+先写测试文件，再写实现代码。写代码前测试必须先存在。
+
+**写完测试后，立即运行确认失败：**
+
+先检查 local.yaml 是否有构建命令配置：
+```bash
+cat .sillyspec/local.yaml 2>/dev/null 2>/dev/null
+```
+
+如果有，使用 local.yaml 中的命令（含 `-s` 等参数）；否则使用默认命令：
+
+```bash
+mvn test -pl <模块> -Dtest=<测试类> 2>/dev/null || ./gradlew test --tests <测试类> 2>/dev/null || npm test -- --testPathPattern=<测试文件> 2>/dev/null || pytest <测试文件> 2>/dev/null
+```
+
+确认：
+- 测试失败（不是编译错误）
+- 失败原因是功能未实现（不是语法错误）
+
+**测试直接通过？** 你在测试已有行为，重写测试。**测试编译报错？** 先修测试语法。
+
+#### 🟢 GREEN — 写最少代码
+
+写刚好让测试通过的最少代码。不加额外功能。
+
+**写完后立即运行确认通过：**
+
+先检查 local.yaml 是否有构建命令配置：
+```bash
+cat .sillyspec/local.yaml 2>/dev/null 2>/dev/null
 ```
-🔴 RED    → 写测试，运行确认失败
-🟢 GREEN  → 写最少代码让测试通过
-🔵 REFACTOR → 清理，保持测试通过
+
+如果有，使用 local.yaml 中的命令；否则使用默认命令：
+
+```bash
+mvn test -pl <模块> -Dtest=<测试类> 2>/dev/null || ./gradlew test --tests <测试类> 2>/dev/null || npm test -- --testPathPattern=<测试文件> 2>/dev/null || pytest <测试文件> 2>/dev/null
 ```
 
-TDD 中间步骤（RED→GREEN→REFACTOR）连续执行，不需要每步等用户确认。
+确认：
+- 测试通过
+- 其他已有测试没有因此失败
+- 无编译错误、无 warnings
+
+**编译不通过或测试失败？** 修代码，不是改测试。**其他测试被破坏？** 立即修复。
+
+#### 🔵 REFACTOR — 清理
 
-**测试文件必须保留**，随代码一起 commit。违反 TDD → 删代码重来。
+在测试全绿的前提下清理：提取重复、改善命名、简化逻辑。重构后重新运行测试确认仍然通过。
+
+**TDD 中间步骤（RED→GREEN→REFACTOR）连续执行，不需要每步等用户确认。但每一步都必须运行测试命令并确认结果，不可省略。**
+
+**测试文件必须保留**，随代码一起 commit。违反 TDD（先写代码后补测试）→ 删代码重来。
 
 **可跳过 TDD（不需要确认）：** 纯配置（YAML/properties）、纯数据（SQL seed）、纯文档（README/注释）。
 
@@ -104,8 +149,17 @@ TDD 中间步骤（RED→GREEN→REFACTOR）连续执行，不需要每步等用
 
 ### 4. Git commit
 
+**先确认当前在 git 仓库中：**
+```bash
+git rev-parse --is-inside-work-tree 2>/dev/null
+```
+
+如果不在 git 仓库中，提示用户当前目录没有 git 管理，跳过 commit 或让用户指定仓库路径。
+
 `git add -A` → 生成 commit message → **根据用户选择的确认频率决定是否立即确认或批量确认**。
 
+**工作区模式下，每个子项目的 commit 独立执行，不要跨子项目 commit。**
+
 ---
 
 ## 偏差处理

package/templates/quick.md

@@ -33,7 +33,7 @@ $ARGUMENTS
    - 纯配置/数据/文档可跳过 TDD
    - 其他情况一律走 TDD
 6. **运行相关测试：** `pnpm test 2>/dev/null || npm test 2>/dev/null || pytest 2>/dev/null`
-7. **Git commit：** 展示 commit message 给用户确认后提交
+7. **Git commit：** 展示 commit message 给用户确认后提交。**工作区模式下，确认当前在正确的子项目目录中执行 commit。**
 8. **记录：**
    - **有 `--change`：** 在 `.sillyspec/changes/<变更名>/tasks.md` 追加 task 并勾选 `[x]`
    - **无 `--change`：** 记录到 `.sillyspec/quicklog/QUICKLOG.md`（见下方规则）

package/templates/scan.md

@@ -55,6 +55,24 @@ AskUserQuestion 依次确认：快速⚡/深度🔍、扫描范围（留空全
 
 汇总选择，用户确认后执行。
 
+### 🚨 工作区扫描铁律（防止上下文爆炸）
+
+**工作区模式下，必须逐个子项目扫描并写入，禁止跨子项目累积上下文：**
+
+```
+子项目 A → 读取 → 写入文档 → 清理上下文
+子项目 B → 读取 → 写入文档 → 清理上下文
+...
+最后 → 生成 CODEBASE-OVERVIEW.md
+```
+
+- ✅ 每个子项目扫描完成后**立即写入** `.sillyspec/codebase/` 文件
+- ✅ 写入后**不再回头读**该子项目的源码
+- ❌ 禁止同时读取多个子项目的源码再一次性全部写入
+- ❌ 禁止在一个子项目扫描过程中去读另一个子项目的文件
+
+**CODEBASE-OVERVIEW.md** 只读各子项目已生成的 ARCHITECTURE.md + CONVENTIONS.md（不读源码），生成汇总。
+
 ---
 
 ## 快速扫描
@@ -76,9 +94,73 @@ find . -type f -not -path "*/node_modules/*" -not -path "*/{dist,.git,vendor,bui
 git log --oneline -20
 ```
 
-## 🚨 三项强制扫描（快速和深度都必须执行）
+## 🚨 四项强制扫描（快速和深度都必须执行）
+
+### A. 构建环境探测（IDE vs 终端差异修复）
+
+**目的：** 解决 IDEA 有私服配置但终端跑不了 `mvn test` / `npm test` 的问题。
+
+**探测步骤：**
+
+```bash
+# 检测项目使用的构建工具
+ls pom.xml build.gradle package.json requirements.txt go.mod Cargo.toml pyproject.toml 2>/dev/null
+# 检测是否有 wrapper
+ls mvnw gradlew package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null
+# 检测是否有 IDEA 特殊配置
+grep -r "mavenHome\|settings\.xml\|gradleHome\|nodeInterpreter" .idea/workspace.xml 2>/dev/null | head -5
+# 检测是否有本地配置文件
+cat .mvn/maven.config 2>/dev/null
+cat .mvn/jvm.config 2>/dev/null
+cat .npmrc 2>/dev/null
+cat pip.conf .pip/pip.conf ~/.pip/pip.conf 2>/dev/null
+cat ~/.gradle/gradle.properties 2>/dev/null
+```
+
+**AskUserQuestion 询问用户：**
+
+> "检测到本项目使用 [Maven/Gradle/npm/pip/Go]，终端执行构建命令时是否需要特殊配置？"
+> 选项：
+> - 不需要，默认配置就能跑
+> - 需要指定配置文件（如 Maven 的 settings.xml）→ 让用户输入路径
+> - 需要额外参数（如私服地址、代理等）→ 让用户输入
+> - 不确定，先试试默认命令
+
+**如果用户选择了需要配置，测试默认命令是否能跑通：**
+
+```bash
+# Maven
+mvn test -s <用户提供的路径> --fail-at-end 2>&1 | tail -5
+# Gradle
+./gradlew test 2>&1 | tail -5 || gradle test 2>&1 | tail -5
+# npm
+npm test 2>&1 | tail -5 || pnpm test 2>&1 | tail -5
+# pip
+pip install -e . 2>&1 | tail -5 && pytest --collect-only 2>&1 | tail -5
+# Go
+go test ./... 2>&1 | tail -5
+```
+
+**写入 `.sillyspec/local.yaml`（本地记忆文件，不提交到 git）：**
+
+此文件存储每个开发者独立的本地配置。如果文件已存在则追加，已有字段则跳过：
 
-### A. 数据库 Schema 扫描
+```yaml
+# .sillyspec/local.yaml — 本地记忆文件（已在 .gitignore 中，不提交）
+# 每个开发者独立配置，clone 后重新 scan 即可生成
+
+build:
+  tool: maven
+  test_cmd: 'mvn test -s "D:/software/maven/conf/settings.xml"'
+  compile_cmd: 'mvn compile -s "D:/software/maven/conf/settings.xml"'
+  single_test_cmd: 'mvn test -s "D:/software/maven/conf/settings.xml" -pl {module} -Dtest={test_class}'
+```
+
+**铁律：后续 execute / verify 阶段执行构建或测试命令时，必须先读取 `.sillyspec/local.yaml` 中的 build 配置，使用记录的命令执行。如果 local.yaml 不存在或无 build 配置，使用默认命令。**
+
+无构建工具 → 跳过此步骤。
+
+### B. 数据库 Schema 扫描
 
 **目的：** 防止后续阶段编造表名和字段名。
 
@@ -101,7 +183,7 @@ find . \( -name "schema.prisma" -o -name "*.model.ts" -o -name "*.entity.ts" -o
 
 无数据库 → 写"本项目无数据库"。**铁律：所有阶段引用的表名必须来自此摘要，或 design.md 中声明的新增表。**
 
-### B. 框架隐形规则扫描
+### C. 框架隐形规则扫描
 
 **目的：** 防止 AI 生成的 SQL/代码违反框架自动处理机制（如自动注入字段、逻辑删除拦截器）。
 
@@ -138,7 +220,7 @@ find . \( -name "*.java" -o -name "*.py" -o -name "*.go" -o -name "*.ts" -o -nam
 
 无发现 → 写"未发现框架级别的自动处理配置"。**铁律：后续阶段生成 SQL/数据操作代码必须遵守这些规则。**
 
-### C. 实体继承规范扫描
+### D. 实体继承规范扫描
 
 **目的：** 防止新建表时漏掉基类通用字段，导致 ORM 查询报 Unknown column。
 
@@ -163,7 +245,7 @@ find . -name "*.java" -not -path "*/{node_modules,.git}/*" | xargs grep -l "@Map
 
 无基类 → 写"本项目没有实体基类"。
 
-### D. 代码风格深度提取
+### E. 代码风格深度提取
 
 读取 2-3 个典型的 Controller、Service、ServiceImpl、Entity 源文件，提取具体风格（从源码提取，禁止编造）：
 
@@ -228,9 +310,16 @@ sillyspec next
 
 ### Git 提交
 
+**单项目模式：**
 ```bash
-git add .sillyspec/
-git commit -m "chore: sillyspec scan - codebase mapped"
+git add .sillyspec/ && git commit -m "chore: sillyspec scan - codebase mapped"
+```
+
+**工作区模式：** 在每个子项目目录分别 commit（主工作区无 git 则跳过）：
+```bash
+for proj in $(cat .sillyspec/config.yaml | grep -oP 'path:\s*\K.*'); do
+  cd "$proj" && git add .sillyspec/ 2>/dev/null && git commit -m "chore: sillyspec scan - codebase mapped" && cd - > /dev/null
+done
 ```
 
 ### 路径校验 + 自检门控

package/templates/status.md

@@ -14,7 +14,37 @@
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-**工作区模式：** 读取 config.yaml 子项目列表，对每个子项目检查 PROJECT.md、codebase 文档数、进行中变更、归档数。检查共享规范和工作区概览。输出汇总后结束，不执行单项目流程。
+**工作区模式：** 读取 config.yaml 子项目列表，对每个子项目检查 PROJECT.md、codebase 文档数、进行中变更、归档数。**同时检查工作区根目录 `.sillyspec/changes/` 下的未归档变更。** 检查共享规范和工作区概览。输出汇总后结束，不执行单项目流程。
+
+工作区变更检查命令：
+```bash
+# 工作区根目录的变更
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+ls .sillyspec/changes/archive/ 2>/dev/null | wc -l
+
+# 每个子项目的变更
+for proj in $(cat .sillyspec/config.yaml | grep -oP 'path:\s*\K.*'); do
+  echo "=== $(basename $proj) changes ==="
+  ls "$proj/.sillyspec/changes/" 2>/dev/null | grep -v archive
+  ls "$proj/.sillyspec/changes/archive/" 2>/dev/null | wc -l
+done
+```
+
+**汇总输出格式：**
+```
+📊 SillySpec 状态
+📋 工作区模式 — N 个子项目
+
+工作区变更：
+  🔄 进行中：sec-bonus-penalty（tasks: 3/5）
+  ✅ 已归档：1 个
+
+┌───────────────────┬────────────┬────────────┬────────┬────────┐
+│ 子项目            │ PROJECT.md │ 代码库文档 │ 进行中 │ 已归档 │
+├───────────────────┼────────────┼────────────┼────────┼────────┤
+│ back-service      │ ✗          │ 7 份       │ 1      │ 0      │
+└───────────────────┴────────────┴────────────┴────────┴────────┘
+```
 
 **单项目模式：** 继续 Step 2。
 

package/templates/verify.md

@@ -11,11 +11,27 @@
 ## 状态检查（必须先执行）
 
 ```bash
-sillyspec status --json
+cat .sillyspec/STATE.md 2>/dev/null
 ```
 
-- `phase: "verify"` → ✅ 继续
-- 其他 phase → 提示 `sillyspec next`
+检查当前阶段。如果没有 STATE.md，检查是否有未归档变更：
+
+```bash
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+```
+
+无 STATE.md 且无未归档变更 → 提示用户先完成 execute 或用 `/sillyspec:status` 查看状态。
+
+---
+
+## 工作区模式处理
+
+如果 `.sillyspec/config.yaml` 包含 `projects` 字段：
+
+1. 检查工作区根目录 `.sillyspec/changes/` 下的未归档变更
+2. 检查每个子项目 `<子项目路径>/.sillyspec/changes/` 下的未归档变更
+3. 列出所有未归档变更，让用户选择要验证哪个
+4. 根据 $ARGUMENTS 或用户选择，cd 到对应目录执行验证
 
 ---
 
@@ -24,8 +40,13 @@ sillyspec status --json
 ### 1. 加载规范
 
 ```bash
-LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
-cat "$LATEST"/{design,tasks}.md 2>/dev/null
+# 确定变更目录
+if [ -n "$ARGUMENTS" ]; then
+  CHANGE_DIR=".sillyspec/changes/$ARGUMENTS"
+else
+  CHANGE_DIR=$(ls -d .sillyspec/changes/*/ 2>/dev/null | grep -v archive | tail -1)
+fi
+cat "$CHANGE_DIR"/{design,tasks}.md 2>/dev/null
 ```
 
 锚定确认实际存在的文件。
@@ -61,14 +82,6 @@ grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.ts
 ## 结论：✅ PASS / ⚠️ PASS WITH NOTES / ❌ FAIL
 ```
 
-```bash
-bash scripts/validate-all.sh 2>/dev/null
-```
-
 ### 7. 完成
 
-```bash
-sillyspec status --json && sillyspec next
-```
-
-更新 `.sillyspec/STATE.md`：阶段改为 `verify ✅` 或 `verify ⚠️`。
+更新 `.sillyspec/STATE.md`（如存在）：阶段改为 `verify ✅` 或 `verify ⚠️`。