superpowers-zh 1.7.12 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/.claude-plugin/marketplace.json +3 -3
  2. package/.claude-plugin/plugin.json +2 -2
  3. package/.codex-plugin/plugin.json +1 -1
  4. package/.cursor-plugin/plugin.json +2 -2
  5. package/.opencode/INSTALL.md +82 -14
  6. package/.opencode/plugins/superpowers.js +319 -31
  7. package/GEMINI.md +3 -2
  8. package/README.md +68 -36
  9. package/README.zh-Hant.md +66 -37
  10. package/RELEASE-NOTES.zh.md +154 -0
  11. package/assets/sponsors/88api.jpg +0 -0
  12. package/assets/sponsors/apinebula.png +0 -0
  13. package/assets/sponsors/logo-infistar-icon.png +0 -0
  14. package/assets/sponsors/logo-sidrune-ai.png +0 -0
  15. package/assets/sponsors/logo-volcengine-icon.png +0 -0
  16. package/assets/sponsors/volcengine.png +0 -0
  17. package/bin/superpowers-zh.js +21 -2
  18. package/docs/README.aider.md +2 -2
  19. package/docs/README.claw.md +1 -1
  20. package/docs/README.cline.md +3 -3
  21. package/docs/README.codearts.md +1 -1
  22. package/docs/README.codebuddy.md +1 -1
  23. package/docs/README.codex.md +26 -0
  24. package/docs/README.crush.md +1 -1
  25. package/docs/README.deepseek-harness.md +1 -1
  26. package/docs/README.deerflow.md +1 -1
  27. package/docs/README.hermes.md +1 -1
  28. package/docs/README.kilocode.md +3 -3
  29. package/docs/README.kiro.md +1 -1
  30. package/docs/README.opencode.md +128 -19
  31. package/docs/README.qoder.md +1 -1
  32. package/docs/README.qwen.md +1 -1
  33. package/docs/README.trae-cn.md +62 -0
  34. package/docs/README.vscode.md +1 -1
  35. package/docs/README.zcode.md +2 -2
  36. package/gemini-extension.json +1 -1
  37. package/hooks/run-hook.cmd +34 -18
  38. package/hooks/session-start +45 -9
  39. package/index.js +9 -0
  40. package/package.json +4 -3
  41. package/skills/brainstorming/SKILL.md +111 -181
  42. package/skills/brainstorming/builder-check-prompt.md +15 -0
  43. package/skills/brainstorming/scripts/server.cjs +1 -1
  44. package/skills/brainstorming/visual-companion.md +36 -33
  45. package/skills/chinese-code-review/SKILL.md +1 -1
  46. package/skills/chinese-commit-conventions/SKILL.md +1 -1
  47. package/skills/diagnosing-superpowers/SKILL.md +102 -0
  48. package/skills/diagnosing-superpowers/prompts/analyst-common.md +32 -0
  49. package/skills/diagnosing-superpowers/prompts/cost-and-time.md +20 -0
  50. package/skills/diagnosing-superpowers/prompts/plan-adherence.md +21 -0
  51. package/skills/diagnosing-superpowers/prompts/quality-evidence.md +20 -0
  52. package/skills/diagnosing-superpowers/prompts/repeated-work.md +24 -0
  53. package/skills/diagnosing-superpowers/prompts/request-conflicts.md +14 -0
  54. package/skills/diagnosing-superpowers/prompts/scrub-audit.md +26 -0
  55. package/skills/diagnosing-superpowers/prompts/scrub.md +22 -0
  56. package/skills/diagnosing-superpowers/prompts/similar-session.md +34 -0
  57. package/skills/diagnosing-superpowers/prompts/skill-timeline.md +23 -0
  58. package/skills/diagnosing-superpowers/prompts/stumbles.md +20 -0
  59. package/skills/diagnosing-superpowers/references/context-safety.md +20 -0
  60. package/skills/diagnosing-superpowers/references/github-issues.md +46 -0
  61. package/skills/diagnosing-superpowers/references/redaction-policy.md +29 -0
  62. package/skills/diagnosing-superpowers/references/session-discovery.md +23 -0
  63. package/skills/diagnosing-superpowers/templates/bundle-README.md +65 -0
  64. package/skills/diagnosing-superpowers/templates/case.md +61 -0
  65. package/skills/diagnosing-superpowers/templates/issue.md +48 -0
  66. package/skills/diagnosing-superpowers/templates/report.md +78 -0
  67. package/skills/executing-plans/SKILL.md +176 -125
  68. package/skills/executing-plans/scripts/task-done +52 -0
  69. package/skills/executing-plans/scripts/task-start +28 -0
  70. package/skills/mcp-builder/SKILL.md +1 -1
  71. package/skills/requesting-code-review/SKILL.md +2 -2
  72. package/skills/requesting-code-review/code-reviewer.md +8 -0
  73. package/skills/subagent-driven-development/SKILL.md +17 -17
  74. package/skills/subagent-driven-development/re-review-prompt.md +1 -1
  75. package/skills/subagent-driven-development/scripts/review-package +8 -1
  76. package/skills/subagent-driven-development/scripts/sdd-workspace +51 -4
  77. package/skills/subagent-driven-development/scripts/task-brief +3 -1
  78. package/skills/subagent-driven-development/task-reviewer-prompt.md +2 -2
  79. package/skills/systematic-debugging/CREATION-LOG.md +1 -1
  80. package/skills/systematic-debugging/SKILL.md +2 -2
  81. package/skills/systematic-debugging/root-cause-tracing.md +1 -1
  82. package/skills/test-driven-development/SKILL.md +2 -0
  83. package/skills/using-superpowers/SKILL.md +19 -14
  84. package/skills/using-superpowers/references/claude-code-tools.md +11 -0
  85. package/skills/using-superpowers/references/muse-tools.md +35 -0
  86. package/skills/writing-plans/SKILL.md +34 -27
  87. package/skills/writing-skills/SKILL.md +5 -3
  88. package/assets/sponsors/apimart.jpg +0 -0
  89. package/assets/sponsors/compshare.jpg +0 -0
  90. package/assets/sponsors/logo-apimart-icon.png +0 -0
  91. package/assets/sponsors/logo-compshare-icon.png +0 -0
  92. package/skills/brainstorming/spec-document-reviewer-prompt.md +0 -48
  93. package/skills/writing-plans/plan-document-reviewer-prompt.md +0 -49
