openclaw-superpowers-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebLeOn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.design.md

@@ -0,0 +1,301 @@
+# Superpowers for OpenClaw - 简化集成设计
+
+## 1. 目标
+
+在 OpenClaw 中集成 `obra/superpowers`，满足以下目标：
+
+- 尽可能使用上游 `superpowers` 的全部 skill 能力
+- 保持高集成度，避免插件 / skill / script 过度拆分
+- 易于管理，日常只维护一个主目录
+- 易于移植，迁移时可整体复制
+- 支持同步上游最新代码
+- 尽量符合 OpenClaw 的插件与工作流习惯
+
+---
+
+## 2. 非目标
+
+以下内容不作为第一阶段目标：
+
+- 不追求 100% 原样复刻上游宿主行为
+- 不修改 OpenClaw 核心加载逻辑
+- 不引入额外独立 skill 包或外部桥接层
+- 不依赖多个分散目录协同工作
+
+---
+
+## 3. 总体方案
+
+采用 **单插件一体化方案**，并固定为：
+
+**静态内嵌 vendor + 显式 update**。
+
+所有集成逻辑集中在一个目录中：
+
+```text
+workspace/plugins/superpowers/
+```
+
+这个插件目录内部负责：
+
+1. 内嵌保存一份上游 `obra/superpowers` 代码副本
+2. 扫描并索引上游 `skills/`
+3. 将上游 skills 适配为 OpenClaw 可用能力
+4. 提供统一的管理与调用入口
+
+外部不再拆分独立 `skills/`、`scripts/`、`vendor/` 顶层目录。
+
+---
+
+## 4. 目录结构
+
+建议结构如下：
+
+```text
+workspace/plugins/superpowers/
+  README.md
+  README.design.md
+  plugin.json
+  index.js
+  vendor/
+    superpowers/
+  cache/
+    index.json
+  docs/
+    compat.md
+```
+
+### 目录说明
+
+- `plugin.json`
+  - 插件元数据与配置入口
+- `index.js`
+  - 插件主逻辑
+- `vendor/superpowers/`
+  - 上游 `obra/superpowers` 的内嵌代码副本（不保留 `.git`）
+- `cache/index.json`
+  - 上游 skills 扫描结果与索引缓存
+- `docs/compat.md`
+  - 记录兼容差异与支持范围
+
+---
+
+## 5. 插件职责
+
+### 5.1 上游代码管理
+
+插件内部负责：
+
+- 首次安装时拉取 `https://github.com/obra/superpowers`
+- 后续更新时显式执行 `update`
+- 将最新代码覆盖到 `vendor/superpowers/`
+- 记录当前上游 commit hash
+- 提供状态查询，明确当前使用的内嵌版本
+
+### 5.2 skill 扫描与索引
+
+插件扫描：
+
+```text
+vendor/superpowers/skills/
+```
+
+读取每个 skill 的元信息，并生成统一索引，例如：
+
+```json
+{
+  "upstreamCommit": "abc123",
+  "skills": [
+    {
+      "name": "brainstorming",
+      "path": "vendor/superpowers/skills/brainstorming",
+      "description": "...",
+      "enabled": true
+    }
+  ]
+}
+```
+
+### 5.3 OpenClaw 适配
+
+插件负责把上游 skills 转换为 OpenClaw 可消费的能力，主要分两类：
+
+#### A. 纯 workflow / prompt 型 skill
+直接读取内容并用于任务指导。
+
+#### B. 依赖宿主执行机制的 skill
+映射到 OpenClaw 原生能力，例如：
+
+- planning → 普通任务规划
+- execution → 由当前会话或子会话执行
+- subagent workflows → 映射到 `sessions_spawn`
+- review workflows → 使用独立子会话做审查
+- parallel workflows → 使用多个子会话并行执行
+
+### 5.4 统一管理入口
+
+插件统一提供如下能力：
+
+- 安装上游代码
+- 更新上游代码
+- 查看状态
+- 列出 skills
+- 读取指定 skill
+- 刷新索引
+- 显式使用某个 skill
+- 在适当场景下推荐某个 skill
+
+---
+
+## 6. 设计原则
+
+### 原则 1：单目录自包含
+
+整个集成应尽量收敛在：
+
+```text
+workspace/plugins/superpowers/
+```
+
+方便备份、迁移和版本管理。
+
+### 原则 2：上游代码不魔改
+
+`vendor/superpowers/` 保持尽量接近上游，只作为内嵌副本与读取来源。
+
+兼容逻辑放在插件自身实现，不直接改写上游 skill 内容。
+
+### 原则 3：更新与运行分离
+
+- 更新上游代码时，显式执行 `update`
+- 日常运行只读取当前内嵌版本
+- 不在启动时自动联网检查或自动升级
+
+这样可以保持稳定、简单和可复现。
+
+### 原则 4：行为可观察
+
+用户应能明确看到：
+
+- 当前上游 commit
+- 当前已索引多少 skills
+- 哪些 skills 可用
+- 哪些是完全支持，哪些是兼容支持
+
+### 原则 5：尽量贴合 OpenClaw
+
+不修改 OpenClaw 核心。
+
+通过插件层完成：
+- 上游同步
+- skill 索引
+- 能力适配
+- 状态管理
+
+---
+
+## 7. 支持范围定义
+
+“完整支持”不等于机械复刻，而定义为：
+
+1. 所有上游 skills 都能被发现和列出
+2. 大多数 workflow / prompt 型 skills 可直接使用
+3. 依赖宿主流程的 skills 可映射到 OpenClaw 原生能力
+4. 少数无法等价映射的能力会在兼容文档中明确标注
+
+这比“复制文件即算支持”更符合实际可维护性。
+
+---
+
+## 8. 与参考桥接项目的关系
+
+可以参考 `vruru/superpowers-bridge` 的思路，主要包括：
+
+- 首次自动拉取上游代码
+- 本地缓存 skills
+- 提供更新机制
+
+但不直接照搬其结构。
+
+本方案的重点是：
+
+- 一体化
+- OpenClaw-first
+- 可观察
+- 易迁移
+
+---
+
+## 9. 推荐功能入口
+
+建议插件最终至少支持以下动作：
+
+- `install`
+- `update`
+- `status`
+- `list`
+- `refresh-index`
+- `use <skill>`
+- `recommend <task-context>`
+
+这些入口由插件统一实现，不再分散到多个外部组件。
+
+---
+
+## 10. 实施阶段
+
+### Phase 1：最小可用
+
+目标：
+
+- 插件目录初始化
+- clone 上游 `superpowers`
+- 扫描 `skills/`
+- 生成 `cache/index.json`
+- 能列出所有 skills
+- 能查看当前上游 commit
+
+### Phase 2：显式调用
+
+目标：
+
+- 支持 `use <skill>`
+- 能读取并应用纯 workflow 型 skills
+- 能在 OpenClaw 中显式使用 superpowers 技能
+
+### Phase 3：宿主适配
+
+目标：
+
+- 将 plan / execute / review / subagent / parallel 等能力映射到 OpenClaw
+- 增加兼容状态说明
+- 优化自动推荐与调度
+
+---
+
+## 11. 最终建议
+
+最终采用：
+
+**一个插件目录 + 一个上游镜像 + 一个索引缓存。**
+
+不再拆出额外顶层 script、skill bridge、vendor 根目录。
+
+这样更符合你的要求：
+
+- 集成度高
+- 管理简单
+- 迁移方便
+- 能持续跟上上游代码
+
+---
+
+## 12. 下一步
+
+下一步应直接开始 Phase 1：
+
+1. 创建 `workspace/plugins/superpowers/`
+2. 初始化插件骨架
+3. 设计 `plugin.json`
+4. 设计 `index.js` 的最小职责
+5. 实现上游 clone + status + list

