rogee/superpowers
1
0
Fork 0
mirror of https://github.com/obra/superpowers.git synced 2026-07-02 07:29:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: re-anchor Shape A examples away from Codex

Browse Source
This commit is contained in:
Drew Ritter
2026-06-30 17:10:01 -07:00
parent 398f67a8b7
commit 00720702e4
1 changed files with 9 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/porting-to-a-new-harness.md
View File

@@ -90,7 +90,7 @@ every session, with no per-session opt-in by your human partner.** This is the
one non-negotiable capability. It can take any form: one non-negotiable capability. It can take any form:
- a **hook/event system** that runs a shell command at session start and reads - a **hook/event system** that runs a shell command at session start and reads
its stdout (Claude Code, Codex, Cursor, Copilot CLI), or its stdout (Claude Code, Cursor, Copilot CLI), or
- an **in-process plugin/extension** with a session-start or message lifecycle - an **in-process plugin/extension** with a session-start or message lifecycle
callback that can mutate the message array (OpenCode, pi), or callback that can mutate the message array (OpenCode, pi), or
- an **instructions-file** convention where the harness loads a context file that - an **instructions-file** convention where the harness loads a context file that
@@ -234,13 +234,13 @@ nesting differ per harness**.
- Reference: `hooks/session-start`, `hooks/run-hook.cmd`, and the per-harness - Reference: `hooks/session-start`, `hooks/run-hook.cmd`, and the per-harness
hook config `hooks/hooks.json` (Claude Code) and `hooks/hooks-cursor.json` hook config `hooks/hooks.json` (Claude Code) and `hooks/hooks-cursor.json`
(Cursor). (Cursor).
- Manifests: `.cursor-plugin/plugin.json` points the harness at `./skills/` and - Manifests: `.cursor-plugin/plugin.json` is the Shape A manifest example that
the right `hooks-*.json`. (Claude Code's `.claude-plugin/plugin.json` sets points the harness at `./skills/` and the right `hooks-*.json`. Claude Code's
neither field — it auto-discovers `skills/` and `hooks/hooks.json` by `.claude-plugin/plugin.json` sets neither field — it auto-discovers `skills/`
convention. Codex's `.codex-plugin/plugin.json` ships skills but declares an and `hooks/hooks.json` by convention. Do **not** copy Codex's
empty `hooks` object: Codex auto-discovers `hooks/hooks.json` when the field `.codex-plugin/plugin.json` for Shape A: it declares an empty `hooks` object
is absent, so the empty object suppresses that — Codex surfaces skills specifically to suppress Codex's `hooks/hooks.json` auto-discovery, because
natively and runs no session-start hook.) Codex surfaces skills natively and runs no session-start hook.
> **A hook *system* is not a session-start *event*.** A harness can have a > **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 > `hooks.json` mechanism — and even contain the literal string `SessionStart` in
@@ -311,7 +311,7 @@ patterns below are summaries; the code is the spec.
Create whatever the harness uses to recognize the plugin. Match the existing Create whatever the harness uses to recognize the plugin. Match the existing
ones in spirit: ones in spirit:
- **Shape A:** a `*-plugin/plugin.json` (see `.codex-plugin/plugin.json`) with - **Shape A:** a `*-plugin/plugin.json` (see `.cursor-plugin/plugin.json`) with
`name`, `version`, `description`, author/license/keywords, `"skills": `name`, `version`, `description`, author/license/keywords, `"skills":
"./skills/"`, and `"hooks": "./hooks/hooks-<harness>.json"`. Plus the "./skills/"`, and `"hooks": "./hooks/hooks-<harness>.json"`. Plus the
`hooks-<harness>.json` itself, registering a session-start hook whose command `hooks-<harness>.json` itself, registering a session-start hook whose command