sillyspec 3.20.3 → 3.20.4

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

@@ -1,17 +1,30 @@
----
-name: sillyspec:execute
-description: 波次执行 — 子代理并行 + 强制 TDD + 两阶段审查
----
-
-## 执行
-
-**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
-
-1. 运行 `sillyspec run execute` — 读取输出的步骤 prompt
-2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
-3. 步骤完成后，运行 `sillyspec run execute --done --output "你的摘要"`
-4. 重复 2-3 直到阶段完成
-5. **禁止**在没有运行 CLI 的情况下自行决定流程
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:execute
+description: 用于按 plan 执行代码实现。适合用户说"开始写代码、执行任务、跑 execute、开干"。按 plan.md 中的 Wave 和 Task 逐步实现，遵循 design.md 和模块文档。
+---
+
+## 多变更说明
+
+如果项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录），所有 `sillyspec run` 命令需要加 `--change <变更名>`。只有一个变更时可省略（CLI 自动检测）。
+
+## 执行
+
+**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
+
+1. 运行 `sillyspec run execute` — CLI 会自动创建 worktree 隔离环境，然后输出步骤 prompt
+2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
+3. 步骤完成后，运行 `sillyspec run execute --done --output "你的摘要"`
+4. 重复 2-3 直到阶段完成
+5. **禁止**在没有运行 CLI 的情况下自行决定流程
+
+## Worktree 隔离
+
+- CLI 启动 execute 阶段时**自动创建 git worktree**，AI agent 不需要手动创建
+- Worktree 路径在 Step 3（确认 worktree 路径）中输出，后续子代理的 cwd 必须设为该路径
+- **禁止跳过 worktree 或在主仓库直接写代码**
+- 如果 worktree 创建失败，CLI 会报错并退出，需要排查后再重试
+- **未提交的文件、dirty 状态等不影响 worktree 创建和进入，直接按 CLI 输出的 worktree 路径操作即可**
+- 不要自行检查 git 状态来判断是否可以进入 worktree，CLI 会自动处理
+
+## 用户指令
+$ARGUMENTS

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

