kilo-openspec-libretto

A Kilo Code / Kilo CLI plugin that packages the OpenSpec spec-driven development workflow into a single installable package, exposing a libretto orchestrator agent that drives explore → propose → apply → verify → sync → archive.

Prerequisites

• Kilo CLI ≥ 7.5 (for the kilo plugin command)
• Node.js ≥ 18 (only needed for the legacy npm installer, see below)
• OpenSpec CLI: npm install -g @fission-ai/openspec (libretto depends on it at runtime for validation, status, and archiving)

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-openspec-libretto@latest setup

setup does everything: verifies/installs the Kilo plugin (kilo plugin kilo-openspec-libretto --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 below).

After it completes: fully restart Kilo (quit the CLI, Reload Window in VS Code) and pick libretto in the agent picker.

⚠ 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-openspec-libretto@latest/.

Verify: after restart, the agent picker lists libretto and the skill list shows the libretto-* 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-openspec-libretto@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-openspec-libretto@latest setup again (it refreshes the plugin with --force).

Per-project initialization (once per project)

cd your-project
openspec init --tools none

💡 --tools none skips per-tool skill/command generation. openspec 1.6.0's adapters (e.g. kilocode) still write into .kilocode/skills/, but kilo CLI ≥ 7.4 no longer scans that directory — those files would be dead writes. libretto ships its own prefixed skills (libretto-*); you only need the openspec/ workspace (config + changes/ + specs/).

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-openspec-libretto uninstall            # ① manifest-based removal — must run while the npm package is still installed
npm rm -g kilo-openspec-libretto            # ② removes the CLI (its uninstall subcommand goes with it)
kilo plugin kilo-openspec-libretto --global # ③ install the plugin form

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

Update & uninstall (plugin form)

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

⚠ kilo plugin kilo-openspec-libretto --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.3.2): 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-openspec-libretto@latest uninstall

Optionally also delete the cache directory ~/.cache/kilo/packages/kilo-openspec-libretto@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. libretto ≥ 0.3.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-openspec-libretto@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-openspec-libretto@latest setup, restart Kilo. The libretto 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-openspec-libretto@latest/ | <npm global prefix>/node_modules/kilo-openspec-libretto/ | | 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 layout, see below) via a runtime skills.paths entry | junction at ~/.kilo/skills/libretto (→ package root) + skills.paths entry | | Manifest | none needed | ~/.config/kilo/.kilo-openspec-libretto.json |

What gets installed

• 8 skills under the libretto namespace: core, explore, propose, apply-change, sync-specs, archive-change, verify-change, handoff.
• 3 agents: libretto (primary orchestrator), libretto-apply (implementation subagent), libretto-verify (verification subagent).
• A global permission.skill["libretto-*"] = "deny" — injected at runtime, only when you have not set it yourself — which hides libretto skills from Kilo's built-in agents. The three shipped agents override it to allow.

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-openspec-libretto@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-openspec-libretto@latest\\node_modules\\kilo-openspec-libretto"
    ]
  }
}

(macOS/Linux: ~/.cache/kilo/packages/kilo-openspec-libretto@latest/node_modules/kilo-openspec-libretto.)

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.

Skill layout: flat at the package root

Since v0.2.2 the skills are laid out flat — <package-root>/<skill>/SKILL.md — matching kilo-vision-bridge's root-level convention and keeping the manual skills.paths entry a single stable path. Skill names are unaffected: they come from each SKILL.md's frontmatter name: field (libretto-*).

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": { "libretto": { "model": "anthropic/claude-sonnet" } } }

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

Legacy npm CLI (alternative install)

The original two-step install, still supported:

npm install -g kilo-openspec-libretto
kilo-openspec-libretto install

kilo-openspec-libretto <command>

Commands:
  install     Install skills and agents (npm mode, default)
  setup       One-shot plugin-mode install (recommended)
  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) | | KILO_LIBRETTO_SKIP_OPENSPEC_CHECK=1 | Skip openspec CLI detection | | KILO_LIBRETTO_DRY_RUN=1 | Print actions without modifying | | KILO_LIBRETTO_VERBOSE=1 | Verbose logging (stderr) | | KILO_LIBRETTO_CACHE_ROOT=<path> | Override kilo plugin cache root (default ~/.cache/kilo/packages) | | KILO_LIBRETTO_KILO_BIN=<path> | Override kilo CLI executable |

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

Development

node --test     # zero-dependency tests
npm pack        # inspect the tarball

Documentation

• docs/specs/2026-07-14-libretto-design.md — locked design
• docs/DESIGN.md — architecture summary
• docs/INSTALLER.md — installer spec
• docs/AGENTS.md — agent specifications
• docs/REFERENCES.md — reference links
• NOTICE — OpenSpec CLI dependency attribution

License

MIT — see LICENSE. libretto's skills/agents/installer are original work. Runtime depends on @fission-ai/openspec (MIT).