superpowers-zh 1.8.0 → 1.9.0-rc.2

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/.antigravity-plugin/plugin.json +27 -0
  2. package/.claude-plugin/marketplace.json +1 -1
  3. package/.claude-plugin/plugin.json +1 -1
  4. package/.codex-plugin/plugin.json +1 -1
  5. package/.cursor-plugin/plugin.json +1 -1
  6. package/.devin-plugin/plugin.json +22 -0
  7. package/.hermes-plugin/__init__.py +127 -0
  8. package/.hermes-plugin/plugin.yaml +6 -0
  9. package/.muse-plugin/marketplace.json +20 -0
  10. package/.muse-plugin/plugin.json +113 -0
  11. package/.opencode/plugins/superpowers.js +61 -39
  12. package/.pi/extensions/superpowers.ts +3 -8
  13. package/README.md +58 -50
  14. package/README.zh-Hant.md +52 -50
  15. package/RELEASE-NOTES.md +431 -0
  16. package/RELEASE-NOTES.zh.md +49 -0
  17. package/assets/antigravity-logo.png +0 -0
  18. package/assets/sponsors/apixo-ai-card-450x250.png +0 -0
  19. package/assets/sponsors/apixo-ai-en.jpg +0 -0
  20. package/assets/sponsors/apixo-ai-zh.jpg +0 -0
  21. package/bin/superpowers-zh.js +57 -30
  22. package/docs/NATIVE-PLUGINS.md +38 -0
  23. package/docs/README.antigravity.md +41 -21
  24. package/docs/README.codebuddy.md +27 -4
  25. package/docs/README.opencode.md +4 -4
  26. package/docs/SDD-LANGUAGE.md +36 -0
  27. package/docs/VERSIONING.md +49 -0
  28. package/docs/evals/brainstorming-v7.0.1.json +330 -0
  29. package/docs/evals/brainstorming-v7.0.2-samples.json +82 -0
  30. package/docs/evals/brainstorming-v7.0.2.json +95 -0
  31. package/docs/evals/brainstorming-why-contract.json +42 -0
  32. package/docs/evals/development-summary.json +97 -0
  33. package/docs/evals/diagnosis-report-v7.0.1.json +134 -0
  34. package/docs/evals/issue-137-versioning.json +47 -0
  35. package/docs/evals/issue-local-verification-2026-11-12.json +58 -0
  36. package/docs/evals/release-acceptance-2026-11-15.json +52 -0
  37. package/docs/evals/remaining-work.json +44 -0
  38. package/docs/evals/skill-splitting-v7.0.1.json +85 -0
  39. package/docs/evals/upstream-skill-audit-v7.0.2.json +28 -0
  40. package/docs/evals/upstream-v7.0.2-sync.json +292 -0
  41. package/gemini-extension.json +1 -1
  42. package/hooks/hooks.json +1 -0
  43. package/hooks/run-hook.cmd +20 -3
  44. package/hooks/session-start +30 -25
  45. package/package.json +9 -3
  46. package/skills/brainstorming/SKILL.md +51 -25
  47. package/skills/brainstorming/scripts/start-server.sh +7 -0
  48. package/skills/chinese-code-review/SKILL.md +1 -1
  49. package/skills/chinese-commit-conventions/SKILL.md +1 -1
  50. package/skills/chinese-documentation/SKILL.md +1 -1
  51. package/skills/chinese-git-workflow/SKILL.md +1 -1
  52. package/skills/diagnosing-superpowers/SKILL.md +3 -2
  53. package/skills/diagnosing-superpowers/references/github-issues.md +9 -4
  54. package/skills/diagnosing-superpowers/templates/issue.md +11 -1
  55. package/skills/dispatching-parallel-agents/SKILL.md +1 -1
  56. package/skills/executing-plans/SKILL.md +5 -57
  57. package/skills/executing-plans/scripts/task-done +6 -3
  58. package/skills/executing-plans/scripts/task-start +7 -2
  59. package/skills/finishing-a-development-branch/SKILL.md +1 -1
  60. package/skills/mcp-builder/SKILL.md +1 -1
  61. package/skills/receiving-code-review/SKILL.md +1 -1
  62. package/skills/requesting-code-review/SKILL.md +1 -1
  63. package/skills/subagent-driven-development/SKILL.md +17 -170
  64. package/skills/subagent-driven-development/re-review-prompt.md +1 -1
  65. package/skills/subagent-driven-development/references/example-workflow.md +66 -0
  66. package/skills/subagent-driven-development/references/final-review.md +6 -0
  67. package/skills/subagent-driven-development/references/finishing.md +8 -0
  68. package/skills/subagent-driven-development/references/fix-loop.md +32 -0
  69. package/skills/subagent-driven-development/references/preflight-and-resuming.md +25 -0
  70. package/skills/subagent-driven-development/references/report-handling.md +20 -0
  71. package/skills/subagent-driven-development/scripts/review-package +25 -14
  72. package/skills/subagent-driven-development/scripts/sdd-repo +54 -0
  73. package/skills/subagent-driven-development/scripts/sdd-workspace +28 -5
  74. package/skills/subagent-driven-development/scripts/task-brief +74 -15
  75. package/skills/subagent-driven-development/task-reviewer-prompt.md +2 -2
  76. package/skills/systematic-debugging/SKILL.md +1 -1
  77. package/skills/test-driven-development/SKILL.md +1 -1
  78. package/skills/using-git-worktrees/SKILL.md +1 -1
  79. package/skills/using-superpowers/SKILL.md +1 -1
  80. package/skills/verification-before-completion/SKILL.md +1 -1
  81. package/skills/workflow-runner/SKILL.md +1 -1
  82. package/skills/writing-plans/SKILL.md +1 -1
  83. package/skills/writing-skills/SKILL.md +5 -294
  84. package/skills/writing-skills/references/bulletproofing.md +74 -0
  85. package/skills/writing-skills/references/discovery.md +150 -0
  86. package/skills/writing-skills/references/flowcharts.md +35 -0
  87. package/skills/writing-skills/references/skill-template.md +47 -0
  88. package/assets/sponsors/logo-sidrune-ai.png +0 -0
  89. package/skills/systematic-debugging/CREATION-LOG.md +0 -119
  90. package/skills/systematic-debugging/test-academic.md +0 -14
  91. package/skills/systematic-debugging/test-pressure-1.md +0 -58
  92. package/skills/systematic-debugging/test-pressure-2.md +0 -68
  93. package/skills/systematic-debugging/test-pressure-3.md +0 -69
