Skip to content

An agentic skills framework & software development methodology that works.

Phase E: action-language tool vocabulary

Jesse Vincentd7f47d350a5f
diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md
index 94c34151b..36d588b4a 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 951206692..16cc4df65 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 35acbb611..60993129d 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 34b834048..0bd03e89b 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 525e4b471..eb3ad887b 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 ea7ac8fd8..436a7dda2 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 51f901a5e..99d91ed1e 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 400c10347..8882a1ec4 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 ab5ddb8a5..4ac2d7b47 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 2db280678..1c12c1d61 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 9818a5f95..9756416a5 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