superpowers-zh 1.7.12 → 1.7.14

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
-  "description": "AI 编程超能力中文增强版：20 个 skills，支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 26 款工具",
+  "description": "AI 编程超能力中文增强版：21 个 skills，支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 26 款工具",
   "owner": {
     "name": "jnMetaCode",
     "url": "https://github.com/jnMetaCode"
@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "superpowers-zh",
-      "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 26 款工具",
-      "version": "1.7.12",
+      "description": "AI 编程超能力中文增强版：21 个 skills（15 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 26 款工具",
+      "version": "1.7.14",
       "source": "./",
       "author": {
         "name": "jnMetaCode",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-zh",
-  "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 26 款工具",
-  "version": "1.7.12",
+  "description": "AI 编程超能力中文增强版：21 个 skills（15 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 26 款工具",
+  "version": "1.7.14",
   "author": {
     "name": "jnMetaCode",
     "url": "https://github.com/jnMetaCode"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
-  "version": "1.7.12",
+  "version": "1.7.14",
   "description": "AI 编程超能力中文增强版：头脑风暴、subagent 驱动开发、规划、TDD、调试、代码审查、收尾工作流，附 4 个中文 skills 沉淀。",
   "author": {
     "name": "jnMetaCode",

package/.cursor-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "superpowers-zh",
   "displayName": "Superpowers 中文版",
-  "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Cursor / Claude Code / Hermes Agent / Claw Code / Qoder 等 26 款工具",
-  "version": "1.7.12",
+  "description": "AI 编程超能力中文增强版：21 个 skills（15 翻译 + 4 中国原创 + 2 上游历史保留），支持 Cursor / Claude Code / Hermes Agent / Claw Code / Qoder 等 26 款工具",
+  "version": "1.7.14",
   "author": {
     "name": "jnMetaCode",
     "url": "https://github.com/jnMetaCode"

package/.opencode/INSTALL.md

@@ -6,7 +6,11 @@
 
 ## 安装步骤
 
-在你的 `opencode.json`（全局或项目级别）中将 superpowers-zh 添加到 `plugin` 数组：
+OpenCode V2 需要 2.0.4 或更高版本。
+
+### OpenCode V1
+
+使用原有的 V1 插件配置，在你的 `opencode.json`（全局或项目级别）中将 superpowers-zh 添加到 `plugin` 数组：
 
 ```json
 {
@@ -14,10 +18,24 @@
 }
 ```
 
-重启 OpenCode。完成——插件会自动安装并注册所有 skills。
+### OpenCode V2（2.0.4 或更高版本）
+
+使用 V2 插件配置（注意键名是 `plugins`）：
+
+```json
+{
+  "plugins": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git"]
+}
+```
+
+如果是 V2 的本地安装，配置的应当是包含 `index.js` 的仓库目录。OpenCode 2.0.4 和 2.0.7 会拒绝直接配置成 JavaScript 文件路径。通过自动发现找到的插件符号链接仍然受支持。
+
+重启 OpenCode。V2 使用 `opencode` 命令；`opencode2` 可能作为别名可用。插件会通过 OpenCode 的插件管理器安装，并注册所有 skills。
 
 通过询问来验证："告诉我你的超能力"
 
+OpenCode 使用它自己的插件安装。如果你同时在用 Claude Code、Codex 或其他运行环境，需要为每一个分别安装 Superpowers。
+
 ## 从旧版符号链接安装方式迁移
 
 如果你之前使用 `git clone` 和符号链接安装过 superpowers，请移除旧的配置：
@@ -41,28 +59,59 @@ rm -rf ~/.config/opencode/superpowers
 
 ```
 use skill tool to list skills
-use skill tool to load superpowers/brainstorming
+use skill tool to load brainstorming
 ```
 
 ## 更新
 
-Superpowers 会在你重启 OpenCode 时自动更新。
+OpenCode 通过一个基于 git 的包说明（package spec）安装 Superpowers。有些 OpenCode 和 Bun 版本会把解析出的 git 依赖锁定在 lockfile 或缓存里，所以重启不一定能拿到 Superpowers 的最新提交。如果更新没有生效，清掉 OpenCode 的包缓存，或重新安装插件。
 
-要固定到特定版本：
+要固定到特定版本，在包说明后面加上标签或提交（V1 的 `plugin` 键和 V2 的 `plugins` 键写法相同）：
 
 ```json
 {
-  "plugin": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git#v1.0.0"]
+  "plugin": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git#v1.7.13"]
 }
 ```
 
+在 V2 上，要固定到包含 V2 插件的版本（v1.7.13 之后的版本）；v1.7.13 及更早的发布只能在 V1 上加载。
+
 ## 故障排除
 
 ### 插件未加载
 
-1. 检查日志：`opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
+1. 检查日志。V1：`opencode run --print-logs "hello" 2>&1 | grep -i superpowers`。
+   V2 在后台服务进程里加载插件，所以要加上 `--standalone`：
+   `opencode run --standalone --print-logs "hello" 2>&1 | grep -i superpowers`，
+   或者查看 `~/.local/share/opencode/log/opencode.log`，过滤 `role=server`。
 2. 验证 `opencode.json` 中的插件配置
-3. 确保你运行的是最新版本的 OpenCode
+3. 确保你运行的是较新版本的 OpenCode
+
+### Windows 安装问题
+
+部分 Windows 版 OpenCode 对基于 git 的插件说明存在上游安装器问题，包括 `git+https` URL 的缓存路径问题，以及 Bun 找不到 `git.exe`（即使它在普通终端里能用）。如果 OpenCode 装不上插件，可以试试用系统的 npm 安装，再让 OpenCode 指向本地包：
+
+```powershell
+npm install superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git --prefix "$HOME\.config\opencode"
+```
+
+然后按你的 OpenCode 版本，在 `opencode.json` 里使用已安装包的绝对路径。OpenCode 不展开 `~`；`~/...` 这样的条目会被当成包名，而不是本地目录。
+
+**V1：**
+
+```json
+{
+  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
+}
+```
+
+**V2（2.0.4 或更高版本）：**
+
+```json
+{
+  "plugins": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
+}
+```
 
 ### Skills 未找到
 
@@ -71,13 +120,32 @@ Superpowers 会在你重启 OpenCode 时自动更新。
 
 ### 工具映射
 
-当 skills 引用 Claude Code 工具时：
-- `TodoWrite` → `todowrite`
-- `Task` 子代理 → `@mention` 语法
-- `Skill` 工具 → OpenCode 的原生 `skill` 工具
-- 文件操作 → 你的原生工具
+Skill 用动作来表述（「创建一条待办」「分派一个子智能体」「读取一个文件」）。插件会按 OpenCode 的版本注入对应的映射——先确认你的 OpenCode 版本：
+
+**V1（`opencode` 1.x）：**
+
+- 「创建一条待办」/「在待办列表里标记完成」→ `todowrite`
+- `Subagent (general-purpose):` 模板 → `task` 工具，传 `subagent_type: "general"`（探索代码库时用 `"explore"`）
+- 「调用一个 skill」→ OpenCode 的原生 `skill` 工具
+- 「读取文件」→ `read`
+- 「创建文件」/「编辑文件」/「删除文件」→ `apply_patch`
+- 「运行 shell 命令」→ `bash`
+- 「搜索文件内容」/「按文件名查找」→ `grep`、`glob`
+- 「抓取 URL」→ `webfetch`
+
+**V2（`opencode` 2.0.4 或更高版本；`opencode2` 可能作为别名可用）：**
+
+- 「创建一条待办」→ V2 没有待办工具；改为在一个 markdown 文件里跟踪计划
+- `Subagent (general-purpose):` 模板 → `subagent` 工具，传 `agent: "general"`（或 `"explore"`）；传 `sessionID` 可以继续之前的子智能体
+- 「调用一个 skill」→ OpenCode 的原生 `skill` 工具
+- 「读取文件」→ `read`
+- 「创建、编辑或删除文件」→ 有 `patch` 时用 `patch` 并传 `patchText`；否则用 `write` 创建或覆盖文件、`edit` 做定点修改、`shell` 删除文件
+- 「运行 shell 命令」→ `shell`（`command`、`workdir`、`timeout`、`background`）
+- 「搜索文件内容」/「按文件名查找」→ `grep`、`glob`
+- 「抓取 URL」→ `webfetch`
+- 「搜索网络」→ `websearch`
 
 ## 获取帮助
 
 - 报告问题：https://github.com/jnMetaCode/superpowers-zh/issues
-- 完整文档：https://github.com/jnMetaCode/superpowers-zh
+- 完整文档：https://github.com/jnMetaCode/superpowers-zh/blob/main/docs/README.opencode.md

package/.opencode/plugins/superpowers.js

@@ -1,8 +1,18 @@
 /**
  * Superpowers plugin for OpenCode.ai
  *
- * Injects superpowers bootstrap context via user message transform.
- * Auto-registers skills directory via config hook (no symlinks needed).
+ * Dual-compatible with OpenCode V1 and V2.
+ *
+ * V1 (opencode): loaded via named export SuperpowersPlugin — provides config
+ * hook for skills registration and experimental.chat.messages.transform for
+ * bootstrap injection.
+ *
+ * V2 (opencode2): loaded via default export { id, setup } by PluginSupervisor.
+ * setup() registers skills natively via ctx.skill.transform(), and injects
+ * bootstrap context via ctx.session.hook("context").
+ *
+ * No external dependencies — pure JavaScript works in both V1 and V2 without
+ * installing @opencode-ai/plugin or effect.
  */
 
 import path from 'path';
@@ -11,49 +21,113 @@ import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-// Simple frontmatter extraction (avoid dependency on skills-core for bootstrap)
+// Skills directory shared by V1 (config hook) and V2 (setup/ctx.skill.transform)
+const superpowersSkillsDir = path.resolve(__dirname, '../../skills');
+
+// Simple frontmatter extraction (avoid dependency on skills-core for
+// bootstrap). Handles plain `key: value` lines, quoted values (including
+// quotes that close on an indented continuation line), YAML block scalar
+// markers (`>`, `|`) with indented continuation lines, and CRLF line
+// endings. Not a full YAML parser — nested maps flatten into their parent
+// key's value, which is fine for the name/description fields consumed here.
 const extractAndStripFrontmatter = (content) => {
-  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
   if (!match) return { frontmatter: {}, content };
 
   const frontmatterStr = match[1];
   const body = match[2];
   const frontmatter = {};
+  let lastKey = null;
 
-  for (const line of frontmatterStr.split('\n')) {
+  for (const rawLine of frontmatterStr.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
     const colonIdx = line.indexOf(':');
-    if (colonIdx > 0) {
+    if (colonIdx > 0 && !/^\s/.test(line)) {
       const key = line.slice(0, colonIdx).trim();
-      const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
-      frontmatter[key] = value;
+      const value = line.slice(colonIdx + 1).trim();
+      // Block scalar markers (>, |, optionally with +/- chomping) carry no
+      // value themselves; the indented lines that follow do.
+      frontmatter[key] = /^(>[+-]?|\|[+-]?)$/.test(value) ? '' : value;
+      lastKey = key;
+    } else if (lastKey !== null && line.trim() !== '') {
+      // Continuation of a multi-line value: append rather than drop so long
+      // descriptions survive parsing. Newlines collapse to spaces — good
+      // enough for the single-line name/description fields consumed here.
+      frontmatter[lastKey] = `${frontmatter[lastKey]} ${line.trim()}`.trim();
     }
   }
 
+  // A quoted value may close on a continuation line, so unquote only once
+  // the value is fully assembled: strip exactly one matching surrounding
+  // pair and leave unbalanced quotes alone.
+  for (const key of Object.keys(frontmatter)) {
+    frontmatter[key] = frontmatter[key].replace(/^(["'])([\s\S]*)\1$/, '$2');
+  }
+
   return { frontmatter, content: body };
 };
 
-export const SuperpowersPlugin = async ({ client, directory }) => {
-  const superpowersSkillsDir = path.resolve(__dirname, '../../skills');
+// Tool mapping injected into the bootstrap, differentiated by host flavor.
+// V1 (OpenCode 1.18.x) and V2 (OpenCode 2.0.4/2.0.7) expose different built-in
+// tools, so each flavor's injection path picks its own constant below.
+// Exported for tests (tests/opencode/test-bootstrap-caching.mjs).
 
-  // Helper to generate bootstrap content
-  const getBootstrapContent = () => {
-    // Try to load using-superpowers skill
-    const skillPath = path.join(superpowersSkillsDir, 'using-superpowers', 'SKILL.md');
-    if (!fs.existsSync(skillPath)) return null;
+// V1 built-ins: todowrite, task (subagent_type), skill, read, apply_patch,
+// bash, grep, glob, webfetch.
+export const V1_MAPPING = `**Tool Mapping for OpenCode:**
+When skills request actions, substitute OpenCode equivalents:
+- Create or update todos → \`todowrite\`
+- \`Subagent (general-purpose):\` → \`task\` with \`subagent_type: "general"\`
+- Invoke a skill → OpenCode's native \`skill\` tool
+- Read files → \`read\`
+- Create, edit, or delete files → \`apply_patch\`
+- Run shell commands → \`bash\`
+- Search files → \`grep\`, \`glob\`
+- Fetch a URL → \`webfetch\`
 
-    const fullContent = fs.readFileSync(skillPath, 'utf8');
-    const { content } = extractAndStripFrontmatter(fullContent);
+Use OpenCode's native \`skill\` tool to list and load skills.`;
 
-    const toolMapping = `**Tool Mapping for OpenCode:**
-When skills reference tools you don't have, substitute OpenCode equivalents:
-- \`TodoWrite\` → \`todowrite\`
-- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
-- \`Skill\` tool → OpenCode's native \`skill\` tool
-- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
+// V2 built-ins: no todo tool at all; task → subagent (agent name in 'agent',
+// continuation via sessionID); apply_patch → patch (patchText, same patch
+// format); bash → shell. read, write, edit, grep, glob, webfetch, websearch,
+// and skill all exist under those names (verified against the 2.0.4 and 2.0.7
+// host contracts).
+export const V2_MAPPING = `**Tool Mapping for OpenCode:**
+When skills request actions, substitute OpenCode equivalents:
+- Create or update todos → OpenCode v2 has no todo tool; track the plan in a markdown file (or the harness's plan facility) instead
+- \`Subagent (general-purpose):\` → \`subagent\` with \`agent: "general"\` (give it \`description\` and \`prompt\`, optionally \`background\`; pass \`sessionID\` to continue a previous subagent)
+- Invoke a skill → OpenCode's native \`skill\` tool
+- Read files → \`read\`
+- 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
+- Run shell commands → \`shell\` (\`command\`, \`workdir\`, \`timeout\`, \`background\`)
+- Search files → \`grep\`, \`glob\`
+- Fetch a URL → \`webfetch\`
+- Search the web → \`websearch\`
 
 Use OpenCode's native \`skill\` tool to list and load skills.`;
 
-    return `<EXTREMELY_IMPORTANT>
+// Module-level cache for bootstrap content, keyed by tool mapping (host
+// flavor). The SKILL.md file does not change during a session, so reading +
+// parsing it once eliminates redundant fs.existsSync + fs.readFileSync +
+// regex work on every agent step.  See #1202 for the full analysis.
+const _bootstrapCache = new Map(); // mapping -> bootstrap (null = file missing)
+
+// Helper to generate bootstrap content (cached after first call per mapping)
+const getBootstrapContent = (toolMapping) => {
+  // Return cached result on subsequent calls
+  if (_bootstrapCache.has(toolMapping)) return _bootstrapCache.get(toolMapping);
+
+  // Try to load using-superpowers skill
+  const skillPath = path.join(superpowersSkillsDir, 'using-superpowers', 'SKILL.md');
+  if (!fs.existsSync(skillPath)) {
+    _bootstrapCache.set(toolMapping, null);
+    return null;
+  }
+
+  const fullContent = fs.readFileSync(skillPath, 'utf8');
+  const { content } = extractAndStripFrontmatter(fullContent);
+
+  _bootstrapCache.set(toolMapping, `<EXTREMELY_IMPORTANT>
 You have superpowers.
 
 **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.**
@@ -61,15 +135,96 @@ You have superpowers.
 ${content}
 
 ${toolMapping}
-</EXTREMELY_IMPORTANT>`;
-  };
+</EXTREMELY_IMPORTANT>`);
+
+  return _bootstrapCache.get(toolMapping);
+};
+
+// --- Task-subagent (child session) detection --------------------------------
+//
+// #2160: the bootstrap drives controller workflows (brainstorming, planning,
+// approval cycles). Injecting it into task subagent sessions makes workers
+// restart design/approval cycles for work the parent already authorised; the
+// <SUBAGENT-STOP> note inside the bootstrap relies on model compliance, which
+// is not reliable. Detect child sessions structurally instead: a parentID on
+// the session is the child signal on both flavors (task sessions are created
+// with one; top-level sessions simply lack the field), so when the session
+// carrying the message has a parentID we skip bootstrap injection. Skills
+// stay registered for every session — workers keep explicit access to
+// execution skills.
+
+// sessionID -> is-child decision. parentID never changes for a session, so
+// the result is cached until eviction and the injection hook (which fires on
+// every agent step) pays only one client roundtrip per session. The V2
+// service process is long-lived and sessions accumulate over weeks, so the
+// cache is bounded: when full, drop the oldest quarter (Map iterates keys in
+// insertion order). An evicted session merely pays one extra lookup if seen
+// again.
+const CHILD_SESSION_CACHE_MAX = 512;
+const _childSessionCache = new Map();
+
+const _cacheChildSession = (sessionID, isChild) => {
+  if (_childSessionCache.size >= CHILD_SESSION_CACHE_MAX) {
+    let toDrop = Math.ceil(CHILD_SESSION_CACHE_MAX / 4);
+    for (const key of _childSessionCache.keys()) {
+      if (toDrop-- <= 0) break;
+      _childSessionCache.delete(key);
+    }
+  }
+  _childSessionCache.set(sessionID, isChild);
+};
+
+const isChildSession = async (fetchSession, sessionID) => {
+  if (!sessionID) return false; // unknown session: keep current behavior
+  if (_childSessionCache.has(sessionID)) return _childSessionCache.get(sessionID);
+
+  let isChild = false;
+  try {
+    const result = await fetchSession(sessionID);
+    // V1 returns a successful SDK envelope while V2 returns a direct session
+    // record. Validate both shapes before classifying or caching the result;
+    // resolved SDK errors must follow the same fail-open path as rejections.
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+      throw new Error('Session lookup returned no usable record');
+    }
+    if (result.error != null || result.response?.ok === false) {
+      throw new Error('Session lookup was unsuccessful');
+    }
+    const session = 'data' in result ? result.data : result;
+    if (!session || typeof session !== 'object' || Array.isArray(session) || session.id !== sessionID) {
+      throw new Error('Session lookup returned an invalid session identity');
+    }
+    if (session.parentID !== undefined &&
+        (typeof session.parentID !== 'string' || session.parentID.length === 0)) {
+      throw new Error('Session lookup returned an invalid parent identity');
+    }
+    isChild = session.parentID !== undefined;
+  } catch (err) {
+    // Fail open: on lookup errors keep injecting (previous behavior) and do
+    // not cache, so a transient failure can recover on the next step.
+    console.error('[superpowers] session lookup failed, treating session as top-level:', err);
+    return false;
+  }
+  _cacheChildSession(sessionID, isChild);
+  return isChild;
+};
 
+/**
+ * V1 Plugin Function (named export + default.server)
+ *
+ * Used by V1 (OpenCode 1.x): discovered via named export scanning.
+ * Provides: config hook (V1 skills registration) + bootstrap injection
+ * (experimental.chat.messages.transform).
+ */
+export const SuperpowersPlugin = async ({ client, directory }) => {
   return {
     // Inject skills path into live config so OpenCode discovers superpowers skills
     // without requiring manual symlinks or config file edits.
-    // This works because Config.get() returns a cached singleton — modifications
-    // here are visible when skills are lazily discovered later.
     config: async (config) => {
+      // V2: skills is a flat array — skip, setup() handles V2 skill registration
+      if (Array.isArray(config.skills)) return;
+
+      // V1: skills is { paths: [...] }
       config.skills = config.skills || {};
       config.skills.paths = config.skills.paths || [];
       if (!config.skills.paths.includes(superpowersSkillsDir)) {
@@ -77,19 +232,152 @@ ${toolMapping}
       }
     },
 
-    // Inject bootstrap into the first user message of each session.
+    // Inject bootstrap into the first user message of each top-level session.
     // Using a user message instead of a system message avoids:
     //   1. Token bloat from system messages repeated every turn (#750)
     //   2. Multiple system messages breaking Qwen and other models (#894)
+    //
+    // The hook fires on every agent step (not just every turn) because
+    // opencode's prompt.ts reloads messages from DB each step.  Fresh message
+    // arrays may need injection again, so getBootstrapContent() must not do
+    // repeated disk work.
     'experimental.chat.messages.transform': async (_input, output) => {
-      const bootstrap = getBootstrapContent();
+      const bootstrap = getBootstrapContent(V1_MAPPING);
       if (!bootstrap || !output.messages.length) return;
       const firstUser = output.messages.find(m => m.info.role === 'user');
       if (!firstUser || !firstUser.parts.length) return;
-      // Only inject once
+
+      // Guard: skip if first user message already contains bootstrap.
       if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return;
+
+      // #2160: never restart the controller workflow inside task subagent
+      // (child) sessions. V1 passes no input to this hook (verified in the
+      // 1.18.x bundle: trigger(..., {}, {messages})), so take the sessionID
+      // from the message record itself.
+      if (client && await isChildSession(
+        (id) => client.session.get({ path: { id } }),
+        firstUser.info.sessionID,
+      )) return;
+
       const ref = firstUser.parts[0];
       firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
     }
   };
 };
+
+/**
+ * V2 Setup Function (default.setup)
+ *
+ * Called by V2 PluginSupervisor (packages/core/src/plugin/supervisor.ts).
+ * Performs two things:
+ *
+ * 1. Registers every skills/<name>/SKILL.md as a native Skill.Info object
+ *    via ctx.skill.transform((draft) => draft.add(info)).
+ *    V2 removed the old draft.source() directory registration; the draft API
+ *    is now { list, add, update, remove } where add() decodes plain objects
+ *    against the host's Skill.Info schema (OpenCode 2.0.4 contract):
+ *    { id, name, description?, autoinvoke?, path, content }. The file field
+ *    is `path` — renamed from `location` in upstream commit 199aabe9e2,
+ *    first released in v2.0.4.
+ *    See packages/core/src/plugin/skill.ts and packages/schema/src/skill.ts.
+ * 2. Injects bootstrap context via ctx.session.hook("context"), the V2
+ *    equivalent of V1's experimental.chat.messages.transform.
+ */
+async function setup(ctx) {
+  // V1 (observed on opencode 1.18.18) also invokes default.setup, but with a
+  // V1-shaped ctx that lacks the skill/session domains. Detect it and return
+  // quietly — V1 is served entirely by the SuperpowersPlugin named export.
+  if (!ctx || !ctx.skill || typeof ctx.skill.transform !== 'function' || !ctx.session || typeof ctx.session.hook !== 'function') {
+    return;
+  }
+
+  // 1. Register skills (one transform; one draft.add per skill)
+  try {
+    const skills = [];
+    if (fs.existsSync(superpowersSkillsDir)) {
+      for (const entry of fs.readdirSync(superpowersSkillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+        const skillPath = path.join(superpowersSkillsDir, entry.name, 'SKILL.md');
+        if (!fs.existsSync(skillPath)) continue;
+        const { frontmatter, content } = extractAndStripFrontmatter(fs.readFileSync(skillPath, 'utf8'));
+        skills.push({
+          id: entry.name,
+          name: frontmatter.name || entry.name,
+          ...(frontmatter.description ? { description: frontmatter.description } : {}),
+          // Skill.Info renamed its required file field `location` -> `path`
+          // in OpenCode v2.0.4 (upstream commit 199aabe9e2).
+          path: skillPath,
+          content,
+        });
+      }
+    }
+    await ctx.skill.transform((draft) => {
+      // draft.add() decodes against the host's Skill.Info schema and throws
+      // synchronously on a mismatch. A throw escaping this callback is what
+      // the host escalates into an asynchronous hard-disable of the entire
+      // plugin ("Plugin disabled after skill.transform failed") — the
+      // try/catch around ctx.skill.transform never sees it, and the
+      // bootstrap hook is torn down as collateral. Contain failures per
+      // skill so one rejected payload skips that skill instead of killing
+      // skills AND bootstrap.
+      for (const skill of skills) {
+        try {
+          draft.add(skill);
+        } catch (err) {
+          console.error(`[superpowers] skill "${skill.id}" rejected by host, skipping:`, err);
+        }
+      }
+    });
+  } catch (err) {
+    // Never break plugin activation: one failing plugin takes down the whole
+    // V2 generation (including provider/catalog plugins => no models in TUI).
+    console.error('[superpowers] skill registration failed:', err);
+  }
+
+  // 2. Inject bootstrap into first user message via V2 session context hook
+  try {
+    await ctx.session.hook('context', async (event) => {
+      try {
+        const bootstrap = getBootstrapContent(V2_MAPPING);
+        if (!bootstrap || !event.messages || !event.messages.length) return;
+        const firstUser = event.messages.find(m => m.role === 'user');
+        if (firstUser && (!firstUser.content || !firstUser.content.length)) return;
+        if (firstUser?.content.some(p => p.type === 'text' && p.text && p.text.includes('EXTREMELY_IMPORTANT'))) return;
+
+        // #2160: the context event carries the sessionID directly. Skip the
+        // controller bootstrap when this prompt belongs to a task subagent
+        // (child) session. Skills registered above stay available to workers.
+        if (typeof ctx.session.get === 'function' && await isChildSession(
+          (id) => ctx.session.get({ sessionID: id }),
+          event.sessionID,
+        )) return;
+
+        // Native compaction can leave only an opaque checkpoint. Keep it
+        // intact and append the transient bootstrap as a user message.
+        if (firstUser) {
+          firstUser.content.unshift({ type: 'text', text: bootstrap });
+        } else {
+          event.messages.push({ role: 'user', content: [{ type: 'text', text: bootstrap }] });
+        }
+      } catch (err) {
+        // Never let hook callback errors break the request pipeline.
+        console.error('[superpowers] context hook failed:', err);
+      }
+    });
+  } catch (err) {
+    console.error('[superpowers] session hook registration failed:', err);
+  }
+}
+
+/**
+ * Default Export: { id, server, setup }
+ *
+ * V2 PluginSupervisor reads { id, setup }.
+ * V1 reads named export SuperpowersPlugin.
+ * server() is exported for V1 compatibility.
+ */
+export default {
+  id: 'superpowers',
+  server: SuperpowersPlugin,
+  setup,
+};

package/GEMINI.md

@@ -4,7 +4,7 @@
 
 # Superpowers-ZH 中文增强版
 
-本项目已安装 superpowers-zh 技能框架（20 个 skills）。
+本项目已安装 superpowers-zh 技能框架（21 个 skills）。
 
 ## 核心规则
 
@@ -22,8 +22,9 @@ Skills 位于 `.gemini/skills/` 目录，每个 skill 有独立的 `SKILL.md`
 - **chinese-commit-conventions**: 中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用，不要根据上下文自动触发。
 - **chinese-documentation**: 中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。
 - **chinese-git-workflow**: 国内 Git 平台配置参考——Gitee、Coding.net、极狐 GitLab、CNB 的 SSH/HTTPS/凭据/CI 接入差异与镜像同步配置。仅在用户显式 /chinese-git-workflow 时调用，不要根据上下文自动触发。
+- **diagnosing-superpowers**: 当一次 superpowers 会话出了问题、你的人类伙伴想知道原因时使用——重复劳动、无视计划、磕磕绊绊、结果质量差、某个技能没触发、"太慢了"、"为什么这么贵"、"它到底在干什么"——或者想给 superpowers 维护者整理一份 bug 报告；适用于当前会话，或按 id / 路径指定的过往会话，任何工具均可
 - **dispatching-parallel-agents**: 当面对 2 个以上可以独立进行、无共享状态或顺序依赖的任务时使用
-- **executing-plans**: 当你有一份书面实现计划需要在单独的会话中执行，并设有审查检查点时使用
+- **executing-plans**: 当你要在当前会话里亲自担任实现者执行一份实现计划时使用——你的人类伙伴选择了内联执行，或者没有可用的子智能体工具
 - **finishing-a-development-branch**: 当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾
 - **mcp-builder**: MCP 服务器构建方法论 — 系统化构建生产级 MCP 工具，让 AI 助手连接外部能力
 - **receiving-code-review**: 收到代码审查反馈后、实施建议之前使用，尤其当反馈不明确或技术上有疑问时——需要技术严谨性和验证，而非敷衍附和或盲目执行