kilo-superpowers-compose

A Kilo Code / Kilo CLI plugin that packages the obra/superpowers development workflow into a single installable package, exposing a compose orchestrator agent that drives brainstorming → planning → subagent implementation → two-stage review → merge.

Status

v0.4.3. Documentation correction: the v0.4.2 flattening alone does not fix the startup failed to load skill errors — that was based on a false-positive test. The real finding: Kilo 7.5.16's skill scope check rejects any plugin-hook-injected skills.paths entry (root or subdirectory); only entries written in kilo.jsonc are trusted. The install docs now include the one-paste skills.paths step (required until Kilo fixes the check). The flat layout is kept — it makes that manual entry a single stable path.

v0.4.2. Skills flattened to the package root (<pkg>/<skill>/SKILL.md); the plugin now registers the package root as its skills.paths entry. (Claimed to fix every-startup failed to load skill on Kilo 7.5.16 — incorrect, corrected in v0.4.3.)

v0.4.1. Documentation only: cold-install transient notes (quit Kilo fully before kilo plugin; the first boot after a fresh install may miss skills while the plugin cache resolves; warm-cache troubleshooting steps).

v0.4.0. The Kilo plugin form (kilo plugin kilo-superpowers-compose --global) is now the recommended install path, verified on Kilo CLI 7.5.16. The plugin's config hook injects the 3 agents at runtime (nothing written to kilo.jsonc), respects user overrides for every field except prompt/description/mode, and carries the permission.skill isolation previously written by the installer. The 2026-07 "plugin field does not work" finding no longer applies. The legacy npm CLI installer remains supported as an alternative.

v0.3.0. Vendored skills upgraded to obra/superpowers v6.3.0.

v0.2.0. Released with the compose- skill namespace, junction renamed to match, and a global permission.skill["compose-*"]="deny" that hides compose skills from Kilo's built-in agents (override-allowed in the compose* agent frontmatter). Verified on both Kilo CLI and the VS Code Kilo Code extension (they share the same config, so one install covers both).

What it is

kilo-superpowers-compose bundles 14 battle-tested Superpowers skills + 3 purpose-built agents into one npm package. Run one install command (kilo plugin kilo-superpowers-compose --global), restart Kilo, and a compose agent appears in the agent picker. Pick compose and the full, disciplined Superpowers workflow runs on any coding task — no extra slash command required (this matches the mimo-compose convention).

Installation (recommended — one command)

Works for humans and for agents installing on the user's behalf (no README reading required beyond this line):

npx kilo-superpowers-compose@latest setup

setup does everything: verifies/installs the Kilo plugin (kilo plugin kilo-superpowers-compose --global), registers the file-based skills path in kilo.jsonc (required on Kilo ≤ 7.5.x — see the known issue), backs up every file before touching it, and aborts with exact fix instructions if your kilo.jsonc already contains a config-breaking {file:…}/{env:…} snippet (see Troubleshooting).

After it completes: fully restart Kilo (quit the CLI, Reload Window in VS Code), then pick compose in the agent picker. One install covers both Kilo CLI and the VS Code Kilo Code extension (they share ~/.config/kilo/).

⚠ Fully quit Kilo before installing. Installing while Kilo is running triggers live config reloads mid-install; agents may attach but skills won't until the next cold start.

Where the registration lives (surprising but expected): the plugin array in ~/.config/kilo/opencode.json — a legacy filename that Kilo still reads. It will not appear in kilo.jsonc (except the skills.paths entry setup adds there). The package itself resolves into ~/.cache/kilo/packages/kilo-superpowers-compose@latest/.

Verify: after restart, the agent picker lists compose and the skill list shows the compose-* skills. If not, run kilo --print-logs --log-level DEBUG and check for plugin load errors.

ℹ First boot after a fresh install may miss the skills — the plugin cache (~/.cache/kilo/packages/kilo-superpowers-compose@latest/) is populated by a real npm resolution that can take several seconds. One more cold restart with the warm cache loads everything. If skills are still missing on a warm cache: run npx kilo-superpowers-compose@latest setup again (it refreshes the plugin).

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. Until then, use the plugin install above.

Migrating from the legacy npm installer

Dual installs on the same machine are not supported — clean the old form first, in this exact order:

kilo-superpowers-compose uninstall            # ① manifest-based removal — must run while the npm package is still installed
npm rm -g kilo-superpowers-compose            # ② removes the CLI (its uninstall subcommand goes with it)
kilo plugin kilo-superpowers-compose --global # ③ install the plugin form