@@ -1,96 +1,109 @@
----
-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. 结束探索
-
-## 禁止事项
-
-- ❌ 写实现代码
-- ❌ 安装依赖
-- ❌ 修改任何文件（除非用户明确要求保存发现）
-- ❌ 强行下结论
-- ❌ 强行结构化（让模式自然涌现）
+---
+name: sillyspec:explore
+description: 用于自由讨论、代码库调研、方案比较、画 ASCII 图、澄清问题。适合用户说"分析下、讨论下、看看怎么设计、先别写代码、调研一下、画个结构图、帮我再分析下"。只读，不修改文件，不实现功能。
+---
+
+## 交互规范
+
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+不要用编号列表让用户手动输入数字。
+如果需要自由输入，在 AskUserQuestion 的选项中加入"Other（自定义输入）"。
+
+---
+
+你现在是 SillySpec 的自由思考伙伴。
+
+## 话题
+$ARGUMENTS
+
+## 多变更说明
+
+如果项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录），所有 `sillyspec run` 命令需要加 `--change <变更名>`。只有一个变更时可省略（CLI 自动检测）。
+
+## 执行
+
+**你必须先使用 exec 工具（shell）执行以下命令读取统一 CLI prompt：**
+
+1. 运行 `sillyspec run explore` — 读取输出的探索模式 prompt
+2. 按照输出的 prompt 和本技能约束执行探索
+3. 探索告一段落后，运行 `sillyspec run explore --done --input "<用户原始话题>" --output "你的摘要"`
+4. **禁止**在没有运行 CLI 的情况下自行决定流程
+
+## 这是什么模式
+
+**探索模式用于思考，不用于实现。** 你可以读文件、搜代码、调查代码库，但绝对不能写代码或实现功能。如果用户要求实现，提醒他们先退出探索模式。
+
+**这不是一个工作流，是一种姿态。** 没有固定步骤、没有必需的输出。你是一个帮助用户思考的伙伴。
+
+## 姿态
+
+- **好奇，不说教** — 问自然产生的问题，不按脚本走
+- **开放式线程** — 展示多个有趣方向，让用户选择
+- **可视化** — 大量使用 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-knowledge/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: sillyspec:knowledge
+description: Agent-safe knowledge base commands for SillySpec repositories. Search, inspect, validate, refresh, and propose knowledge entries.
+argument-hint: "search --query \"<text>\" --limit N | inspect --id \"<id>\" | validate | refresh | propose --title \"<title>\" --category <name>"
+version: "3.19.2"
+---
+
+## 交互规范
+当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。
+
+## 何时使用此技能
+Use this skill when working on a SillySpec repository and the task may depend on prior project knowledge, known issues, implementation patterns, scan-derived learnings, execute-stage knowledge hits, or `.sillyspec/knowledge`.
+
+Before implementing changes, **first search the knowledge base** to avoid repeating known work or running into known issues.
+
+## 命令列表
+
+### 1. knowledge search — 搜索知识库
+在执行任务前搜索相关知识。
+
+```bash
+sillyspec knowledge search --query "<task summary>" --limit 5
+```
+
+**示例：**
+```bash
+sillyspec knowledge search --query "worktree baseline apply conflict" --limit 5
+sillyspec knowledge search --query "postcheck validation error"
+sillyspec knowledge search --query "GLM usage metadata"
+```
+
+**输出（JSON）：**
+```json
+{
+  "ok": true,
+  "query": "worktree baseline",
+  "matches": [
+    {
+      "id": "patterns",
+      "path": "knowledge/patterns.md",
+      "title": "Patterns",
+      "summary": "每个阶段对应 `src/stages/` 下的独立模块...",
+      "score": 3,
+      "tags": ["worktree", "git-worktree", "WorktreeManager"],
+      "category": "Patterns"
+    }
+  ]
+}
+```
+
+**使用场景：**
+- 实现新功能前，检查是否有现有模式可复用
+- 遇到报错前，搜索是否是已知问题
+- 修改特定模块前，了解约定和坑点
+
+---
+
+### 2. knowledge inspect — 读取知识条目详情
+搜索命中后，读取完整条目内容。
+
+```bash
+sillyspec knowledge inspect --id "<knowledge-id>"
+```
+
+**示例：**
+```bash
+sillyspec knowledge inspect --id "patterns"
+sillyspec knowledge inspect --id "known-issues/sqljs-wasm-only"
+sillyspec knowledge inspect --id "generated/worktree-baseline-conflict"
+```
+
+**输出（JSON）：**
+```json
+{
+  "ok": true,
+  "entry": {
+    "id": "patterns",
+    "title": "Patterns",
+    "summary": "每个阶段对应 `src/stages/` 下的独立模块...",
+    "zone": "manual",
+    "path": "knowledge/patterns.md",
+    "meta": {
+      "author": "qinyi",
+      "created_at": "2026-06-19T12:40:00+08:00",
+      "updated_at": "2026-06-24T10:00:00+08:00"
+    },
+    "body": "完整 markdown 内容..."
+  }
+}
+```
+
+**zone 说明：**
+- `manual` — 人工维护的知识（可直接信任）
+- `generated` — 自动提取的知识（scan 生成，需人工审核）
+- `proposed` — 提议待审核的知识（未合并）
+
+---
+
+### 3. knowledge validate — 校验知识库健康度
+在 commit/archive 前检查知识库是否可用。
+
+```bash
+sillyspec knowledge validate
+```
+
+**输出（JSON）：**
+```json
+{
+  "ok": false,
+  "errors": [
+    {
+      "code": "broken_reference",
+      "path": "knowledge/generated/foo.md",
+      "referenced_in": "INDEX.md",
+      "display": "Foo Pattern"
+    },
+    {
+      "code": "empty_file",
+      "path": "knowledge/bar.md"
+    }
+  ],
+  "warnings": [
+    {
+      "code": "too_many_uncategorized",
+      "count": 12,
+      "path": "knowledge/uncategorized.md"
+    },
+    {
+      "code": "unregistered_file",
+      "path": "knowledge/new-file.md"
+    }
+  ]
+}
+```
+
+**错误码说明：**
+| code | 说明 |
+|---|---|
+| `knowledge_dir_missing` | `.sillyspec/knowledge/` 目录不存在 |
+| `missing_index` | `INDEX.md` 不存在 |
+| `broken_reference` | INDEX.md 引用的文件不存在 |
+| `empty_file` | 知识文件为空 |
+| `too_many_uncategorized` | uncategorized.md 条目 ≥10，需清理 |
+| `unregistered_file` | 手动知识文件未在 INDEX.md 注册 |
+
+---
+
+### 4. knowledge refresh — 从 scan 文档刷新自动知识
+**仅写 generated/ 区，不覆盖 manual/。**
+
+```bash
+sillyspec knowledge refresh
+```
+
+**使用场景：**
+- scan 阶段完成后，自动提取可复用知识
+- archive 阶段完成后，沉淀长期有效的模式
+
+**行为：**
+1. 扫描 `.sillyspec/docs/<project>/scan/*.md`
+2. 提取每个 `## 章节`（至少 3 行）作为知识条目
+3. 写入 `.sillyspec/knowledge/generated/<slug>.md`
+4. 生成 `generated/INDEX.md`
+
+**输出（JSON）：**
+```json
+{
+  "ok": true,
+  "generated_count": 8,
+  "new_count": 5,
+  "overwritten_count": 3,
+  "files": [
+    { "file": "generated/worktree-isolation.md", "title": "...", "new": true },
+    { "file": "generated/progress-management.md", "title": "...", "new": false }
+  ]
+}
+```
+
+**注意事项：**
+- generated/ 区知识是自动生成，不保证准确，需人工审核后合并到 manual/
+- 已有文件会被覆盖（ overwrite_count）
+
+---
+
+### 5. knowledge propose — 提议新知识
+不直接编辑 manual/，而是写入 proposed/ 供审核。
+
+```bash
+sillyspec knowledge propose --title "<title>" --category <category> --body "<content>" --from "<source>"
+```
+
+**参数说明：**
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--title` | ✅ | 知识标题 |
+| `--category` | ❌ | 分类（默认 uncategorized），如 known-issues, patterns, conventions |
+| `--body` | ❌ | 知识正文 |
+| `--from` | ❌ | 来源标注（如 execute/quick/scan） |
+
+**示例：**
+```bash
+sillyspec knowledge propose --title "GLM API 超时处理" --category known-issues --body "GLM 模型默认超时 30 秒..." --from "execute"
+```
+
+**输出（JSON）：**
+```json
+{
+  "ok": true,
+  "id": "proposed/glm-api-timeout",
+  "path": "knowledge/proposed/glm-api-timeout.md",
+  "title": "GLM API 超时处理",
+  "category": "known-issues",
+  "new": true,
+  "action": "created"
+}
+```
+
+**后续流程：**
+- archive/commit 阶段审核 proposed/ 条目
+- 合格的合并到 manual/，不合格的删除
+
+---
+
+## Agent 使用指南
+
+### 任务前必查
+在开始实现新功能、修改现有代码、或遇到报错前：
+1. `knowledge search --query "<任务关键词>"`
+2. 命中则 `knowledge inspect --id "<id>"`
+3. 遵循知识中的约定和避坑建议
+
+### 发现新知识
+执行任务中发现可复用模式或新坑：
+1. `knowledge propose --title "<标题>" --category <分类> --body "<内容>"`
+2. 不要直接编辑 `.sillyspec/knowledge/manual/*.md`
+
+### 提交前校验
+commit/archive 前检查知识库状态：
+1. `knowledge validate`
+2. 如有 errors，先修复再提交
+
+### 扫描后刷新
+scan 阶段完成后：
+1. `knowledge refresh`
+2. 审核生成的 `generated/*.md`，有用的合并到 manual/
+
+---
+
+## 禁止事项
+
+❌ **不要直接编辑** `manual/` 或 `generated/` 中的知识文件
+- 使用 `knowledge propose` 提议新知识
+- 使用 `knowledge refresh` 刷新自动知识
+
+❌ **不要使用 `grep` 或 `cat` 直接读取知识文件**
+- 使用 `knowledge search` 和 `knowledge inspect`
+- 它们使用与 execute 阶段相同的匹配引擎
+
+❌ **不要让 agent 去审核 proposed/ 条目**
+- 提议供人工审核，不要自动合并
+- 只有用户明确要求才合并
+
+---
+
+## 设计原则
+
+- **Agent-safe：** 所有输出为 JSON，失败有明确错误码
+- **写保护：** refresh 仅写 generated/，propose 仅写 proposed/，不碰 manual/
+- **匹配引擎：** 使用 `knowledge-match.js`（与 execute 阶段一致）
+- **审计友好：** 每个条目记录来源、创建/更新时间

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

@@ -1,52 +1,21 @@
----
-name: sillyspec:plan
-description: 编写实现计划 — 2-5 分钟粒度，精确到文件路径和代码
----
-
-## 执行
-
-**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
-
-1. 运行 `sillyspec run plan` — 读取输出的步骤 prompt
-2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
-3. 步骤完成后，运行 `sillyspec run plan --done --output "你的摘要"`
-4. 重复 2-3 直到阶段完成
-5. **禁止**在没有运行 CLI 的情况下自行决定流程
-
-## 子代理并行优化（可选）
-
-当 CLI 进入"写任务蓝图 task-N.md"步骤时（Step 5 之后），可以用子代理并行加速：
-
-1. 读取 plan.md，统计任务数量
-2. 为每个 task-N.md 启动一个独立子代理
-3. 每个子代理的任务：
-   - 读取 design.md 和 plan.md
-   - 读取相关源文件
-   - 按格式要求写 task-N.md 并保存
-4. 所有子代理完成后，继续 CLI 的下一步（审查一致性）
-
-**子代理 prompt 模板：**
-```
-你是计划编写者。请为以下任务编写详细蓝图。
-
-任务：${taskName}
-变更目录：${changeDir}
-文件路径：${changeDir}/tasks/task-${taskNum}.md
-
-要求：
-1. 读取 design.md 和 plan.md 了解上下文
-2. 读取相关源文件了解现有代码
-3. 按以下格式编写任务蓝图并保存到文件：
-   - 修改文件列表
-   - 实现要求
-   - 接口定义/数据结构
-   - 边界处理
-   - 参考
-   - TDD 步骤
-   - 验收标准（checkbox）
-```
-
-**注意：** 手动跑 plan 时不用子代理（串行即可），auto skill 中建议用子代理并行。
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:plan
+description: 用于把 design 拆解为可执行的实现计划。适合用户说"拆任务、做计划、排 wave、规划实现步骤"。产出 plan.md（Wave 分组 + Task 列表 + 依赖关系）。
+---
+
+## 多变更说明
+
+如果项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录），所有 `sillyspec run` 命令需要加 `--change <变更名>`。只有一个变更时可省略（CLI 自动检测）。
+
+## 执行
+
+**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
+
+1. 运行 `sillyspec run plan` — 读取输出的步骤 prompt
+2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
+3. 步骤完成后，运行 `sillyspec run plan --done --output "你的摘要"`
+4. 重复 2-3 直到阶段完成
+5. **禁止**在没有运行 CLI 的情况下自行决定流程
+
+## 用户指令
+$ARGUMENTS

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

@@ -1,17 +1,21 @@
----
-name: sillyspec:propose
-description: 生成结构化规范 — proposal + design + tasks
----
-
-## 执行
-
-**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
-
-1. 运行 `sillyspec run propose` — 读取输出的步骤 prompt
-2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
-3. 步骤完成后，运行 `sillyspec run propose --done --output "你的摘要"`
-4. 重复 2-3 直到阶段完成
-5. **禁止**在没有运行 CLI 的情况下自行决定流程
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:propose
+description: 生成结构化规范 — proposal + design + tasks
+---
+
+## 多变更说明
+
+如果项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录），所有 `sillyspec run` 命令需要加 `--change <变更名>`。只有一个变更时可省略（CLI 自动检测）。
+
+## 执行
+
+**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
+
+1. 运行 `sillyspec run propose` — 读取输出的步骤 prompt
+2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
+3. 步骤完成后，运行 `sillyspec run propose --done --output "你的摘要"`
+4. 重复 2-3 直到阶段完成
+5. **禁止**在没有运行 CLI 的情况下自行决定流程
+
+## 用户指令
+$ARGUMENTS

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

@@ -1,17 +1,21 @@
----
-name: sillyspec:quick
-description: 快速任务 — 跳过完整流程，直接做
----
-
-## 执行
-
-**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
-
-1. 运行 `sillyspec run quick` — 读取输出的步骤 prompt
-2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
-3. 步骤完成后，运行 `sillyspec run quick --done --output "你的摘要"`
-4. 重复 2-3 直到阶段完成
-5. **禁止**在没有运行 CLI 的情况下自行决定流程
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:quick
+description: 用于明确、低风险、范围很小的直接任务。适合用户说"直接改、快速修、顺手调整、改个文案、修个小 bug、更新一个文件、不要完整流程"。跳过 brainstorm/plan，但仍按 sillyspec quick 流程执行。
+---
+
+## 多变更说明
+
+如果项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录），所有 `sillyspec run` 命令需要加 `--change <变更名>`。只有一个变更时可省略（CLI 自动检测）。
+
+## 执行
+
+**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
+
+1. 运行 `sillyspec run quick` — 读取输出的步骤 prompt
+2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
+3. 步骤完成后，运行 `sillyspec run quick --done --output "你的摘要"`
+4. 重复 2-3 直到阶段完成
+5. **禁止**在没有运行 CLI 的情况下自行决定流程
+
+## 用户指令
+$ARGUMENTS