kilo-superpowers-compose 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChengZiiii
+
+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/NOTICE

@@ -0,0 +1,49 @@
+NOTICE
+=======
+
+kilo-superpowers-compose
+------------------------
+
+This package (`kilo-superpowers-compose`) is licensed under the MIT License
+(see `LICENSE`). Copyright (c) 2026 ChengZiiii.
+
+The `skills/` directory of this package is a **verbatim, unmodified copy**
+of the `skills/` directory from the upstream project:
+
+    obra/superpowers
+    Source : https://github.com/obra/superpowers
+    Tag    : v6.1.1
+    Commit : d884ae04edebef577e82ff7c4e143debd0bbec99
+    License: MIT (Copyright (c) 2025 Jesse Vincent)
+
+Only the `skills/` directory is vendored. No other upstream content
+(`hooks/`, `scripts/`, `.opencode/`, `.claude-plugin/`, `.codex-plugin/`,
+`.cursor-plugin/`, `.kimi-plugin/`, `.pi/`, `tests/`, `docs/`, `assets/`,
+etc.) is included.
+
+The 14 vendored skills (each a `<name>/SKILL.md` plus any sibling files
+such as reference notes, example prompts, or helper scripts) are copied
+unchanged so that the upstream MIT attribution and authorship are
+preserved:
+
+  - 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
+
+To upgrade the vendored skills: re-copy `skills/` from a newer tag of
+obra/superpowers, then update the tag/commit above in this file.
+
+The three agent prompts in `agents/` and the `/superpowers` command in
+`commands/` are original to this package and are MIT-licensed as part of
+it. The installer in `bin/` is likewise original to this package.

package/README.md