If the agent picker still shows compose* entries after ①–③ and a restart, an early installer generation left inline agent."compose" / agent."compose-dev" / agent."compose-review" blocks inside kilo.jsonc (those predate the manifest and are not removed automatically). Delete those keys manually.

What gets installed

• 14 skills, each prefixed compose- (e.g. compose-brainstorming), vendored from obra/superpowers v6.3.0 (MIT). Since v0.4.2 they are laid out flat at the package root (<pkg>/<skill>/SKILL.md), so the manual registration below is a single stable path. Folder names are kept verbatim (brainstorming/, using-superpowers/, …); the compose- prefix lives in each SKILL.md's frontmatter name: field. Full list: compose-using-superpowers, compose-brainstorming, compose-test-driven-development, compose-systematic-debugging, compose-verification-before-completion, compose-writing-plans, compose-executing-plans, compose-subagent-driven-development, compose-requesting-code-review, compose-receiving-code-review, compose-using-git-worktrees, compose-finishing-a-development-branch, compose-dispatching-parallel-agents, compose-writing-skills.

Skills require one manual step (Kilo 7.5.16 known issue)

Kilo 7.5.16's skill scope check (blocked file reference outside project config scope) rejects skills registered via a plugin's runtime skills.paths injection — regardless of layout. Only skills.paths entries written in kilo.jsonc itself are trusted. (Single-skill plugins like kilo-vision-bridge are unaffected: their root-level SKILL.md goes through the plugin-owned channel.)

So after kilo plugin, add the skills entry manually — one paste, and the path is stable across --force updates — or, better, let npx kilo-superpowers-compose@latest setup do it for you (it writes exactly this entry, with backup and validation):

// ~/.config/kilo/kilo.jsonc
{
  "skills": {
    "paths": [
      "C:\\Users\\<you>\\.cache\\kilo\\packages\\kilo-superpowers-compose@latest\\node_modules\\kilo-superpowers-compose"
    ]
  }
}

(macOS/Linux: ~/.cache/kilo/packages/kilo-superpowers-compose@latest/node_modules/kilo-superpowers-compose.)

Agents and the permission isolation need no manual step — they are injected at runtime and unaffected by this check. The plugin also keeps injecting the skills path (harmless, deduplicated); once Kilo fixes the scope check, the manual entry becomes optional.

• 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 unless you override it.
• A global permission.skill["compose-*"] = "deny" — injected at runtime, only when you have not set it yourself — which hides compose skills from Kilo's built-in agents (code / plan / debug / ask / explore / general). Each of the three shipped agents declares the override allow.

Update & uninstall (plugin form)

npx kilo-superpowers-compose@latest setup   # upgrade: detects stale cache and refreshes it automatically

⚠ kilo plugin kilo-superpowers-compose --force --global does not refresh an existing plugin cache on Kilo 7.5.16 (verified empirically) — the cache is only re-resolved when its directory is absent. setup handles this for you (≥ 0.5.1): it compares the cached version with its own (fetched via npx @latest), deletes the stale cache, and re-runs the plugin install.

Uninstall — Kilo does not yet ship a kilo plugin uninstall command. The manifest-aware uninstaller removes everything this package registered (kilo.jsonc skills entry, permission deny, opencode.json plugin entry, manifest):

npx kilo-superpowers-compose@latest uninstall

Optionally also delete the cache directory ~/.cache/kilo/packages/kilo-superpowers-compose@latest/.

Troubleshooting

Kilo suddenly lost ALL its config (plugins, skills, agents gone)

Your kilo.jsonc contains a {file:…} or {env:…} snippet. Kilo treats these as config variable substitution — {file:line} makes it try to read a file named line, fails, and silently skips the entire config file (log: skipped config due to error).

Where do these snippets come from? Almost always an agent copied a report template placeholder — {issue}: {file:line}: {suggestion} — out of a plugin's agent definitions and pasted it into kilo.jsonc. This package ≥ 0.5.0 renamed its placeholder to {path}:{line} so this can no longer happen with its files.

Fix: delete the {file:…}/{env:…} text from kilo.jsonc (or restore one of the kilo.jsonc.bak.* backups next to it), then restart Kilo. npx kilo-superpowers-compose@latest setup detects and reports exactly these lines before touching anything.

