@wenaixi/dsh-superpower 6.3.1 → 7.0.1

package/skills/{superpower-test-driven-development → test-driven-development}/writing-good-tests.md

@@ -1,6 +1,6 @@
 # 编写高质量测试
 
-**何时加载本文档：** 编写或修改测试、添加 Mock，或为测试添加清理/辅助方法时。
+**何时加载本文档：** 编写或修改测试、添加 mock，或为测试添加清理/辅助方法时。
 
 ## 概述
 
@@ -11,7 +11,7 @@
 2. 每个测试都要验证真实对象
 ```
 
-严格的 TDD 能自然地满足这两点：先写测试并观察其在真实代码上失败，就已经证明了它具备失败能力；只有当真实依赖被证明缓慢或涉及外部系统时，才引入 Mock。
+严格的 TDD 能自然地满足这两点：先写测试并观察其在真实代码上失败，就已经证明了它具备失败能力；只有当真实依赖被证明缓慢或涉及外部系统时，才引入 mock。
 
 ## 原则一：明确测试要捕获的缺陷
 
@@ -20,19 +20,19 @@
 **独立推导期望值。** 使用字面量和人工校验的固件；表格驱动测试中 `want` 使用字面量是首选形式。由被测代码（或其辅助函数）计算出的期望值，无论代码做什么都能通过：
 
 ```typescript
-// ❌ Mirror assertion: the same builder computes both sides — always true
+// [FAIL] 镜像断言：同一个构造器算出两侧——永远为真
 const expected = buildSearchQuery({ tag: 'urgent' });
 expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected);
 
-// ✅ Hand-derived literal
+// [OK] 手工推导的字面量
 expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"');
 ```
 
-**不要写变更探测器。** 如果只有有意决策才能让测试失败——如常量的取值、文案措辞、内部结构——那么它只会在重构时触发，却在真正的缺陷面前保持沉默。应该测试依赖于该决策的行为：不要写 `expect(MAX_RETRIES).toBe(5)`，而要验证“失败调用会被重试 5 次，第 6 次绝不会发起”。
+**不要写变更探测器。** 如果只有有意决策才能让测试失败——如常量的取值、精确的措辞、内部结构——那么它只会在重新设计时触发，却在真正的缺陷面前保持沉默。应测试依赖于该决策的行为：不要写 `expect(MAX_RETRIES).toBe(5)`，而要验证“失败调用会被重试 5 次，且第 6 次绝不会发生”。
 
-**测行为，而非文本。** 断言脚本、技能或配置包含某一行，只能证明源码就是源码本身。应在受控输入下运行脚本，并断言其输出、副作用或退出码。面向 Agent 的指令性文档，应通过消费方 Agent 的行为来测试（superpower-writing-skills）；面向人的 prose 则完全不需要测试。
+**测行为，而非文本。** 断言脚本、技能或配置包含某一行，只能证明源码就是源码本身。应在受控输入下运行脚本，并断言其输出、副作用或退出码。面向 agent 的指令性文档，应通过消费方 agent 的行为来测试（writing-skills）；面向人的 prose 则完全不需要测试。
 
-**测你的代码，而非框架。** 测试你的代码在其边界上做出的契约——你注册的路由、你发出的查询、你生成的负载。上游的实现机制应由其维护者来测试（典型反例：断言你的路由会调用已注册的处理器——那是框架的测试，不是你的）。当上游行为确实出乎意料时，针对该假设写一个窄范围的特征测试（characterization test）并明确命名假设。同样边界也适用于你的内部代码：构造函数、getter、常量和简单透传，只有在它们承担校验、归一化、默认值、推导、约束或副作用时才值得测试——否则应断言首个依赖于它们的、消费者可见的结果。
+**测你的代码，而非框架。** 测试你的代码在其边界上做出的契约——你注册的路由、你发出的查询、你生成的负载。上游的实现机制应由其维护者来测试（典型反例：断言你的路由会调用已注册的处理器——那是框架的测试，不是你的）。当上游行为确实出乎意料时，针对该假设写一个窄范围的特征测试（characterization test），并命名该假设。同样的边界也适用于你的内部代码：构造函数、getter、常量和简单透传，只有在它们承担校验、归一化、默认值、推导、约束或副作用时才值得测试——否则应断言首个依赖于它们的、消费者可见的结果。
 
 ### 门禁检查
 
@@ -52,51 +52,51 @@ expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"');
 
 ## 原则二：使用真实对象
 
-**Mock 本身不值得断言。** 对 Mock 的断言，只在 Mock 存在时通过、不存在时失败——它对组件本身一无所言。应断言真实组件的行为；如果你发现自己在检查 Mock，那就去掉 Mock 或删掉该断言。
+**mock 本身不值得断言。** 对 mock 的断言，只在 mock 存在时通过、不存在时失败——它对组件本身一无所言。应断言真实组件的行为；如果你发现自己在检查 mock，那就去掉 mock 或删掉该断言。
 
 ```typescript
