An agentic skills framework & software development methodology that works.
docs: add 'Porting Superpowers to a New Harness' guide
Jesse Vincent3608167e0598
diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.mdnew file mode 100644index 000000000..927576e63--- /dev/null+++ b/docs/porting-to-a-new-harness.md@@ -0,0 +1,826 @@+# Porting Superpowers to a New Harness++This guide explains how to add support for a new harness — an IDE, CLI, or+agent runner that isn't Claude Code — so that Superpowers skills auto-trigger+there the same way they do natively.++It is written in two layers. **Part 1–3** explain how the system works and how+to tell whether a harness can be supported at all; read these before you touch+anything. **Part 4–8** are a prescriptive procedure for an agent (supervised by+a human partner) to execute the port end to end, through distribution. An+appendix indexes the current reference integrations so you can copy the closest+one.++The integration mechanism differs across harnesses, and it will keep changing.+This guide deliberately teaches the **invariants** — the things that must be+true no matter the mechanism — and points you at a live reference implementation+to copy. When this guide and the code disagree, the code wins; fix the guide.++## Before you start++Adding a harness is the highest-stakes contribution type in this repo. Before+writing anything:++- Read `CLAUDE.md` and `.github/PULL_REQUEST_TEMPLATE.md` in full — the+ contributor rules and the new-harness PR requirements are not optional.+- Search open **and closed** PRs for a prior attempt at this harness. If one+ exists, understand why it stalled before starting your own.++---++## Part 1 — How Superpowers works across harnesses++Superpowers is the same content everywhere. What changes per harness is the thin+layer that delivers that content to the model and translates its instructions+into the harness's native tools. Three components:++1. **Skills (harness-agnostic).** Everything in `skills/` is the source of+ truth, shared verbatim by every harness. Skills are written to describe+ *actions* — "invoke a skill", "read a file", "dispatch a subagent", "create a+ todo" — and never name a specific tool. This is what lets one skill body run+ on Claude Code, Codex, Gemini, pi, and the rest without edits.++2. **Tool mapping (per-harness).** Each harness needs the action vocabulary+ translated into its real tool names. That translation lives in+ `skills/using-superpowers/references/<harness>-tools.md` and/or inline in the+ harness's bootstrap injector (see Part 5). It says, e.g., "*dispatch a+ subagent* → call `task` with `subagent_type`."++3. **Bootstrap (per-harness).** At the start of every session, the full+ `skills/using-superpowers/SKILL.md` is injected into the model's context,+ wrapped in `<EXTREMELY_IMPORTANT>` tags, with the tool mapping appended. That+ injected skill is what teaches the model that skills exist and that it must+ check for a relevant skill before acting. **The bootstrap is the entire+ integration.** Without it, the skill files are inert — present on disk, never+ invoked.++### Two rules that make this work++**1. Skills name actions, not tools.** Do **not** edit skill bodies to fit your+harness. Porting adds a tool-mapping reference and a bootstrap injector; it+never reaches into `skills/*/SKILL.md` to swap tool names. (The project's+contributor guidelines treat skill content as carefully-tuned behavior-shaping+code; rewording it for "compliance" is rejected on sight.)++**2. Everything ships through the harness's own install mechanism. Never edit the+user's files.** The bootstrap, the skills, and the tool mapping all get delivered+*as part of what the harness installs* — a plugin, an extension, a marketplace+entry, an extension-bundled context file. A port **must not** reach into a user's+global or personal config (`~/.gemini/config/AGENTS.md`, `settings.json`,+`trustedFolders.json`, a hand-edited `~/.bashrc`, etc.) to inject anything. The+harness owns what it loads; your install artifact is the only thing you get to+write. If the install mechanism genuinely can't carry the bootstrap, that is a+limitation to surface (Part 6) — never a license to hand-edit the user's config.+(Shape C is *not* an exception: Gemini's context file is fine because it ships+*inside the installed extension* and is declared by the manifest's+`contextFileName` — the harness loads the extension's own file, not a file you+edited in the user's home.)++---++## Part 2 — Can this harness be supported?++A harness can support Superpowers only if it can do all of the following. Check+these before writing code — if the first one fails, stop.++### Hard requirement: automatic session-start injection++The harness must let you inject text into the model's context **at the start of+every session, with no per-session opt-in by your human partner.** This is the+one non-negotiable capability. It can take any form:++- a **hook/event system** that runs a shell command at session start and reads+ its stdout (Claude Code, Codex, Cursor, Copilot CLI), or+- an **in-process plugin/extension** with a session-start or message lifecycle+ callback that can mutate the message array (OpenCode, pi), or+- an **instructions-file** convention where the harness loads a context file that+ *your installed extension ships and declares* (e.g. Gemini's `contextFileName`+ pointing at the extension's own `GEMINI.md`) — not a file you edit in the user's+ home.++If the only way to get Superpowers in front of the model is for your human+partner to opt in each session (paste a prompt, run a command, enable a mode),+the harness+**cannot** be properly supported. The acceptance test in Part 3 will fail, and+the PR will be closed. This is the single most common reason a "port" isn't a+real port.++### The rest of the capability checklist++| Capability | Why it's needed | If absent |+|---|---|---|+| **Skill discovery + invocation** | The model must be able to load a skill's full content on demand | If there's no native skill tool, the sanctioned fallback is to `read` the relevant `SKILL.md` directly — see Part 5. A harness with neither a skill tool nor file-read cannot work. |+| **File read / write / edit** | Nearly every skill manipulates files | Essential. No workaround. |+| **Run shell commands** | TDD, verification, git workflows | Essential. |+| **Subagent / task dispatch** | `dispatching-parallel-agents`, `subagent-driven-development` | Degradable: if unavailable, those specific skills tell the model to do the work inline or report the missing capability — *never* to invent a `Task` call. Some harnesses gate this behind a config flag (e.g. Codex needs multi-agent enabled). |+| **Todo / task tracking** | Progress tracking in several skills | Degradable: fall back to a plan file or `TODO.md`. |+| **Web fetch / search** | A few skills | Degradable. |+| **Shell or polyglot script execution (Windows)** | Only for the shell-hook shape, only if you want Windows support | See Part 7. In-process-plugin harnesses sidestep this entirely. |++"Degradable" means: the skill already has fallback wording for the missing+tool. Your job in the tool mapping is to point at the real tool when it exists+and reuse that fallback wording when it doesn't.++### You may not need a new directory at all++Some "new harnesses" are really existing integrations under a different+installer. Factory's Droid, for example, consumes the Claude Code plugin via its+own `plugin install` command and needs no new files here. Before building,+check whether the harness can simply load an existing manifest. A port that adds+nothing to this repo but a paragraph in the README is a perfectly good outcome.++---++## Part 3 — Definition of done++A port is finished when **all** of these are true:++1. The `using-superpowers` bootstrap loads at session start, every session, with+ no per-session opt-in.+2. A tool mapping exists for the harness (in+ `references/<harness>-tools.md`, inline in the bootstrap, or both — per Part 5).+3. Skills can actually be invoked — natively, or via the documented+ read-`SKILL.md` fallback — and the model follows them.+4. **The acceptance test passes.** In a clean session, the user message:++ > Let's make a react todo list++ auto-triggers the `brainstorming` skill *before any code is written*. Capture+ the full transcript — the PR requires it.+5. Tests cover the integration (Part 5) and pass.+6. A real user can install it through the harness's own mechanism (not by+ hand-copying files), and the version is tracked in `.version-bump.json` where+ applicable (Part 6). Note that some installers rewrite or strip the manifest on+ install (one drops it to just `{"name": …}`), so "the *installed* files report+ the repo version" is not always achievable — track the version at the source+ manifest and don't treat a rewritten installed manifest as a failure.++A quick smoke check before the full acceptance test: start a session and ask the+model to describe its superpowers. If the bootstrap injected, it knows it has+them. (OpenCode's install doc uses `opencode run --print-logs "hello" 2>&1 |+grep -i superpowers` for the same goal via a different mechanism — log-grep+rather than asking the model; the `2>&1` matters because logs go to stderr. Find+your harness's equivalent.)++---++## Part 4 — Choose your integration shape++There are three structural shapes, distinguished by *how you get the bootstrap+in front of the model*. Pick the one that matches what your harness exposes,+then copy that reference implementation. The shape determines almost everything+in Part 5 — the steps below branch on it.++### How to tell which shape you have++Before routing, learn the harness's *actual* mechanism — and don't assume it's+well documented or that it behaves like whatever harness it forked from.++**Find the surface:**++- **Search the web for the harness's docs** (extension / plugin / hook / skill /+ MCP / "context file" / "rules file"). Vendor tools change fast; search rather+ than trust training knowledge.+- **Find and read an existing third-party extension/plugin for the harness.** A+ real working example beats docs — it shows the manifest shape, the install+ command, and which components the harness actually loads.+- Check what the harness loads at startup: a settings file? an extensions+ directory? a per-project or global instructions file (`AGENTS.md`, `<NAME>.md`)?++**If it's underdocumented, reverse-engineer it empirically** (a real porter has+had to do every one of these):++- `strings` the binary / grep the install tree for hook event names, config+ paths, and the instructions file it reads.+- **Ask the running model to enumerate its own tool names** — e.g. "list the+ exact machine names of every tool you can call." This is the authoritative way+ to get tool names without inventing them (see Step 4).+- Prove every assumption with a **unique-marker test**: inject a nonsense token+ through the mechanism you think works, start a fresh session, and confirm the+ token actually reached the model.++**A fork does not inherit its parent's behavior.** A harness derived from another+(e.g. a Gemini-derived CLI) may expose the parent's manifest fields and+`@`-include syntax and *still not honor them the same way*. Verify with a marker;+never assume the parent's recipe transfers.++Then route to a shape:++- Shell command at session start whose stdout is read → **Shape A**.+- Plugin/extension module with lifecycle callbacks you run code in → **Shape B**.+- Only ever an always-on instructions file, no hook and no code plugin →+ **Shape C**.++**Shapes compose — they are not mutually exclusive.** The *skill-discovery*+mechanism and the *bootstrap* mechanism need not be the same shape — but **both+must still ride the install mechanism** (rule 2). Decide the two questions+separately: *where do skills get discovered?* and *how does the bootstrap reach+the model every session?* A harness might install skills via a plugin yet need+the bootstrap delivered another install-shipped way (an extension-declared+context file, or — see below — by the harness surfacing the installed+`using-superpowers` skill's own description at session start). If more than one+install-mechanism surface injects automatically, prefer the most reliable. What+you may **not** do is bridge a gap by editing the user's global config.++### Shape A — Shell-hook++The harness has a hook system that runs a shell command at session start and+reads JSON from its stdout. The configured command runs `run-hook.cmd`, a+polyglot wrapper that just locates bash and dispatches the named script; the+script (`hooks/session-start`, or a harness-specific variant like+`hooks/session-start-codex`) is what reads `using-superpowers/SKILL.md` and+prints a JSON object whose **field name and nesting differ per harness**.++- Reference: `hooks/session-start` (and `hooks/session-start-codex`),+ `hooks/run-hook.cmd`, and the per-harness hook config `hooks/hooks.json`+ (Claude Code), `hooks/hooks-codex.json` (Codex), `hooks/hooks-cursor.json`+ (Cursor).+- Manifests: `.codex-plugin/plugin.json`, `.cursor-plugin/plugin.json` point the+ harness at `./skills/` and the right `hooks-*.json`. (Claude Code's+ `.claude-plugin/plugin.json` sets neither field — it auto-discovers `skills/`+ and `hooks/hooks.json` by convention.)++> **A hook *system* is not a session-start *event*.** A harness can have a+> `hooks.json` mechanism — and even contain the literal string `SessionStart` in+> its binary — while having no hook event that fires at session start and can+> inject context. (One real harness only exposed pre/post-tool and stop events;+> the `SessionStart` strings were telemetry.) Confirm the *specific event* you+> need exists and can write to the model's context before committing to Shape A.+> If it can't, the bootstrap belongs in an instructions file (Shape C) instead.++### Shape B — In-process plugin / extension++The harness loads a JS/TS module that exposes lifecycle callbacks. You register+the skills directory through the harness's API and inject the bootstrap by+mutating the message array in code.++- Reference: `.opencode/plugins/superpowers.js` (JavaScript) and+ `.pi/extensions/superpowers.ts` (TypeScript). pi is the closest reference for+ any harness that has **no native skill tool**.++### Shape C — Instructions-file++The harness has neither a shell hook nor a code plugin — its session-start+surface is a context file that *your installed extension ships and the manifest+declares* (e.g. Gemini's `contextFileName` → the extension's own `GEMINI.md`).+You can't run code or mutate messages; the extension's context file points at the+bootstrap. There is no injector to assemble a string or strip frontmatter — the+harness loads the referenced content as-is. **This works only because the file is+part of the installed extension** — never substitute "edit the user's global+`GEMINI.md`/`AGENTS.md`" for shipping your own (rule 2).++- Reference: `gemini-extension.json` (manifest, with `contextFileName`),+ `GEMINI.md` (two `@`-includes — the bootstrap skill and the tool-mapping+ reference), `skills/using-superpowers/references/gemini-tools.md`.+- Note: `@`-include is a Gemini feature. If your harness loads an instructions+ file but has no include syntax, you must inline the bootstrap content into the+ file instead.+- **Don't trust that an `@`-include is actually expanded — prove it.** A+ Gemini-*derived* harness can accept `@./path` syntax yet treat it as a *hint+ the model may choose to read* (it emits a file-read tool call) rather than a+ guaranteed inline expansion. That's the difference between the bootstrap being+ reliably present every session and the model maybe-reading it. Run a+ unique-marker test: if the marker isn't in context *without* a tool call,+ **inline the content** rather than `@`-include it.++### Routing table++| If the harness… | Use shape | Copy from |+|---|---|---|+| runs a shell command at session start and reads its stdout | A (shell-hook) | Codex (`hooks/session-start-codex` + `hooks/hooks-codex.json` + `.codex-plugin/`) |+| is a JS/TS plugin host with session/message lifecycle callbacks | B (in-process) | OpenCode (`.opencode/`) — or pi (`.pi/`) if it has no native skill tool |+| ships an extension-declared context file it always loads | C (instructions-file) | Gemini (`gemini-extension.json` + `GEMINI.md` + `references/gemini-tools.md`) |+| has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |++Most real harnesses fit one row cleanly; the last is the hybrid case (rule 2 still+holds — the bootstrap rides the install mechanism, never a user-config edit).++---++## Part 5 — The porting procedure++### Step 1 — Study the closest reference implementation++Open the files named in Part 4 for your shape and read them end to end. The+patterns below are summaries; the code is the spec.++### Step 2 — Create the manifest / entry point++Create whatever the harness uses to recognize the plugin. Match the existing+ones in spirit:++- **Shape A:** a `*-plugin/plugin.json` (see `.codex-plugin/plugin.json`) with+ `name`, `version`, `description`, author/license/keywords, `"skills":+ "./skills/"`, and `"hooks": "./hooks/hooks-<harness>.json"`. Plus the+ `hooks-<harness>.json` itself, registering a session-start hook whose command+ invokes `run-hook.cmd`.+- **Shape B:** the module the harness loads (e.g. `.<harness>/plugins/*.js`) plus+ whatever package metadata it needs to be discovered. The committed package+ metadata is the **repo-root `package.json`**: `main` points at the OpenCode+ plugin, the `pi` field (`pi.extensions`, `pi.skills`) plus the `pi-package`+ keyword declare the pi extension. Per-harness local manifests and lockfiles are+ kept out of git — `.opencode/.gitignore` excludes `node_modules`,+ `package.json`, and lockfiles. Do the same for your harness's *local* install+ artifacts so they don't pollute the repo — but never gitignore the repo-root+ `package.json`, which is the tracked source of truth.+ - **Build/dependency check.** Decide how the harness loads your module:+ does it run the source directly (pi's `.ts` is referenced as-is from+ `package.json`; OpenCode ships plain `.js`), or does it need a transpile/build+ step? Superpowers is zero-runtime-dependency. pi's `import type+ { ExtensionAPI }` works specifically because the harness runs the `.ts`+ directly, supplies that type at load, and the repo never type-checks the file+ in CI — the import isn't even declared as a dependency. If *your* harness+ actually type-checks or bundles the plugin, that breaks: an undeclared type+ import fails, and the PR rules only carve out *runtime* deps for new+ harnesses, not dev/type packages. If you hit this, confirm the approach with+ the maintainer rather than quietly adding a dependency. Keep any build output+ out of git and document the command.+- **Shape C (instructions-file):** a small manifest (see `gemini-extension.json`:+ `name`, `description`, `version`, `contextFileName`) plus the context file+ itself (`GEMINI.md` is just two `@`-includes: the bootstrap skill and the+ tool-mapping reference). The Gemini manifest has no `skills` field — Gemini+ auto-discovers the `skills/` directory bundled in the installed extension. If+ your harness has a native skill tool but no manifest field to register the+ directory, you must find its discovery convention (read its extension docs),+ then verify empirically: after wiring, ask the model to list its available+ skills — if the bundled skills don't appear, discovery isn't working yet.++### Step 3 — Wire the bootstrap injection++This is the heart of the port. The shared goal: at session start, get the+`using-superpowers` skill content (wrapped in `<EXTREMELY_IMPORTANT>` tags) plus+the harness's tool mapping in front of the model, with a note that the skill is+already active so the model doesn't try to load it again. *How* you do that —+and what you assemble vs. what the harness loads raw — depends entirely on your+shape. Do **not** apply one shape's recipe to another.++**Shape A — a script reads `SKILL.md` and prints the harness's JSON.** The+dispatched script (`hooks/session-start`) `cat`s the whole `SKILL.md` (frontmatter+included — that's fine; it's emitted verbatim), wraps it with the "You have+superpowers… for all other skills use the Skill tool" preamble, escapes it, and+prints the harness's JSON shape. The tool mapping for Shape A does **not** go+inline here — it lives in `references/<harness>-tools.md` (Step 4). Get the JSON+output shape exactly right. `hooks/session-start`+detects the harness from environment variables and prints *one of three* shapes:++- Cursor (`CURSOR_PLUGIN_ROOT` set): `{ "additional_context": "…" }`+- Claude Code (`CLAUDE_PLUGIN_ROOT` set, `COPILOT_CLI` unset):+ `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "…" } }`+- Copilot CLI / SDK standard (else): `{ "additionalContext": "…" }`++This is a trap. Emitting the wrong field, or an extra one, means the bootstrap+either never injects or injects twice (Claude Code reads both+`additional_context` and `hookSpecificOutput` without de-duplicating, so emitting+both double-injects). Find the+exact field, nesting, and event-matcher values your harness expects. Then+decide: add a fourth branch to `hooks/session-start`, or — if the harness needs+a different bootstrap message or env contract — add a dedicated+`hooks/session-start-<harness>` script, the way Codex did. If you add a branch+and your harness *also* sets an env var an earlier branch keys on (some harnesses+set `CLAUDE_PLUGIN_ROOT` too), order your branch before the one that would+otherwise shadow it. Match the harness's+own event-matcher strings (Claude Code uses `startup|clear|compact`, Codex+`startup|resume|clear`, Cursor `sessionStart`); wrong matchers mean the hook+silently never fires.++The **hook-config schema itself varies per harness** — don't assume the+Claude/Codex shape is universal. Compare `hooks/hooks.json`,+`hooks/hooks-codex.json`, and `hooks/hooks-cursor.json`: Cursor's uses+`"version": 1`, a lowercase `sessionStart` key, a relative+`./hooks/run-hook.cmd` command, and omits the `matcher`/`type`/`async` fields the+others use. Match your `hooks-<harness>.json` to whichever existing file is+closest, not to a single canonical template.++The hook **command string references a harness-provided plugin-root variable**,+and its name differs per harness: `hooks.json` uses `${CLAUDE_PLUGIN_ROOT}`,+`hooks-codex.json` uses `${PLUGIN_ROOT}`, Cursor uses a relative path. Use+whatever your harness exports. (The `session-start` script re-derives the root+itself via `dirname`, so the script body doesn't depend on this — but the+command in the manifest does.)++**Discovering the harness's contract.** The three facts above — env var, JSON+field/nesting, matcher strings — are the harness's contract, not Superpowers',+so you have to source them. Read the harness's hook docs, or find out+empirically: register a throwaway session-start hook that dumps its environment+and emits a marker, then observe which env var identifies the harness and+whether/how the harness ingests your stdout. Pin these down before writing the+real branch.++**Shape B — assemble the string in code, then inject as a user message.** Here+you build the bootstrap yourself: read `SKILL.md`, strip its YAML frontmatter,+and assemble `<EXTREMELY_IMPORTANT>` + a short preamble that the skill is already+loaded and must not be re-invoked + the stripped body + the inline tool mapping ++`</EXTREMELY_IMPORTANT>`. One subtlety the references disagree on: OpenCode's+preamble says "do NOT use the skill tool…" (assumes a `skill` tool exists), while+pi's just says "do not try to load using-superpowers again." If your harness has+no skill tool, use pi's wording, not OpenCode's.++Inject the result as a **user-role message, not a system message** — system+messages bloat tokens when repeated every turn (#750) and multiple system+messages break some models (#894). Three things you must replicate:++- **Dedup guard.** The lifecycle callback can fire repeatedly (OpenCode's+ transform runs on *every* agent step; pi's `context` fires per turn). Before+ injecting, check whether a bootstrap marker is already present and skip if so.+ (The references pick different markers — pi a custom string, OpenCode the+ `EXTREMELY_IMPORTANT` tag; matching the tag is more robust since it needs no+ harness-specific constant.) Cache the bootstrap content at module level so+ you're not re-reading and re-parsing `SKILL.md` on every call (#1202).+- **Compaction.** If the harness compacts/summarizes history, re-inject+ afterward. pi sets an `injectBootstrap` flag on `session_start` and+ `session_compact`, clears it on `agent_end`, and inserts the message *after*+ any leading compaction-summary messages. OpenCode relies on its per-step+ re-injection plus the dedup guard.+- **Message-object shape is per-harness — discover yours, don't copy a literal.**+ The two references use *incompatible* shapes: pi builds+ `{ role, content: [{ type, text }], timestamp }`; OpenCode manipulates+ `message.info.role` and `message.parts[]`. Find your harness's message shape+ from its API; copying a reference's object literal verbatim will fail silently.++**Shape C — point your extension's context file at the bootstrap; assemble+nothing.** There is no injector, so you do *not* strip frontmatter or build a+wrapped string. The context file your extension ships (declared by the manifest —+*not* the user's own global file) pulls in two things: the `using-superpowers`+skill and the harness's tool-mapping reference. `GEMINI.md`+does this with two `@`-includes (`@./skills/using-superpowers/SKILL.md` and+`@./skills/using-superpowers/references/<harness>-tools.md`); the harness loads+them raw, frontmatter and all, and `SKILL.md` already carries its own+`<EXTREMELY-IMPORTANT>` block internally. If your harness has no include syntax,+inline the content into the instructions file instead. Gemini ships **no**+"already loaded, don't re-invoke" preamble — for an `@`-include harness the+content is the active instruction set, not a skill the model would re-load. If+you find your harness does try to re-invoke, add that note as a literal line in+the instructions file (you have no code to add it any other way).++### Step 4 — Write the tool mapping++Translate the action vocabulary into the harness's real tools. Cover every one+of these actions (omit only what genuinely doesn't apply):++- read a file+- create / edit / delete a file (one `apply_patch`-style tool, or separate+ write/edit?)+- run a shell command+- search file contents / find files by name (grep, glob)+- fetch a URL / web search+- **dispatch a subagent**, including how to pass the agent type — and any config+ flag needed to enable it+- **create / update todos** (treat older `TodoWrite` references as this action)+- **invoke a skill** — see Step 5++**Get the real tool names from the harness; never invent them.** If the docs+don't list them, the authoritative source is the harness itself: in a live+session, ask the model to "list the exact machine names of every tool you can+call, one per line" and use what it reports.++**How the harness finds the `skills/` directory is itself per-harness** — confirm+it, don't assume. Possibilities: a manifest `skills` path field (Codex's+`"skills": "./skills/"`); a *co-located* `skills/` the harness auto-scans (where a+path field is **ignored** — one real harness only scanned a `skills/` sitting next+to `plugin.json`); an API/registration call (OpenCode, pi); or you stage an+install dir that pairs the manifest with a **symlink to the repo's `skills/`** and+point the installer at the staging dir (verify the installer *dereferences* the+symlink and copies the real files — confirm with `agy plugin validate`/`install`+or the equivalent before relying on it). A `skills` path field is *not* portable.++Where the mapping lives depends on shape:++- **Shape A:** put it in `skills/using-superpowers/references/<harness>-tools.md`.+ The agent reaches it from the bootstrap — `SKILL.md`'s "Platform Adaptation"+ section links the per-harness references files. (Shape A harnesses have no+ instructions file; the mapping is *not* inlined into the hook output.)+- **Shape B:** the mapping is typically inlined into the bootstrap string you+ inject (see the `toolMapping` constant in `superpowers.js`). pi keeps it in+ *both* places — `piToolMapping()` inline **and** `references/pi-tools.md`. If+ you maintain it in two places, update both, or the port is half-done.+- **Shape C:** put it in `references/<harness>-tools.md` and pull it into the+ always-loaded instructions file (e.g. `GEMINI.md` `@`-includes+ `gemini-tools.md`).++You may also add a one-line pointer to your harness in `SKILL.md`'s "Platform+Adaptation" section so an agent reading the bootstrap knows where its mapping+lives. This is the one edit to a `SKILL.md` a port may make — and only because+that section is a pointer list, not behavior-shaping content. It does not violate+the "don't edit skill bodies" rule (Part 1); do not touch anything else in any+skill. (The list is a convenience pointer, not an exhaustive registry — not every+harness is listed.)++### Step 5 — Handle a harness with no native skill tool++`using-superpowers/SKILL.md` tells the model to *never read skill files manually+with file tools — always use your platform's skill-loading mechanism.* The point+is "don't bypass the mechanism," not "never use file-read." What counts as "your+platform's mechanism" depends on the harness — and for a harness with no skill+tool, the documented mechanism *is* reading `SKILL.md`. So reading it there+honors the rule rather than breaking it. Distinguish three cases:++1. **Native `Skill`-style tool** (Claude Code, Copilot CLI, Gemini's+ `activate_skill`): point the mapping at that tool.+2. **Native skill *discovery* but no `Skill` tool** (pi, Antigravity): the harness+ can find and list skills, but the model can't call a tool to load one. Get the+ skills installed where the harness scans (pi registers via `resources_discover`+ → `skillPaths`; OpenCode via its `config` hook; `agy plugin install` copies+ them in), and tell the model to load a skill by **reading its `SKILL.md` with+ the file-read tool when the skill applies** — the sanctioned mechanism here,+ the way `references/pi-tools.md` states it.++ **For the bootstrap itself, prefer a declared context file (Part 6).** If the+ harness has a `contextFileName`-style manifest field — as Antigravity does —+ ship a generated context file through the installer: it's guaranteed-loaded and+ carries both the `using-superpowers` content and the tool mapping. That is the+ strong, preferred path.++ **Fallback — the surfaced skill index.** If there's no context-file field but+ the harness surfaces each installed skill's name + description at session start,+ you need *neither* a built index nor a runtime-list instruction — the harness+ is the index, and `using-superpowers`'s own surfaced description can be what+ triggers the model to load it. This is softer than a declared context file;+ two things it does **not** give you, versus a context file / hook / in-process+ injector — account for both:+ - **It bootstraps *triggering*, not the *tool mapping*.** An injector prepends+ `<harness>-tools.md` alongside `using-superpowers` every session. Here nothing+ injects the mapping — the model only sees skill *descriptions* and must *read*+ your `references/<harness>-tools.md` when it needs tool names. It works+ because skills name actions (the model reads the mapping when it acts), but+ it's softer than injection. Make sure the mapping is reachable from what the+ model loads — e.g. linked from `SKILL.md`'s Platform Adaptation section and+ installed alongside the skills — not just sitting in the repo.+ - **There's no structural guarantee the trigger fires.** No `<EXTREMELY_IMPORTANT>`+ wrapper, no dedup, no re-injection after compaction — firing depends on the+ model choosing to act on a description it sees in the index. This is exactly+ why the acceptance test is mandatory here: it is the *only* guarantee, so run+ it on the model(s) your users will actually use, not just the strongest one.+3. **No skill system at all:** there is nothing to register, and the *only*+ mechanism is the model reading `SKILL.md` on demand. But the model can't read+ what it can't find: `using-superpowers/SKILL.md` does **not** enumerate the+ available skills, so on its own the model won't know which skills exist or+ their triggers. You must supply a discovery path. Two options, and they differ+ in durability: (a) generate a skill index (each `skills/*/SKILL.md`'s `name` ++ `description` frontmatter) and place it *inside* the `<EXTREMELY_IMPORTANT>`+ wrapper alongside the tool mapping (Shape B recipe above) so it's covered by+ the dedup guard — but a build-time index goes stale as skills are added; or+ (b) instruct the model to list `skills/*/SKILL.md` at runtime and read their+ frontmatter to find a match — slower but never stale. Prefer (b) unless you+ have a reason not to. Without either, a no-skill-system port loads the+ bootstrap but silently never triggers any other skill.++In cases 2 and 3, say plainly in your tool mapping that reading `SKILL.md` is the+blessed path, so the model doesn't think it's violating the "never read skill+files" rule. Don't go hunting for a `skillPaths`-style registration API in a+harness that has no skill system — case 3 has none.++### Step 6 — Add tests++Match the existing per-harness test style:++- **Shape A:** assert the hook's stdout has the exact JSON shape your harness+ consumes, and that it contains the bootstrap. See `tests/hooks/test-session-start.sh`,+ which validates each harness's output shape.+- **Shape B:** a unit test that fakes the harness's plugin API and asserts the+ lifecycle handlers register, the bootstrap injects once, the dedup guard+ works, and (if relevant) compaction re-injection works. See+ `tests/pi/test-pi-extension.mjs`. Add an isolated-install integration check in+ the style of `tests/opencode/`.+- If the bootstrap is cached, test that the cache behaves when the file is+ missing (see the OpenCode caching tests).++These automated tests cover the wiring; the live tmux run in Step 7 is what+proves the integration actually triggers skills.++### Step 7 — Install locally, then drive a live instance to verify++You cannot confirm a port works by reading code. You have to run the harness with+your in-progress port loaded and watch a real session — which is also how you+produce the transcript the PR requires.++**Install locally.** Point a *local* instance of the harness at your working+tree, not a published build:++- **Shape A / C:** install the plugin/extension from this repo's local path (or+ symlink its directory into wherever the harness looks). Find the harness's+ "install from a local directory / git checkout" path in its docs.+- **Shape B:** register the local module — e.g. an `opencode.json` `plugin`+ entry pointing at the local path, or pi resolving the `package.json` fields+ from the repo.++Reinstall after each change and restart the harness, since the bootstrap loads at+startup.++**Drive it with tmux.** Most harnesses are interactive REPLs/TUIs that can't be+driven by piping stdin, so run the harness inside a detached tmux session and+control it with `send-keys` / `capture-pane`. A harness may advertise a+non-interactive "run one prompt" mode (e.g. `opencode run "..."`) — try it for the+quick smoke check, but **don't depend on it**: these modes are frequently flaky,+auth-gated, or trust-gated (one real harness's `--print` mode hung and timed out+with no output every time). Be ready to do *everything*, including the smoke+check, through tmux.++**Clear the gates first, or tmux stalls silently.** Many harnesses block on+first-run onboarding, a "do you trust this folder?" prompt, a sandbox mode, or a+permission gate — and a detached tmux session will just sit there with no error+while it waits. Before the run, pre-trust your scratch directory (in the harness's+settings/config) or be prepared to answer those prompts via `send-keys`, and+account for the harness's startup time in your first `sleep`.++```bash+# 1. Launch the harness detached, in a throwaway project dir+mkdir -p /tmp/port-smoke+tmux new-session -d -s port-test -c /tmp/port-smoke '<harness-launch-command>'++# 2. Let it initialize — real TUIs take longer than you think (10s+ with a model+# handshake); tune this. THEN capture and clear any blocking modal before you+# type a prompt: first-run onboarding and "trust this folder?" are modal, so+# keystrokes sent during them select menu items instead of typing your prompt.+sleep 12+tmux capture-pane -t port-test -p # onboarding / trust prompt? answer it via send-keys first+# (e.g. tmux send-keys -t port-test Enter # to accept a trust prompt — inspect before assuming)++# 3. Smoke check: does the model know it has superpowers?+# Send the text and Enter as SEPARATE send-keys with a beat between them —+# sending them together races on some TUIs (Enter arrives before the text lands).+tmux send-keys -t port-test 'What are your superpowers?'; sleep 0.4; tmux send-keys -t port-test Enter+sleep 5+tmux capture-pane -t port-test -p # reply should show it knows its skills++# 4. Acceptance test: exact prompt (note the escaped apostrophe), fresh session+tmux send-keys -t port-test 'Let'\''s make a react todo list'; sleep 0.4; tmux send-keys -t port-test Enter+# poll until the turn finishes — re-capture every few seconds, don't capture once+sleep 8+tmux capture-pane -t port-test -p # PASS = brainstorming triggers BEFORE any code++# 5. Save the transcript for the PR, then clean up+tmux capture-pane -t port-test -p > /tmp/port-smoke/transcript.txt+tmux kill-session -t port-test+```++tmux gotchas that bite here: wait after launch before the first capture; send the+prompt text and `Enter` as *separate* `send-keys` calls with a short `sleep`+between them (sending them together races on some TUIs), and `Enter` is a key name+not `\n`; the agent's turn takes time, so **poll `capture-pane` in a loop** rather+than capturing once; `capture-pane` shows only the visible pane, so for a long+conversation use the harness's own transcript/log file as the record of truth;+always `kill-session` when done.++If the smoke check shows the model *doesn't* know it has superpowers, the+bootstrap isn't loading — fix that before bothering with the acceptance test.++---++## Part 6 — Distribution and release++A working integration in this repo isn't usable until a real user can install+it. Distribution differs per harness ecosystem — find yours:++| Channel | Example | What you do |+|---|---|---|+| Native plugin marketplace | Claude Code | Register in `.claude-plugin/marketplace.json`; users `/plugin install`. The external `superpowers-marketplace` repo is the source of truth users install from — see the release steps in `CLAUDE.md`. |+| External marketplace fork, synced by script | Codex | `scripts/sync-to-codex-plugin.sh` rsyncs the tracked plugin files into a separate fork repo and opens a PR. Read its include/exclude list so you ship the right tree (it deliberately drops repo-internal dirs and other harnesses' dotdirs). |+| Git-URL extension install | Gemini, OpenCode | Users install from a git URL (`gemini extensions install …`; an `opencode.json` `plugin` array entry). Document the exact command. |+| Package-manifest fields | pi | Declared through fields in the repo-root `package.json`; users install via the harness's package command. |+| Local installer (plugin install) | Antigravity (`agy`) | A small `install.sh` that runs the harness's own `agy plugin install` against a staging dir holding the manifest, the skills, and a generated `contextFileName` context file (the bootstrap). Everything arrives through the install mechanism — *not* by editing the user's config (see below). |++Then:++- **A plugin installer may silently strip *undeclared* files — so make the+ bootstrap a file the installer *recognizes*, never a user-config edit.** A+ `plugin install` typically copies only the components it knows about+ (skills/agents/commands/mcp/hooks/context) and discards anything else, so a+ context file the manifest doesn't declare just vanishes from the install. The+ fix is **not** to give up and write into the user's config (**rule 2**) — it's+ to declare the bootstrap as a recognized component. In escalation order:+ - **Ship a context file the manifest declares.** If the harness has a+ `contextFileName`-style field (an extension-declared file it loads every+ session), that is the strongest clean bootstrap: declare it, and the installer+ preserves it *and* the harness loads it. Generate it at install time from the+ live `using-superpowers/SKILL.md` + the tool mapping (wrapped in+ `<EXTREMELY_IMPORTANT>`) so the installed bootstrap never drifts. This is what+ `.antigravity-plugin/install.sh` does — `agy plugin install` reports+ `✔ context : ANTIGRAVITY.md`, and a clean session reads `using-superpowers`'s+ SKILL.md, loads `brainstorming`, and enters the brainstorming flow before any+ code. **Verify with a marker** that the installer keeps the file and the+ harness loads it: one porter wrongly concluded it couldn't, because they+ shipped the file *without* declaring `contextFileName` and it was stripped as+ unrecognized.+ - **Otherwise lean on the installed `using-superpowers` skill itself.** If the+ harness surfaces each installed skill's name + description at session start,+ the `using-superpowers` description ("Use when starting any conversation…")+ can prompt the model to load it — installing the skill *is* the bootstrap.+ Softer (no guaranteed wrapper; it carries triggering but not the tool mapping+ — see Step 5), so prefer the declared context file when available.+ - If neither works, the harness cannot be cleanly supported yet — **say so**+ and raise it, rather than hand-editing the user's config.++- **Write install docs.** A `docs/README.<harness>.md` and/or a+ `.<harness>/INSTALL.md` (see `docs/README.opencode.md` and+ `.opencode/INSTALL.md`), plus an install section in the top-level `README.md`.+ The only supported install action is **running the harness's own install+ command** (`agy plugin install`, `gemini extensions install`, `/plugin+ install`, etc.). Hand-copying skill files and editing the user's global/personal+ config are *both* off-limits (rule 2 / the PR rules). If the harness has no+ install command at all — its only surface is a user-owned config file — then it+ fails the "deliver via install mechanism" rule, and you should raise that rather+ than ship an installer that edits the user's files.+- **Register the version.** If your harness introduces a *new* versioned+ manifest, add its path and version field to `.version-bump.json` so+ `scripts/bump-version.sh` keeps it in lockstep (read that file to see what's+ currently tracked). A new manifest that isn't registered there will ship a+ stale version. If your harness instead rides an already-tracked file — pi+ declares itself in the repo-root `package.json`, which is already listed —+ there's nothing new to add.+- **If no existing channel fits, you're standing up a new one.** None of the four+ rows may match your harness. If it needs a Codex-style external fork sync,+ `scripts/sync-to-codex-plugin.sh` is the template to clone (note its anchored+ include/exclude list and its PR automation). And whenever you add a new+ per-harness directory, add it to the *other* harnesses' sync excludes (e.g. the+ EXCLUDES list in `sync-to-codex-plugin.sh`) so your dotdir doesn't leak into+ their distributions.++---++## Part 7 — Cross-platform / Windows++Only relevant to the shell-hook shape. `hooks/run-hook.cmd` is a polyglot: a+single file that's valid as both a Windows batch script and a Unix shell script.+On Windows, `cmd.exe` runs the batch portion, which locates `bash` (Git for+Windows, then `bash` on PATH) and runs the named hook script; if no bash is+found it exits cleanly so the harness still works, just without injection. On+Unix, the leading `:` makes the batch block a no-op and the shell runs the+script directly.++Two rules this enforces, which you must respect:++- **Hook scripts are extensionless** (`session-start`, not `session-start.sh`).+ Claude Code's Windows handling prepends `bash` to any command containing+ `.sh`, which would double-invoke. Name your hook script without an extension.+- Don't write per-OS variants of the hook script. One extensionless bash script+ plus the polyglot wrapper covers all three platforms.++`hooks/run-hook.cmd` itself is the authoritative implementation — read it.+(`docs/windows/polyglot-hooks.md` covers the background and rationale but+describes an earlier per-script `.cmd`/`.sh` variant, so trust the code over that+doc where they differ.)++---++## Part 8 — Submitting the PR++- Target the **`dev`** branch. One harness per PR.+- Fill in the PR template's **"New harness support"** section and paste the+ complete acceptance-test transcript (the "Let's make a react todo list"+ session showing `brainstorming` auto-triggering). A PR without this proof will+ be closed.+- Superpowers is a zero-dependency plugin. Don't add a third-party runtime+ dependency. Adding a new harness is the one carve-out the contributor rules+ allow, and even then keep it to what the integration strictly requires —+ type-only imports that compile away are fine; runtime packages are not.+- Don't touch skill bodies (Part 1). If you found yourself editing a `SKILL.md`+ to make the port work, the fix belongs in your tool mapping instead.++---++## Appendix A — Reference integrations (current)++Use this as the live index; when in doubt, read the files, not this table.++| Harness | Entry point | Bootstrap mechanism | Tool mapping | Tests | Distribution |+|---|---|---|---|---|---|+| Claude Code | `.claude-plugin/plugin.json` + `hooks/hooks.json` | shell hook → `hooks/session-start` (`hookSpecificOutput.additionalContext`) | native `Skill` tool; `references/claude-code-tools.md` | `tests/hooks/` | marketplace |+| Codex | `.codex-plugin/plugin.json` + `hooks/hooks-codex.json` | shell hook → `hooks/session-start-codex` | `references/codex-tools.md` | `tests/codex-plugin-sync/`, `tests/hooks/` | fork sync (`scripts/sync-to-codex-plugin.sh`) |+| Cursor | `.cursor-plugin/plugin.json` + `hooks/hooks-cursor.json` | shell hook → `hooks/session-start` (`additional_context`) | `references/claude-code-tools.md` | `tests/hooks/` | hand-authored |+| Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | `references/copilot-tools.md` | `tests/hooks/` | — |+| Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |+| OpenCode | `.opencode/plugins/superpowers.js` (declared via root `package.json` `main`) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` plugin git URL |+| pi | `.pi/extensions/superpowers.ts` | in-process: `resources_discover` registers skills; `context` event injects user message; lifecycle-flag + compaction-aware | `piToolMapping()` inline **and** `references/pi-tools.md` | `tests/pi/` | repo-root `package.json` fields |++## Appendix B — Gotchas that have bitten porters++- **Opt-in isn't a port.** If your human partner has to do anything per session+ to get Superpowers, the acceptance test fails. Re-read Part 2.+- **Wrong JSON field → silent failure or double injection.** Shape A only.+ Confirm the exact field/nesting; Claude Code reads two fields without dedup.+- **Hook-config schema varies per harness.** Shape A. Cursor's `hooks-cursor.json`+ looks nothing like the Claude/Codex one (`version`, lowercase `sessionStart`,+ relative command, no `matcher`/`type`/`async`). Match the closest existing file.+- **Plugin-root env var differs per harness.** Shape A. The hook command uses+ `${CLAUDE_PLUGIN_ROOT}` (Claude), `${PLUGIN_ROOT}` (Codex), or a relative path+ (Cursor). Use what your harness exports; the script re-derives the root itself.+- **System-message injection.** Shape B injects a *user* message on purpose+ (#750, #894). Don't "fix" it to a system message.+- **Per-step vs per-turn callbacks.** OpenCode fires every step (per-call dedup+ guard); pi fires per turn (lifecycle flag + `agent_end` reset). Copying one+ harness's dedup strategy onto the other's callback frequency breaks injection.+- **Message-object shape is per-harness.** Shape B. pi and OpenCode use+ incompatible shapes; discover yours, don't copy a reference's object literal.+- **Hunting for a skill-registration API that doesn't exist.** A harness with no+ skill system (not just no `Skill` tool) has nothing to register — the model+ reads `SKILL.md` on demand. Don't assume a `skillPaths` equivalent exists.+- **Mapping in two places.** For in-process plugins the mapping may live both+ inline and in a `references/` file (pi). Update both.+- **The "never read skill files" line.** It means "don't bypass your platform's+ skill-loading mechanism," not "never use file-read." On a no-skill-tool harness+ that mechanism *is* reading `SKILL.md` — say so explicitly in the mapping+ (Part 5).+- **`.sh` on Windows.** Keep hook scripts extensionless (Part 7).+- **Unregistered version.** A new manifest not added to `.version-bump.json`+ ships stale (Part 6).+- **Editing skills to fit the harness.** Never. The fix goes in the tool mapping.