sillyspec 3.20.6 → 3.20.7

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

@@ -1,30 +1,90 @@
----
-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
+---
+name: sillyspec:execute
+description: 用于按 plan 执行代码实现。适合用户说"开始写代码、执行任务、跑 execute、开干"。按 plan.md 中的 Wave 和 Task 逐步实现，遵循 design.md 和模块文档。
+---
+
+## 何时使用
+
+- 用户说"开始写代码、执行任务、跑 execute、开干"
+- 按 plan.md 的 Wave 分组和 Task 逐步实现代码
+- 遵循 design.md + 模块文档 + CONVENTIONS.md
+
+## 多变更说明
+
+项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录）时，所有 `sillyspec run` 命令需加 `--change <变更名>` 指定操作目标；只有一个变更时可省略（CLI 自动检测）。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec execute` 是 `sillyspec run execute` 的顶层别名，两者等价。
+
+```bash
+sillyspec run execute                          # 输出当前步骤 prompt（首次自动创建 worktree）
+sillyspec run execute --done --output "摘要"   # 完成当前步骤（--input "用户原话" 记录输入）
+sillyspec run execute --status                 # 查看阶段进度
+sillyspec run execute --skip                   # 跳过可选步骤
+sillyspec run execute --reset                  # 重置阶段（从头开始）
+sillyspec run execute --reopen --from-step N   # 重新打开已完成阶段修订（N=序号或名称）
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--change <名>` | 指定变更名（多活跃变更必填，单变更可省略自动检测） |
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--non-interactive` | CI/脚本下禁用交互式 prompt |
+| `--skip-approval` | 跳过审批/校验门控（需明确意图） |
+| `--json` | 输出 JSON（程序化读取） |
+
+## execute 特有：Worktree 隔离
+
+- CLI 启动 execute 阶段时**自动创建 git worktree**，AI 不需要手动创建
+- worktree 路径在步骤 prompt 中输出（`worktreePath`），后续子代理的 cwd 必须设为该路径
+- **禁止跳过 worktree 或在主仓库直接写代码**
+- worktree 创建失败时 CLI 报错退出，排查后重试
+- dirty 状态/未提交文件**不影响** worktree 创建和进入，直接按 CLI 输出的路径操作，不要自行检查 git 状态
+
+### 依赖门控（depsStatus）
+
+`--done` 时 CLI 校验 worktree 的依赖状态（`depsStatus`）。不达标会阻断完成并提示：
+
+```bash
+# 修复依赖供给
+sillyspec worktree doctor --fix --change <变更名>
+```
+
+`linked / installed / n/a` 放行；`missing / stale / failed / unknown` 阻断。Wave 内所有 task 声明 `no_deps_verify: true` 时可 opt-out。
+
+### Task Review Gate
+
+execute 完成时，每个 task 必须有 `review.json` 且 verdict 通过，否则阻断完成。`cannot_verify` 的 task 会写入 `verify-required-evidence.json`，由 verify 阶段消费。
+
+## worktree 子命令（execute 相关）
+
+```bash
+sillyspec worktree apply <变更名>              # 校验并应用 worktree 变更到主工作区
+sillyspec worktree apply <变更名> --check-only # 只检查不应用
+sillyspec worktree assess <变更名>             # 风险审计 + 自动 apply
+sillyspec worktree list                        # 列出所有活跃 worktree
+sillyspec worktree meta <变更名>               # 读取 worktree meta.json
+sillyspec worktree cleanup <变更名>            # 清理 worktree
+sillyspec worktree doctor [--fix]              # 健康检查 + 修复
+```
+
+## 阶段流转
+
+```
+plan → execute → verify
+```
+
+execute 完成后（所有 Wave/task 完成 + Task Review Gate 通过），运行 `sillyspec run verify --change <变更名>` 验证。
+
+## 铁律
+
+- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
+- 你是执行者不是设计师——按 plan 搬砖，发现 plan 不合理就停下来反馈，不自己改方案
+- 子代理 cwd 必须用 CLI 输出的 worktreePath
+- 完成后立即 `--done`，不跳过
+
+## 用户指令
+$ARGUMENTS

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