-// ✅ Real behavior
+// [OK] 真实行为
 expect(screen.getByRole('navigation')).toBeInTheDocument();
 
-// ❌ Mock existence
+// [FAIL] mock 的存在性
 expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
 ```
 
-**你的搭档的提醒：**“我们在测试 Mock 的行为吗？”
+**你的 human partner 的提醒：**“我们在测试 mock 的行为吗？”
 
-**在正确的层级 Mock。** 在替换真实方法前，先了解它的所有副作用；只 Mock 缓慢或外部的操作，保留测试所依赖的部分为真实实现。不确定时，先让测试跑在真实实现上，观察究竟需要发生什么。
+**在正确的层级 mock。** 在替换真实方法前，先了解它的所有副作用；只 mock 缓慢或外部的操作，保留测试所依赖的部分为真实实现。不确定时，先让测试跑在真实实现上，观察究竟需要发生什么。
 
 ```typescript
-// ❌ The mock swallows the config write that duplicate detection reads
+// [FAIL] mock 吞掉了重复检测所读取的配置写入
 vi.mock('ToolCatalog', () => ({
   discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
 }));
 
-// ✅ Mock only the slow server startup; the config write stays real
+// [OK] 只 mock 缓慢的服务器启动；配置写入保持真实
 vi.mock('MCPServerManager');
 ```
 
 **让替身足够具体。** 当参数、调用次数或顺序属于契约的一部分时，就要断言它们——一个接受任意参数的假对象什么也验证不了。为每个分支（成功、失败、畸形输入）提供独立的固件或 spy，这样错误的分支就无法满足期望。
 
-**完整镜像真实数据。** 按真实存在的完整结构来 Mock——包含所有已文档化的字段——而不仅仅是你测试中读取的字段。部分 Mock 会在下游代码读取缺失字段时静默失败：测试通过，而集成已损坏。
+**完整镜像真实数据。** 按真实存在的完整结构来 mock——包含所有已文档化的字段——而不仅仅是你测试中读取的字段。部分 mock 会在下游代码读取缺失字段时静默失败：测试通过，而集成已损坏。
 
-**生产类只承载生产方法。** 仅测试需要的清理逻辑应放在测试工具中，绝不要以 `destroy()` 的形式出现在生产类上。自问：这个方法是否只被测试调用？这个类是否拥有该资源的生命周期？答案有误 → 放到测试工具里。
+**生产类只承载生产方法。** 仅测试需要的清理逻辑应放在测试工具中，绝不要以 `destroy()` 的形式出现在生产类上。自问：这个方法是否只被测试调用？这个类是否拥有该资源的lifecycle？答案有误 → 放到测试工具里。
 
-**复杂 Mock 不如真实组件。** 当 Mock 的搭建超过测试逻辑本身、Mock 缺少真实组件拥有的方法、或测试因 Mock 变更而崩溃时，改用基于真实组件的集成测试。**你的搭档的提问：**“这里真的需要用 Mock 吗？”
+**复杂 mock 不如真实组件。** 当 mock 的搭建超过测试逻辑本身、mock 缺少真实组件拥有的方法、或测试因 mock 变更而崩溃时，改用基于真实组件的集成测试。**你的 human partner 的提问：**“这里真的需要用 mock 吗？”
 
 ### 门禁检查
 
 ```
-添加 Mock 或测试辅助方法之前：
+添加 mock 或测试辅助方法之前：
   列出真实方法的所有副作用；测试所依赖的保持真实——
-  只在更底层的缓慢/外部层级进行 Mock。
+  只在更底层的缓慢/外部层级进行 mock。
 
-  Mock 的响应需完整镜像真实结构。
+  mock 的响应需完整镜像真实结构。
 
   仅被测试调用的方法归属于测试工具，而非生产代码。
 
