superpowers-zh 1.6.0 → 1.7.1

package/skills/subagent-driven-development/scripts/sdd-workspace

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Resolve and ensure the working-tree directory SDD uses for its short-lived
+# artifacts: task briefs, implementer reports, review packages, and the
+# progress ledger. Print the directory's absolute path.
+#
+# The workspace lives in the working tree (not under .git/) because Claude Code
+# treats .git/ as a protected path and denies agent writes there — which blocks
+# an implementer subagent from writing its report file. A self-ignoring
+# .gitignore keeps the workspace out of `git status` and out of accidental
+# commits without modifying any tracked file.
+#
+# Single source of truth for the workspace location, so task-brief and
+# review-package cannot drift to different directories.
+#
+# Usage: sdd-workspace
+set -euo pipefail
+
+root=$(git rev-parse --show-toplevel)
+dir="$root/.superpowers/sdd"
+mkdir -p "$dir"
+printf '*\n' > "$dir/.gitignore"
+cd "$dir" && pwd

package/skills/subagent-driven-development/scripts/task-brief

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Extract one task's full text from an implementation plan into a file the
+# implementer reads in one call, so the task text never has to be pasted
+# through the controller's context.
+#
+# Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]
+# Default OUTFILE: <repo-root>/.superpowers/sdd/task-<N>-brief.md
+# (per worktree; concurrent runs in the same working tree share it).
+#
+# 中文 fork 适配：上游只识别英文任务标题 "## Task N"，而 superpowers-zh
+# 的 writing-plans 产出的是 "### 任务 N：..."。下方 awk 同时匹配
+# "Task" 与 "任务"，两种计划都能抽取。
+set -euo pipefail
+
+if [ $# -lt 2 ] || [ $# -gt 3 ]; then
+  echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
+  exit 2
+fi
+
+plan=$1
+n=$2
+[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
+
+if [ $# -eq 3 ]; then
+  out=$3
+else
+  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace")
+  out="$dir/task-${n}-brief.md"
+fi
+
+awk -v n="$n" '
+  /^```/ { infence = !infence }
+  !infence && /^#+[ \t]+(Task|任务)[ \t]*[0-9]+/ {
+    intask = ($0 ~ ("^#+[ \t]+(Task|任务)[ \t]*" n "([^0-9]|$)"))
+  }
+  intask { print }
+' "$plan" > "$out"
+
+if [ ! -s "$out" ]; then
+  echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}' / '任务 ${n}')" >&2
+  exit 3
+fi
+
+echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"

package/skills/subagent-driven-development/task-reviewer-prompt.md

@@ -0,0 +1,169 @@
+# 任务审查者提示词模板
+
+分派任务审查子智能体时使用此模板。审查者一次性读取该任务的 diff，
+返回两个结论：规格合规性和代码质量。
+
+**目的：** 核实一个任务的实现与其需求匹配（不多不少）且构建良好（整洁、有测试、可维护）
+
+```
+Subagent (general-purpose):
+  description: "审查任务 N（规格 + 质量）"
+  model: [模型 —— 必填：按 SKILL.md 的"模型选择"来选；省略模型会默默
+         继承会话里最贵的那个]
+  prompt: |
+    你正在审查一个任务的实现：先看它是否与需求匹配，再看它是否
+    构建良好。这是一个任务范围内的关卡，不是合并审查——覆盖整个
+    分支的宽范围审查会在所有任务完成后另行进行。
+
+    ## 要求的内容
+
+    读取任务简报：[BRIEF_FILE]
+
+    来自规格/设计、约束本任务的全局约束：
+    [GLOBAL_CONSTRAINTS]
+
+    ## 实现者声称构建了什么
+
+    读取实现者的报告：[REPORT_FILE]
+
+    ## 待审查的 Diff
+
+    **Base：** [BASE_SHA]
+    **Head：** [HEAD_SHA]
+    **Diff 文件：** [DIFF_FILE]
+
+    一次性读取这个 diff 文件——它包含提交列表、stat 摘要，以及
+    带上下文的完整 diff，它就是你对本次改动的视图。diff 的上下文行
+    **就是**那些被改动的文件：不要单独去 Read 某个被改动的文件，除非
+    你必须判断的某个 hunk 在函数中途被截断——并在报告中说明这一点。
+    不要重跑 git 命令。如果 diff 文件缺失，就自己取 diff：
+    `git diff --stat [BASE_SHA]..[HEAD_SHA]` 和 `git diff [BASE_SHA]..[HEAD_SHA]`。
+    不要爬取更广的代码库。只有为了评估一个你能点名的具体风险，才去
+    查看 diff 之外的代码——每个点名的风险做一次聚焦检查，并在报告中
+    同时点名这个风险和你检查了什么。横切改动是正当的、可点名的风险：
+    如果 diff 改动了锁顺序、某个函数或 API 契约、或共享的可变状态，
+    检查其调用点就是正确的方法。
+
+    你的审查在这个 checkout 上是只读的。不要以任何方式改动工作树、
+    索引、HEAD 或分支状态。
+
+    ## 不要信任报告
+
+    把实现者的报告当作关于代码的、未经核实的说法。它可能不完整、
+    不准确或过于乐观。对照 diff 去核实这些说法。报告里的设计理由
+    同样是说法："出于 YAGNI 留着没做""特意保持简单"或任何其他辩解，
+    都是实现者在给自己的工作打分。就代码本身评判它的优劣——一句
+    陈述出来的理由永远不会降低一个发现的严重度。
+
+    ## 测试
+
+    实现者已经跑过测试，并为正是这份代码报告了带 TDD 证据的结果。
+    不要为了确认他们的报告而重跑测试套件。只有当阅读代码引出一个
+    现有任何运行都无法回答的具体疑问时，才去跑测试——而且是聚焦
+    测试，绝不是包级套件、竞态检测运行、或反复的/高次数的循环。
+    如果看起来确实需要重度验证，就在报告里建议它，而不是自己去跑。
+    如果你在这个环境里无法运行命令，就点名你会跑的那个测试。
+
+    实现者报告的测试输出里的告警或其他噪声都是发现——测试输出
+    应当是干净的。
+
+    ## 第一部分：规格合规性
+
+    把 diff 对照"要求的内容"来看：
+
+    - **缺失：** 他们跳过、遗漏、或声称却未实现的需求
+    - **多余：** 未被要求的功能、过度工程、不需要的"锦上添花"
+    - **理解偏差：** 正确的功能却用错了方式来构建，解决了错误的问题
+
+    如果某个需求无法仅从这份 diff 中核实（它藏在未改动的代码里、
+    或横跨多个任务），就把它作为一个 ⚠️ 事项报告出来，而不是
+    扩大你的搜索范围。
+
+    ## 第二部分：代码质量
+
+    **代码质量：**
+    - 关注点分离是否干净？
+    - 错误处理是否恰当？
+    - 是否做到 DRY 而没有过早抽象？
+    - 边界情况是否处理了？
+
+    **测试：**
+    - 新增和改动的测试是否验证了真实行为，而非 mock？
+    - 本任务的边界情况是否被覆盖？
+
+    **结构：**
+    - 每个文件是否有单一明确的职责和定义清晰的接口？
+    - 各单元是否拆分得足以独立理解和测试？
+    - 实现是否遵循了计划中的文件结构？
+    - 本次改动是否创建了已经很大的新文件，或显著增大了现有文件？
+      （不要标记已有的文件大小问题——聚焦于本次改动带来的贡献。）
+
+    你的报告应指向证据：每一个发现、以及任何你本来会用一句干巴巴的
+    "是"来回答的检查，都要给出 file:line 引用。一份引用了行号的
+    紧凑报告，就把控制者需要的一切都给它了。
+
+    你的最终消息就是报告本身：直接从规格合规性结论开始。每一行
+    要么是一个结论、要么是一个带 file:line 的发现、要么是你跑过的
+    一个检查——没有开场白、没有流程叙述、没有结尾小结。
+
+    ## 校准
+
+    按实际严重度给问题分类。不是所有东西都是 关键。
+    重要 意味着这个任务在修好之前不可信：不正确或脆弱的行为、
+    一个漏掉的需求、或你会为之拦下合并的可维护性损害——逻辑块的
+    逐字重复、被吞掉的错误、什么都不断言的测试。"覆盖面可以更广"
+    和打磨类建议是 次要。
+    如果计划或简报明确强制了某个本评分标准称之为缺陷的东西（一个
+    什么都不断言的测试、逻辑块的逐字重复），那**就是**一个发现——
+    把它报告为 重要，并标注为"计划强制"。计划的作者身份不能给它
+    自己的工作打分；由人类来决定。
+    在列出问题之前，先承认做得好的地方——准确的赞扬能帮实现者
+    信任其余的反馈。
+
+    ## 输出格式
+
+    ### 规格合规性
+
+    - ✅ 符合规格 | ❌ 发现问题：[缺失/多余/理解偏差的内容，
+      附带 file:line 引用]
+    - ⚠️ 无法从 diff 中核实：[你无法仅凭 diff 核实的需求，以及
+      控制者应当检查什么——与你能核实的一切的 ✅/❌ 结论一起报告]
+
+    ### 优点
+    [哪些做得好？要具体。]
+
+    ### 问题
+
+    #### 关键（必须修复）
+    #### 重要（应当修复）
+    #### 次要（锦上添花）
+
+    每个问题：file:line、哪里错了、为什么重要、如何修复（如果不明显）。
+
+    ### 评估
+
+    **任务质量：** [通过 | 需要修复]
+
+    **理由：** [1-2 句技术性评估]
+```
+
+**占位符：**
+- `[模型]` —— 必填：按 SKILL.md 的"模型选择"选审查者模型
+- `[BRIEF_FILE]` —— 必填：任务简报文件（`scripts/task-brief PLAN N`
+  会打印路径；与实现者所用的是同一个文件）
+- `[GLOBAL_CONSTRAINTS]` —— 从计划的"全局约束"一节或规格里逐字抄下的、
+  有约束力的需求：精确的取值、格式、以及组件之间被明确规定的关系
+  （不是流程规则——那些已经在本模板里了）
+- `[REPORT_FILE]` —— 必填：实现者写入其详细报告的那个文件
+- `[BASE_SHA]` —— 本任务之前的提交
+- `[HEAD_SHA]` —— 当前提交
+- `[DIFF_FILE]` —— 必填：控制者写入审查包的那个路径
+  （`scripts/review-package BASE HEAD` 会打印它写入的唯一路径；
+  审查包永远不会进入控制者的上下文）
+
+**审查者返回：** 规格合规性结论（✅/❌/⚠️）、优点、问题
+（关键/重要/次要）、任务质量结论
+
+一次修复分派可以同时处理规格差距和质量发现；修复后的重新审查
+覆盖两个结论。
+</content>

package/skills/using-superpowers/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 ---
 
 <SUBAGENT-STOP>
-如果你是作为子智能体被分派来执行特定任务的，跳过此技能。
+如果你是作为子智能体被分派来执行特定任务的，忽略此技能。
 </SUBAGENT-STOP>
 
 <EXTREMELY-IMPORTANT>
@@ -17,70 +17,23 @@ metadata:
 
 如果一个技能适用于你的任务，你没有选择。你必须使用它。
 
-这不可协商。这不是可选的。你不能通过合理化来逃避。
+这不可协商。你不能通过合理化来逃避。
 </EXTREMELY-IMPORTANT>
 
-## 指令优先级
-
-Superpowers 技能覆盖默认系统提示行为，但**用户指令始终具有最高优先级**：
-
-1. **用户的明确指令**（CLAUDE.md、GEMINI.md、AGENTS.md、直接请求）——最高优先级
-2. **Superpowers 技能** ——在冲突处覆盖默认系统行为
-3. **默认系统提示** ——最低优先级
-
-如果 CLAUDE.md、GEMINI.md 或 AGENTS.md 说"不要使用 TDD"，而某个技能说"始终使用 TDD"，遵循用户的指令。用户拥有控制权。
-
-## 如何访问技能
-
-**在 Claude Code 中：** 使用 `Skill` 工具。当你调用一个技能时，其内容会被加载并呈现给你——直接遵循即可。绝不要用 Read 工具读取技能文件。
-
-**在 Copilot CLI 中：** 使用 `skill` 工具。技能从已安装的插件中自动发现。`skill` 工具的工作方式与 Claude Code 的 `Skill` 工具相同。
-
-**在 Hermes Agent 中：** 使用 `skill_view` 工具加载技能。Hermes 支持三级渐进式加载：`skills_list` 浏览 → `skill_view(name)` 加载完整内容 → `skill_view(name, path)` 查看引用文件。
-
-**在 Gemini CLI 中：** 技能通过 `activate_skill` 工具激活。Gemini 在会话开始时加载技能元数据，并按需激活完整内容。
+## 规则
 
-**在其他环境中：** 查看你的平台文档了解技能的加载方式。
+**在任何响应或操作之前调用相关或被请求的技能**——包括澄清性问题、探索代码库、或查看文件之前。如果调用后发现技能不适合当前情况，你不需要使用它。
 
-## 平台适配
+**在进入 EnterPlanMode 之前：** 如果你还没有头脑风暴过，先调用头脑风暴技能。
 
-技能使用 Claude Code 的工具名称。非 CC 平台：查看 `references/copilot-tools.md`（Copilot CLI）、`references/hermes-tools.md`（Hermes Agent）、`references/codex-tools.md`（Codex）、`references/qoder-tools.md`（Qoder）了解工具对应关系。Gemini CLI 用户通过 GEMINI.md 自动获得工具映射。
+然后宣布"使用 [技能] 来 [目的]"，并严格遵循该技能。如果它有检查清单，为每个条目创建一个待办。
 
-# 使用技能
+## 技能优先级
 
-## 规则
+当多个技能都适用时，流程技能优先——它们决定处理方式，然后由实现技能（前端设计等）负责执行。头脑风暴和系统化调试是 Superpowers 中最常见的流程技能，但这条规则适用于任何流程技能。
 
-**在任何响应或操作之前调用相关或被请求的技能。** 哪怕只有 1% 的可能性某个技能适用，你都应该调用该技能来检查。如果调用后发现技能不适合当前情况，你不需要使用它。
-
-```dot
-digraph skill_flow {
-    "收到用户消息" [shape=doublecircle];
-    "即将进入 EnterPlanMode？" [shape=doublecircle];
-    "已经头脑风暴过？" [shape=diamond];
-    "调用头脑风暴技能" [shape=box];
-    "可能有技能适用？" [shape=diamond];
-    "调用 Skill 工具" [shape=box];
-    "宣布：'使用 [技能] 来 [目的]'" [shape=box];
-    "有检查清单？" [shape=diamond];
-    "为每个条目创建 TodoWrite 待办" [shape=box];
-    "严格遵循技能" [shape=box];
-    "响应（包括澄清）" [shape=doublecircle];
-
-    "即将进入 EnterPlanMode？" -> "已经头脑风暴过？";
-    "已经头脑风暴过？" -> "调用头脑风暴技能" [label="否"];
-    "已经头脑风暴过？" -> "可能有技能适用？" [label="是"];
-    "调用头脑风暴技能" -> "可能有技能适用？";
-
-    "收到用户消息" -> "可能有技能适用？";
-    "可能有技能适用？" -> "调用 Skill 工具" [label="是，哪怕只有 1%"];
-    "可能有技能适用？" -> "响应（包括澄清）" [label="确定不适用"];
-    "调用 Skill 工具" -> "宣布：'使用 [技能] 来 [目的]'";
-    "宣布：'使用 [技能] 来 [目的]'" -> "有检查清单？";
-    "有检查清单？" -> "为每个条目创建 TodoWrite 待办" [label="是"];
-    "有检查清单？" -> "严格遵循技能" [label="否"];
-    "为每个条目创建 TodoWrite 待办" -> "严格遵循技能";
-}
-```
+- "让我们构建 X" → 先用 superpowers:brainstorming，再用实现技能。
+- "修复这个 bug" → 先用 superpowers:systematic-debugging，再用领域技能。
 
 ## 红线
 
@@ -101,15 +54,17 @@ digraph skill_flow {
 | "这样做感觉很高效" | 无纪律的行动浪费时间。技能防止这一点。 |
 | "我知道那是什么意思" | 知道概念 ≠ 使用技能。调用它。 |
 
-## 技能优先级
+## 平台适配
 
-当多个技能可能适用时，使用此顺序：
+如果你的运行环境在下面列出，请阅读对应的参考文件获取特殊说明：
 
-1. **流程技能优先**（头脑风暴、调试）- 这些决定如何处理任务
-2. **实现技能其次**（前端设计、mcp-builder）- 这些指导执行
+- Codex：`references/codex-tools.md`
+- Pi：`references/pi-tools.md`
+- Copilot CLI：`references/copilot-tools.md`
+- Hermes Agent：`references/hermes-tools.md`
+- Qoder：`references/qoder-tools.md`
 
-"让我们构建 X" → 先头脑风暴，再使用实现技能。
-"修复这个 bug" → 先调试，再使用领域特定技能。
+Gemini CLI 用户通过 GEMINI.md 自动获得 `references/gemini-tools.md` 的工具映射。
 
 ## 中国特色技能路由
 
@@ -130,14 +85,6 @@ digraph skill_flow {
 
 中国特色技能与翻译技能**叠加使用**，不互斥。例如：做代码审查时，同时使用 requesting-code-review（流程）+ chinese-code-review（风格）。
 
-## 技能类型
-
-**刚性的**（TDD、调试）：严格遵循。不要偏离纪律。
-
-**灵活的**（模式）：根据上下文调整原则。
-
-技能本身会告诉你它属于哪种。
-
 ## 用户指令
 
-指令说明做什么，而非怎么做。"添加 X"或"修复 Y"不意味着跳过工作流。
+用户指令（CLAUDE.md、AGENTS.md、GEMINI.md 等、直接请求）优先于技能，技能又优先于默认行为。只有当你的人类伙伴明确告诉你跳过时，才能跳过技能工作流或指令。

package/skills/using-superpowers/references/codex-tools.md

@@ -6,7 +6,7 @@ Skills 使用 Claude Code 的工具名称。在 Codex 中遇到这些名称时
 |---------------|---------------|
 | `Task` 工具（派遣子 agent） | `spawn_agent` |
 | 多个 `Task` 调用（并行） | 多个 `spawn_agent` 调用 |
-| Task 返回结果 | `wait` |
+| Task 返回结果 | `wait_agent` |
 | Task 自动完成 | `close_agent` 释放槽位 |
 | `TodoWrite`（任务跟踪） | `update_plan` |
 | `Skill` 工具（调用 skill） | Skills 原生加载——直接按说明操作 |
@@ -22,4 +22,4 @@ Skills 使用 Claude Code 的工具名称。在 Codex 中遇到这些名称时
 multi_agent = true
 ```
 
-启用后可使用 `spawn_agent`、`wait` 和 `close_agent`，支持 `dispatching-parallel-agents` 和 `subagent-driven-development` 等 skills。
+启用后可使用 `spawn_agent`、`wait_agent` 和 `close_agent`，支持 `dispatching-parallel-agents` 和 `subagent-driven-development` 等 skills。使用 subagent-driven-development 时，implementer 和 reviewer 子 agent 完成全部工作后应始终 `close_agent` 释放。

package/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -1,26 +0,0 @@
-# 代码质量审查者提示词模板
-
-分派代码质量审查子智能体时使用此模板。
-
-**目的：** 验证实现是否构建良好（整洁、有测试、可维护）
-
-**仅在规格合规性审查通过后才分派。**
-
-```
-Task tool (superpowers:code-reviewer):
-  使用模板 requesting-code-review/code-reviewer.md
-
-  WHAT_WAS_IMPLEMENTED: [来自实现者的报告]
-  PLAN_OR_REQUIREMENTS: [plan-file] 中的任务 N
-  BASE_SHA: [任务开始前的提交]
-  HEAD_SHA: [当前提交]
-  DESCRIPTION: [任务摘要]
-```
-
-**除标准代码质量关注点外，审查者还应检查：**
-- 每个文件是否有单一明确的职责和定义清晰的接口？
-- 各单元是否拆分得足以独立理解和测试？
-- 实现是否遵循了计划中的文件结构？
-- 本次实现是否创建了已经很大的新文件，或显著增大了现有文件？（不要标记已有的文件大小问题——聚焦于本次变更带来的影响。）
-
-**代码审查者返回：** 优点、问题（关键/重要/次要）、评估结论

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -1,61 +0,0 @@
-# 规格合规审查者提示词模板
-
-分派规格合规审查子智能体时使用此模板。
-
-**目的：** 验证实现者是否构建了所要求的内容（不多不少）
-
-```
-Task tool (general-purpose):
-  description: "审查任务 N 的规格合规性"
-  prompt: |
-    你正在审查一个实现是否与其规格匹配。
-
-    ## 要求的内容
-
-    [任务需求的完整文本]
-
-    ## 实现者声称构建了什么
-
-    [来自实现者的报告]
-
-    ## 关键：不要信任报告
-
-    实现者完成得疑似过快。他们的报告可能不完整、
-    不准确或过于乐观。你必须独立验证所有内容。
-
-    **不要：**
-    - 相信他们关于实现内容的说法
-    - 信任他们关于完整性的声明
-    - 接受他们对需求的解读
-
-    **要做的：**
-    - 阅读他们写的实际代码
-    - 逐行对比实际实现和需求
-    - 检查他们声称已实现但实际遗漏的部分
-    - 寻找他们未提及的多余功能
-
-    ## 你的工作
-
-    阅读实现代码并验证：
-
-    **缺失的需求：**
-    - 他们是否实现了所有被要求的内容？
-    - 是否有他们跳过或遗漏的需求？
-    - 是否有他们声称可用但实际未实现的功能？
-
-    **多余/不需要的工作：**
-    - 他们是否构建了未被要求的内容？
-    - 他们是否过度工程化或添加了不必要的功能？
-    - 他们是否添加了规格中没有的"锦上添花"功能？
-
-    **理解偏差：**
-    - 他们是否以不同于预期的方式解读了需求？
-    - 他们是否解决了错误的问题？
-    - 他们是否实现了正确的功能但方式不对？
-
-    **通过阅读代码来验证，而非信任报告。**
-
-    报告：
-    - ✅ 符合规格（如果经过代码检查后一切匹配）
-    - ❌ 发现问题：[具体列出缺失或多余的内容，附带 file:line 引用]
-```