package/README.md

@@ -0,0 +1,150 @@
+# openclaw-superpowers-plugin
+
+Superpowers skills adapter for OpenClaw.
+
+## What is this?
+
+This plugin brings [obra/superpowers](https://github.com/obra/superpowers) skills to OpenClaw. It provides:
+
+- Vendored skills from upstream superpowers repository
+- Skill recommendation based on task keywords
+- Manual skill loading by name
+- One-click install/update of upstream content
+
+## Installation
+
+### From local path
+```bash
+openclaw plugins install /path/to/openclaw-superpowers-plugin
+```
+
+### From GitHub (future)
+```bash
+openclaw plugins install openclaw-superpowers-plugin
+```
+
+### Enable the plugin
+Add to your `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": ["/path/to/openclaw-superpowers-plugin"]
+    },
+    "entries": {
+      "superpowers": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+Then restart the Gateway:
+```bash
+openclaw gateway restart
+```
+
+## Usage
+
+### Command
+```text
+/superpowers
+/superpowers overview
+/superpowers use <task description>
+/superpowers use name <skill-name>
+/superpowers install
+/superpowers update
+```
+
+### Tools
+- `superpowers_overview` — Show installation status and skill list
+- `superpowers_use` — Recommend a skill for a task or load a skill by name
+- `superpowers_install` — Install vendored superpowers repository
+- `superpowers_update` — Update vendored superpowers from upstream
+
+### Examples
+
+#### Get overview
+```text
+/superpowers overview
+```
+
+#### Recommend a skill for debugging
+```text
+/superpowers use 帮我系统排查一个难复现的 bug
+```
+
+#### Load a specific skill
+```text
+/superpowers use name systematic-debugging
+```
+
+#### Update upstream skills
+```text
+/superpowers update
+```
+
+## Configuration
+
+Optional config in `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "superpowers": {
+        "enabled": true,
+        "config": {
+          "upstreamRepo": "https://github.com/obra/superpowers.git",
+          "defaultBranch": "main"
+        }
+      }
+    }
+  }
+}
+```
+
+## Directory Structure
+
+```
+openclaw-superpowers-plugin/
+  package.json            # npm package manifest
+  openclaw.plugin.json    # OpenClaw plugin manifest
+  index.js                # Plugin entry point
+  lib/
+    vendor.js             # Vendor management (install/update)
+    recommend.js          # Keyword-based skill recommendation
+    adapter.js            # OpenClaw integration helpers
+  vendor/                 # Vendored superpowers (generated)
+  cache/                  # Skill index cache (generated)
+  README.md
+  LICENSE
+```
+
+## How it works
+
+1. **Install/Update**: Clones `obra/superpowers` into `vendor/superpowers`
+2. **Index**: Scans `vendor/superpowers/skills/` and builds a local index
+3. **Recommend**: Matches task keywords against skill rules
+4. **Load**: Reads skill content (SKILL.md or README.md)
+
+## Mapped Execution Modes
+
+The plugin maps superpowers skills to OpenClaw execution patterns:
+
+| Skill | Mode |
+|-------|------|
+| brainstorming | local-guidance |
+| writing-plans | local-guidance |
+| executing-plans | local-execution |
+| systematic-debugging | local-guidance |
+| test-driven-development | local-execution |
+| requesting-code-review | review |
+| subagent-driven-development | subagent |
+| dispatching-parallel-agents | parallel |
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,215 @@
+const path = require('path');
+const { createVendorApi } = require('./lib/vendor');
+const { createRecommendApi, RECOMMEND_RULES } = require('./lib/recommend');
+const { createAdapterApi } = require('./lib/adapter');
+
+const ROOT = __dirname;
+const CONFIG = require(path.join(ROOT, 'openclaw.plugin.json')).config;
+const VENDOR_DIR = path.join(ROOT, CONFIG.vendorDir);
+const CACHE_FILE = path.join(ROOT, CONFIG.cacheFile);
+const DEBUG_STATE_FILE = path.join(ROOT, CONFIG.debugStateFile);
+const SKILLS_DIR = path.join(VENDOR_DIR, 'skills');
+
+const vendorApi = createVendorApi({ ROOT, CONFIG, VENDOR_DIR, CACHE_FILE, SKILLS_DIR });
+const recommendApi = createRecommendApi({ ROOT, vendorApi });
+const adapterApi = createAdapterApi({ ROOT, CONFIG, DEBUG_STATE_FILE, recommendApi });
+
+function textResult(text, details = undefined) {
+  return {
+    content: [{ type: 'text', text }],
+    details
+  };
+}
+
+function buildOverview() {
+  const status = vendorApi.status();
+  const index = vendorApi.list();
+  const skills = index.skills || [];
+  const lines = [
+    `installed: ${status.installed ? 'yes' : 'no'}`,
+    `vendorDir: ${status.vendorDir}`,
+    `skillsDir: ${status.skillsDir}`,
+    `cacheFile: ${status.cacheFile}`,
+    `upstreamCommit: ${status.upstreamCommit || 'unknown'}`,
+    `indexedSkills: ${skills.length}`,
+    '',
+    'skills:'
+  ];
+
+  if (!skills.length) lines.push('- none');
+  else {
+    for (const skill of skills) {
+      lines.push(`- ${skill.name}${skill.description ? `: ${skill.description}` : ''}`);
+    }
+  }
+
+  return {
+    status,
+    index,
+    skills,
+    text: lines.join('\n')
+  };
+}
+
+function buildUseResult(params) {
+  if (params.name) {
+    const skillResult = recommendApi.useSkill(params.name);
+    if (!skillResult.ok) return {
+      ok: false,
+      mode: 'skill',
+      message: skillResult.message,
+      result: skillResult
+    };
+    return {
+      ok: true,
+      mode: 'skill',
+      skillName: params.name,
+      content: skillResult.content || skillResult.message,
+      result: skillResult
+    };
+  }
+
+  const runResult = adapterApi.run(params.task || '', { includeContent: true });
+  return {
+    ok: true,
+    mode: 'recommend',
+    task: params.task || '',
+    result: runResult,
+    content: runResult.content || null
+  };
+}
+
+function buildHelpText() {
+  return [
+    'Superpowers 菜单：',
+    '',
+    '/superpowers overview',
+    '/superpowers use <任务描述>',
+    '/superpowers use name <skill名>',
+    '/superpowers install',
+    '/superpowers update'
+  ].join('\n');
+}
+
+module.exports = {
+  id: 'superpowers',
+  name: 'superpowers',
+  description: 'Native OpenClaw adapter for obra/superpowers skills and recommendations.',
+  register(api) {
+    api.registerCommand({
+      name: 'superpowers',
+      description: 'Superpowers menu and actions.',
+      acceptsArgs: true,
+      handler: async (ctx) => {
+        const tokens = (ctx.args?.trim() ?? '').split(/\s+/).filter(Boolean);
+        const action = (tokens[0] || '').toLowerCase();
+        const rest = tokens.slice(1);
+
+        if (!action || action === 'help' || action === 'menu') {
+          return { text: buildHelpText() };
+        }
+
+        if (action === 'overview' || action === 'status' || action === 'list') {
+          const overview = buildOverview();
+          return { text: overview.text };
+        }
+
+        if (action === 'use') {
+          if (!rest.length) return { text: buildHelpText() };
+          if ((rest[0] || '').toLowerCase() === 'name') {
+            const skillName = rest.slice(1).join(' ').trim();
+            if (!skillName) return { text: '用法: /superpowers use name <skill名>' };
+            const result = buildUseResult({ name: skillName });
+            return { text: result.ok ? (result.content || 'Skill loaded.') : (result.message || 'Skill load failed.') };
+          }
+          const task = rest.join(' ').trim();
+          const result = buildUseResult({ task });
+          return { text: JSON.stringify(result.result, null, 2) };
+        }
+
+        if (action === 'install') {
+          const result = vendorApi.install();
+          return { text: JSON.stringify(result, null, 2) };
+        }
+
+        if (action === 'update') {
+          const result = vendorApi.update();
+          return { text: JSON.stringify(result, null, 2) };
+        }
+
+        return { text: buildHelpText() };
+      }
+    });
+
+    api.registerTool({
+      name: 'superpowers_overview',
+      label: 'Superpowers Overview',
+      description: 'Show superpowers installation status and the current indexed skill list.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false
+      },
+      async execute() {
+        const overview = buildOverview();
+        return textResult(overview.text, overview);
+      }
+    });
+
+    api.registerTool({
+      name: 'superpowers_use',
+      label: 'Superpowers Use',
+      description: 'Either recommend a superpowers skill for a task, or load a skill directly by name.',
+      parameters: {
+        type: 'object',
+        properties: {
+          task: { type: 'string', description: 'Task description to analyze and recommend against.' },
+          name: { type: 'string', description: 'Skill name to load directly, for example systematic-debugging.' }
+        },
+        additionalProperties: false,
+        anyOf: [
+          { required: ['task'] },
+          { required: ['name'] }
+        ]
+      },
+      async execute(_id, params) {
+        const result = buildUseResult(params);
+        if (!result.ok) return textResult(result.message || 'superpowers_use failed', { error: true, ...result });
+        if (result.mode === 'skill') return textResult(result.content || 'Skill loaded.', result);
+        return textResult(JSON.stringify(result.result, null, 2), result);
+      }
+    });
+
+    api.registerTool({
+      name: 'superpowers_install',
+      label: 'Superpowers Install',
+      description: 'Install the vendored superpowers repository for first-time setup.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false
+      },
+      async execute() {
+        const result = vendorApi.install();
+        return textResult(JSON.stringify(result, null, 2), result);
+      }
+    });
+
+    api.registerTool({
+      name: 'superpowers_update',
+      label: 'Superpowers Update',
+      description: 'Update the vendored superpowers repository from upstream.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false
+      },
+      async execute() {
+        const result = vendorApi.update();
+        return textResult(JSON.stringify(result, null, 2), result);
+      }
+    });
+
+    api.logger.info?.(`[superpowers] registered with ${RECOMMEND_RULES.length} recommendation rules`);
+  }
+};

package/lib/adapter.js

@@ -0,0 +1,256 @@
+const fs = require('fs');
+const path = require('path');
+
+function createAdapterApi({ ROOT, CONFIG, DEBUG_STATE_FILE, recommendApi }) {
+  function getDebugVisible() {
+    if (fs.existsSync(DEBUG_STATE_FILE)) {
+      try {
+        const state = JSON.parse(fs.readFileSync(DEBUG_STATE_FILE, 'utf8'));
+        if (typeof state.enabled === 'boolean') return state.enabled;
+      } catch {}
+    }
+    return Boolean(CONFIG.debugVisible);
+  }
+
+  function setDebugVisible(enabled) {
+    fs.mkdirSync(path.dirname(DEBUG_STATE_FILE), { recursive: true });
+    const payload = {
+      enabled: Boolean(enabled),
+      updatedAt: new Date().toISOString()
+    };
+    fs.writeFileSync(DEBUG_STATE_FILE, JSON.stringify(payload, null, 2));
+    return payload;
+  }
+
+  function getExecutionMode(skillName) {
+    const map = {
+      'brainstorming': 'local-guidance',
+      'writing-plans': 'local-guidance',
+      'executing-plans': 'local-execution',
+      'systematic-debugging': 'local-guidance',
+      'test-driven-development': 'local-execution',
+      'requesting-code-review': 'review',
+      'receiving-code-review': 'review',
+      'subagent-driven-development': 'subagent',
+      'dispatching-parallel-agents': 'parallel',
+      'using-git-worktrees': 'local-execution',
+      'finishing-a-development-branch': 'local-execution'
+    };
+    return map[skillName] || 'local-guidance';
+  }
+
+  function buildNextStep(skillName) {
+    const map = {
+      'brainstorming': '先阅读 skill 指导内容，再围绕目标列出方向、约束和备选方案。',
+      'writing-plans': '先根据 skill 输出分阶段计划，再决定是否进入执行。',
+      'executing-plans': '将已有计划拆成可执行步骤，逐项执行并验证。',
+      'systematic-debugging': '先收集现象和证据，再按 skill 要求定位根因，不直接修。',
+      'test-driven-development': '先定义测试，再写实现，最后验证通过。',
+      'requesting-code-review': '整理变更背景、风险点和重点审查项，再发起 review。',
+      'receiving-code-review': '先读取 review 反馈，再按优先级消化和修正。',
+      'subagent-driven-development': '将任务拆分后映射到 OpenClaw 子会话执行。',
+      'dispatching-parallel-agents': '识别可并行部分，再使用多个子会话分工执行。',
+      'using-git-worktrees': '确认仓库策略后，为并行分支任务使用 git worktree。',
+      'finishing-a-development-branch': '在合并前整理变更、验证状态并完成收尾。'
+    };
+    return map[skillName] || '读取 skill 内容后，按其流程在 OpenClaw 中执行。';
+  }
+
+  function buildOpenClawHint(skillName, executionMode) {
+    const hints = {
+      'local-guidance': '建议在当前会话中直接按 skill 流程推进。',
+      'local-execution': '建议在当前会话中执行，并结合 read/edit/exec 等工具逐步落实。',
+      'review': '建议使用独立会话或子会话做审查，避免和主执行混在一起。',
+      'subagent': '建议使用 sessions_spawn 创建子会话承接拆分任务。',
+      'parallel': '建议将任务拆成互相独立的部分，并使用多个子会话并行处理。'
+    };
+    return hints[executionMode] || `按 ${skillName} 的流程在 OpenClaw 中执行。`;
+  }
+
+  function buildSuggestedActions(skillName, executionMode) {
+    const actions = {
+      'local-guidance': [
+        '读取 skill 内容并提炼关键步骤',
+        '在当前会话中确认目标、约束和输入信息',
+        '按 skill 流程逐步推进'
+      ],
+      'local-execution': [
+        '读取 skill 内容并拆成执行步骤',
+        '在当前会话中直接执行',
+        '每步后进行验证和汇报'
+      ],
+      'review': [
+        '整理背景、变更范围和风险点',
+        '使用独立会话或子会话执行 review',
+        '汇总 review 结论并回到主会话处理'
+      ],
+      'subagent': [
+        '识别可拆分子任务',
+        '用 sessions_spawn 创建子会话',
+        '汇总子会话结果并统一收口'
+      ],
+      'parallel': [
+        '先拆分互相独立的任务块',
+        '为每个任务块创建独立子会话',
+        '并行执行后汇总结果并统一验证'
+      ]
+    };
+    return actions[executionMode] || [`按 ${skillName} 的流程在 OpenClaw 中执行`];
+  }
+
+  function buildExecutionPlan(skillName, executionMode) {
+    const plans = {
+      'local-guidance': [
+        { step: 1, action: 'read-skill', description: '读取并提炼 skill 的关键流程' },
+        { step: 2, action: 'clarify-context', description: '确认目标、约束、输入和预期产出' },
+        { step: 3, action: 'guide-in-session', description: '在当前会话中按流程推进' }
+      ],
+      'local-execution': [
+        { step: 1, action: 'read-skill', description: '读取 skill 并转成执行步骤' },
+        { step: 2, action: 'execute-in-session', description: '在当前会话中执行具体改动或命令' },
+        { step: 3, action: 'verify-result', description: '验证执行结果并汇报' }
+      ],
+      'review': [
+        { step: 1, action: 'prepare-review-context', description: '整理背景、范围、重点与风险' },
+        { step: 2, action: 'spawn-review-session', description: '创建独立 review 会话或子会话' },
+        { step: 3, action: 'merge-review-feedback', description: '汇总 review 结论并回到主流程处理' }
+      ],
+      'subagent': [
+        { step: 1, action: 'split-task', description: '将任务拆成清晰子任务' },
+        { step: 2, action: 'spawn-subagents', description: '用 sessions_spawn 创建子会话' },
+        { step: 3, action: 'collect-results', description: '汇总子会话结果并统一收口' }
+      ],
+      'parallel': [
+        { step: 1, action: 'split-independent-work', description: '拆分互相独立的任务块' },
+        { step: 2, action: 'spawn-parallel-subagents', description: '为每个任务块创建独立子会话' },
+        { step: 3, action: 'merge-and-verify', description: '汇总并验证所有并行结果' }
+      ]
+    };
+
+    return {
+      skillName,
+      executionMode,
+      plan: plans[executionMode] || [
+        { step: 1, action: 'read-skill', description: `按 ${skillName} 的流程在 OpenClaw 中执行` }
+      ]
+    };
+  }
+
+  function buildOpenClawActions(skillName, executionMode, taskText = '') {
+    const baseTask = String(taskText || '').trim();
+    const templates = {
+      'local-guidance': [
+        {
+          type: 'in-session-guidance',
+          purpose: 'guide-current-session',
+          messageTemplate: `在当前会话中按 ${skillName} 流程推进：${baseTask || '补充任务描述'}`
+        }
+      ],
+      'local-execution': [
+        {
+          type: 'in-session-execution',
+          purpose: 'execute-current-session',
+          messageTemplate: `在当前会话中执行任务，并按 ${skillName} 流程验证：${baseTask || '补充任务描述'}`
+        }
+      ],
+      'review': [
+        {
+          type: 'sessions_spawn',
+          purpose: 'review-session',
+          messageTemplate: `请基于 ${skillName} 对以下内容进行审查，并给出结构化结论：${baseTask || '补充审查对象和背景'}`
+        }
+      ],
+      'subagent': [
+        {
+          type: 'sessions_spawn',
+          purpose: 'subtask-worker',
+          messageTemplate: `请作为子会话承接拆分后的任务，并按 ${skillName} 流程执行：${baseTask || '补充子任务描述'}`
+        }
+      ],
+      'parallel': [
+        {
+          type: 'split-task',
+          purpose: 'identify-independent-work',
+          messageTemplate: `先把任务拆成可并行的独立部分：${baseTask || '补充任务描述'}`
+        },
+        {
+          type: 'sessions_spawn',
+          purpose: 'parallel-worker',
+          messageTemplate: `请作为并行子会话处理其中一个独立任务块，并回报结果：${baseTask || '补充任务描述'}`
+        },
+        {
+          type: 'merge-results',
+          purpose: 'collect-and-verify',
+          messageTemplate: '汇总所有并行子会话结果，并统一验证最终输出。'
+        }
+      ]
+    };
+
+    return templates[executionMode] || [
+      {
+        type: 'manual',
+        purpose: 'fallback',
+        messageTemplate: `按 ${skillName} 的流程在 OpenClaw 中手动执行。`
+      }
+    ];
+  }
+
+  function formatDebugTag(result) {
+    if (!result || !result.recommendation || !result.recommendation.matched) return null;
+    if (!getDebugVisible()) return null;
+    const skill = result.recommendation.matched;
+    const mode = result.executionMode || 'unknown';
+    const keywords = (result.recommendation.candidates?.[0]?.keywords || []).join(', ');
+    return keywords
+      ? `_⚡️[superpowers] ${skill} | ${mode} | ${keywords}_`
+      : `_⚡️[superpowers] ${skill} | ${mode}_`;
+  }
+
+  function run(taskText = '', options = {}) {
+    const recommendation = recommendApi.recommend(taskText);
+    if (!recommendation.matched) {
+      return {
+        ok: true,
+        taskText,
+        recommendation,
+        usedSkill: null,
+        suggestedActions: ['手动调用 list()', '手动指定 useSkill(name)', '补充更明确的任务描述'],
+        executionPlan: null,
+        openclawActions: [],
+        nextStep: '未匹配到明确 skill，建议手动 list 或指定 useSkill(name)。'
+      };
+    }
+
+    const used = recommendApi.useSkill(recommendation.matched);
+    const executionMode = getExecutionMode(recommendation.matched);
+
+    const result = {
+      ok: used.ok,
+      taskText,
+      recommendation,
+      usedSkill: used.skill || null,
+      executionMode,
+      openclawHint: buildOpenClawHint(recommendation.matched, executionMode),
+      suggestedActions: buildSuggestedActions(recommendation.matched, executionMode),
+      executionPlan: buildExecutionPlan(recommendation.matched, executionMode),
+      openclawActions: buildOpenClawActions(recommendation.matched, executionMode, taskText),
+      content: options.includeContent === false ? null : used.content,
+      nextStep: buildNextStep(recommendation.matched),
+      message: used.message
+    };
+    result.debugTag = formatDebugTag(result);
+    return result;
+  }
+
+  return {
+    getDebugVisible,
+    setDebugVisible,
+    getExecutionMode,
+    buildExecutionPlan,
+    buildOpenClawActions,
+    formatDebugTag,
+    run
+  };
+}
+
+module.exports = { createAdapterApi };

package/lib/recommend.js

@@ -0,0 +1,95 @@
+const RECOMMEND_RULES = [
+  { keywords: ['brainstorm', 'idea', '创意', '思路', '头脑风暴'], skill: 'brainstorming', score: 2 },
+  { keywords: ['plan', '规划', '方案', '拆解', '计划'], skill: 'writing-plans', score: 2 },
+  { keywords: ['execute', '执行', '落地', '实施', '开始做'], skill: 'executing-plans', score: 2 },
+  { keywords: ['debug', '排查', '故障', '问题定位', '根因'], skill: 'systematic-debugging', score: 3 },
+  { keywords: ['test', '测试', 'tdd', '先写测试'], skill: 'test-driven-development', score: 2 },
+  { keywords: ['review', '审查', '代码评审', '代码审查'], skill: 'requesting-code-review', score: 3 },
+  { keywords: ['subagent', '子代理', '子任务'], skill: 'subagent-driven-development', score: 3 },
+  { keywords: ['parallel', '并行', '并发'], skill: 'dispatching-parallel-agents', score: 4 },
+  { keywords: ['并行代理', '并行处理'], skill: 'dispatching-parallel-agents', score: 5 },
+  { keywords: ['worktree', '分支工作树'], skill: 'using-git-worktrees', score: 2 }
+];
+
+function createRecommendApi({ ROOT, vendorApi }) {
+  function getSkill(name) {
+    const index = vendorApi.list();
+    return index.skills.find((skill) => skill.name === name) || null;
+  }
+
+  function useSkill(name) {
+    const skill = getSkill(name);
+    if (!skill) {
+      return { ok: false, message: `skill not found: ${name}` };
+    }
+
+    const sourcePath = require('path').join(ROOT, skill.sourceFile || '');
+    const content = skill.sourceFile && vendorApi.exists(sourcePath)
+      ? require('fs').readFileSync(sourcePath, 'utf8')
+      : null;
+
+    return {
+      ok: true,
+      skill,
+      content,
+      message: content ? `loaded skill: ${name}` : `skill found, but no readable source file: ${name}`
+    };
+  }
+
+  function recommend(taskText = '') {
+    const text = String(taskText).toLowerCase();
+    const scores = new Map();
+
+    for (const rule of RECOMMEND_RULES) {
+      const matchedKeywords = rule.keywords.filter((kw) => text.includes(kw));
+      if (!matchedKeywords.length) continue;
+
+      const current = scores.get(rule.skill) || { score: 0, keywords: [] };
+      current.score += matchedKeywords.length * rule.score;
+      current.keywords.push(...matchedKeywords);
+      scores.set(rule.skill, current);
+    }
+
+    if (!scores.size) {
+      return {
+        ok: true,
+        matched: null,
+        reason: 'no keyword match',
+        skill: null,
+        candidates: []
+      };
+    }
+
+    const ranked = Array.from(scores.entries())
+      .map(([skillName, data]) => ({
+        skillName,
+        score: data.score,
+        keywords: Array.from(new Set(data.keywords)),
+        skill: getSkill(skillName)
+      }))
+      .sort((a, b) => b.score - a.score);
+
+    const top = ranked[0];
+
+    return {
+      ok: true,
+      matched: top.skillName,
+      reason: `matched keywords: ${top.keywords.join(', ')}`,
+      skill: top.skill,
+      candidates: ranked.map((item) => ({
+        skill: item.skillName,
+        score: item.score,
+        keywords: item.keywords
+      }))
+    };
+  }
+
+  return {
+    RECOMMEND_RULES,
+    getSkill,
+    useSkill,
+    recommend
+  };
+}
+
+module.exports = { createRecommendApi, RECOMMEND_RULES };

package/lib/vendor.js

@@ -0,0 +1,163 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+function createVendorApi({ ROOT, CONFIG, VENDOR_DIR, CACHE_FILE, SKILLS_DIR }) {
+  function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  function exists(p) {
+    return fs.existsSync(p);
+  }
+
+  function runCommand(command, cwd = ROOT) {
+    return execSync(command, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+  }
+
+  function safeRemove(target) {
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+
+  function copyDir(src, dest) {
+    safeRemove(dest);
+    ensureDir(path.dirname(dest));
+    fs.cpSync(src, dest, { recursive: true });
+  }
+
+  function loadIndex() {
+    if (!exists(CACHE_FILE)) return null;
+    return JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+  }
+
+  function getEmbeddedCommit() {
+    return loadIndex()?.upstreamCommit || null;
+  }
+
+  function withTempClone(callback) {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'superpowers-'));
+    const cloneDir = path.join(tempRoot, 'repo');
+    try {
+      runCommand(`git clone --depth 1 --branch ${CONFIG.defaultBranch} ${CONFIG.upstreamRepo} ${cloneDir}`);
+      const commit = runCommand('git rev-parse HEAD', cloneDir);
+      return callback({ tempRoot, cloneDir, commit });
+    } finally {
+      safeRemove(tempRoot);
+    }
+  }
+
+  function listSkillDirs() {
+    if (!exists(SKILLS_DIR)) return [];
+    return fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .sort();
+  }
+
+  function readSkillMeta(skillName) {
+    const skillDir = path.join(SKILLS_DIR, skillName);
+    const readme = path.join(skillDir, 'README.md');
+    const skill = path.join(skillDir, 'SKILL.md');
+    const sourceFile = exists(skill) ? skill : readme;
+    let description = '';
+
+    if (exists(sourceFile)) {
+      const firstLines = fs.readFileSync(sourceFile, 'utf8').split('\n').slice(0, 12);
+      description = firstLines.find((line) => line.trim() && !line.startsWith('#'))?.trim() || '';
+    }
+
+    return {
+      name: skillName,
+      path: path.relative(ROOT, skillDir),
+      sourceFile: exists(sourceFile) ? path.relative(ROOT, sourceFile) : null,
+      description,
+      enabled: true,
+      source: 'obra/superpowers'
+    };
+  }
+
+  function refreshIndex(upstreamCommit = null) {
+    ensureDir(path.dirname(CACHE_FILE));
+    const skills = listSkillDirs().map(readSkillMeta);
+    const payload = {
+      updatedAt: new Date().toISOString(),
+      upstreamCommit: upstreamCommit || getEmbeddedCommit(),
+      skills
+    };
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(payload, null, 2));
+    return payload;
+  }
+
+  function install() {
+    if (exists(VENDOR_DIR) && exists(SKILLS_DIR)) {
+      return {
+        ok: true,
+        message: 'superpowers vendor already installed',
+        vendorDir: VENDOR_DIR,
+        upstreamCommit: getEmbeddedCommit()
+      };
+    }
+
+    return withTempClone(({ cloneDir, commit }) => {
+      const gitDir = path.join(cloneDir, '.git');
+      if (exists(gitDir)) safeRemove(gitDir);
+      copyDir(cloneDir, VENDOR_DIR);
+      const index = refreshIndex(commit);
+      return {
+        ok: true,
+        message: 'superpowers vendor installed',
+        vendorDir: VENDOR_DIR,
+        upstreamCommit: commit,
+        indexedSkills: index.skills.length
+      };
+    });
+  }
+
+  function update() {
+    return withTempClone(({ cloneDir, commit }) => {
+      const gitDir = path.join(cloneDir, '.git');
+      if (exists(gitDir)) safeRemove(gitDir);
+      copyDir(cloneDir, VENDOR_DIR);
+      const index = refreshIndex(commit);
+      return {
+        ok: true,
+        message: 'superpowers vendor updated',
+        vendorDir: VENDOR_DIR,
+        upstreamCommit: commit,
+        indexedSkills: index.skills.length
+      };
+    });
+  }
+
+  function list() {
+    return loadIndex() || refreshIndex();
+  }
+
+  function status() {
+    return {
+      installed: exists(VENDOR_DIR) && exists(SKILLS_DIR),
+      vendorDir: VENDOR_DIR,
+      skillsDir: SKILLS_DIR,
+      cacheFile: CACHE_FILE,
+      upstreamCommit: getEmbeddedCommit(),
+      indexedSkills: (loadIndex()?.skills || []).length
+    };
+  }
+
+  return {
+    exists,
+    ensureDir,
+    loadIndex,
+    getEmbeddedCommit,
+    listSkillDirs,
+    readSkillMeta,
+    refreshIndex,
+    install,
+    update,
+    list,
+    status
+  };
+}
+
+module.exports = { createVendorApi };

package/openclaw.plugin.json

@@ -0,0 +1,29 @@
+{
+  "id": "superpowers",
+  "name": "superpowers",
+  "description": "Native OpenClaw adapter for obra/superpowers skills and recommendations.",
+  "skills": ["./vendor/superpowers/skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "upstreamRepo": {
+        "type": "string",
+        "description": "Upstream superpowers repository URL.",
+        "default": "https://github.com/obra/superpowers.git"
+      },
+      "defaultBranch": {
+        "type": "string",
+        "description": "Branch to clone from upstream.",
+        "default": "main"
+      }
+    }
+  },
+  "config": {
+    "upstreamRepo": "https://github.com/obra/superpowers.git",
+    "vendorDir": "vendor/superpowers",
+    "cacheFile": "cache/index.json",
+    "defaultBranch": "main",
+    "debugStateFile": "cache/debug.json"
+  }
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "openclaw-superpowers-plugin",
+  "version": "1.0.0",
+  "description": "Superpowers skills adapter for OpenClaw",
+  "main": "index.js",
+  "type": "commonjs",
+  "files": [
+    "index.js",
+    "lib/",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webleon/webleonclawdbot.git",
+    "directory": "packages/plugins/superpowers"
+  },
+  "author": "WebLeOn",
+  "license": "MIT",
+  "keywords": ["openclaw", "plugin", "superpowers", "skills"]
+}