-  正要对 Mock 本身做断言？
-    去掉 Mock 或删掉该断言。
+  正要对 mock 本身做断言？
+    去掉 mock 或删掉该断言。
 ```
 
 ## 测试与实现一同交付
@@ -123,11 +123,11 @@ TDD 循环——失败的测试、最小实现、重构——才是“完成”
 | 构造期望值 | 手工推导；绝不要用被测代码来计算 |
 | 测试脚本或文档 | 运行它 / 对其消费者做压力测试；不要 grep 文本 |
 | 想测试依赖 | 测试你的边界契约，而非对方已文档化的实现机制 |
-| 想对 Mock 元素做断言 | 测试真实组件，或去掉 Mock |
-| 准备 Mock 方法 | 了解其副作用；在缓慢/外部层级 Mock |
-| 构造 Mock 响应 | 完整镜像真实结构 |
+| 想对 mock 元素做断言 | 测试真实组件，或去掉 mock |
+| 准备 mock 方法 | 了解其副作用；在缓慢/外部层级 mock |
+| 构造 mock 响应 | 完整镜像真实结构 |
 | 需要仅测试使用的清理逻辑 | 放到测试工具中 |
-| Mock 搭建急剧膨胀 | 改用基于真实组件的集成测试 |
+| mock 搭建急剧膨胀 | 改用基于真实组件的集成测试 |
 | 完成测试文件 | 执行变异检查 |
 
 ## 警示信号
@@ -139,7 +139,7 @@ TDD 循环——失败的测试、最小实现、重构——才是“完成”
 - 测试 grep 源码文本，或断言已移除的符号保持移除
 - 即使只剩下框架，该测试依然“有意义”
 - 测试仅为覆盖率而存在，未检查任何副作用或结果
-- 断言检查 `*-mock` 测试 ID，或在移除 Mock 后失败
+- 断言检查 `*-mock` 测试 ID，或在移除 mock 后失败
 - 某个方法只被测试文件调用
-- Mock 搭建超过测试的一半，或你无法解释为何需要 Mock
-- “为了保险”而 Mock
+- mock 搭建超过测试的一半，或你无法解释为何需要 mock
+- “为了保险”而 mock

package/skills/{superpower-using-git-worktrees → using-git-worktrees}/SKILL.md

@@ -1,21 +1,21 @@
 ---
-name: superpower-using-git-worktrees
-description: "适用于需与当前工作区隔离的功能开发或执行实现计划前，通过原生工具优先、git worktree 兜底的方式确保独立工作区就绪"
+name: using-git-worktrees
+description: "Superpower Skill：适用于需与当前 worktree 隔离的功能开发或执行实现计划前，通过原生工具优先、git worktree 兜底的方式确保独立 worktree 就绪。"
 ---
 
 # 使用 Git Worktree
 
 ## 概述
 
-确保所有工作都在独立工作区中进行。优先使用平台原生的 worktree 工具，仅在无原生工具可用时再回退到手动 git worktree。
+确保所有工作都在独立 worktree 中进行。优先使用平台原生的 worktree 工具，仅在无原生工具可用时再回退到手动 git worktree。
 
 **核心原则：** 先检测是否已处于隔离环境，再使用原生工具，最后回退到 git。不要与 harness 对抗。
 
-**开始时声明：** “我正在使用 using-git-worktrees 技能来创建独立工作区。”
+**开始时声明：** “我正在使用 using-git-worktrees 技能来创建独立 worktree。”
 
 ## 步骤 0：检测现有隔离状态
 
-**在创建任何内容之前，先检查是否已处于独立工作区中。**
+**在创建任何内容之前，先检查是否已处于独立 worktree 中。**
 
 ```bash
 GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
@@ -33,8 +33,8 @@ git rev-parse --show-superproject-working-tree 2>/dev/null
 **若 `GIT_DIR != GIT_COMMON`（且不在子模块中）：** 说明已处于关联 worktree 中。跳至步骤 2（项目初始化），不要再创建新的 worktree。
 
 按分支状态报告：
-- 处于分支上：“已在独立工作区 `<path>`，分支为 `<name>`。”
-- 游离 HEAD：“已在独立工作区 `<path>`（游离 HEAD，外部托管），结束时需创建分支。”
+- 处于分支上：“已在独立 worktree `<path>`，分支为 `<name>`。”
+- 游离 HEAD：“已在独立 worktree `<path>`（游离 HEAD，外部托管），结束时需创建分支。”
 
 **若 `GIT_DIR == GIT_COMMON`（或处于子模块中）：** 说明处于常规仓库检出状态。
 
@@ -44,13 +44,13 @@ git rev-parse --show-superproject-working-tree 2>/dev/null
 
 若已存在明确偏好则直接遵循，无需询问。若用户拒绝，则在原地工作并跳至步骤 2。
 
-## 步骤 1：创建独立工作区
+## 步骤 1：创建独立 worktree
 
 **你有两种机制，请按以下顺序尝试。**
 
 ### 1a. 原生 Worktree 工具（优先）
 