@@ -0,0 +1,150 @@
+# kilo-superpowers-compose
+
+> 一个 Kilo Code / Kilo CLI 插件，将 [obra/superpowers](https://github.com/obra/superpowers)
+> 开发工作流打包为单个可安装的 npm 包，对外暴露一个 `compose` 编排器代理，驱动
+> 头脑风暴 → 规划 → 子代理实现 → 两阶段评审 → 合并的完整流程。
+
+## 状态
+
+**v0.1.0 —— 可用。** 已实现安装器、14 个内嵌技能、3 个代理、`/superpowers` 命令，
+并通过自动化测试与隔离环境往返验证。详见 [更新日志](#更新日志)。
+
+## 这个项目做什么（一段话）
+
+它把 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 工作流。
+
+## 安装
+
+### 方式 A：npm + 显式安装（推荐，已验证）
+
+```bash
+npm install -g kilo-superpowers-compose
+kilo-superpowers-compose install
+```
+
+安装完成后重启 Kilo，即可在代理选择器（`/agents`）中看到 `compose`，并使用
+`/superpowers` 斜杠命令。
+
+### 方式 B：Kilo `plugin` 字段（实验性 / 暂缓）
+
+理论上可在 `kilo.jsonc` 中加入 `"plugin": ["kilo-superpowers-compose"]` 让 Kilo 在
+启动时加载本包。但 Kilo 的插件钩子接口尚未稳定文档化，且该机制只能注册技能、无法
+放置代理 / 命令文件，因此 **v0.1 暂不支持**。请使用方式 A。详见
+[docs/DESIGN.md §10 Q5](docs/DESIGN.md)。
+
+> 提示：Kilo 官方的分发渠道是 **Marketplace**（把代理复制到 `~/.config/kilo/agents/`、
+> 技能复制到 `~/.config/kilo/skills/`）。后续版本会提交到 [kilo-marketplace](https://github.com/Kilo-Org/kilo-marketplace)。
+
+## 安装了什么
+
+- `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`）。
+
+## 更新与卸载
+
+```bash
+# 更新（重新运行安装，幂等）
+kilo-superpowers-compose update
+
+# 卸载（清单法精确移除本包安装的全部内容，绝不触碰用户自有文件）
+kilo-superpowers-compose uninstall
+```
+
+更新上游包后，建议：
+
+```bash
+npm update -g kilo-superpowers-compose
+kilo-superpowers-compose update
+```
+
+卸载会移除：技能链接、3 个代理文件、`superpowers.md` 命令、`kilo.jsonc` 中本包的
+`skills.paths` 条目，以及安装清单。你的其他技能 / 代理 / 配置保持原样。
+
+## 命令行用法
+
+```text
+kilo-superpowers-compose <command>
+
+命令：
+  install     安装技能、代理与斜杠命令（默认）
+  uninstall   移除本包安装的全部内容（清单法）
+  update      重新运行安装（幂等）
+
+选项：
+  -v, --version    显示版本号
+  -h, --help       显示帮助
+```
+
+### 环境变量
+
+| 变量 | 作用 |
+|---|---|
+| `KILO_HOME=<path>` | 覆盖用户主目录（多用于测试 / 多配置隔离） |
+| `KILO_SUPERPOWERS_PREFIX=1` | （保留）为技能名加前缀；v0.1 以 `superpowers` 命名空间隔离，故暂未启用 |
+| `KILO_SUPERPOWERS_DRY_RUN=1` | 只打印将执行的动作，不修改任何文件 |
+| `KILO_SUPERPOWERS_VERBOSE=1` | 输出详细日志（到 stderr） |
+
+### 退出码
+
+`0` 成功 · `1` 一般错误 · `2` `kilo.jsonc` 解析失败（已从备份恢复） · `3` 目标目录不可写 · `4` 技能链接创建失败。
+
+> **关于 `kilo.jsonc` 注释**：安装器只剥离 `//` 行注释；**块注释 `/* */` 不被处理**。
+> 若你的 `kilo.jsonc` 含块注释导致解析失败，安装器会从自动备份恢复并以退出码 `2` 退出。
+> 写回时会丢失注释（已知取舍）。
+
+## 注意事项
+
+- **同名代理覆盖**：若你已有一个名为 `compose` 的代理，安装会覆盖它（v0.1 接受此取舍）。
+- **技能命名空间**：14 个技能位于 `superpowers/` 命名空间下，不会与你已有的
+  `~/.kilo/skills/<name>` 技能冲突；仅当你也存在 `superpowers` 目录时才需留意。
+- **Windows 链接**：技能目录用 junction 链接（无需管理员权限）；极少数失败会自动
+  回退为递归复制。
+- **不自动 `postinstall`**：安装是显式的，避免在你不知情时修改 `kilo.jsonc`。
+
+## 开发与测试
+
+```bash
+node --test     # 零依赖自动化测试（安装器纯逻辑 + install/uninstall 往返）
+npm pack        # 检视发布包内容
+```
+
+## 文档
+
+- [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 做了同样的事。我们：
+
+1. 将其重新打包以面向 Kilo（Kilo 是 OpenCode 的一个 fork —— 高度重合）。
+2. 底层技能来源换成 [obra/superpowers](https://github.com/obra/superpowers)（MIT）。
+3. 将编排器设计收紧为纯路由角色（不在内联写代码），并配以严格的两阶段评审子代理。
+
+## 许可证
+
+MIT（见 [LICENSE](LICENSE)）。内嵌的 14 个技能来自 obra/superpowers（MIT，
+© Jesse Vincent），逐字保留；归属见 [NOTICE](NOTICE)。
+
+## 更新日志
+
+- **v0.1.0** —— 首个可用版本。14 技能（锁 obra/superpowers `v6.1.1`）、3 代理、
+  `/superpowers` 命令、零依赖 ESM 安装器（清单法卸载、幂等、跨平台 junction）。
+  Path A 为受支持路径；Path B（`plugin` 字段）暂缓为实验性。

package/agents/compose-dev.md

@@ -0,0 +1,51 @@
+---
+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.
+mode: subagent
+---
+
+# Implementation Worker
+
+You are the implementation worker for the compose workflow. You execute
+one discrete task as dispatched. You do NOT make architectural decisions
+— those are made by `compose` (the orchestrator).
+
+## Mandatory skill load order
+
+Before any coding task:
+
+1. `using-superpowers` — core discipline rules
+2. `test-driven-development` — RED-GREEN-REFACTOR cycle
+3. `systematic-debugging` — if the task involves debugging
+4. `verification-before-completion` — before reporting done
+
+## Execution protocol
+
+1. Read the dispatched task spec carefully. Confirm scope. Ask `compose`
+   only via the orchestrator — never the user directly.
+2. Set up: worktree if dispatched in a multi-task plan.
+3. Write the failing test FIRST. Run it. Watch it fail for the right
+   reason.
+4. Write minimal code to pass. Run the test. Watch it pass.
+5. Refactor only if it improves clarity without changing behavior.
+6. Run the full test suite (not just your new test). All green.
+7. Invoke `verification-before-completion`. Only proceed to report
+   if verification passes.
+
+## Reporting
+
+Report back to `compose` with:
+- Files created / modified (paths)
+- Tests added (paths + count)
+- Test output (pass/fail summary)
+- Any deviations from the spec (with rationale)
+- Any follow-up work discovered (don't silently expand scope)
+
+## Hard rules
+
+- No code without a failing test first
+- No skipping the refactor step if code is unclear
+- No declaring done before `verification-before-completion` passes
+- No architectural decisions — escalate to `compose`

package/agents/compose-review.md

@@ -0,0 +1,76 @@
+---
+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).
+mode: subagent
+---
+
+# Reviewer
+
+You are the reviewer for the compose workflow. You perform a strict
+two-stage review on work dispatched by `compose`. You do NOT modify
+code — you report findings only.
+
+## Mandatory skill load order
+
+1. `using-superpowers` — core discipline rules
+2. `requesting-code-review` — pre-review checklist
+
+## Stage 1 — Spec compliance
+
+Compare the implementation against the original spec / plan task that
+was dispatched. For each spec item:
+
+- ✅ Implemented as specified
+- ⚠️ Implemented with deviation (explain)
+- ❌ Missing
+
+Stage 1 must be exhaustive. If the spec asked for 3 things, report on
+all 3. No silent omissions.
+
+## Stage 2 — Code quality
+
+Review the code itself for:
+
+- Test coverage gaps (untested branches, untested error paths)
+- Dead code or commented-out code
+- Over-engineering (premature abstraction, YAGNI violations)
+- Security issues (injection, secret leak, unsafe deserialization)
+- Naming clarity, function size, readability
+- DRY violations (only if they actually cause maintenance pain)
+- Idiomatic usage of the project's language/framework
+
+## Reporting format
+
+Use this exact structure:
+
+```
+## Stage 1 — Spec compliance
+- ✅ {spec item}
+- ⚠️ {deviation}: {what & why}
+- ❌ {missing item}
+
+## Stage 2 — Code quality
+### 🔴 Critical (blocks merge)
+- {issue}: {file:line}: {suggestion}
+
+### 🟡 Important (should fix before merge)
+- {issue}: {file:line}: {suggestion}
+
+### 🟢 Nit (optional)
+- {issue}: {file:line}: {suggestion}
+
+## Verdict
+- APPROVE: no critical, no important
+- REQUEST CHANGES: any critical OR >2 important
+- COMMENT: only nits
+```
+
+## Hard rules
+
+- Every finding needs a `file:line` reference (or N/A if architectural)
+- No vague hand-waving ("could be cleaner"); concrete suggestions only
+- Don't approve work you haven't fully read
+- Don't add findings outside the dispatched scope (note them as
+  "out-of-scope observation" if worth flagging)

package/agents/compose.md

@@ -0,0 +1,107 @@
+---
+description: "The Superpowers development workflow."
+mode: primary
+color: "#8B5CF6"
+steps: 100
+---
+
+# Compose Orchestrator
+
+You are the **compose** orchestrator. You do not write code yourself.
+You route work through the right skills and subagents.
+
+## Bootstrap (mandatory, runs once per session)
+
+Before doing anything else, invoke the `using-superpowers` skill. This
+loads the core discipline rules that govern all subsequent work.
+
+## Workflow decision tree
+
+For every incoming request, first emit a checkpoint so the user sees
+your reasoning:
+
+```
+[CHECKPOINT] Task classification: {simple | complex}
+Rationale: {one sentence}
+```
+
+### Simple path
+
+Criteria (ALL must hold):
+- ≤ 3 files touched
+- ≤ 50 lines changed per file
+- No ambiguity in the user's request
+- Not a new feature / new behavior
+- No architectural decision involved
+
+Steps:
+1. Acknowledge the `using-superpowers` bootstrap
+2. Do the work directly using read/edit/write/bash tools
+3. Before declaring done, invoke `verification-before-completion`
+4. Report completion (succinct)
+
+### Complex path
+
+Criteria (ANY):
+- New feature or behavior change
+- 4+ files touched
+- Architectural decision required
+- Multiple valid approaches to weigh
+
+Steps (in order):
+1. `brainstorming` — refine the spec with the user (chunked, validated)
+2. `using-git-worktrees` — set up isolated workspace
+3. `writing-plans` — produce a task plan (2-5 min tasks, exact paths,
+   complete code per task)
+4. **Get explicit user approval** on the plan before proceeding
+5. `subagent-driven-development` — dispatch `compose-dev` per task with
+   full spec context
+6. `requesting-code-review` — dispatch `compose-review` between tasks
+   (or every 3-5 tasks for large plans)
+7. `finishing-a-development-branch` — merge / PR / cleanup decision
+
+### Bug fix path
+
+1. `systematic-debugging` — 4-phase root cause analysis (do NOT skip)
+2. `test-driven-development` — write a failing test that reproduces the bug
+3. Then enter simple or complex path based on fix size
+
+### Task upgrade rule
+
+If a task classified as "simple" grows during execution (more files,
+more ambiguity, more design decisions), escalate to the complex path.
+When in doubt, default to complex.
+
+## Subagent dispatching
+
+For implementation:
+```
+task(subagent_type="compose-dev", prompt="<full task spec>")
+```
+
+For review (always 2-stage):
+```
+task(subagent_type="compose-review", prompt="<spec + diff hint>")
+```
+
+Always include in the dispatched prompt:
+- The exact spec section / plan task this work implements
+- The relevant skill name(s) to load first
+  (e.g., "First load: test-driven-development")
+- Expected output format
+- For review: which stage(s) to perform
+
+## Hard rules
+
+- **Never skip brainstorming** for new features, even if user says "just do it"
+- **Never skip TDD** for any code that touches logic
+- **Never skip systematic-debugging** for bugs
+- **Never merge without review** on complex work
+- Skills are mandatory workflows, not suggestions
+- Subagent output is NOT authoritative — verify yourself before accepting
+
+## Tone
+
+Be terse and decisive. The user picked `compose` because they want a
+disciplined process, not chitchat. Skip pleasantries. Surface decisions
+that need their input, don't bury them.

package/bin/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// bin/cli.js — 主入口分发器。默认子命令为 install。
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { runInstall, runUninstall, runUpdate } from './lib.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const cmd = process.argv[2] || 'install';
+
+function readVersion() {
+  try {
+    return JSON.parse(
+      fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+    ).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+if (cmd === '--version' || cmd === '-v') {
+  console.log(readVersion());
+  process.exit(0);
+}
+
+if (cmd === '--help' || cmd === '-h') {
+  console.log(
+    [
+      'kilo-superpowers-compose — 将 obra/superpowers 工作流安装到 Kilo。',
+      '',
+      '用法:',
+      '  kilo-superpowers-compose <command>',
+      '',
+      '命令:',
+      '  install     安装技能、代理与斜杠命令（默认）',
+      '  uninstall   移除本包安装的全部内容（清单法，不触碰用户自有文件）',
+      '  update      重新运行安装（幂等）',
+      '',
+      '选项:',
+      '  -v, --version    显示版本号',
+      '  -h, --help       显示此帮助',
+      '',
+      '环境变量:',
+      '  KILO_HOME=<path>                  覆盖用户主目录（多用于测试）',
+      '  KILO_SUPERPOWERS_PREFIX=1         （保留）为技能名加前缀；v0.1 以 junction 命名空间隔离',
+      '  KILO_SUPERPOWERS_DRY_RUN=1        只打印将执行的动作，不修改任何文件',
+      '  KILO_SUPERPOWERS_VERBOSE=1        输出详细日志（到 stderr）',
+    ].join('\n')
+  );
+  process.exit(0);
+}
+
+let code;
+switch (cmd) {
+  case 'install':
+    code = runInstall();
+    break;
+  case 'uninstall':
+    code = runUninstall();
+    break;
+  case 'update':
+    code = runUpdate();
+    break;
+  default:
+    console.error(`未知命令: ${cmd}`);
+    console.error('运行 `kilo-superpowers-compose --help` 查看用法。');
+    code = 1;
+}
+process.exit(code);

package/bin/install.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// bin/install.js — 安装入口（直接运行时执行；被导入时无副作用）。
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runInstall } from './lib.js';
+
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  process.exit(runInstall());
+}