summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/README.opencode.md4
-rw-r--r--docs/porting-to-a-new-harness.md15
2 files changed, 10 insertions, 9 deletions
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 35e8226..252e2b5 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -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`)
diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.md
index fa99a23..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
@@ -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