-用户已请求独立工作区（步骤 0 已获同意）。你是否已有创建 worktree 的方式？可能是名为 `EnterWorktree`、`WorktreeCreate`、`/worktree` 命令或 `--worktree` 参数的工具。如果有，请直接使用并跳至步骤 2。
+用户已请求独立 worktree（步骤 0 已获同意）。你是否已有创建 worktree 的方式？可能是名为 `EnterWorktree`、`WorktreeCreate`、`/worktree` 命令或 `--worktree` 参数的工具。如果有，请直接使用并跳至步骤 2。
 
 原生工具会自动处理目录选址、分支创建和清理。使用 `git worktree add` 而绕过原生工具会产生 harness 无法感知和管理的幽灵状态。
 
@@ -120,7 +120,7 @@ if [ -f go.mod ]; then go mod download; fi
 
 ## 步骤 3：验证干净基线
 
-运行测试以确保工作区初始状态干净：
+运行测试以确保 worktree 初始状态干净：
 
 ```bash
 # 使用项目对应的命令
@@ -162,6 +162,6 @@ Ready to implement <feature-name>
 |--------|---------|
 | “我显然不在 worktree 里，没必要检查” | 执行步骤 0。harness 创建的隔离和子模块都会让肉眼判断失误，用检测命令才能确定。 |
 | “`git worktree add` 比到处找原生工具更快” | 原生工具（如 `EnterWorktree`）负责选址、分支和清理。绕过它是头号错误——会产生 harness 无法感知和管理的幽灵状态。 |
-| “worktree 目录肯定已经被忽略了” | 请执行 `git check-ignore`。未被忽略的 worktree 目录会把整个工作树提交进仓库。 |
+| “worktree 目录肯定已经被忽略了” | 请执行 `git check-ignore`。未被忽略的 worktree 目录会把整个 working tree 提交进仓库。 |
 | “随便起个目录名都行” | 显式指令优先于已存在的项目本地目录，项目本地目录优先于 `.worktrees/` 默认值。 |
-| “工作区是全新的，基线测试可以等等再跑” | 脏基线会让后续所有失败变得无法定位。现在就跑测试；是否带病继续由你的协作人决定。 |
+| “worktree 是全新的，基线测试可以等等再跑” | 脏基线会让后续所有失败变得无法定位。现在就跑测试；是否带病继续由你的 human partner 决定。 |

package/skills/{superpower-using-superpowers → using-superpowers}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: superpower-using-superpowers
-description: "适用于任何对话开始前，建立技能查找与调用规范，要求在任何回复前优先调用相关技能，包括澄清问题"
+name: using-superpowers
+description: "Superpower Skill：适用于任何对话开始前，建立技能查找与调用规范，要求在任何回复前优先调用相关技能，包括澄清问题。"
 ---
 
 <SUBAGENT-STOP>
-如果你是作为子代理被派来执行特定任务，请忽略本技能。
+如果你是作为 subagent 被派来执行特定任务，请忽略本技能。
 </SUBAGENT-STOP>
 
 <EXTREMELY-IMPORTANT>
@@ -27,8 +27,8 @@ description: "适用于任何对话开始前，建立技能查找与调用规范
 
 当多个技能同时适用时，流程类技能优先——它们决定方法论，然后由实现类技能（如 frontend-design 等）负责落地。头脑风暴与系统化调试是 Superpowers 中最常见的流程技能，但该规则适用于所有技能。
 
-- "Let's build X" → 优先使用 superpower-brainstorming，再使用实现类技能。
-- "Fix this bug" → 优先使用 superpower-systematic-debugging，再使用领域技能。
+- "Let's build X" → 优先使用 brainstorming，再使用实现类技能。
+- "Fix this bug" → 优先使用 systematic-debugging，再使用领域技能。
 
 ## 警示信号
 
@@ -51,14 +51,10 @@ description: "适用于任何对话开始前，建立技能查找与调用规范
 
 ## 平台适配
 
-如果你的执行环境出现在此列表中，请先阅读对应的参考文件获取专项说明：
+本套件专为 **DSH (DeepSeek Harness)** 原生环境设计，仅支持 DSH 平台：
 
-- DSH (DeepSeek Harness): `references/dsh-tools.md` — **请优先阅读。** 将 Bash→pwsh/bash、Read/Write/Edit→fs、Glob/Grep→fs-search、Task/Subagent→subagent/workflow、TodoWrite→todo、AskUserQuestion→ask-user、Skill→skill 进行映射。本套件中的所有技能均假定使用 DSH 工具。
-- Codex: `references/codex-tools.md`
-- Pi: `references/pi-tools.md`
-- Antigravity: `references/antigravity-tools.md`
-- Hermes Agent: `references/hermes-tools.md`
+- DSH 工具规范：`references/dsh-tools.md` — 本套件中的所有技能均假定使用 DSH 工具（Bash→pwsh/bash、Read/Write/Edit→fs、Glob/Grep→fs-search、Task/Subagent→subagent/workflow、TodoWrite→todo、AskUserQuestion→ask-user、Skill→skill）。
 
 ## 用户指令
 
-用户指令（CLAUDE.md、AGENTS.md、GEMINI.md 等，以及直接请求）的优先级高于技能，技能又高于默认行为。仅当人类协作方明确指示时，才可跳过技能工作流或指令。
+用户指令（AGENTS.md、CLAUDE.md 等，以及直接请求）的优先级高于技能，技能又高于默认行为。仅当 human partner 明确指示时，才可跳过技能工作流或指令。

package/skills/{superpower-using-superpowers → using-superpowers}/references/dsh-tools.md

@@ -1,11 +1,11 @@
 # DSH Tools Reference for Superpowers
 
-> 面向模型的 DSH 工具速查。Superpowers 原版文案中的 Claude Code / Codex 工具名在此映射为 DSH 等价物。
-> 当 skill 指示使用某一工具时，按下表替换即可。
+> 面向模型的 DSH 工具速查。Superpowers 技能在 DSH 平台环境下的原生工具等价物与行为规范。
+> 当 skill 指示执行特定工具动作时，按本表原生 DSH 工具执行。
 
 ## 核心映射
 
-| 原版提及 | DSH 等价 | 备注 |
+| 技能动作 | DSH 等价 | 备注 |
 |---|---|---|
 | `Bash` / `bash` | `pwsh`（首选，Windows 友好）或 `bash` | 长耗时命令用 `run_in_background: true`，通过 `job_output` / `job_list` 收敛 |
 | `Read` / `Write` / `Edit` | `fs` 工具的 `read` / `write` / `edit` | `read` 前无需 `fs/observed` 校验，`write/edit` 自动触发 `fs/observed` 失效 |
@@ -15,7 +15,7 @@
 | `TodoWrite` | `todo` | 每次提供全量列表，`in_progress` 至少一项 |
 | `Skill` | `skill` | `skill(name)` 加载 `<skill_content>`，与 `ctx.skills.get()` 同源 |
 | `WebSearch` / `WebFetch` | `web` 工具 | `web_search` + `web_fetch_exa` 已封装为统一 `web` |
-| `/skill superpower-<name>` | `skill` 工具或用户显式 `/skill` 命令 | 两种路径渲染一致的 `<skill_content>` |
+| `/skill <name>` | `skill` 工具或用户显式 `/skill` 命令 | 两种路径渲染一致的 `<skill_content>` |
 | `git worktree` | `bash` / `pwsh` 中直接执行 `git worktree` | DSH 无 worktree 专属封装，按原命令执行 |
 
 ## DSH 专属能力（原版无直接对应）
@@ -25,7 +25,7 @@
 | `goal` / `ralph` | 长周期目标的创建、续跑、阻塞判定 |
 | `workflow` 脚本 | 需要编排数十个 subagent 的审计/迁移/批量改写 |
 | `jobs` | 托管后台任务的查询与终止 |
-| `plan-mode` | 只读规划锁定，与 `superpower-writing-plans` 的细粒度切片互补 |
+| `plan-mode` | 只读规划锁定，与 `writing-plans` 的细粒度切片互补 |
 | `cordis` 动态插件 | 会话内临时扩展能力（非本移植包范畴） |
 
 ## 约束与习惯
@@ -39,9 +39,9 @@
 
 ```text
 用户：帮我加一个重试工具