@@ -1,109 +1,96 @@
----
-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. 结束探索
-
-## 禁止事项
-
-- ❌ 写实现代码
-- ❌ 安装依赖
-- ❌ 修改任何文件（除非用户明确要求保存发现）
-- ❌ 强行下结论
-- ❌ 强行结构化（让模式自然涌现）
+---
+name: sillyspec:explore
+description: 用于自由讨论、代码库调研、方案比较、画 ASCII 图、澄清问题。适合用户说"分析下、讨论下、看看怎么设计、先别写代码、调研一下、画个结构图、帮我再分析下"。只读，不修改文件，不实现功能。
+---
+
+## 交互规范
+
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。** 不要用编号列表让用户手动输入数字。
+
+## 话题
+$ARGUMENTS
+
+---
+
+你现在是 SillySpec 的自由思考伙伴。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec explore` 是 `sillyspec run explore` 的顶层别名，两者等价。explore 是 1 步只读阶段。
+
+```bash
+sillyspec run explore                              # 输出探索模式 prompt
+sillyspec run explore --done --input "<用户话题>" --output "你的摘要"   # 结束探索
+sillyspec run explore --status                     # 查看阶段状态
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--change <名>` | 指定变更名（多活跃变更时） |
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--json` | 输出 JSON（程序化读取） |
+
+## 这是什么模式
+
+**探索模式用于思考，不用于实现。** 你可以读文件、搜代码、调查代码库，但绝对不能写代码或实现功能。如果用户要求实现，提醒他们先退出探索模式。
+
+**这不是一个工作流，是一种姿态。** 没有固定步骤、没有必需的输出。你是一个帮助用户思考的伙伴。
+
+## 姿态
+
+- **好奇，不说教** — 问自然产生的问题，不按脚本走
+- **开放式线程** — 展示多个有趣方向，让用户选择
+- **可视化** — 大量使用 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，自然地引用它们。发现重要决策时**提议保存**（不自动保存）。
+
+## 没有必需的结束
+
+探索可以：创建变更提案 → 流入 proposal / 产出文档更新 / 继续探索 / 结束探索。
+
+## 禁止事项
+
+- ❌ 写实现代码
+- ❌ 安装依赖
+- ❌ 修改任何文件（除非用户明确要求保存发现）
+- ❌ 强行下结论
+- ❌ 强行结构化（让模式自然涌现）

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

@@ -5,6 +5,10 @@ description: 导出成功方案为可复用模板
 
 ---
 
+## CLI 边界（重要）
+
+sillyspec CLI **没有 `export` 顶层命令**。本 skill 通过直接复制变更文件到 `~/.sillyspec/templates/<change-name>/` 生成可复用模板，是纯文件操作。**不要编造 `sillyspec export ...` 子命令。**
+
 你现在是 SillySpec 的模板导出器。
 
 ## 参数解析

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

@@ -12,6 +12,13 @@ description: 绿地项目初始化 — 深度提问、调研、需求文档、
 
 ---
 
+## 两个 init 的区别（重要）
+
+- **`sillyspec init`（CLI 命令）** — 安装命令模板/MCP 工具到项目（零交互，自动检测工具）。用法：`sillyspec init [--tool <名>] [--interactive] [--dir <path>] [--spec-dir <path>]`
+- **`/sillyspec:init`（本 skill）** — 绿地项目的需求文档生成流程（深度提问 → REQUIREMENTS.md → ROADMAP.md → PROJECT.md），不写代码、不装依赖
+
+两者用途不同、不冲突：可先用本 skill 搞清需求，再用 CLI `sillyspec init` 装工具。
+
 你现在是 SillySpec 的项目初始化器。
 
 ## 用户输入

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

