From 11ad1f48297a41c25f5e89e43e7d70c38b473d88 Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Tue, 5 May 2026 18:26:21 -0700 Subject: [PATCH] Phase E: action-language tool vocabulary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace Claude-Code-specific tool names in skill prose, prompt templates, and OpenCode-facing docs with action-language descriptions that resolve to each runtime's native tool via the per-platform refs. Changes by category: - Prose mentions ("Use TodoWrite to track...", "Use Task tool with general-purpose type") → action language ("Track each item as a todo", "Dispatch a general-purpose subagent") - Prompt template headers (6 files): "Task tool (general-purpose):" → "Subagent (general-purpose):" — preserves the type information without naming Claude Code's specific dispatch tool - DOT flowchart node labels: "Invoke Skill tool" → "Invoke the skill"; "Create TodoWrite todo per item" → "Create a todo per item" - OpenCode INSTALL.md and docs/README.opencode.md: replace the old "TodoWrite → todowrite, Task → @mention" mapping (which both taught a vocabulary skills no longer use AND was wrong about @mention being a real OpenCode syntax) with an action-language mapping verified against the installed OpenCode CLI's tool inventory. The platform-tools refs landed in Phase B already document each runtime's resolution; skills now speak in the actions those refs map. Tool names that genuinely belong only in the per-platform dispatch section ("In Claude Code: Use the `Skill` tool") and the Claude-Code-specific Bash run_in_background flag note in visual-companion remain — those are intentional carve-outs. --- .opencode/INSTALL.md | 14 +++++++++----- docs/README.opencode.md | 15 ++++++++++----- .../spec-document-reviewer-prompt.md | 2 +- skills/requesting-code-review/SKILL.md | 2 +- skills/requesting-code-review/code-reviewer.md | 2 +- skills/subagent-driven-development/SKILL.md | 12 ++++++------ .../code-quality-reviewer-prompt.md | 2 +- .../implementer-prompt.md | 2 +- .../spec-reviewer-prompt.md | 2 +- .../plan-document-reviewer-prompt.md | 2 +- skills/writing-skills/persuasion-principles.md | 6 +++--- 11 files changed, 35 insertions(+), 26 deletions(-) diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md index 94c34151..36d588b4 100644 --- a/.opencode/INSTALL.md +++ b/.opencode/INSTALL.md @@ -98,11 +98,15 @@ Then use the installed package path in `opencode.json`: ### Tool mapping -When skills reference Claude Code tools: -- `TodoWrite` → `todowrite` -- `Task` with subagents → `@mention` syntax -- `Skill` tool → OpenCode's native `skill` tool -- File operations → your native tools +Skills speak in actions ("create a todo", "dispatch a subagent", "read a file"). On OpenCode these resolve to: + +- "Create a todo" / "mark complete in todo list" → `todowrite` +- `Subagent (general-purpose):` template → `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration) +- "Invoke a skill" → OpenCode's native `skill` tool +- "Read a file" / "create a file" / "edit a file" → `read`, `write`, `edit` +- "Run a shell command" → `bash` +- "Search file contents" / "find files by name" → `grep`, `glob` +- "Fetch a URL" / "search the web" → `webfetch`, `websearch` ## Getting Help diff --git a/docs/README.opencode.md b/docs/README.opencode.md index 95120669..16cc4df6 100644 --- a/docs/README.opencode.md +++ b/docs/README.opencode.md @@ -104,12 +104,17 @@ The plugin does two things: ### Tool Mapping -Skills written for Claude Code are automatically adapted for OpenCode: +Skills speak in actions rather than naming any one runtime's tools. On OpenCode these resolve to: -- `TodoWrite` → `todowrite` -- `Task` with subagents → OpenCode's `@mention` system -- `Skill` tool → OpenCode's native `skill` tool -- File operations → Native OpenCode tools +- "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 +- "Read a file" / "create a file" / "edit a file" → `read`, `write`, `edit` +- "Run a shell command" → `bash` +- "Search file contents" / "find files by name" → `grep`, `glob` +- "Fetch a URL" / "search the web" → `webfetch`, `websearch` + +(Verified against the installed OpenCode CLI's tool inventory.) ## Troubleshooting diff --git a/skills/brainstorming/spec-document-reviewer-prompt.md b/skills/brainstorming/spec-document-reviewer-prompt.md index 35acbb61..60993129 100644 --- a/skills/brainstorming/spec-document-reviewer-prompt.md +++ b/skills/brainstorming/spec-document-reviewer-prompt.md @@ -7,7 +7,7 @@ Use this template when dispatching a spec document reviewer subagent. **Dispatch after:** Spec document is written to docs/superpowers/specs/ ``` -Task tool (general-purpose): +Subagent (general-purpose): description: "Review spec document" prompt: | You are a spec document reviewer. Verify this spec is complete and ready for planning. diff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.md index 34b83404..0bd03e89 100644 --- a/skills/requesting-code-review/SKILL.md +++ b/skills/requesting-code-review/SKILL.md @@ -31,7 +31,7 @@ HEAD_SHA=$(git rev-parse HEAD) **2. Dispatch code reviewer subagent:** -Use Task tool with `general-purpose` type, fill template at `code-reviewer.md` +Dispatch a `general-purpose` subagent, filling the template at `code-reviewer.md` **Placeholders:** - `{DESCRIPTION}` - Brief summary of what you built diff --git a/skills/requesting-code-review/code-reviewer.md b/skills/requesting-code-review/code-reviewer.md index 525e4b47..eb3ad887 100644 --- a/skills/requesting-code-review/code-reviewer.md +++ b/skills/requesting-code-review/code-reviewer.md @@ -5,7 +5,7 @@ Use this template when dispatching a code reviewer subagent. **Purpose:** Review completed work against requirements and code quality standards before it cascades into more work. ``` -Task tool (general-purpose): +Subagent (general-purpose): description: "Review code changes" prompt: | You are a Senior Code Reviewer with expertise in software architecture, diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index ea7ac8fd..436a7dda 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -57,15 +57,15 @@ digraph process { "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box]; "Code quality reviewer subagent approves?" [shape=diamond]; "Implementer subagent fixes quality issues" [shape=box]; - "Mark task complete in TodoWrite" [shape=box]; + "Mark task complete in todo list" [shape=box]; } - "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box]; + "Read plan, extract all tasks with full text, note context, create todos" [shape=box]; "More tasks remain?" [shape=diamond]; "Dispatch final code reviewer subagent for entire implementation" [shape=box]; "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; - "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)"; + "Read plan, extract all tasks with full text, note context, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)"; "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?"; "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"]; "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)"; @@ -78,8 +78,8 @@ digraph process { "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?"; "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"]; "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"]; - "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"]; - "Mark task complete in TodoWrite" -> "More tasks remain?"; + "Code quality reviewer subagent approves?" -> "Mark task complete in todo list" [label="yes"]; + "Mark task complete in todo list" -> "More tasks remain?"; "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"]; "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"]; "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch"; @@ -132,7 +132,7 @@ You: I'm using Subagent-Driven Development to execute this plan. [Read plan file once: docs/superpowers/plans/feature-plan.md] [Extract all 5 tasks with full text and context] -[Create TodoWrite with all tasks] +[Create todos for all tasks] Task 1: Hook installation script diff --git a/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/skills/subagent-driven-development/code-quality-reviewer-prompt.md index 51f901a5..99d91ed1 100644 --- a/skills/subagent-driven-development/code-quality-reviewer-prompt.md +++ b/skills/subagent-driven-development/code-quality-reviewer-prompt.md @@ -7,7 +7,7 @@ Use this template when dispatching a code quality reviewer subagent. **Only dispatch after spec compliance review passes.** ``` -Task tool (general-purpose): +Subagent (general-purpose): Use template at requesting-code-review/code-reviewer.md DESCRIPTION: [task summary, from implementer's report] diff --git a/skills/subagent-driven-development/implementer-prompt.md b/skills/subagent-driven-development/implementer-prompt.md index 400c1034..8882a1ec 100644 --- a/skills/subagent-driven-development/implementer-prompt.md +++ b/skills/subagent-driven-development/implementer-prompt.md @@ -3,7 +3,7 @@ Use this template when dispatching an implementer subagent. ``` -Task tool (general-purpose): +Subagent (general-purpose): description: "Implement Task N: [task name]" prompt: | You are implementing Task N: [task name] diff --git a/skills/subagent-driven-development/spec-reviewer-prompt.md b/skills/subagent-driven-development/spec-reviewer-prompt.md index ab5ddb8a..4ac2d7b4 100644 --- a/skills/subagent-driven-development/spec-reviewer-prompt.md +++ b/skills/subagent-driven-development/spec-reviewer-prompt.md @@ -5,7 +5,7 @@ Use this template when dispatching a spec compliance reviewer subagent. **Purpose:** Verify implementer built what was requested (nothing more, nothing less) ``` -Task tool (general-purpose): +Subagent (general-purpose): description: "Review spec compliance for Task N" prompt: | You are reviewing whether an implementation matches its specification. diff --git a/skills/writing-plans/plan-document-reviewer-prompt.md b/skills/writing-plans/plan-document-reviewer-prompt.md index 2db28067..1c12c1d6 100644 --- a/skills/writing-plans/plan-document-reviewer-prompt.md +++ b/skills/writing-plans/plan-document-reviewer-prompt.md @@ -7,7 +7,7 @@ Use this template when dispatching a plan document reviewer subagent. **Dispatch after:** The complete plan is written. ``` -Task tool (general-purpose): +Subagent (general-purpose): description: "Review plan document" prompt: | You are a plan document reviewer. Verify this plan is complete and ready for implementation. diff --git a/skills/writing-skills/persuasion-principles.md b/skills/writing-skills/persuasion-principles.md index 9818a5f9..9756416a 100644 --- a/skills/writing-skills/persuasion-principles.md +++ b/skills/writing-skills/persuasion-principles.md @@ -33,7 +33,7 @@ LLMs respond to the same persuasion principles as humans. Understanding this psy **How it works in skills:** - Require announcements: "Announce skill usage" - Force explicit choices: "Choose A, B, or C" -- Use tracking: TodoWrite for checklists +- Use tracking: todos for checklists **When to use:** - Ensuring skills are actually followed @@ -80,8 +80,8 @@ LLMs respond to the same persuasion principles as humans. Understanding this psy **Example:** ```markdown -✅ Checklists without TodoWrite tracking = steps get skipped. Every time. -❌ Some people find TodoWrite helpful for checklists. +✅ Checklists without todo tracking = steps get skipped. Every time. +❌ Some people find a todo list helpful for checklists. ``` ### 5. Unity