-模型：Using superpower-brainstorming to clarify requirements
-      -> 调用 skill(name="superpower-brainstorming")
+模型：Using brainstorming to clarify requirements
+      -> 调用 skill(name="brainstorming")
       -> 按 skill 流程提问、分类 Spike/Bounded/Architectural
-      -> 设计获批后调用 skill(name="superpower-writing-plans") 切片
+      -> 设计获批后调用 skill(name="writing-plans") 切片
       -> 每切片派发 subagent(prompt="实现 task-03...") 并用 todo 跟踪
 ```

package/skills/{superpower-verification-before-completion → verification-before-completion}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: superpower-verification-before-completion
-description: "在声称完成、修复或通过前强制执行校验，用于提交或创建PR前必须运行验证命令并确认输出，始终以证据为准而非断言"
+name: verification-before-completion
+description: "Superpower Skill：在声称完成、修复或通过前强制执行校验，用于提交或创建 PR 前必须运行验证命令并确认输出，始终以证据为准而非断言。"
 ---
 
 # 完成前的校验
@@ -44,7 +44,7 @@ description: "在声称完成、修复或通过前强制执行校验，用于提
 | 构建成功 | 构建命令：exit 0 | Linter 通过、日志看起来正常 |
 | 缺陷已修复 | 复现原症状的测试：通过 | 已改代码、想当然认为已修 |
 | 回归测试有效 | 红绿循环已验证 | 仅通过一次 |
-| 代理已完成 | VCS diff 显示有变更 | 代理报告“成功” |
+| agent 已完成 | VCS diff 显示有变更 | agent 报告“成功” |
 | 需求已满足 | 逐项核对清单 | 测试通过 |
 
 ## 危险信号 - 立即停止
@@ -52,7 +52,7 @@ description: "在声称完成、修复或通过前强制执行校验，用于提
 - 使用“应该”“大概”“似乎”等不确定表述
 - 校验前就表达满意（“太好了！”“完美！”“搞定了！”等）
 - 未经校验就准备 commit / push / 提 PR
-- 轻信代理的成功报告
+- 轻信 agent 的成功报告
 - 依赖局部校验
 - 心存“就这一次”的侥幸
 - 因疲惫而想草草收工
@@ -66,7 +66,7 @@ description: "在声称完成、修复或通过前强制执行校验，用于提
 | “我很有把握” | 把握 ≠ 证据 |
 | “就这一次” | 没有例外 |
 | “Linter 过了” | Linter ≠ 编译器 |
-| “代理说成功了” | 需独立核验 |
+| “agent 说成功了” | 需独立核验 |
 | “我太累了” | 疲惫不是理由 |
 | “局部检查就够了” | 局部证明不了任何事 |
 | “换个说法就不算违规” | 重精神而非抠字眼 |
@@ -75,32 +75,32 @@ description: "在声称完成、修复或通过前强制执行校验，用于提
 
 **测试：**
 ```