@@ -1,21 +1,74 @@
----
-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
+---
+name: sillyspec:plan
+description: 用于把 design 拆解为可执行的实现计划。适合用户说"拆任务、做计划、排 wave、规划实现步骤"。产出 plan.md（Wave 分组 + Task 列表 + 依赖关系）。
+---
+
+## 何时使用
+
+- 用户说"拆任务、做计划、排 wave、规划实现步骤"
+- 把 brainstorm 的 design.md 拆成可执行的 Wave + Task
+- 产出：`plan.md`（Wave 分组 + Task 列表 + 依赖关系），可能含 `tasks/task-NN.md` 任务蓝图
+
+## 多变更说明
+
+项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录）时，所有 `sillyspec run` 命令需加 `--change <变更名>` 指定操作目标；只有一个变更时可省略（CLI 自动检测）。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec plan` 是 `sillyspec run plan` 的顶层别名，两者等价。
+
+```bash
+sillyspec run plan                             # 输出当前步骤 prompt
+sillyspec run plan --done --output "摘要"      # 完成当前步骤（--input "用户原话" 记录输入）
+sillyspec run plan --status                    # 查看阶段进度
+sillyspec run plan --skip                      # 跳过可选步骤
+sillyspec run plan --reset                     # 重置阶段（从头开始）
+sillyspec run plan --reopen --from-step N      # 重新打开已完成阶段修订（N=序号或名称）
+sillyspec run plan --wait --reason "..." --options "A,B"   # 暂停等用户决策
+sillyspec run plan --continue --answer "..."               # 恢复等待中的步骤
+sillyspec run plan --done --answer "..." --output "..."    # 一步完成 wait+done
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--change <名>` | 指定变更名（多活跃变更必填，单变更可省略自动检测） |
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--non-interactive` | CI/脚本下禁用交互式 prompt |
+| `--interactive` | 强制交互（即便 stdin 非 TTY） |
+| `--skip-approval` | 跳过审批/校验门控（需明确意图） |
+| `--json` | 输出 JSON（程序化读取） |
+
+## plan 特有
+
+### 动态步骤
+
+plan 的步骤是动态的：`generate_plan` 步骤完成后，CLI 会从刚生成的 `plan.md` 解析出 task，自动插入"任务蓝图协调器"步骤（per-task）。这是正常行为，不要手动添加。
+
+### 契约门控（阻断完成）
+
+- **plan 启动前**：CLI 校验 `design.md` 是否满足 plan 契约（缺文件变更清单/风险登记/自审章节会阻断）。若失败需先 `sillyspec run brainstorm --reopen --from-step N` 修订设计。
+- **plan 完成时**：CLI 校验 `plan.md` 是否满足 execute 契约（Wave 结构、task 引用等）。失败会阻断完成，提示修复后重新 `--done`。
+
+### 生产接线路径检查
+
+plan 完成校验会检查：design 提到入口文件（cli.ts/main.ts/server.ts 等）但 task 的 allowed_paths 不含该文件 → 报 error。若确实不需要改入口，在 design.md 明示理由。
+
+## 阶段流转
+
+```
+brainstorm → plan → execute
+```
+
+plan 完成后（plan.md 通过 execute 契约校验），运行 `sillyspec run execute --change <变更名>` 开始实现。
+
+## 铁律
+
+- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
+- 只做当前步骤 prompt 描述的操作，不跳过、不自行扩展
+- plan.md 是任务完成的唯一真相源，task 拆解粒度要均匀、依赖要明确
+- 完成后立即 `--done`，不跳过
+
+## 用户指令
+$ARGUMENTS

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

@@ -1,21 +1,61 @@
----
-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
+---
+name: sillyspec:propose
+description: 生成结构化规范 — proposal + design + tasks。适合用户说"生成规范、补全四件套、propose"。产出 proposal.md + design.md + tasks.md（+ 可能的 requirements.md）。
+---
+
+## 何时使用
+
+- 用户说"生成规范、补全四件套、propose"
+- 已有零散设计/需求，需补全结构化规范四件套
+- 产出：`proposal.md` + `design.md` + `tasks.md`（+ 可选 `requirements.md`）
+
+> 注：propose 与 brainstorm 都产出四件套。brainstorm 是从需求开始的完整设计流程；propose 更偏"补全/生成规范"。新需求一般走 brainstorm。
+
+## 多变更说明
+
+项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录）时，所有 `sillyspec run` 命令需加 `--change <变更名>` 指定操作目标；只有一个变更时可省略（CLI 自动检测）。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec run propose` 需用 `run` 形式（propose 无顶层别名，与 brainstorm/plan 等不同）。
+
+```bash
+sillyspec run propose                          # 输出当前步骤 prompt
+sillyspec run propose --done --output "摘要"   # 完成当前步骤
+sillyspec run propose --status                 # 查看阶段进度
+sillyspec run propose --skip                   # 跳过可选步骤
+sillyspec run propose --reset                  # 重置阶段（从头开始）
+sillyspec run propose --reopen --from-step N   # 重新打开已完成阶段修订
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--change <名>` | 指定变更名（多活跃变更必填，单变更可省略自动检测） |
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--non-interactive` | CI/脚本下禁用交互式 prompt |
+| `--skip-approval` | 跳过审批/校验门控 |
+| `--json` | 输出 JSON（程序化读取） |
+
+## propose 特有：自检门控
+
+propose 含自检步骤，完成时校验四件套文档齐全 + 内容章节（如 proposal 的 Non-Goals、design 的文件变更清单/风险登记/自审）。缺失会阻断完成。
+
+## 阶段流转
+
+```
+(零散设计/需求) → propose → plan
+```
+
+propose 完成后（四件套齐 + 自检通过），运行 `sillyspec run plan --change <变更名>` 进入实现计划。
+
+## 铁律
+
+- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
+- 只做当前步骤 prompt 描述的操作，不跳过
+- 产物写入 CLI 输出的 `changeDir` 目录
+- 完成后立即 `--done`，不跳过
+
+## 用户指令
+$ARGUMENTS

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

