summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/README.opencode.md10
-rw-r--r--docs/porting-to-a-new-harness.md23
-rw-r--r--docs/windows/polyglot-hooks.md10
3 files changed, 27 insertions, 16 deletions
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 3ffdd81..6509d84 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -111,7 +111,7 @@ V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.1"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.2"]
}
```
@@ -126,7 +126,7 @@ The plugin does two things, using host-flavor-specific APIs:
- **V2:** via the `setup()` function using `ctx.skill.transform()` (V2 native API, confirmed active at runtime)
2. **Injects bootstrap context** with a flavor-specific tool mapping: V1 sessions get the V1 tool names below, and V2 sessions get the V2 names.
- **V1:** via `experimental.chat.messages.transform` hook
- - **V2:** via `ctx.session.hook("context")` — the V2 equivalent (confirmed active at runtime)
+ - **V2:** via `ctx.session.hook()` on `context`, `compaction`, and `generate` — the V2 equivalent (confirmed active at runtime). Registering on all three keeps compaction requests on the same cached prompt prefix as normal turns.
Controller sessions receive the using-superpowers bootstrap in transient model
context. Delegated child sessions keep access to native skills but do not receive
@@ -148,7 +148,7 @@ Skills speak in actions rather than naming any one runtime's tools. The bootstra
- "Create a todo" / "mark complete in todo list" → `todowrite`
- `Subagent (general-purpose):` template → OpenCode's `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
-- "Invoke a skill" → OpenCode's native `skill` tool
+- "Invoke a skill" → OpenCode's native `skill` tool with the bare skill name (`superpowers:brainstorming` → `name: "brainstorming"`)
- "Read a file" → `read`
- "Create a file" / "edit a file" / "delete a file" → `apply_patch`
- "Run a shell command" → `bash`
@@ -159,7 +159,7 @@ Skills speak in actions rather than naming any one runtime's tools. The bootstra
- "Create a todo" → V2 has no todo tool of any kind; the mapping tells the model to track the plan in a markdown file (or the harness's plan facility) instead
- `Subagent (general-purpose):` template → OpenCode's `subagent` tool with `agent: "general"` (or `"explore"`); pass `sessionID` to continue a previous subagent
-- "Invoke a skill" → OpenCode's native `skill` tool
+- "Invoke a skill" → OpenCode's native `skill` tool with the bare skill id (`superpowers:brainstorming` → `id: "brainstorming"`)
- "Read a file" → `read`
- "Create, edit, or delete files" → use `patch` with `patchText` when available; otherwise use `write` to create or overwrite files, `edit` for targeted changes, and `shell` for deletion
- "Run a shell command" → `shell` (`command`, `workdir`, `timeout`, `background`)
@@ -234,7 +234,7 @@ package name, not a local directory.
### Bootstrap not appearing
- **V1:** Check OpenCode version supports `experimental.chat.messages.transform` hook. Restart OpenCode after config changes.
-- **V2:** The plugin uses `ctx.session.hook("context")` for bootstrap injection. Verify the plugin loaded via `opencode api get /api/plugin`. Restart with `opencode service restart` after config changes. The `opencode2` command may be available as an alias.
+- **V2:** The plugin uses `ctx.session.hook()` on `context`, `compaction`, and `generate` for bootstrap injection. Verify the plugin loaded via `opencode api get /api/plugin`. Restart with `opencode service restart` after config changes. The `opencode2` command may be available as an alias.
## Getting Help
diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.md
index f52cd70..a48ecdf 100644
--- a/docs/porting-to-a-new-harness.md
+++ b/docs/porting-to-a-new-harness.md
@@ -428,10 +428,9 @@ messages break some models (#894). Three things you must replicate:
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.
+ afterward. pi re-injects on every `context` call 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
@@ -519,8 +518,8 @@ honors the rule rather than breaking it. Distinguish three cases:
`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
+ skills installed where the harness scans (pi declares them in the package
+ manifest's `pi.skills`; 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.
@@ -810,8 +809,8 @@ Use this as the live index; when in doubt, read the files, not this table.
| Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | none needed (Claude Code–compatible tool surface) | `tests/hooks/` | — |
| Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |
| Kimi Code | `.kimi-plugin/plugin.json` | manifest `sessionStart.skill` loads `using-superpowers` | inline `skillInstructions` in manifest | `tests/kimi/` | marketplace or `/plugins install` GitHub URL |
-| OpenCode | `.opencode/plugins/superpowers.js` (root `package.json` `main` for package installs; root `index.js` re-export for the V2 directory form) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` (V1) / `session.hook("context")` (V2) injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` `plugin` (V1) / `plugins` (V2) 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 |
+| OpenCode | `.opencode/plugins/superpowers.js` (root `package.json` `main` for package installs; root `index.js` re-export for the V2 directory form) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` (V1) / `session.hook` on `context`/`compaction`/`generate` (V2) injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` `plugin` (V1) / `plugins` (V2) git URL |
+| pi | `.pi/extensions/superpowers.ts` | in-process: package manifest 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
@@ -827,9 +826,11 @@ Use this as the live index; when in doubt, read the files, not this table.
(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.
+- **Disarming injection after the first prompt.** If your harness's transform
+ output is not saved to session history (pi's `context` result is not), the
+ bootstrap must be injected into every provider request. A flag cleared on a
+ per-prompt event such as pi's `agent_end` drops the bootstrap after the first
+ prompt (#2083).
- **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
diff --git a/docs/windows/polyglot-hooks.md b/docs/windows/polyglot-hooks.md
index 3da01ae..d753d90 100644
--- a/docs/windows/polyglot-hooks.md
+++ b/docs/windows/polyglot-hooks.md
@@ -51,6 +51,7 @@ hooks/
{
"type": "command",
"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+ "powershell": "& \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
"shell": "bash",
"async": false
}
@@ -63,6 +64,15 @@ hooks/
The path is quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces.
+### The `powershell` key
+
+GitHub Copilot (the CLI and VS Code) on Windows runs hook commands through
+PowerShell regardless of the `shell` key (#2189), where a leading quoted path
+parses as a string expression and the trailing bareword is an error
+("Unexpected token 'session-start'"). Copilot uses the `powershell` key
+instead of `command` when it is present, and it gives the same dispatch with
+the `&` call operator. Claude Code ignores the key.
+
## How `run-hook.cmd` Works at a High Level
`run-hook.cmd` is a polyglot script: Windows treats the first block as batch