@@ -22,10 +22,17 @@ head=$3
22
22
  git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
23
23
  git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
24
24
 
25
+ # Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
26
+ # not rooted at BASE; either would silently produce a bogus review package.
27
+ git merge-base --is-ancestor "$base" "$head" || { echo "HEAD is not a descendant of BASE: ${base}..${head}" >&2; exit 3; }
28
+ [ "$(git rev-list --count "${base}..${head}")" -gt 0 ] || { echo "empty commit range: ${base}..${head}" >&2; exit 3; }
29
+
25
30
  if [ $# -eq 4 ]; then
26
31
  out=$4
27
32
  else
28
- dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
33
+ # Invoke via bash rather than direct exec: some extractors (Python zipfile)
34
+ # strip Unix exec bits when unpacking marketplace packages (#2040).
35
+ dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
29
36
  out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
30
37
  fi
31
38
 
@@ -8,6 +8,16 @@
8
8
  # artifacts. A stale ledger misread as current progress makes controllers
9
9
  # skip whole task sequences — plan-scoping removes that failure structurally.
10
10
  #
11
+ # Basename slugs collide when two plans share a filename (docs/alpha/plan.md
12
+ # vs docs/beta/plan.md), so each workspace records its owning plan's path in
13
+ # a plan-path marker (repo-relative in-repo, absolute outside). A workspace
14
+ # owned by a different plan is skipped and the slug disambiguated with the
15
+ # plan's parent-directory name, then a counter. A workspace with no marker
16
+ # predates the marker scheme and is adopted for the current plan so in-flight
17
+ # workspaces keep resolving — which means the first collision on such a
18
+ # legacy workspace adopts instead of detecting; acceptable, marker-less
19
+ # workspaces age out as plans finish.
20
+ #
11
21
  # The workspace lives in the working tree (not under .git/) because Claude Code
12
22
  # treats .git/ as a protected path and denies agent writes there — which blocks
13
23
  # an implementer subagent from writing its report file. A self-ignoring
@@ -32,9 +42,46 @@ slug=$(basename "$plan" .md)
32
42
  [ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
33
43
  || { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
34
44
 
35
- root=$(git rev-parse --show-toplevel)
45
+ # Physical path, spelled the way pwd -P spells the plan path below: on Git
46
+ # Bash, rev-parse prints C:/Users/... while pwd prints /c/Users/..., and the
47
+ # repo-relative marker check needs both in the same form.
48
+ root=$(CDPATH='' cd -- "$(git rev-parse --show-toplevel)" && pwd -P)
36
49
  base="$root/.superpowers/sdd"
50
+
51
+ # Normalize the plan path (physical directory, so relative/absolute/../
52
+ # spellings of one plan compare equal) and express it as the marker value:
53
+ # repo-relative when the plan lives under the repo root, absolute otherwise.
54
+ plan_dir=$(CDPATH='' cd -- "$(dirname "$plan")" && pwd -P)
55
+ plan_abs="$plan_dir/$(basename "$plan")"
56
+ case "$plan_abs" in
57
+ "$root"/*) plan_id=${plan_abs#"$root"/} ;;
58
+ *) plan_id=$plan_abs ;;
59
+ esac
60
+
61
+ # True when the workspace at $1 is (or becomes) this plan's: an existing
62
+ # marker must name this plan; a missing marker means a new workspace or a
63
+ # pre-marker legacy one, and either way the plan claims it by writing one.
64
+ owns() {
65
+ if [ -e "$1/plan-path" ]; then
66
+ [ "$(cat "$1/plan-path")" = "$plan_id" ]
67
+ else
68
+ mkdir -p "$1"
69
+ printf '%s\n' "$plan_id" > "$1/plan-path"
70
+ fi
71
+ }
72
+
37
73
  dir="$base/$slug"
38
- mkdir -p "$dir"
39
- printf '*\n' > "$base/.gitignore"
40
- cd "$dir" && pwd
74
+ if ! owns "$dir"; then
75
+ parent=$(basename "$plan_dir")
76
+ dir="$base/$slug-$parent"
77
+ if ! owns "$dir"; then
78
+ n=2
79
+ while ! owns "$base/$slug-$parent-$n"; do n=$((n + 1)); done
80
+ dir="$base/$slug-$parent-$n"
81
+ fi
82
+ fi
83
+
84
+ # Create-only: a repo may commit its own .gitignore here (e.g. to version
85
+ # progress.md ledgers); overwriting it would revert that on every run.
86
+ [ -e "$base/.gitignore" ] || printf '*\n' > "$base/.gitignore"
87
+ CDPATH='' cd -- "$dir" && pwd
@@ -25,7 +25,9 @@ n=$2
25
25
  if [ $# -eq 3 ]; then
26
26
  out=$3
27
27
  else
28
- dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
28
+ # Invoke via bash rather than direct exec: some extractors (Python zipfile)
29
+ # strip Unix exec bits when unpacking marketplace packages (#2040).
30
+ dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
29
31
  out="$dir/task-${n}-brief.md"
30
32
  fi
31
33
 
@@ -168,7 +168,7 @@ Subagent (general-purpose):
168
168
 
169
169
  **占位符:**
170
170
  - `[模型]` —— 必填:按 SKILL.md 的"模型选择"选审查者模型
171
- - `[BRIEF_FILE]` —— 必填:任务简报文件(`scripts/task-brief PLAN N`
171
+ - `[BRIEF_FILE]` —— 必填:任务简报文件(`bash scripts/task-brief PLAN N`
172
172
  会打印路径;与实现者所用的是同一个文件)
173
173
  - `[GLOBAL_CONSTRAINTS]` —— 从计划的"全局约束"一节或规格里逐字抄下的、
174
174
  有约束力的需求:精确的取值、格式、以及组件之间被明确规定的关系
@@ -177,7 +177,7 @@ Subagent (general-purpose):
177
177
  - `[BASE_SHA]` —— 本任务之前的提交
178
178
  - `[HEAD_SHA]` —— 当前提交
179
179
  - `[DIFF_FILE]` —— 必填:控制者写入审查包的那个路径
180
- (`scripts/review-package PLAN_FILE BASE HEAD` 会打印它写入的唯一路径;
180
+ (`bash scripts/review-package PLAN_FILE BASE HEAD` 会打印它写入的唯一路径;
181
181
  审查包永远不会进入控制者的上下文)
182
182
 
183
183
  **审查者返回:** 规格合规性结论(✅/❌/⚠️)、优点、问题
@@ -4,7 +4,7 @@ Reference example of extracting, structuring, and bulletproofing a critical skil
4
4
 
5
5
  ## Source Material
6
6
 
7
- Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
7
+ Extracted debugging framework from `~/.claude/CLAUDE.md`:
8
8
  - 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
9
9
  - Core mandate: ALWAYS find root cause, NEVER fix symptoms
10
10
  - Rules designed to resist time pressure and rationalization
@@ -93,11 +93,11 @@ metadata:
93
93
  ```bash
94
94
  # 第 1 层:工作流
95
95
  echo "=== Secrets available in workflow: ==="
96
- echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
96
+ echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
97
97
 
98
98
  # 第 2 层:构建脚本
99
99
  echo "=== Env vars in build script: ==="
100
- env | grep IDENTITY || echo "IDENTITY not in environment"
100
+ printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"
101
101
 
102
102
  # 第 3 层:签名脚本
103
103
  echo "=== Keychain state: ==="
@@ -101,7 +101,7 @@ npm test 2>&1 | grep 'DEBUG git init'
101
101
  使用本目录下的二分查找脚本 `find-polluter.sh`:
102
102
 
103
103
  ```bash
104
- ./find-polluter.sh '.git' 'src/**/*.test.ts'
104
+ bash ./find-polluter.sh '.git' 'src/**/*.test.ts'
105
105
  ```
106
106
 
107
107
  逐个运行测试,在第一个"污染者"处停止。详见脚本中的使用说明。
@@ -187,6 +187,8 @@ npm test path/to/test.test.ts
187
187
 
188
188
  **其他测试失败了?** 立即修复。
189
189
 
190
+ **"其他测试"指的是项目的整个测试套件,不只是你那个文件。** 你写的那个测试跑绿了,不等于测试套件是绿的。在宣称改动完成之前,运行项目的测试命令(直接 `pytest`、`npm test`、`cargo test`——仓库用什么就跑什么),即使你的任务只点名了一个测试文件。任务里的范围说明约束的是交付物,不是你的验证。那次运行暴露出的任何失败——包括不是你造成的——都要在报告里点名写出;一个你眼看着滚过去却没提的红色测试,就是一份靠遗漏造假的报告。
191
+
190
192
  ### 重构 - 清理代码
191
193
 
192
194
  只有在绿灯之后才重构:
@@ -58,36 +58,41 @@ metadata:
58
58
 
59
59
  如果你的运行环境在下面列出,请阅读对应的参考文件获取特殊说明:
60
60
 
61
+ - Claude Code:`references/claude-code-tools.md`
61
62
  - Codex:`references/codex-tools.md`
62
63
  - Pi:`references/pi-tools.md`
63
64
  - Antigravity:`references/antigravity-tools.md`
64
65
  - Copilot CLI:`references/copilot-tools.md`
65
66
  - Hermes Agent:`references/hermes-tools.md`
66
67
  - Qoder:`references/qoder-tools.md`
68
+ - Muse:`references/muse-tools.md`
67
69
 
68
70
  Gemini CLI 用户通过 GEMINI.md 自动获得 `references/gemini-tools.md` 的工具映射。
69
71
 
70
72
  ## 中国特色技能路由
71
73
 
72
74
  > 🇨🇳 **本节是 superpowers-zh 的增量内容,上游 obra/superpowers 没有。**
73
- > 用于把中文场景路由到本 fork 原创的 chinese-* 系列 skill。其余各节均为逐节翻译。
75
+ > 用于说明本 fork 原创的 chinese-* 系列 skill 何时使用。其余各节均为逐节翻译。
74
76
 
75
- 当检测到以下场景时,**必须**优先调用对应的中国特色技能:
77
+ 这 4 个 chinese-* 是**参考资料,不是工作流** —— 话术模板、排版约定、平台配置差异。
78
+ 它们**只在用户显式调用时才加载**,不要根据上下文自动触发:上下文里多一份排版参考
79
+ 不会让你写得更好,只会挤掉真正需要的内容。
76
80
 
77
- | 场景 | 调用技能 |
78
- |------|---------|
79
- | 代码审查且团队使用中文沟通 | **chinese-code-review** |
80
- | 使用 Gitee/Coding/极狐 GitLab | **chinese-git-workflow** |
81
- | 编写中文技术文档或 README | **chinese-documentation** |
82
- | 编写 git commit message(中文项目) | **chinese-commit-conventions** |
83
- | 构建 MCP 服务器/工具 | **mcp-builder** |
81
+ | 用户显式说 | 加载技能 | 里面是什么 |
82
+ |------|---------|---------|
83
+ | `/chinese-code-review` | **chinese-code-review** | 中文 review 话术模板、分级标注、国内团队常见反模式应对 |
84
+ | `/chinese-git-workflow` | **chinese-git-workflow** | Gitee / Coding.net / 极狐 GitLab / CNB 的 SSH、凭据、CI 接入差异 |
85
+ | `/chinese-documentation` | **chinese-documentation** | 中英文空格、全半角标点、术语保留、中文文案排版指北约定 |
86
+ | `/chinese-commit-conventions` | **chinese-commit-conventions** | Conventional Commits 中文适配、commitlint / husky 中文模板 |
84
87
 
85
- **判断依据:**
86
- - 项目中有中文注释、中文 README、或 .gitee 目录 → 启用中文系列技能
87
- - commit 历史中有中文 → 使用中文提交规范
88
- - 用户用中文交流 → 所有输出使用中文,优先考虑中国特色技能
88
+ 用户没点名就不要主动拉进来。反过来,用户点名了就照它执行,不要因为"看起来只是格式问题"
89
+ 而跳过。
89
90
 
90
- 中国特色技能与翻译技能**叠加使用**,不互斥。例如:做代码审查时,同时使用 requesting-code-review(流程)+ chinese-code-review(风格)。
91
+ 它们与翻译技能**叠加使用**,不互斥:用户要求做中文 review 时,是
92
+ requesting-code-review(流程)**加上** chinese-code-review(风格),不是二选一。
93
+
94
+ > 这个「只在显式调用时加载」是刻意决定,不是漏写(见 commit `392ff75`)。改动它需要
95
+ > eval 证据 —— 参见 PR #123 与本仓 CLAUDE.md「Skill 改动需要 eval」。
91
96
 
92
97
  ## 用户指令
93
98
 
@@ -0,0 +1,11 @@
1
+ # Claude Code 工具说明
2
+
3
+ Claude Code 是基准运行环境:skill 用的就是它的词汇(`Agent` 表示分派子智能体、todos、`Skill`)。这份说明只讲一处:Claude Code 可以用比 skill 默认形态更便宜的方式跑一份计划。它需要你的人类伙伴主动选择,不改变 skill 的任何要求。
4
+
5
+ ## 子智能体驱动开发的更便宜编排方式
6
+
7
+ 在一次 subagent-driven-development 运行里,控制者会话是最贵的那个席位:它要读每一次分派的结果和每一份报告,而且通常跑在会话里最强的模型上。Claude Code 支持嵌套子智能体(默认可在主对话之下嵌套三层;`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` 可调整),所以整个循环可以下沉一层来跑。
8
+
9
+ 当你的人类伙伴要求这样做——或者说过会话模型太贵、不值得花在协调上——就分派**一个**跑在中档模型上的编排者子智能体,给它计划路径,并指示它端到端地使用 subagent-driven-development。编排者按那个技能的「模型选择」分派它自己的实现者和审查者;工作区和账本都在磁盘上,所以多出来的这一层不会丢任何东西。它的最后一条消息必须逐字带上「我作出的裁决」(Rulings I made)清单——这份清单是这些决定抵达你人类伙伴的途径,你要原样转达,而不是概括。
10
+
11
+ 只对整份计划这样做。只为单个任务的分派多嵌一层,什么也换不来,只是多了一个席位。
@@ -0,0 +1,35 @@
1
+ # Muse 工具映射
2
+
3
+ Skill 用动作来表述(「分派一个子智能体」「创建一条待办」「读取一个文件」)。在 Muse 上,这些动作对应下面的工具。
4
+
5
+ | Skill 里要做的动作 | Muse 对应工具 |
6
+ |----------------------|----------------|
7
+ | 读取文件 | `read_file` |
8
+ | 读取多个文件 | `read_file`(多次调用)或 `search` |
9
+ | 创建新文件 | `write_file` |
10
+ | 编辑文件 | `edit_file` |
11
+ | 运行 shell 命令 | `bash` |
12
+ | 搜索文件内容 | `search` |
13
+ | 按文件名查找 | `search` 配合 `glob` |
14
+ | 抓取 URL | `web_fetch` |
15
+ | 搜索网络 | `web_search` |
16
+ | 调用 skill | 对 `skills/<name>/SKILL.md` 用 `read_file`,或用原生 skill 工具 |
17
+ | 分派子智能体(`Subagent (general-purpose):` 模板) | `subagent_spawn`,并填好提示词 |
18
+ | 任务跟踪(「创建一条待办」「标记完成」) | `write_todos` 或用 `bash` 维护任务文件 |
19
+ | 向用户提问 | `request_user_input` |
20
+
21
+ ## 指令文件
22
+
23
+ 当某个 skill 提到「你的指令文件」时,在 Muse 上指的是项目根目录里的 **`CLAUDE.md`** 或 **`AGENTS.md`**。在配置了的情况下,Muse 会分层加载它们。
24
+
25
+ ## 调用 skill
26
+
27
+ Muse 通过 `muse skills` 原生支持 skill。要调用某个 Superpowers skill,读取它的 `SKILL.md` 并按其中的指示执行。引导技能(`using-superpowers`)会在 `SessionStart` 时通过插件 hook 自动注入——你已经在遵循它了,不要再加载一次。
28
+
29
+ ## 分派子智能体
30
+
31
+ 用 `subagent_spawn` 把工作委派给相互隔离的子智能体。分派之前先填好提示词模板(例如 `implementer-prompt.md`、`task-reviewer-prompt.md`)。如果没有可用的子智能体工具,就内联完成这项工作,而不是编造工具调用。
32
+
33
+ ## 任务跟踪
34
+
35
+ 用 `write_todos` 跟踪清单。技能清单里的每一项建一条待办,边做边标记 in_progress/completed。如果 `write_todos` 不可用,就用 `write_file`/`edit_file` 维护一个 markdown 任务文件。
@@ -12,9 +12,7 @@ metadata:
12
12
 
13
13
  ## 概述
14
14
 
15
- 编写全面的实现计划,假设工程师对我们的代码库零上下文,且品味存疑。记录他们需要知道的一切:每个任务要修改哪些文件、代码、测试、可能需要查阅的文档、如何测试。将整个计划拆成小步骤任务。DRY。YAGNI。TDD。频繁 commit。
16
-
17
- 假设他们是有经验的开发者,但对我们的工具链和问题领域几乎一无所知。假设他们不太擅长测试设计。
15
+ 为一位没见过这个代码库、也没见过这份规格的工程师编写实现计划。假设他们一旦知道确切的接口和确切的测试,就能用项目所用的语言写出地道的代码;也假设在计划留出选择余地的地方,他们会做出合理的选择。他们无从知道的,是你已经决定了什么:哪些文件、哪些名字和签名、规格里的哪些取值、哪些测试证明每个任务。把这些记下来。将整个计划拆成小步骤任务。DRY。YAGNI。TDD。频繁 commit。
18
16
 
19
17
  **开始时宣布:** "我正在使用 writing-plans 技能创建实现计划。"
20
18
 
@@ -42,9 +40,9 @@ metadata:
42
40
 
43
41
  一个任务是**能独立承载自己那一轮测试循环、且值得一个全新审查者把关**的最小单元。划任务边界时:把搭建、配置、脚手架和文档这些步骤,折进那个真正需要它们的交付物所在的任务里;只在「审查者有可能否掉这个任务、同时批准它旁边那个」的地方才拆开。每个任务都以一个**可独立测试的交付物**结束。
44
42
 
45
- ## 小步骤任务粒度
43
+ ## 步骤粒度
46
44
 
47
- **每步是一个操作(2-5 分钟):**
45
+ **每步是一个操作,并有一个可检查的结果:**
48
46
  - "编写失败的测试" - 一步
49
47
  - "运行它确认失败" - 一步
50
48
  - "实现最少代码让测试通过" - 一步
@@ -73,6 +71,10 @@ metadata:
73
71
 
74
72
  [来自规格的项目级要求 —— 版本下限、依赖限制、命名与文案规则、平台要求 —— 每条一行,数值从规格里逐字照抄。每个任务的要求都隐含包含本节。]
75
73
 
74
+ ## 审查重点(Review Focus)
75
+
76
+ [规格隐含了、但没有任何任务的测试覆盖到的输入类别或失败模式中,最可能伤到这个软件使用者的五个 —— 每条一行,写明那个输入或条件,以及一个正常人会期待的行为,最可能的排最前。规格是一份愿景文档:它说软件必须做什么,而不是软件会遇到的一切;规格对某种输入没有提及,不等于允许这种输入把程序弄坏。趁规格就在眼前,在这里一次写完这份清单。然后针对每一行,把钉住它的那个测试,按那个任务自己的步骤写法,加进负责那段代码的任务里。]
77
+
76
78
  ---
77
79
  ```
78
80
 
@@ -99,12 +101,9 @@ def test_specific_behavior():
99
101
  运行:`pytest tests/path/test.py::test_name -v`
100
102
  预期:FAIL,报错 "function not defined"
101
103
 
102
- - [ ] **步骤 3:编写最少实现代码**
104
+ - [ ] **步骤 3:在 `exact/path/to/file.py` 中实现 `function(input: InputType) -> ResultType`**
103
105
 
104
- ```python
105
- def function(input):
106
- return expected
107
- ```
106
+ 当签名和测试还留有选择余地时(用哪个库调用、哪种数据结构),用一行说明做法;只有签名和测试决定不了的算法,才给代码块。
108
107
 
109
108
  - [ ] **步骤 4:运行测试验证通过**
110
109
 
@@ -119,15 +118,16 @@ git commit -m "feat: add specific feature"
119
118
  ```
120
119
  ````
121
120
 
122
- ## 禁止占位符
121
+ ## 一个步骤包含什么
122
+
123
+ 当实现者能根据一个步骤**恰好写出一种合理的东西**时,这个步骤就写完了。要求就这一条:无歧义,而不是完整。每一类步骤只带上让它无歧义的内容,不多带:
123
124
 
124
- 每个步骤都必须包含工程师需要的实际内容。以下是**计划缺陷**——绝不要写出来:
125
- - "待定"、"TODO"、"后续实现"、"补充细节"
126
- - "添加适当的错误处理" / "添加验证" / "处理边界情况"
127
- - "为上述代码编写测试"(没有实际测试代码)
128
- - "类似任务 N"(重复代码——工程师可能不按顺序阅读任务)
129
- - 只描述做什么而不展示怎么做的步骤(代码步骤必须有代码块)
130
- - 引用了未在任何任务中定义的类型、函数或方法
125
+ - **测试步骤:** 测试的名字和它的断言,以代码形式给出,里面是规格的确切取值。
126
+ - **代码步骤:** 确切的签名(名字、参数、返回类型)、它所在的文件,以及规格钉死的具体取值。函数体由实现者来写。只有签名和测试决定不了的算法,或规格定死的确切文案,才写出函数体。
127
+ - **验证步骤:** 要运行的命令,以及代表通过的输出。
128
+ - **引用另一个任务:** 那个任务的 Interfaces 块说明要用什么;计划不重复那个任务的代码。
129
+
130
+ 计划是实现者无法独自作出的那些决定的集合。一份比它所描述的代码还长的计划,其实是把代码写了一遍。什么都没决定的行("待定"、"处理边界情况"、"添加适当的验证"、"为上述代码编写测试"、没有任何任务定义的类型或函数)是反方向的失败,自检会把这两种都抓出来。
131
131
 
132
132
  ## 自检
133
133
 
@@ -135,28 +135,35 @@ git commit -m "feat: add specific feature"
135
135
 
136
136
  **1. 规格覆盖度:** 浏览规格中的每个章节/需求。你能指出实现它的任务吗?列出所有遗漏。
137
137
 
138
- **2. 占位符扫描:** 搜索计划中的红旗——上方"禁止占位符"章节中的任何模式。修复它们。
138
+ **2. 步骤扫描:** 每个步骤都必须让实现者恰好写出一种合理的东西,而且任何步骤都不能多带:什么都没决定的行是缺口,签名和测试已经决定了的函数体是照抄。两种都要修。
139
139
 
140
140
  **3. 类型一致性:** 后续任务中使用的类型、方法签名和属性名是否与前面任务中定义的一致?任务 3 中叫 `clearLayers()` 但任务 7 中叫 `clearFullLayers()` 就是 bug。
141
141
 
142
+ **4. 审查重点:** 对规格隐含的每个输入类别或失败模式,有没有哪个任务的测试覆盖到它?没被覆盖、最可能伤到使用者的五个写进「审查重点」一节,那里的每一行都要把对应的测试加进负责的任务里。这一节为空,意味着你检查过、没发现,而不是你跳过了检查。
143
+
144
+ **5. 比例:** 拿计划的长度和规格比一比。一份比它所实现的规格长好几倍的计划,是程序的抄本,不是计划。如果代码块占了文档的大半,就把函数体换成签名、测试名和断言,然后检查每个步骤是否仍然无歧义。
145
+
142
146
  如果发现问题,直接内联修复。无需重新审查——修好继续推进。如果发现规格中的需求没有对应任务,就添加任务。
143
147
 
144
148
  ## 执行交接
145
149
 
146
- 保存计划后,提供执行选项:
150
+ 保存并自检完计划之后,把计划链接给你的人类伙伴阅读。如果他们已经明确给出了执行方式,就请他们审阅计划、确认它抓住了他们想要的东西;等他们审阅完再开始实现,然后沿用那个既定的方式。否则,请他们审阅计划,并在实现之前选定一种执行方式。
151
+
152
+ **尚未给出执行方式时:**
153
+
154
+ **"计划已完成并保存到 `docs/superpowers/plans/<filename>.md`。请审阅这份计划。你希望用哪种执行方式?**
147
155
 
148
- **"计划已完成并保存到 `docs/superpowers/plans/<filename>.md`。两种执行方式:**
156
+ - **子代理驱动** - 每个任务由一个全新子代理实现,并在下一个任务开始前由一个全新审查者检查,最后再做一次覆盖整个分支的审查。最彻底;代价是每个任务、每次审查各一个全新上下文。
157
+ - **原生执行** - 我在当前会话里按这个运行环境的方式亲自实现每个任务,最后由一个跑在最强模型上的全新审查者检查整个分支。最便宜、最快;直到最后才有独立审查。会话用中档模型就能跑好,因为计划已经承载了设计。
149
158
 
150
- **1. 子代理驱动(推荐)** - 每个任务调度一个新的子代理,任务间进行审查,快速迭代
159
+ **针对这份计划,我推荐<两者之一>,因为<从计划里得出的一句话:任务之间对彼此接口的依赖有多深、有多少个任务、一个错误上线的代价是什么>。这份计划抓住你想要的东西了吗?我们用哪种方式?"**
151
160
 
152
- **2. 内联执行** - 在当前会话中使用 executing-plans 执行任务,批量执行并设有检查点
161
+ **已经给出执行方式时:**
153
162
 
154
- **选哪种方式?"**
163
+ **"计划已完成并保存到 `docs/superpowers/plans/<filename>.md`。请审阅这份计划。它抓住你想要的东西了吗?"**
155
164
 
156
165
  **如果选择子代理驱动:**
157
166
  - **必需子技能:** 使用 subagent-driven-development
158
- - 每个任务一个新子代理 + 两阶段审查
159
167
 
160
- **如果选择内联执行:**
168
+ **如果选择原生执行:**
161
169
  - **必需子技能:** 使用 executing-plans
162
- - 批量执行并设有检查点供审查
@@ -14,7 +14,7 @@ metadata:
14
14
 
15
15
  **编写技能就是将测试驱动开发应用于流程文档。**
16
16
 
17
- **个人技能存放在智能体特定的目录中(Claude Code 用 `~/.claude/skills`,Codex 用 `~/.agents/skills/`)**
17
+ **个人技能存放在你所用运行环境的技能目录中**(Claude Code 上是 `~/.claude/skills/`)——其他运行环境的路径见 [codex-tools.md](../using-superpowers/references/codex-tools.md) 或 [gemini-tools.md](../using-superpowers/references/gemini-tools.md)。Codex、Copilot CLI 和 Gemini CLI 也都认 `~/.agents/skills/`,作为跨运行环境的别名。
18
18
 
19
19
  你编写测试用例(带子智能体的压力场景),观察它们失败(基线行为),编写技能(文档),观察测试通过(智能体遵守规则),然后重构(堵住漏洞)。
20
20
 
@@ -321,8 +321,8 @@ digraph when_flowchart {
321
321
 
322
322
  **为你的搭档可视化:** 使用此目录中的 `render-graphs.js` 将技能的流程图渲染为 SVG:
323
323
  ```bash
324
- ./render-graphs.js ../some-skill # 每个图表分别渲染
325
- ./render-graphs.js ../some-skill --combine # 所有图表合并为一个 SVG
324
+ node ./render-graphs.js ../some-skill # 每个图表分别渲染
325
+ node ./render-graphs.js ../some-skill --combine # 所有图表合并为一个 SVG
326
326
  ```
327
327
 
328
328
  ## 代码示例
@@ -375,6 +375,8 @@ pptx/
375
375
  ```
376
376
  适用场景:参考资料太多无法内联
377
377
 
378
+ 在正文里调用技能自带的脚本时,要通过解释器来调用(`bash scripts/tool.sh`、`node scripts/tool.js`),绝不用裸路径:有些运行环境的插件打包器会去掉可执行位,在那里裸写 `scripts/tool.sh` 会以 `Permission denied` 失败。
379
+
378
380
  ## 铁律(与 TDD 相同)
379
381
 
380
382
  ```
Binary file
Binary file
@@ -1,48 +0,0 @@
1
- # 规格文档审查员提示模板
2
-
3
- 调度规格文档审查员子代理时使用此模板。
4
-
5
- **用途:** 验证规格是否完整、一致,并为实现计划做好准备。
6
-
7
- **调度时机:** 规格文档写入 docs/superpowers/specs/ 之后
8
-
9
- ```
10
- Task tool(通用):
11
- description: "审查规格文档"
12
- prompt: |
13
- 你是一名规格文档审查员。验证此规格是否完整并准备好进行计划编写。
14
-
15
- **待审查规格:** [SPEC_FILE_PATH]
16
-
17
- ## 检查内容
18
-
19
- | 类别 | 检查要点 |
20
- |------|----------|
21
- | 完整性 | TODO、占位符、"TBD"、不完整的章节 |
22
- | 一致性 | 内部矛盾、相互冲突的需求 |
23
- | 清晰度 | 需求模糊到可能导致构建出错误的东西 |
24
- | 范围 | 是否足够聚焦以用于单个计划——而非涵盖多个独立子系统 |
25
- | YAGNI | 未请求的功能、过度设计 |
26
-
27
- ## 校准标准
28
-
29
- **只标记会在实现计划阶段造成实际问题的事项。**
30
- 缺失的章节、矛盾之处、或者模糊到可能被两种不同方式理解的需求——
31
- 这些才是问题。措辞上的小改进、风格偏好、以及"某些章节不如其他章节详细"则不是。
32
-
33
- 除非存在会导致计划出错的严重缺陷,否则应予以通过。
34
-
35
- ## 输出格式
36
-
37
- ## 规格审查
38
-
39
- **状态:** 通过 | 发现问题
40
-
41
- **问题(如有):**
42
- - [章节 X]:[具体问题] - [为什么这对计划编写很重要]
43
-
44
- **建议(仅供参考,不阻止通过):**
45
- - [改进建议]
46
- ```
47
-
48
- **审查员返回:** 状态、问题(如有)、建议
@@ -1,49 +0,0 @@
1
- # 计划文档审查员提示模板
2
-
3
- 调度计划文档审查员子代理时使用此模板。
4
-
5
- **用途:** 验证计划是否完整、与规格匹配,并且任务分解合理。
6
-
7
- **调度时机:** 完整计划编写完成后。
8
-
9
- ```
10
- Task tool(通用):
11
- description: "审查计划文档"
12
- prompt: |
13
- 你是一名计划文档审查员。验证此计划是否完整并准备好进行实现。
14
-
15
- **待审查计划:** [PLAN_FILE_PATH]
16
- **参考规格:** [SPEC_FILE_PATH]
17
-
18
- ## 检查内容
19
-
20
- | 类别 | 检查要点 |
21
- |------|----------|
22
- | 完整性 | TODO、占位符、不完整的任务、缺失的步骤 |
23
- | 规格对齐 | 计划覆盖了规格需求,没有重大范围蔓延 |
24
- | 任务分解 | 任务有清晰的边界,步骤可执行 |
25
- | 可构建性 | 工程师能否按此计划执行而不会卡住? |
26
-
27
- ## 校准标准
28
-
29
- **只标记会在实现阶段造成实际问题的事项。**
30
- 实现者构建了错误的东西或卡住了——这是问题。
31
- 措辞上的小改进、风格偏好和"锦上添花"的建议则不是。
32
-
33
- 除非存在严重缺陷——规格中的需求遗漏、
34
- 矛盾的步骤、占位内容、或者模糊到无法执行的任务——否则应予以通过。
35
-
36
- ## 输出格式
37
-
38
- ## 计划审查
39
-
40
- **状态:** 通过 | 发现问题
41
-
42
- **问题(如有):**
43
- - [任务 X,步骤 Y]:[具体问题] - [为什么这对实现很重要]
44
-
45
- **建议(仅供参考,不阻止通过):**
46
- - [改进建议]
47
- ```
48
-
49
- **审查员返回:** 状态、问题(如有)、建议