@@ -1,21 +1,84 @@
----
-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
+---
+name: sillyspec:quick
+description: 用于明确、低风险、范围很小的直接任务。适合用户说"直接改、快速修、顺手调整、改个文案、修个小 bug、更新一个文件、不要完整流程"。跳过 brainstorm/plan，但仍按 sillyspec quick 流程执行。
+---
+
+## 何时使用
+
+- 明确、低风险、范围小的直接修改：改文案、修小 bug、更新单个文件
+- 用户说"直接改、快速修、顺手调整、不要完整流程"
+- 跳过 brainstorm/plan，但仍走 quick 的 3 步流程（理解任务 → 实现 → 自检提交）
+
+## 多变更说明（quick 特殊，务必注意）
+
+quick 阶段的 `--change` 语义是「关联变更」**且会触发步骤重置**，**不要用 `--change` 来指定关联变更**。多活跃变更时改用：
+
+- `--linked-changes none`：不关联，仅记 QUICKLOG
+- `--linked-changes a,b`：显式关联到变更 a、b
+- `--non-interactive`：CI/脚本环境，默认不关联（避免交互 prompt 崩溃）
+
+首次 `sillyspec run quick` 选定的关联会持久化到 `.runtime/quick-guard.json`，后续 `--done` 自动复用，**不会重复弹交互 prompt**。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec quick` 是 `sillyspec run quick` 的顶层别名，两者等价。
+
+```bash
+sillyspec run quick                            # 输出当前步骤 prompt（首次会记录 baseline）
+sillyspec run quick --done --output "摘要"     # 完成当前步骤
+sillyspec run quick --status                   # 查看阶段进度
+sillyspec run quick --skip                     # 跳过可选步骤
+sillyspec run quick --reset                    # 重置阶段（从头开始）
+sillyspec run quick --reopen --from-step N     # 重新打开已完成阶段修订（N=序号或名称）
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--non-interactive` | CI/脚本下禁用交互式 prompt |
+| `--interactive` | 强制交互（即便 stdin 非 TTY） |
+| `--skip-approval` | 跳过审批/校验门控（需明确意图） |
+| `--json` | 输出 JSON（程序化读取） |
+
+## quick 特有参数
+
+| 参数 | 说明 |
+|---|---|
+| `--linked-changes none\|a,b` | **显式关联变更（取代 `--change`，推荐）**。none=不关联，a,b=关联列表 |
+| `--files a.js,b.js` | 显式声明本次允许修改的文件（边界保护） |
+| `--allow-new` | 允许新增文件（默认禁止，防意外创建） |
+| `--force-baseline` | 允许覆盖 baseline 受保护文件（危险，慎用） |
+| `--confirm` | 完成时确认接受变更审计结果（warning/blocked 时用） |
+
+## 典型用法
+
+```bash
+# 单变更项目，直接开始
+sillyspec run quick
+
+# 多变更项目，显式不关联
+sillyspec run quick --linked-changes none
+
+# 多变更项目，关联到指定变更
+sillyspec run quick --linked-changes 2026-07-03-add-login
+
+# CI/脚本（非交互，避免 prompt 崩溃）
+sillyspec run quick --non-interactive
+sillyspec run quick --done --linked-changes none --output "修复手机号校验"
+
+# 限定修改文件范围
+sillyspec run quick --files src/phone.ts,src/phone.test.ts
+```
+
+## 铁律
+
+- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
+- quick 直接在主工作区改代码（不创建 worktree），范围必须小且明确
+- 完成后立即 `--done`，不跳过
+- step 2 会创建 `.sillyspec/quicklog/QUICKLOG-<user>.md` 记录，完成前 CLI 会校验它存在
+- **禁止**在没有运行 CLI 的情况下自行决定流程
+
+## 用户指令
+$ARGUMENTS