@@ -0,0 +1,27 @@
1
+ {
2
+ "name": "superpowers-zh",
3
+ "displayName": "Superpowers 中文增强版",
4
+ "version": "1.9.0-rc.2",
5
+ "description": "Make your coding agent a better engineer",
6
+ "logo": "assets/antigravity-logo.png",
7
+ "suggestedPrompts": [
8
+ "I've got an idea for something I'd like to build",
9
+ "Let's figure out why this broke"
10
+ ],
11
+ "category": "Developer Tools",
12
+ "keywords": [
13
+ "skills",
14
+ "tdd",
15
+ "debugging",
16
+ "collaboration",
17
+ "best-practices",
18
+ "workflows"
19
+ ],
20
+ "author": {
21
+ "name": "jnMetaCode",
22
+ "url": "https://github.com/jnMetaCode"
23
+ },
24
+ "homepage": "https://github.com/jnMetaCode/superpowers-zh",
25
+ "repository": "https://github.com/jnMetaCode/superpowers-zh",
26
+ "license": "MIT"
27
+ }
@@ -9,7 +9,7 @@
9
9
  {
10
10
  "name": "superpowers-zh",
11
11
  "description": "AI 编程超能力中文增强版:21 个 skills(15 翻译 + 4 中国原创 + 2 上游历史保留),支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 26 款工具",
12
- "version": "1.8.0",
12
+ "version": "1.9.0-rc.2",
13
13
  "source": "./",
14
14
  "author": {
15
15
  "name": "jnMetaCode",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "superpowers-zh",
3
3
  "description": "AI 编程超能力中文增强版:21 个 skills(15 翻译 + 4 中国原创 + 2 上游历史保留),支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 26 款工具",
4
- "version": "1.8.0",
4
+ "version": "1.9.0-rc.2",
5
5
  "author": {
6
6
  "name": "jnMetaCode",
7
7
  "url": "https://github.com/jnMetaCode"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "superpowers-zh",
3
- "version": "1.8.0",
3
+ "version": "1.9.0-rc.2",
4
4
  "description": "AI 编程超能力中文增强版:头脑风暴、subagent 驱动开发、规划、TDD、调试、代码审查、收尾工作流,附 4 个中文 skills 沉淀。",
5
5
  "author": {
6
6
  "name": "jnMetaCode",
@@ -2,7 +2,7 @@
2
2
  "name": "superpowers-zh",
3
3
  "displayName": "Superpowers 中文版",
4
4
  "description": "AI 编程超能力中文增强版:21 个 skills(15 翻译 + 4 中国原创 + 2 上游历史保留),支持 Cursor / Claude Code / Hermes Agent / Claw Code / Qoder 等 26 款工具",
5
- "version": "1.8.0",
5
+ "version": "1.9.0-rc.2",
6
6
  "author": {
7
7
  "name": "jnMetaCode",
8
8
  "url": "https://github.com/jnMetaCode"
@@ -0,0 +1,22 @@
1
+ {
2
+ "name": "superpowers-zh",
3
+ "version": "1.9.0-rc.2",
4
+ "description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
5
+ "author": {
6
+ "name": "jnMetaCode",
7
+ "url": "https://github.com/jnMetaCode"
8
+ },
9
+ "homepage": "https://github.com/jnMetaCode/superpowers-zh",
10
+ "repository": "https://github.com/jnMetaCode/superpowers-zh",
11
+ "license": "MIT",
12
+ "keywords": [
13
+ "brainstorming",
14
+ "subagent-driven-development",
15
+ "skills",
16
+ "planning",
17
+ "tdd",
18
+ "debugging",
19
+ "code-review",
20
+ "workflow"
21
+ ]
22
+ }
@@ -0,0 +1,127 @@
1
+ import os
2
+ import re
3
+ from pathlib import Path
4
+
5
+ BOOTSTRAP_MARKER = "superpowers-zh:using-superpowers bootstrap for hermes"
6
+
7
+
8
+ def _skills_dir() -> str:
9
+ """Locate the stock skills/ tree for either supported install layout.
10
+
11
+ - git-clone install (`hermes plugins install jnMetaCode/superpowers-zh`): the plugin
12
+ dir is the repo root, so `.hermes-plugin/` and `skills/` are siblings and
13
+ this module resolves `../skills`.
14
+ - flattened install (plugin files copied to the plugin dir root): `skills/`
15
+ sits next to this module.
16
+
17
+ Raises loudly when neither matches — a bootstrap that silently skips is how
18
+ a broken install masquerades as a working one.
19
+ """
20
+ here = os.path.dirname(os.path.realpath(__file__))
21
+ candidates = (
22
+ os.path.realpath(os.path.join(here, "..", "skills")),
23
+ os.path.realpath(os.path.join(here, "skills")),
24
+ )
25
+ for cand in candidates:
26
+ if os.path.isfile(os.path.join(cand, "using-superpowers", "SKILL.md")):
27
+ return cand
28
+ raise RuntimeError(
29
+ "superpowers plugin: cannot find the skills/ tree "
30
+ f"(looked at {candidates}). Reinstall with "
31
+ "`hermes plugins install jnMetaCode/superpowers-zh`."
32
+ )
33
+
34
+
35
+ def _strip_frontmatter(content: str) -> str:
36
+ match = re.match(r"^---\n[\s\S]*?\n---\n([\s\S]*)$", content)
37
+ return (match.group(1) if match else content).strip()
38
+
39
+
40
+ def _frontmatter_value(content: str, key: str) -> str:
41
+ """Return a flat ``key: value`` scalar from a SKILL.md frontmatter block.
42
+
43
+ Hermes reads a skill's description from ``register_skill``'s ``description``
44
+ argument, which defaults to "" — registering only the path left every stock
45
+ skill with a blank description in the skill catalogue, so the model had
46
+ nothing to select on. Stock frontmatter is a flat block of single-line
47
+ scalars, so a line scan covers it without a YAML dependency.
48
+ """
49
+ match = re.match(r"^---\n([\s\S]*?)\n---\n", content)
50
+ if not match:
51
+ return ""
52
+ for line in match.group(1).splitlines():
53
+ name, sep, value = line.partition(":")
54
+ if sep and name.strip() == key:
55
+ return value.strip().strip("\"'")
56
+ return ""
57
+
58
+
59
+ def _build_bootstrap(skills_dir: str) -> str:
60
+ with open(
61
+ os.path.join(skills_dir, "using-superpowers", "SKILL.md"),
62
+ encoding="utf-8",
63
+ ) as f:
64
+ body = _strip_frontmatter(f.read())
65
+
66
+ tools_path = os.path.join(
67
+ skills_dir, "using-superpowers", "references", "hermes-tools.md"
68
+ )
69
+ with open(tools_path, encoding="utf-8") as f:
70
+ tool_mapping = f.read().strip()
71
+
72
+ return (
73
+ f"<EXTREMELY_IMPORTANT>\n"
74
+ f"{BOOTSTRAP_MARKER}\n\n"
75
+ f"You have superpowers.\n\n"
76
+ f"The using-superpowers skill content is included below and is already "
77
+ f"loaded for this Hermes session. Follow it now. "
78
+ f"Do not try to load using-superpowers again.\n\n"
79
+ f"{body}\n\n"
80
+ f"## Loading Superpowers Skills on Hermes\n\n"
81
+ f"Superpowers skills are registered with Hermes' native skill loader: "
82
+ f'invoke one with `skill_view("superpowers-zh:skill-name")` '
83
+ f'(for example `skill_view("superpowers-zh:brainstorming")`). '
84
+ f"If a namespaced lookup returns 'not found', read the skill file "
85
+ f"directly instead:\n"
86
+ f'`read_file("{skills_dir}/skill-name/SKILL.md")`\n\n'
87
+ f"The superpowers skills directory is: `{skills_dir}`\n\n"
88
+ f"{tool_mapping}\n"
89
+ f"</EXTREMELY_IMPORTANT>"
90
+ )
91
+
92
+
93
+ def register(ctx):
94
+ skills_dir = _skills_dir()
95
+ bootstrap = _build_bootstrap(skills_dir)
96
+
97
+ # Register every stock skill with Hermes' native loader so skill_view can
98
+ # load them on demand. Standard markdown; no conversion (plugin guide).
99
+ # register_skill requires a pathlib.Path — a str raises AttributeError and
100
+ # hermes silently disables the whole plugin (verified 2026-07-23).
101
+ for name in sorted(os.listdir(skills_dir)):
102
+ skill_md = os.path.join(skills_dir, name, "SKILL.md")
103
+ if os.path.isfile(skill_md):
104
+ with open(skill_md, encoding="utf-8") as f:
105
+ description = _frontmatter_value(f.read(), "description")
106
+ ctx.register_skill(name, Path(skill_md), description=description)
107
+
108
+ # pre_llm_call returning {"context": ...} is the documented injection path
109
+ # (on_session_start return values are ignored, and ctx.inject_message
110
+ # refuses from that hook — verified empirically 2026-07-23). The context is
111
+ # appended to the first turn's user message. delegate_task children run
112
+ # with platform="subagent" and an empty history, so every child's first
113
+ # turn would otherwise get the controller bootstrap too.
114
+ def pre_llm_call(
115
+ session_id=None,
116
+ user_message=None,
117
+ conversation_history=None,
118
+ is_first_turn=None,
119
+ model=None,
120
+ platform=None,
121
+ **kwargs,
122
+ ):
123
+ if is_first_turn and platform != "subagent":
124
+ return {"context": bootstrap}
125
+ return None
126
+
127
+ ctx.register_hook("pre_llm_call", pre_llm_call)
@@ -0,0 +1,6 @@
1
+ name: superpowers-zh
2
+ version: "1.9.0-rc.2"
3
+ description: Superpowers skills and workflow bootstrap for Hermes Agent
4
+ author: jnMetaCode
5
+ provides_hooks:
6
+ - pre_llm_call
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "superpowers-zh",
3
+ "description": "Development marketplace for Superpowers core skills library",
4
+ "owner": {
5
+ "name": "jnMetaCode",
6
+ "url": "https://github.com/jnMetaCode"
7
+ },
8
+ "plugins": [
9
+ {
10
+ "name": "superpowers-zh",
11
+ "description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques",
12
+ "version": "1.9.0-rc.2",
13
+ "source": "./",
14
+ "author": {
15
+ "name": "jnMetaCode",
16
+ "url": "https://github.com/jnMetaCode"
17
+ }
18
+ }
19
+ ]
20
+ }
@@ -0,0 +1,113 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "name": "superpowers-zh",
4
+ "displayName": "Superpowers 中文增强版",
5
+ "version": "1.9.0-rc.2",
6
+ "description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques",
7
+ "compat": {
8
+ "source": "native",
9
+ "manifestDir": ".muse-plugin"
10
+ },
11
+ "capabilities": {
12
+ "skills": [
13
+ {
14
+ "id": "brainstorming",
15
+ "path": "skills/brainstorming/SKILL.md"
16
+ },
17
+ {
18
+ "id": "chinese-code-review",
19
+ "path": "skills/chinese-code-review/SKILL.md"
20
+ },
21
+ {
22
+ "id": "chinese-commit-conventions",
23
+ "path": "skills/chinese-commit-conventions/SKILL.md"
24
+ },
25
+ {
26
+ "id": "chinese-documentation",
27
+ "path": "skills/chinese-documentation/SKILL.md"
28
+ },
29
+ {
30
+ "id": "chinese-git-workflow",
31
+ "path": "skills/chinese-git-workflow/SKILL.md"
32
+ },
33
+ {
34
+ "id": "diagnosing-superpowers",
35
+ "path": "skills/diagnosing-superpowers/SKILL.md"
36
+ },
37
+ {
38
+ "id": "dispatching-parallel-agents",
39
+ "path": "skills/dispatching-parallel-agents/SKILL.md"
40
+ },
41
+ {
42
+ "id": "executing-plans",
43
+ "path": "skills/executing-plans/SKILL.md"
44
+ },
45
+ {
46
+ "id": "finishing-a-development-branch",
47
+ "path": "skills/finishing-a-development-branch/SKILL.md"
48
+ },
49
+ {
50
+ "id": "mcp-builder",
51
+ "path": "skills/mcp-builder/SKILL.md"
52
+ },
53
+ {
54
+ "id": "receiving-code-review",
55
+ "path": "skills/receiving-code-review/SKILL.md"
56
+ },
57
+ {
58
+ "id": "requesting-code-review",
59
+ "path": "skills/requesting-code-review/SKILL.md"
60
+ },
61
+ {
62
+ "id": "subagent-driven-development",
63
+ "path": "skills/subagent-driven-development/SKILL.md"
64
+ },
65
+ {
66
+ "id": "systematic-debugging",
67
+ "path": "skills/systematic-debugging/SKILL.md"
68
+ },
69
+ {
70
+ "id": "test-driven-development",
71
+ "path": "skills/test-driven-development/SKILL.md"
72
+ },
73
+ {
74
+ "id": "using-git-worktrees",
75
+ "path": "skills/using-git-worktrees/SKILL.md"
76
+ },
77
+ {
78
+ "id": "using-superpowers",
79
+ "path": "skills/using-superpowers/SKILL.md"
80
+ },
81
+ {
82
+ "id": "verification-before-completion",
83
+ "path": "skills/verification-before-completion/SKILL.md"
84
+ },
85
+ {
86
+ "id": "workflow-runner",
87
+ "path": "skills/workflow-runner/SKILL.md"
88
+ },
89
+ {
90
+ "id": "writing-plans",
91
+ "path": "skills/writing-plans/SKILL.md"
92
+ },
93
+ {
94
+ "id": "writing-skills",
95
+ "path": "skills/writing-skills/SKILL.md"
96
+ }
97
+ ],
98
+ "commands": [],
99
+ "hooks": [
100
+ {
101
+ "id": "session-start",
102
+ "event": "SessionStart",
103
+ "command": [
104
+ "bash",
105
+ "hooks/session-start"
106
+ ],
107
+ "timeoutMs": 5000
108
+ }
109
+ ],
110
+ "mcpServers": [],
111
+ "reminders": []
112
+ }
113
+ }
@@ -9,7 +9,8 @@
9
9
  *
10
10
  * V2 (opencode2): loaded via default export { id, setup } by PluginSupervisor.
11
11
  * setup() registers skills natively via ctx.skill.transform(), and injects
12
- * bootstrap context via ctx.session.hook("context").
12
+ * bootstrap context via ctx.session.hook on `context`, `compaction`, and
13
+ * `generate` so every request shape carries the same cached prefix.
13
14
  *
14
15
  * No external dependencies — pure JavaScript works in both V1 and V2 without
15
16
  * installing @opencode-ai/plugin or effect.
@@ -78,7 +79,7 @@ export const V1_MAPPING = `**Tool Mapping for OpenCode:**
78
79
  When skills request actions, substitute OpenCode equivalents:
79
80
  - Create or update todos → \`todowrite\`
80
81
  - \`Subagent (general-purpose):\` → \`task\` with \`subagent_type: "general"\`
81
- - Invoke a skill → OpenCode's native \`skill\` tool
82
+ - Invoke a skill → OpenCode's native \`skill\` tool. Skill ids are bare names, so drop the \`superpowers:\` prefix skills use when they name each other (\`superpowers:brainstorming\` → \`skill\` with \`name: "brainstorming"\`)
82
83
  - Read files → \`read\`
83
84
  - Create, edit, or delete files → \`apply_patch\`
84
85
  - Run shell commands → \`bash\`
@@ -96,7 +97,7 @@ export const V2_MAPPING = `**Tool Mapping for OpenCode:**
96
97
  When skills request actions, substitute OpenCode equivalents:
97
98
  - Create or update todos → OpenCode v2 has no todo tool; track the plan in a markdown file (or the harness's plan facility) instead
98
99
  - \`Subagent (general-purpose):\` → \`subagent\` with \`agent: "general"\` (give it \`description\` and \`prompt\`, optionally \`background\`; pass \`sessionID\` to continue a previous subagent)
99
- - Invoke a skill → OpenCode's native \`skill\` tool
100
+ - Invoke a skill → OpenCode's native \`skill\` tool. Skill ids are bare names, so drop the \`superpowers:\` prefix skills use when they name each other (\`superpowers:brainstorming\` → \`skill\` with \`id: "brainstorming"\`)
100
101
  - Read files → \`read\`
101
102
  - Create, edit, or delete files → use \`patch\` with \`patchText\` when available; otherwise use \`write\` to create or overwrite files, \`edit\` for targeted changes, and \`shell\` for deletion
102
103
  - Run shell commands → \`shell\` (\`command\`, \`workdir\`, \`timeout\`, \`background\`)
@@ -112,6 +113,11 @@ Use OpenCode's native \`skill\` tool to list and load skills.`;
112
113
  // regex work on every agent step. See #1202 for the full analysis.
113
114
  const _bootstrapCache = new Map(); // mapping -> bootstrap (null = file missing)
114
115
 
116
+ // Opening of every injected bootstrap part. The already-injected guards match
117
+ // it at the start of a part, so a prompt that merely mentions the tag (#2197)
118
+ // is not mistaken for the bootstrap.
119
+ const BOOTSTRAP_MARKER = '<EXTREMELY_IMPORTANT>\nYou have superpowers.';
120
+
115
121
  // Helper to generate bootstrap content (cached after first call per mapping)
116
122
  const getBootstrapContent = (toolMapping) => {
117
123
  // Return cached result on subsequent calls
@@ -127,8 +133,7 @@ const getBootstrapContent = (toolMapping) => {
127
133
  const fullContent = fs.readFileSync(skillPath, 'utf8');
128
134
  const { content } = extractAndStripFrontmatter(fullContent);
129
135
 
130
- _bootstrapCache.set(toolMapping, `<EXTREMELY_IMPORTANT>
131
- You have superpowers.
136
+ _bootstrapCache.set(toolMapping, `${BOOTSTRAP_MARKER}
132
137
 
133
138
  **IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.**
134
139
 
@@ -248,7 +253,7 @@ export const SuperpowersPlugin = async ({ client, directory }) => {
248
253
  if (!firstUser || !firstUser.parts.length) return;
249
254
 
250
255
  // Guard: skip if first user message already contains bootstrap.
251
- if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return;
256
+ if (firstUser.parts.some(p => p.type === 'text' && p.text.startsWith(BOOTSTRAP_MARKER))) return;
252
257
 
253
258
  // #2160: never restart the controller workflow inside task subagent
254
259
  // (child) sessions. V1 passes no input to this hook (verified in the
@@ -280,8 +285,12 @@ export const SuperpowersPlugin = async ({ client, directory }) => {
280
285
  * is `path` — renamed from `location` in upstream commit 199aabe9e2,
281
286
  * first released in v2.0.4.
282
287
  * See packages/core/src/plugin/skill.ts and packages/schema/src/skill.ts.
283
- * 2. Injects bootstrap context via ctx.session.hook("context"), the V2
284
- * equivalent of V1's experimental.chat.messages.transform.
288
+ * 2. Injects bootstrap context via ctx.session.hook on `context`,
289
+ * `compaction`, and `generate` — the V2 equivalents of V1's
290
+ * experimental.chat.messages.transform. OpenCode's built-in plugins
291
+ * register on all three; skipping any one makes that request's prompt
292
+ * diverge from the cached prefix at the first user message, which for a
293
+ * large session forces a cold re-prefill. See issue #2391.
285
294
  */
286
295
  async function setup(ctx) {
287
296
  // V1 (observed on opencode 1.18.18) also invokes default.setup, but with a
@@ -334,38 +343,51 @@ async function setup(ctx) {
334
343
  console.error('[superpowers] skill registration failed:', err);
335
344
  }
336
345
 
337
- // 2. Inject bootstrap into first user message via V2 session context hook
338
- try {
339
- await ctx.session.hook('context', async (event) => {
340
- try {
341
- const bootstrap = getBootstrapContent(V2_MAPPING);
342
- if (!bootstrap || !event.messages || !event.messages.length) return;
343
- const firstUser = event.messages.find(m => m.role === 'user');
344
- if (firstUser && (!firstUser.content || !firstUser.content.length)) return;
345
- if (firstUser?.content.some(p => p.type === 'text' && p.text && p.text.includes('EXTREMELY_IMPORTANT'))) return;
346
-
347
- // #2160: the context event carries the sessionID directly. Skip the
348
- // controller bootstrap when this prompt belongs to a task subagent
349
- // (child) session. Skills registered above stay available to workers.
350
- if (typeof ctx.session.get === 'function' && await isChildSession(
351
- (id) => ctx.session.get({ sessionID: id }),
352
- event.sessionID,
353
- )) return;
354
-
355
- // Native compaction can leave only an opaque checkpoint. Keep it
356
- // intact and append the transient bootstrap as a user message.
357
- if (firstUser) {
358
- firstUser.content.unshift({ type: 'text', text: bootstrap });
359
- } else {
360
- event.messages.push({ role: 'user', content: [{ type: 'text', text: bootstrap }] });
361
- }
362
- } catch (err) {
363
- // Never let hook callback errors break the request pipeline.
364
- console.error('[superpowers] context hook failed:', err);
346
+ // 2. Inject bootstrap into first user message via V2 session hooks.
347
+ // OpenCode V2 dispatches three request shapes — context (normal turn),
348
+ // compaction (auto-summary), and generate (explicit generation). The
349
+ // compaction payload is the same `{ sessionID, messages, ... }` shape as
350
+ // context (observed on 2.1.2/2.1.3); generate's is taken from upstream
351
+ // source and the built-in plugins, not observed. OpenCode's
352
+ // own built-in plugins register on all three; if superpowers only covers
353
+ // `context`, the other two requests diverge from the cached prefix at
354
+ // exactly the position the bootstrap would have occupied, forcing a cold
355
+ // re-prefill of the whole session on the largest request of its lifetime.
356
+ // See issue #2391.
357
+ const injectBootstrap = async (event) => {
358
+ try {
359
+ const bootstrap = getBootstrapContent(V2_MAPPING);
360
+ if (!bootstrap || !event.messages || !event.messages.length) return;
361
+ const firstUser = event.messages.find(m => m.role === 'user');
362
+ if (firstUser && (!firstUser.content || !firstUser.content.length)) return;
363
+ if (firstUser?.content.some(p => p.type === 'text' && p.text && p.text.startsWith(BOOTSTRAP_MARKER))) return;
364
+
365
+ // #2160: the request event carries the sessionID directly. Skip the
366
+ // controller bootstrap when this prompt belongs to a task subagent
367
+ // (child) session. Skills registered above stay available to workers.
368
+ if (typeof ctx.session.get === 'function' && await isChildSession(
369
+ (id) => ctx.session.get({ sessionID: id }),
370
+ event.sessionID,
371
+ )) return;
372
+
373
+ // Native compaction can leave only an opaque checkpoint. Keep it
374
+ // intact and append the transient bootstrap as a user message.
375
+ if (firstUser) {
376
+ firstUser.content.unshift({ type: 'text', text: bootstrap });
377
+ } else {
378
+ event.messages.push({ role: 'user', content: [{ type: 'text', text: bootstrap }] });
365
379
  }
366
- });
367
- } catch (err) {
368
- console.error('[superpowers] session hook registration failed:', err);
380
+ } catch (err) {
381
+ // Never let hook callback errors break the request pipeline.
382
+ console.error('[superpowers] session hook failed:', err);
383
+ }
384
+ };
385
+ for (const hookName of ['context', 'compaction', 'generate']) {
386
+ try {
387
+ await ctx.session.hook(hookName, injectBootstrap);
388
+ } catch (err) {
389
+ console.error(`[superpowers] session hook registration failed (${hookName}):`, err);
390
+ }
369
391
  }
370
392
  }
371
393
 
@@ -16,10 +16,6 @@ let cachedBootstrap: string | null | undefined;
16
16
  export default function superpowersPiExtension(pi: ExtensionAPI) {
17
17
  let injectBootstrap = true;
18
18
 
19
- pi.on("resources_discover", async () => ({
20
- skillPaths: [skillsDir],
21
- }));
22
-
23
19
  pi.on("session_start", async () => {
24
20
  injectBootstrap = true;
25
21
  });
@@ -28,10 +24,9 @@ export default function superpowersPiExtension(pi: ExtensionAPI) {
28
24
  injectBootstrap = true;
29
25
  });
30
26
 
31
- pi.on("agent_end", async () => {
32
- injectBootstrap = false;
33
- });
34
-
27
+ // Messages returned from a context handler are sent to the provider but never
28
+ // written to session history, so the bootstrap has to be injected into every
29
+ // provider request, on every prompt, for the whole session.
35
30
  pi.on("context", async (event) => {
36
31
  if (!injectBootstrap) return;
37
32
  if (event.messages.some(messageContainsBootstrap)) return;