kilo-superpowers-compose 0.1.0 → 0.1.2

package/README.md

@@ -1,150 +1,211 @@
 # kilo-superpowers-compose
 
-> 一个 Kilo Code / Kilo CLI 插件，将 [obra/superpowers](https://github.com/obra/superpowers)
-> 开发工作流打包为单个可安装的 npm 包，对外暴露一个 `compose` 编排器代理，驱动
-> 头脑风暴 → 规划 → 子代理实现 → 两阶段评审 → 合并的完整流程。
+[![npm version](https://img.shields.io/npm/v/kilo-superpowers-compose.svg)](https://www.npmjs.com/package/kilo-superpowers-compose)
+[![license](https://img.shields.io/npm/l/kilo-superpowers-compose.svg)](./LICENSE)
 
-## 状态
+> A Kilo Code / Kilo CLI plugin that packages the
+> [obra/superpowers](https://github.com/obra/superpowers) development workflow
+> into a single installable package, exposing a **`compose`** orchestrator agent
+> that drives brainstorming → planning → subagent implementation → two-stage
+> review → merge.
 
-**v0.1.0 —— 可用。** 已实现安装器、14 个内嵌技能、3 个代理、`/superpowers` 命令，
-并通过自动化测试与隔离环境往返验证。详见 [更新日志](#更新日志)。
+## Status
 
-## 这个项目做什么（一段话）
+**v0.1.2.** Installed via the npm CLI and verified on both **Kilo CLI** and the
+**VS Code Kilo Code** extension (they share the same config, so one install
+covers both).
 
-它把 14 个久经考验的 Superpowers 技能 + 3 个专门构建的代理打包成一个名为
-`kilo-superpowers-compose` 的 npm 包。运行一条安装命令后，本包会把技能链接到
-`~/.kilo/skills/`，把代理的 `.md` 文件复制到 `~/.config/kilo/agent/`，把
-`/superpowers` 命令复制到 `~/.config/kilo/commands/`，并在 `kilo.jsonc` 中注册技能
-路径。重启 Kilo CLI 或 VS Code 扩展后，用户即可在代理选择器中看到一个 `compose`
-代理，对任意编码任务运行完整的、有纪律的 Superpowers 工作流。
+> **About the `plugin` field:** Kilo's `plugin: ["…"]` field in `kilo.jsonc`
+> does **not** load npm-named plugins in current Kilo — adding it only slows
+> startup. This package ships a plugin module (`plugin/index.js`) for the
+> future, but **do not add it to the `plugin` field**. Use the npm CLI install
+> below. See [docs/DESIGN.md §10 Q5](docs/DESIGN.md#10-open-questions--decisions-pending).
 
-## 安装
+## What it is
 
-### 方式 A：npm + 显式安装（推荐，已验证）
+`kilo-superpowers-compose` bundles 14 battle-tested Superpowers skills + 3
+purpose-built agents + a `/superpowers` slash command into one npm package.
+Run one install command and the skills link into `~/.kilo/skills/`, the agent
+files copy into `~/.config/kilo/agent/`, the command into
+`~/.config/kilo/commands/`, and `kilo.jsonc` gets the skill path registered.
+Restart Kilo and a `compose` agent appears in the agent picker, ready to run
+the full, disciplined Superpowers workflow on any coding task.
+
+## Installation
+
+> ⚠ **Two steps required.** Running only step ① (`npm install -g`) does
+> nothing visible — it only installs the CLI binary, not the agent/command
+> files, the skills link, or `kilo.jsonc`. Skipping step ② is the most
+> common mistake.
+
+**Step ① — Install the CLI**:
 
 ```bash
 npm install -g kilo-superpowers-compose
+```
+
+Only installs the CLI binary (the `kilo-superpowers-compose` command
+itself); does not touch your config directory.
+
+**Step ② — Install into Kilo**:
+
+```bash
 kilo-superpowers-compose install
 ```
 
-安装完成后重启 Kilo，即可在代理选择器（`/agents`）中看到 `compose`，并使用
-`/superpowers` 斜杠命令。
+Copies the 3 agent files to `~/.config/kilo/agent/`, the command to
+`~/.config/kilo/commands/`, creates the skills link at
+`~/.kilo/skills/superpowers`, and adds an entry to `kilo.jsonc`'s
+`skills.paths`. **Idempotent**: safe to re-run.
 
-### 方式 B：Kilo `plugin` 字段（实验性 / 暂缓）
+**Step ③ — Restart Kilo** (fully quit and reopen the CLI; **Reload Window**
+in VS Code).
 
-理论上可在 `kilo.jsonc` 中加入 `"plugin": ["kilo-superpowers-compose"]` 让 Kilo 在
-启动时加载本包。但 Kilo 的插件钩子接口尚未稳定文档化，且该机制只能注册技能、无法
-放置代理 / 命令文件，因此 **v0.1 暂不支持**。请使用方式 A。详见
-[docs/DESIGN.md §10 Q5](docs/DESIGN.md)。
+After this, `compose` appears in `/agents` and `/superpowers` works. One
+install covers both Kilo CLI and the VS Code Kilo Code extension (they
+share `~/.config/kilo/`).
 
-> 提示：Kilo 官方的分发渠道是 **Marketplace**（把代理复制到 `~/.config/kilo/agents/`、
-> 技能复制到 `~/.config/kilo/skills/`）。后续版本会提交到 [kilo-marketplace](https://github.com/Kilo-Org/kilo-marketplace)。
+### Kilo Marketplace (official channel — coming soon)
 
-## 安装了什么
+The Marketplace lets you install from the Kilo sidebar with no terminal. We're
+preparing a contribution to
+[`Kilo-Org/kilo-marketplace`](https://github.com/Kilo-Org/kilo-marketplace).
+Until then, use the npm install above.
 
-- `superpowers` 技能目录下的 **14 个技能**（来自 obra/superpowers `v6.1.1`，逐字内嵌）：
-  `using-superpowers`、`brainstorming`、`test-driven-development`、`systematic-debugging`、
-  `verification-before-completion`、`writing-plans`、`executing-plans`、
-  `subagent-driven-development`、`requesting-code-review`、`receiving-code-review`、
-  `using-git-worktrees`、`finishing-a-development-branch`、`dispatching-parallel-agents`、
-  `writing-skills`。
-- **3 个代理**：`compose`（主代理 / 编排器）、`compose-dev`（子代理 / 实现者）、
-  `compose-review`（子代理 / 评审者）。三者均**不锁定 `model`**，沿用你的全局默认模型。
-- **1 个斜杠命令**：`/superpowers`（路由到 `compose`）。
+## What gets installed
 
-## 更新与卸载
+- **14 skills** under the `superpowers` namespace, vendored verbatim from
+  obra/superpowers `v6.1.1` (MIT): `using-superpowers`, `brainstorming`,
+  `test-driven-development`, `systematic-debugging`,
+  `verification-before-completion`, `writing-plans`, `executing-plans`,
+  `subagent-driven-development`, `requesting-code-review`,
+  `receiving-code-review`, `using-git-worktrees`,
+  `finishing-a-development-branch`, `dispatching-parallel-agents`,
+  `writing-skills`.
+- **3 agents**: `compose` (primary orchestrator), `compose-dev` (TDD
+  implementer subagent), `compose-review` (two-stage reviewer subagent). None
+  pin a `model` — they use your global default model.
+- **1 slash command**: `/superpowers` (routes to `compose`).
 
-```bash
-# 更新（重新运行安装，幂等）
-kilo-superpowers-compose update
+## Update & uninstall
+
+> **Update is also two steps.** `npm update -g` upgrades the package
+> itself; the `update` subcommand re-syncs the artifacts to Kilo's config.
+> Running only step ① won't update your agents/commands/skills link.
 
-# 卸载（清单法精确移除本包安装的全部内容，绝不触碰用户自有文件）
-kilo-superpowers-compose uninstall
+**Update** (two steps, after a new version is published):
+
+```bash
+npm update -g kilo-superpowers-compose   # ① upgrade the package
+kilo-superpowers-compose update         # ② re-sync artifacts to Kilo (idempotent)
 ```
 
-更新上游包后，建议：
+You can also just re-run `kilo-superpowers-compose update` (without
+`npm update`) — it refreshes artifacts using the current global package
+version, but won't pull a newer version.
+
+**Uninstall** (removes everything this package installed, manifest-based;
+never touches your own files):
 
 ```bash
-npm update -g kilo-superpowers-compose
-kilo-superpowers-compose update
+kilo-superpowers-compose uninstall       # remove artifacts
+npm uninstall -g kilo-superpowers-compose  # remove the CLI itself
 ```
 
-卸载会移除：技能链接、3 个代理文件、`superpowers.md` 命令、`kilo.jsonc` 中本包的
-`skills.paths` 条目，以及安装清单。你的其他技能 / 代理 / 配置保持原样。
+Uninstall removes: the skills link, the 3 agent files, the
+`superpowers.md` command, this package's `skills.paths` entry in
+`kilo.jsonc`, and the install manifest. Your own skills, agents, and config
+are left untouched.
+
+## Common mistakes
+
+**"I ran `npm install -g` but `/agents` doesn't show `compose`."**
+— You only ran step ①. The CLI is installed, but no agent files, skills
+link, or command were created. Run `kilo-superpowers-compose install`.
 
-## 命令行用法
+**"I changed package code after install; restarting Kilo doesn't pick it up."**
+— `~/.kilo/skills/superpowers` is a junction pointing to the package
+directory, so package upgrades are picked up automatically. But
+agent/command files were copied at install time and don't auto-update. Run
+`kilo-superpowers-compose update`.
+
+**"I added `plugin: ['kilo-superpowers-compose']` to `kilo.jsonc`."**
+— Remove it. Current Kilo doesn't load this field; it only slows startup.
+This package installs via the npm CLI — no `plugin` field needed.
+
+## CLI usage
 
 ```text
 kilo-superpowers-compose <command>
 
-命令：
-  install     安装技能、代理与斜杠命令（默认）
-  uninstall   移除本包安装的全部内容（清单法）
-  update      重新运行安装（幂等）
+Commands:
+  install     Install skills, agents, and the slash command (default)
+  uninstall   Remove everything this package installed (manifest-based)
+  update      Re-run install (idempotent)
 
-选项：
-  -v, --version    显示版本号
-  -h, --help       显示帮助
+Options:
+  -v, --version    Show version
+  -h, --help       Show help
 ```
 
-### 环境变量
+### Environment variables
 
-| 变量 | 作用 |
+| Variable | Purpose |
 |---|---|
-| `KILO_HOME=<path>` | 覆盖用户主目录（多用于测试 / 多配置隔离） |
-| `KILO_SUPERPOWERS_PREFIX=1` | （保留）为技能名加前缀；v0.1 以 `superpowers` 命名空间隔离，故暂未启用 |
-| `KILO_SUPERPOWERS_DRY_RUN=1` | 只打印将执行的动作，不修改任何文件 |
-| `KILO_SUPERPOWERS_VERBOSE=1` | 输出详细日志（到 stderr） |
+| `KILO_HOME=<path>` | Override user home (for testing / isolated configs) |
+| `KILO_SUPERPOWERS_PREFIX=1` | (reserved) prefix skill names; v0.1 isolates via the `superpowers` namespace instead |
+| `KILO_SUPERPOWERS_DRY_RUN=1` | Print intended actions without modifying anything |
+| `KILO_SUPERPOWERS_VERBOSE=1` | Verbose logging (to stderr) |
 
-### 退出码
+### Exit codes
 
-`0` 成功 · `1` 一般错误 · `2` `kilo.jsonc` 解析失败（已从备份恢复） · `3` 目标目录不可写 · `4` 技能链接创建失败。
+`0` success · `1` generic error · `2` `kilo.jsonc` parse error (restored from
+backup) · `3` target dir not writable · `4` skills link creation failed.
 
-> **关于 `kilo.jsonc` 注释**：安装器只剥离 `//` 行注释；**块注释 `/* */` 不被处理**。
-> 若你的 `kilo.jsonc` 含块注释导致解析失败，安装器会从自动备份恢复并以退出码 `2` 退出。
-> 写回时会丢失注释（已知取舍）。
+> **`kilo.jsonc` comments**: the installer strips only `//` line comments;
+> **block comments `/* */` are not handled**. If your `kilo.jsonc` has block
+> comments and fails to parse, the installer restores from the auto-backup and
+> exits with code `2`. Writing back loses comments (accepted trade-off).
 
-## 注意事项
+## Notes
 
-- **同名代理覆盖**：若你已有一个名为 `compose` 的代理，安装会覆盖它（v0.1 接受此取舍）。
-- **技能命名空间**：14 个技能位于 `superpowers/` 命名空间下，不会与你已有的
-  `~/.kilo/skills/<name>` 技能冲突；仅当你也存在 `superpowers` 目录时才需留意。
-- **Windows 链接**：技能目录用 junction 链接（无需管理员权限）；极少数失败会自动
-  回退为递归复制。
-- **不自动 `postinstall`**：安装是显式的，避免在你不知情时修改 `kilo.jsonc`。
+- **Same-name agent**: if you already have an agent named `compose`, installing
+  overwrites it (accepted for v0.1).
+- **Skill namespace**: the 14 skills live under `superpowers/`, so they won't
+  collide with your own `~/.kilo/skills/<name>` skills — only an existing
+  `superpowers` directory would conflict.
+- **Windows links**: skills are linked via a directory junction (no admin
+  rights needed); on rare failure it falls back to a recursive copy.
+- **No auto-`postinstall`**: install is explicit, so your `kilo.jsonc` is never
+  modified without you running the command.
 
-## 开发与测试
+## Development & testing
 
 ```bash
-node --test     # 零依赖自动化测试（安装器纯逻辑 + install/uninstall 往返）
-npm pack        # 检视发布包内容
+node --test     # zero-dependency tests (installer logic + plugin module + install/uninstall round-trip)
+npm pack        # inspect the published tarball
 ```
 
-## 文档
-
-- [docs/DESIGN.md](docs/DESIGN.md) —— 架构、命名、包布局、设计决策、风险
-- [docs/INSTALLER.md](docs/INSTALLER.md) —— `bin/` 安装器规格与源码
-- [docs/AGENTS.md](docs/AGENTS.md) —— 三个代理的规格（frontmatter + 系统提示词）
-- [docs/REFERENCES.md](docs/REFERENCES.md) —— 所有参考链接（上游项目、Kilo 文档等）
-- [NOTICE](NOTICE) —— 上游 obra/superpowers 归属（tag `v6.1.1`，MIT）
-
-## 灵感来源
-
-本项目移植 / 改编自
-[moyu-by/opencode-mimo-compose](https://github.com/moyu-by/opencode-mimo-compose)，
-后者为 OpenCode 做了同样的事。我们：
+## Documentation
 
-1. 将其重新打包以面向 Kilo（Kilo 是 OpenCode 的一个 fork —— 高度重合）。
-2. 底层技能来源换成 [obra/superpowers](https://github.com/obra/superpowers)（MIT）。
-3. 将编排器设计收紧为纯路由角色（不在内联写代码），并配以严格的两阶段评审子代理。
+- [docs/DESIGN.md](docs/DESIGN.md) — architecture, naming, layout, decisions, risks
+- [docs/INSTALLER.md](docs/INSTALLER.md) — `bin/` installer spec and source
+- [docs/AGENTS.md](docs/AGENTS.md) — the three agents (frontmatter + prompts)
+- [docs/REFERENCES.md](docs/REFERENCES.md) — all reference links
+- [NOTICE](NOTICE) — upstream obra/superpowers attribution (tag `v6.1.1`, MIT)
 
-## 许可证
+## Inspiration
 
-MIT（见 [LICENSE](LICENSE)）。内嵌的 14 个技能来自 obra/superpowers（MIT，
-© Jesse Vincent），逐字保留；归属见 [NOTICE](NOTICE)。
+This project ports/adapts
+[moyu-by/opencode-mimo-compose](https://github.com/moyu-by/opencode-mimo-compose)
+(which did the same for OpenCode). We: re-target it at Kilo (a Kilo is an
+OpenCode fork — high overlap); swap the skill source to
+[obra/superpowers](https://github.com/obra/superpowers) (MIT); and tighten the
+orchestrator into a pure-routing role (it never writes code itself) with a
+strict two-stage review subagent.
 
-## 更新日志
+## License
 
-- **v0.1.0** —— 首个可用版本。14 技能（锁 obra/superpowers `v6.1.1`）、3 代理、
-  `/superpowers` 命令、零依赖 ESM 安装器（清单法卸载、幂等、跨平台 junction）。
-  Path A 为受支持路径；Path B（`plugin` 字段）暂缓为实验性。
+MIT — see [LICENSE](LICENSE). The 14 vendored skills are from
+obra/superpowers (MIT, © Jesse Vincent), kept verbatim; attribution in
+[NOTICE](NOTICE).

package/agents/compose-dev.md

@@ -1,8 +1,5 @@
 ---
-description: |
-  Implementation subagent for the compose workflow. Loads TDD,
-  systematic debugging, and verification-before-completion skills.
-  Receives a single discrete task; executes it; reports back.
+description: "Implementation subagent for the compose workflow. Executes a single discrete task via TDD, systematic debugging, and verification."
 mode: subagent
 ---
 

package/agents/compose-review.md

@@ -1,8 +1,5 @@
 ---
-description: |
-  Two-stage code review subagent for the compose workflow.
-  Stage 1: spec compliance. Stage 2: code quality.
-  Reports findings by severity (critical / important / nit).
+description: "Two-stage code review subagent (spec compliance + code quality) for the compose workflow. Reports findings only; never edits code."
 mode: subagent
 ---
 

package/bin/lib.js

@@ -368,6 +368,8 @@ export function runInstall(opts = {}) {
   console.log(`  kilo.jsonc: skills.paths ${added ? '已新增条目' : '已存在（幂等跳过）'}`);
   console.log('');
   console.log('  请重启 Kilo CLI / VS Code 扩展以加载。');
+  console.log('');
+  console.log('  💡 To upgrade later: npm update -g kilo-superpowers-compose && kilo-superpowers-compose update');
   return EXIT.OK;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kilo-superpowers-compose",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "将 obra/superpowers 工作流打包为 Kilo 插件：一个 compose 编排器代理、/superpowers 斜杠命令与 14 个技能，一条命令安装。",
   "keywords": [
     "kilo",
@@ -29,14 +29,25 @@
   "engines": {
     "node": ">=18"
   },
+  "main": "plugin/index.js",
+  "exports": {
+    ".": "./plugin/index.js"
+  },
   "bin": {
     "kilo-superpowers-compose": "bin/cli.js"
   },
+  "kilo": {
+    "type": "plugin"
+  },
+  "opencode": {
+    "type": "plugin"
+  },
   "files": [
     "bin",
     "skills",
     "agents",
     "commands",
+    "plugin",
     "NOTICE"
   ],
   "scripts": {

package/plugin/index.js

@@ -0,0 +1,246 @@
+// plugin/index.js
+// kilo-superpowers-compose — Kilo 插件模块（Path B）。
+//
+// 这是 Path A（npm CLI 安装器，见 bin/）之外的另一条安装路径：
+// 在 kilo.jsonc 里写 `"plugin": ["kilo-superpowers-compose"]`，Kilo 启动时
+// 会加载本模块的默认导出（工厂函数），调用其 `config(config)` 钩子，向**运行时**
+// 配置对象直接注入 3 个 agent 与 skills.paths —— agent 从不落盘，仅存活于运行时。
+//
+// 设计参考：moyu-by/opencode-mimo-compose 的 src/index.js（OpenCode 插件机制）。
+// Kilo 是 OpenCode 的 fork，复用同样的 `config` 钩子契约。
+//
+// 硬性约束（与 bin/lib.js 一致）：
+// - 零第三方依赖；仅用 node:fs / node:path / node:os / node:url。
+// - 绝不抛异常：**插件崩溃会让 Kilo 启动失败**。所有 fs / 解析操作均包 try/catch。
+// - 跨平台路径一律用 path.join，绝不手拼反斜杠；尊重 KILO_HOME。
+// - skills.paths 幂等判定用规范化路径比较（path.resolve + toLowerCase）。
+//
+// 自动更新原理：
+// - agents：每次 Kilo 启动由 config 钩子重注（永远取包内最新内容）。
+// - skills：config.skills.paths 指向**包内** skills 目录，`npm update -g` 后即时刷新。
+// - /superpowers 命令：无法经 config 钩子注册（Kilo 无对应钩子），故采用
+//   "复制到 ~/.config/kilo/commands/ + 版本标记" 的方式；包升级时标记比对触发重同步。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+// ─── 路径常量 ──────────────────────────────────────────────────────────
+// 本文件即 plugin/index.js；其上一级为包根。
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+const AGENTS_SRC = path.join(PKG_ROOT, 'agents');
+const SKILLS_SRC = path.join(PKG_ROOT, 'skills');
+const COMMANDS_SRC = path.join(PKG_ROOT, 'commands');
+
+// Kilo 配置目录（尊重 KILO_HOME，便于测试与隔离配置）。
+// 惰性求值 —— 读取在调用时进行（而非模块加载时），使测试可用临时 KILO_HOME 隔离，
+// 不触碰用户真实配置目录。
+function defaultConfigDir() {
+  const home = (process.env.KILO_HOME || os.homedir()) + '';
+  return path.join(home, '.config', 'kilo');
+}
+function defaultMarkerFile() {
+  return path.join(defaultConfigDir(), '.kilo-superpowers-compose-plugin');
+}
+function defaultCommandsDstDir() {
+  return path.join(defaultConfigDir(), 'commands');
+}
+
+// 包版本（仅用于版本标记比对；读失败回退为占位串）。
+const PKG_VERSION = readPkgVersion(PKG_ROOT);
+
+function readPkgVersion(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version || '0.0.0';
+  } catch (_) {
+    return '0.0.0';
+  }
+}
+
+// ─── 纯函数 / 路径规范化 ───────────────────────────────────────────────
+// 与 bin/lib.js 的 normalizePath 行为一致，便于 skills.paths 去重判定。
+export function normalizePath(p) {
+  try {
+    return path.resolve(p).toLowerCase();
+  } catch (_) {
+    return String(p || '').toLowerCase();
+  }
+}
+
+// skills.paths 是否已包含目标（规范化比较，跨分隔符 / 大小写）。
+export function skillsPathsContains(paths, target) {
+  const t = normalizePath(target);
+  return Array.isArray(paths) && paths.some((p) => normalizePath(p) === t);
+}
+
+// 去除字符串两端的成对引号。
+function stripQuotes(v) {
+  if (v.length >= 2) {
+    const a = v[0];
+    const b = v[v.length - 1];
+    if ((a === '"' && b === '"') || (a === "'" && b === "'")) {
+      return v.slice(1, -1);
+    }
+  }
+  return v;
+}
+
+// ─── Frontmatter 解析 ──────────────────────────────────────────────────
+// 既支持单行 `key: value`（我们的 3 个 agent description 现均为单行），
+// 也防御性地支持 YAML 块标量（`|` 字面量 / `>` 折叠）以防有人改回多行。
+// 不引入第三方 YAML 解析器 —— 只覆盖我们用到的子集。
+export function parseFrontmatter(content) {
+  const m = typeof content === 'string'
+    ? content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+    : null;
+  if (!m) return { data: {}, body: typeof content === 'string' ? content : '' };
+  const lines = m[1].split(/\r?\n/);
+  const data = {};
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const kv = line.match(/^([\w-]+)[ \t]*:[ \t]*(.*)$/);
+    if (!kv) {
+      i++;
+      continue;
+    }
+    const key = kv[1];
+    let val = kv[2];
+    // 块标量：|（字面量，保留换行）或 >（折叠为空格）。
+    if (/^[|>][+-]?$/.test(val)) {
+      const folded = val.startsWith('>');
+      const collected = [];
+      i++;
+      while (i < lines.length && (lines[i] === '' || /^[ \t]/.test(lines[i]))) {
+        collected.push(lines[i].replace(/^[ \t]+/, ''));
+        i++;
+      }
+      val = (folded ? collected.join(' ') : collected.join('\n')).trim();
+      data[key] = val;
+      continue;
+    }
+    const tv = val.trim();
+    if (tv === 'true') data[key] = true;
+    else if (tv === 'false') data[key] = false;
+    else data[key] = stripQuotes(tv);
+    i++;
+  }
+  return { data, body: m[2] };
+}
+
+// ─── Agent 加载 ────────────────────────────────────────────────────────
+// 读取包内 agents/*.md，剥离 frontmatter 取 description / mode 与正文 prompt。
+export function loadAgents(agentsSrc) {
+  const dir = agentsSrc || AGENTS_SRC;
+  const agents = {};
+  try {
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(path.join(dir, file), 'utf8');
+        const { data, body } = parseFrontmatter(content);
+        const name = file.replace(/\.md$/, '');
+        agents[name] = {
+          description: data.description || name,
+          // primary 保持 primary；其余一律按 subagent 处理（防御性默认）。
+          mode: data.mode === 'primary' ? 'primary' : 'subagent',
+          prompt: body,
+        };
+      } catch (_) {
+        // 单个 agent 解析失败不阻断其余 agent。
+      }
+    }
+  } catch (_) {
+    // agents 目录不存在 / 不可读 → 返回空集（不抛）。
+  }
+  return agents;
+}
+
+// ─── 版本标记：同步复制的命令 ──────────────────────────────────────────
+// agents / skills 每次启动自动重注 / 自动刷新；只有复制的 /superpowers 命令
+// 需要版本标记触发重同步。
+export function needsSetup(markerFile) {
+  const f = markerFile || defaultMarkerFile();
+  try {
+    if (!fs.existsSync(f)) return true;
+    return fs.readFileSync(f, 'utf8').trim() !== PKG_VERSION;
+  } catch (_) {
+    return true;
+  }
+}
+
+// 执行命令同步：把 commands/superpowers.md 复制到 ~/.config/kilo/commands/，并写标记。
+export function runSetup(opts = {}) {
+  const commandsDst = opts.commandsDstDir || defaultCommandsDstDir();
+  const mf = opts.markerFile || defaultMarkerFile();
+  try {
+    const srcCmd = path.join(opts.commandsSrc || COMMANDS_SRC, 'superpowers.md');
+    if (fs.existsSync(srcCmd)) {
+      try {
+        fs.mkdirSync(commandsDst, { recursive: true });
+        fs.copyFileSync(srcCmd, path.join(commandsDst, 'superpowers.md'));
+      } catch (_) {
+        // 命令复制失败不应阻断 agent / skills 注入 —— 仅记录为无命令。
+      }
+    }
+    try {
+      fs.mkdirSync(path.dirname(mf), { recursive: true });
+      fs.writeFileSync(mf, PKG_VERSION, 'utf8');
+    } catch (_) {
+      // 标记写失败：下次启动会重试，无致命影响。
+    }
+  } catch (_) {
+    // 整体防御：runSetup 任何异常都不外泄。
+  }
+}
+
+// ─── 插件工厂（Kilo 加载入口，当前休眠）──────────────────────────────
+// 设计目标：Kilo 按 PluginModule 契约（{ server: Plugin }，见 @kilocode/plugin）
+// import 本模块、调用 server() 工厂、再调用返回的 config() 钩子，向运行时配置
+// 注入 agents/skills/command。
+//
+// 实测结论（2026-07，见 docs/DESIGN.md §10 Q5）：当前 Kilo **不会**经
+// `kilo.jsonc` 的 `plugin:["包名"]` 字段加载 npm 命名插件（该字段无效，还会拖慢
+// 启动）。本模块的 config() 钩子契约本身正确（经 glob 加载器实测可注入 agent），
+// 但作为用户安装方式暂不启用 —— 安装走 npm CLI（见 bin/）。本模块保留待 Kilo
+// 正式支持插件加载后即可启用。命名兼容：同时以 server 命名导出（与 mimo 一致）。
+export async function plugin(_input, _options) {
+  // 首次安装或包升级时同步命令（失败被 runSetup 内部吞掉）。
+  try {
+    if (needsSetup()) runSetup();
+  } catch (_) {}
+
+  const agents = loadAgents();
+
+  return {
+    // config 钩子：**副作用式**改写传入的 Kilo 配置对象（不返回新对象）。
+    config: async (kiloConfig) => {
+      try {
+        if (!kiloConfig || typeof kiloConfig !== 'object') return;
+        // 1. 注册 agents：config.agent[name] = { prompt, description, mode }。
+        if (!kiloConfig.agent) kiloConfig.agent = {};
+        for (const [name, agent] of Object.entries(agents)) {
+          kiloConfig.agent[name] = {
+            prompt: agent.prompt,
+            description: agent.description,
+            mode: agent.mode,
+          };
+        }
+        // 2. 注册 skills：config.skills.paths 追加包内 skills 目录（规范化去重）。
+        if (!kiloConfig.skills) kiloConfig.skills = {};
+        if (!Array.isArray(kiloConfig.skills.paths)) kiloConfig.skills.paths = [];
+        if (fs.existsSync(SKILLS_SRC) && !skillsPathsContains(kiloConfig.skills.paths, SKILLS_SRC)) {
+          kiloConfig.skills.paths.push(SKILLS_SRC);
+        }
+      } catch (_) {
+        // config 钩子内任何异常都不外泄，避免拖垮 Kilo 启动。
+      }
+    },
+  };
+}
+
+export { plugin as server };
+export default plugin;