-✅ [执行测试命令] [看到：34/34 通过] “所有测试通过”
-❌ “现在应该能过了” / “看起来是对的”
+[OK] [执行测试命令] [看到：34/34 通过] “所有测试通过”
+[FAIL] “现在应该能过了” / “看起来是对的”
 ```
 
 **回归测试（TDD 红绿循环）：**
 ```
-✅ 编写 → 运行（通过）→ 回退修复 → 运行（必须失败）→ 恢复 → 运行（通过）
-❌ “我已写好回归测试”（未经红绿验证）
+[OK] 编写 → 运行（通过）→ 回退修复 → 运行（必须失败）→ 恢复 → 运行（通过）
+[FAIL] “我已写好回归测试”（未经红绿验证）
 ```
 
 **构建：**
 ```
-✅ [执行构建] [看到：exit 0] “构建通过”
-❌ “Linter 过了”（Linter 不检查编译）
+[OK] [执行构建] [看到：exit 0] “构建通过”
+[FAIL] “Linter 过了”（Linter 不检查编译）
 ```
 
 **需求：**
 ```
-✅ 重读方案 → 创建核对清单 → 逐项核验 → 报告缺口或完成情况
-❌ “测试通过，阶段完成”
+[OK] 重读方案 → 创建核对清单 → 逐项核验 → 报告缺口或完成情况
+[FAIL] “测试通过，阶段完成”
 ```
 
-**代理委派：**
+**agent 委派：**
 ```