Skills missing but agents present

That is the Kilo #12222 known issue — run npx kilo-superpowers-compose@latest setup, restart Kilo. The compose agent itself will also tell you this command if it notices its skills are unavailable.

File locations

| | Plugin form (recommended) | Legacy npm installer | |---|---|---| | Registration | one entry in the plugin array of ~/.config/kilo/opencode.json | skills.paths entry in kilo.jsonc + agent .md copies + manifest file | | Package files | ~/.cache/kilo/packages/kilo-superpowers-compose@latest/ | <npm global prefix>/node_modules/kilo-superpowers-compose/ | | Agents | injected into the runtime config at every startup — never on disk | copied to ~/.config/kilo/agent/*.md | | Skills | read from the package root (flattened since v0.4.2) via a runtime skills.paths entry | junction at ~/.kilo/skills/compose (→ package root) + skills.paths entry | | Manifest | none needed | ~/.config/kilo/.kilo-superpowers-compose.json |

User overrides are respected

The plugin re-injects prompt, description, and mode from the package on every startup (the workflow content is owned by the package), but never overwrites anything else you configured for these agents. To pin a model:

// kilo.jsonc
{ "agent": { "compose": { "model": "anthropic/claude-sonnet" } } }

model, temperature, steps, color, permission, hidden, disable and any other field you set explicitly always win over the package defaults.

Common mistakes

"I installed the plugin but the agent picker doesn't show compose." — Fully restart Kilo (quit and reopen; Reload Window in VS Code). If it's still missing, check ~/.config/kilo/opencode.json actually contains "kilo-superpowers-compose" in its plugin array, then run kilo --print-logs --log-level DEBUG to look for plugin load errors.

"I previously installed via npm install -g." — Clean it up before using the plugin form, or you'll get duplicated skills and stale agents. Follow Migrating from the legacy npm installer (the order of the three commands matters).

"I want to remove the plugin entirely." — There is no kilo plugin uninstall yet; follow the manual steps in Update & uninstall.

Legacy npm CLI (alternative install)

The original two-step install, still supported:

npm install -g kilo-superpowers-compose
kilo-superpowers-compose install

kilo-superpowers-compose <command>

Commands:
  install     Install skills and agents (default)
  uninstall   Remove everything this package installed (manifest-based)
  update      Re-run install (idempotent)

Options:
  -v, --version    Show version
  -h, --help       Show help

| Variable | Purpose | |---|---| | KILO_HOME=<path> | Override user home (for testing / isolated configs) | | KILO_SUPERPOWERS_DRY_RUN=1 | Print intended actions without modifying anything | | KILO_SUPERPOWERS_VERBOSE=1 | Verbose logging (to stderr) |

Exit codes: 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 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).

Do not keep both forms installed at once — see Migrating from the legacy npm installer.

Notes

• Skill namespace & isolation: all 14 skills are intrinsically prefixed compose- (e.g. compose-brainstorming). A global permission.skill["compose-*"]="deny" (written to kilo.jsonc by the legacy installer, injected at runtime by the plugin form) keeps Kilo's built-in agents from seeing or invoking them; each of the three shipped agents declares the override allow in its frontmatter, which Kilo's findLast-based Permission.evaluate honours. Folder names under skills/ remain verbatim from upstream (brainstorming/, using-superpowers/, …).
• Windows links (legacy installer): skills are linked via a directory junction (no admin rights needed); on rare failure it falls back to a recursive copy.
• No auto-postinstall: the legacy installer is explicit, so your kilo.jsonc is never modified without you running the command. The plugin form never writes to disk at all.

Development & testing

node --test     # zero-dependency tests (installer logic + plugin module + install/uninstall round-trip)
npm pack        # inspect the published tarball

Documentation

• docs/DESIGN.md — architecture, naming, layout, decisions, risks
• docs/INSTALLER.md — bin/ installer spec and source
• docs/AGENTS.md — the three agents (frontmatter + prompts)
• docs/REFERENCES.md — all reference links
• NOTICE — upstream obra/superpowers attribution (tag v6.3.0, MIT)

Inspiration

This project ports/adapts 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 (MIT); and tighten the orchestrator into a pure-routing role (it never writes code itself) with a strict two-stage review subagent.

License

MIT — see LICENSE. The 14 vendored skills are from obra/superpowers (MIT, © Jesse Vincent), kept verbatim; attribution in NOTICE.