-✅ 代理报告成功 → 检查 VCS diff → 核验变更 → 报告实际状态
-❌ 轻信代理报告
+[OK] agent 报告成功 → 检查 VCS diff → 核验变更 → 报告实际状态
+[FAIL] 轻信 agent 报告
 ```
 
 ## 适用时机
@@ -111,7 +111,7 @@ description: "在声称完成、修复或通过前强制执行校验，用于提
 - 任何关于工作状态的肯定性陈述
 - 提交、创建 PR、任务收尾
 - 进入下一项任务
-- 委派给代理
+- 委派给 agent
 
 **规则适用于：**
 - 准确措辞

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: writing-plans
+description: "Superpower Skill：当已具备清晰的需求规格或多步骤 task description 且尚未开始编码时使用，用于把需求拆解为结构清晰、粒度可控、可直接执行、可测试与可验证的完整实施计划。"
+---
+
+# 编写计划
+
+## 概述
+
+为一个尚未见过本代码库、也未见过本规格的工程师编写实施计划。假设对方一旦获知精确的接口与精确的测试，就能用项目所用语言写出惯用代码，并会在计划留白之处做出合理选择。他们无从知晓的是你的决定：选哪些文件、用哪些名称与签名、从规格里取哪些值、每个任务由哪些测试来证明。把这些写进文档。把整份计划按一口大小的任务交给他们。遵循 DRY。遵循 YAGNI。遵循 TDD。频繁提交。
+
+**开始时声明：** “我正在使用 writing-plans 技能创建实施计划。”
+
+**上下文：** 如在隔离的 worktree 中工作，该 worktree 应在执行时通过 `using-git-worktrees` 技能创建。
+
+**计划保存路径：** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+- （如用户已指定计划存放位置，则以用户偏好为准）
+
+## 范围检查
+
+若需求规格涵盖多个独立子系统，理应在头脑风暴阶段就已拆分为子项目规格。若未拆分，建议将其拆为多份独立计划——每个子系统一份。每份计划都应能独立产出可运行、可测试的软件。
+
+## 文件结构
+
+在定义任务之前，先梳理清楚将创建或修改哪些文件，以及每个文件的职责。这是锁定拆解方案的关键环节。
+
+- 设计边界清晰、接口明确的单元。每个文件只承担单一、明确的职责。
+- 人对能一次性完整装入上下文的代码推理最准确，聚焦的文件也更利于可靠地编辑。优先选择小而聚焦的文件，而非承载过多职责的大文件。
+- 会一同变更的文件应放在一起。按职责拆分，而非按技术分层。
+- 在现有代码库中遵循既有模式。若项目本身采用大文件结构，不要擅自重构；但若你正修改的文件已过于臃肿，在计划中安排一次拆分是合理的。
+
+该结构将直接决定任务如何拆解。每个任务都应产出自洽、独立有意义的变更。
+
+## 任务规模控制
+
+任务是具备完整测试闭环、值得独立评审的最小单元。划分任务边界时：将初始化、配置、脚手架与文档等步骤归入真正需要其产物的任务中；仅在 reviewer 可能对相邻两个任务做出不同评审结论（一个通过、一个驳回）时才进行拆分。每个任务结束时都应产出可独立测试的交付物。
+
+## 步骤粒度
+
+**每个步骤都是带有可校验结果的一个动作：**
+- “编写失败的测试”——一个步骤
+- “运行它，确认它确实失败”——一个步骤
+- “编写让测试通过的最小实现”——一个步骤
+- “运行测试，确认它们通过”——一个步骤
+- “提交”——一个步骤
+
+## 计划文档头部
+
+**每份计划必须以此头部开头：**
+
+```markdown
+# [功能名称] 实施计划
+
+> **面向 Agent 执行者：** 必需子技能：使用 subagent-driven-development（推荐）或 executing-plans 按任务逐项实现本计划。步骤使用复选框（`- [ ]`）语法跟踪进度。
+
+**目标：** [一句话描述本计划构建的内容]
+
+**架构：** [2-3 句话说明技术路线]
+
+**技术栈：** [关键技术与依赖库]
+
+**规格：** [本计划实现的规格/设计文档路径——计划以规格为依据进行论证，故规格须随计划一起流转；执行者两者都要读]
+
+## 全局约束
+
+[规格中项目级的要求——版本下限、依赖限制、命名与文案规则、平台要求——每项一行，数值从规格原文逐字复制。每个任务的需求默认隐含包含本节。]
+
+## Review Focus
+
+[规格隐含、但没有任何任务的测试覆盖、最可能坑到使用该软件之人的五种输入类别或失败模式——每项一行，写明该输入或条件，以及理性之人会期待的行为，最可能发生的排最前。规格是愿景文档：它说明软件必须做什么，而不是它会遇到的一切；规格对某输入的沉默不等于允许该输入弄坏程序。把这份清单一次写全于此处，写作时规格就在眼前。然后为每一行，把钉住它的测试加进拥有该代码的任务，套用那个任务自己的步骤风格。]
+
+---
+```
+
+## 任务结构
+
+````markdown
+### 任务 N：[组件名称]
+
+**文件：**
+- 新建：`exact/path/to/file.py`
+- 修改：`exact/path/to/existing.py:123-145`
+- 测试：`tests/exact/path/to/test.py`
+
+**接口：**
+- 消费：[本任务使用的前置任务产物——精确签名]
+- 产出：[后续任务依赖的内容——精确的函数名、参数与返回类型。任务的实现者只看到自己的任务；本块是他们获知相邻任务所用名称与类型的方式。]
+
+- [ ] **步骤 1：编写失败的测试**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **步骤 2：运行测试，确认其失败**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：FAIL，报 "function not defined"
+
+- [ ] **步骤 3：在 `exact/path/to/file.py` 中实现 `function(input: InputType) -> ResultType`**
+
+当签名与测试留下选择余地时（调用哪个库、用哪个数据结构），写一行说明；只有执行者无法自行确定的算法才给代码块。
+
+- [ ] **步骤 4：运行测试，确认其通过**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：PASS
+
+- [ ] **步骤 5：提交**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## 步骤包含什么
+
+一个步骤在“执行者能凭它写出恰好一件合理的事”时即为完成。这就是全部要求：无歧义，而非完备。每类步骤只携带使它无歧义所需的东西，不多不少：
+
+- **测试步骤：** 测试的名称及其断言，以代码形式给出，内含规格中的精确取值。
+- **代码步骤：** 精确签名（名称、参数、返回类型）、所在文件，以及规格钉死的具体取值。函数体由执行者自己写。只有签名与测试都无法确定的算法、或规格固定了要逐字照抄的内容，才给出函数体。
+- **验证步骤：** 要运行的命令，以及代表通过的输出。
+- **对另一个任务的引用：** 那个任务的 Interfaces 块已经说明了要使用什么；计划不重复那个任务的代码。
+
+一份计划是执行者独自无法做出的那组决定。计划比它所描述的代码还长，等于把代码写了出来。不决定任何内容的行（“TBD”、“处理边界情况”、“添加适当的校验”、“为上述内容编写测试”、没有任何任务定义过的类型或函数）是另一端的失败，自检会把两端都抓住。
+
+## 自检
+
+写完完整计划后，带着全新视角重读规格，用它核对计划。这是你亲自运行的清单——不是分发给 subagent 的活。
+
+**1. 规格覆盖度：** 逐节浏览规格中的每一项要求。能否指出实现它的那个任务？列出所有遗漏。
+
+**2. 步骤扫描：** 每个步骤都必须让执行者只写出恰好一件合理的事，且任何步骤不得携带更多内容：不决定任何内容的行是缺口，签名与测试已能确定却仍写出的函数体是转写。两者都要修复。
+
+**3. 类型一致性：** 后续任务中使用的类型、方法签名与属性名，是否与前置任务中定义的一致？任务 3 里叫 `clearLayers()`、任务 7 里却写成 `clearFullLayers()` 的函数就是缺陷。
+
+**4. Review Focus：** 规格隐含的每种输入类别或失败模式，是否都有某个任务的测试在覆盖它？最可能坑人的五种未覆盖项写入 Review Focus 段，且该段每一行都要把对应测试加进所属任务。段落为空意味着你去检查过、确认没有，而不是跳过了这项检查。
+
+**5. 篇幅比例：** 把计划长度与规格长度相比。一份比它所实现规格长数倍的计划，是对程序的转写，不是计划。如果代码块占了文档大半，把函数体换成签名、测试名与断言，并核实每个步骤仍然无歧义。
+
+如发现问题，直接原地修复。无需再评审一轮——修完继续即可。若发现某项规格要求没有对应任务，补上该任务。
+
+## 执行交接
+
+保存并自检完计划后，把计划链接给到你的 human partner 阅读。若对方已明确提供执行方式，请其复核计划、确认它捕捉到了对方想要的；实现前等待该复核，然后使用保留的方式。否则，请在实现前请对方复核计划并选择一种执行方式。
+
+**当尚未提供执行方式时：**
+
+**“计划已完成并保存至 `docs/superpowers/plans/<filename>.md`。请复核计划。你倾向哪种执行方式？**
+
+- **subagent 驱动**——每个任务由全新 subagent 实现，由全新 reviewer 在下一个任务开始前检查，最后再做一次全分支评审。最彻底；每个任务与每次评审各耗一份全新上下文。
+- **原生**——我在本会话中亲手逐任务实现，按本 harness 运行工作的方式推进，最后在最强模型上用一位全新 reviewer 检查整个分支。最省钱最快；结束前没有独立评审。用中档会话模型跑得很好，因为设计由计划承载。
+
+**就本计划我推荐 <二者之一>，因为 <从计划取一句话：任务之间对彼此接口的依赖有多深、有多少个任务、交付一个错误要付出什么代价>。计划是否符合你的期望，我们该用哪种方式？”**
+
+**当已提供执行方式时：**
+
+**“计划已完成并保存至 `docs/superpowers/plans/<filename>.md`。请复核计划。它是否捕捉到了你想要的？”**
+
+**若选择 subagent 驱动：**
+- **必需子技能：** 使用 subagent-driven-development
+
+**若选择原生：**
+- **必需子技能：** 使用 executing-plans