Skip to content

An agentic skills framework & software development methodology that works.

Add OpenCode support design document

Jesse Vincent5dd8871a1b23
diff --git a/docs/plans/2025-11-22-opencode-support-design.md b/docs/plans/2025-11-22-opencode-support-design.md
new file mode 100644
index 000000000..144f1cea2
--- /dev/null
+++ b/docs/plans/2025-11-22-opencode-support-design.md
@@ -0,0 +1,294 @@
+# OpenCode Support Design
+
+**Date:** 2025-11-22
+**Author:** Bot & Jesse
+**Status:** Design Complete, Awaiting Implementation
+
+## Overview
+
+Add full superpowers support for OpenCode.ai using a native OpenCode plugin architecture that shares core functionality with the existing Codex implementation.
+
+## Background
+
+OpenCode.ai is a coding agent similar to Claude Code and Codex. Previous attempts to port superpowers to OpenCode (PR #93, PR #116) used file-copying approaches. This design takes a different approach: building a native OpenCode plugin using their JavaScript/TypeScript plugin system while sharing code with the Codex implementation.
+
+### Key Differences Between Platforms
+
+- **Claude Code**: Native Anthropic plugin system + file-based skills
+- **Codex**: No plugin system → bootstrap markdown + CLI script
+- **OpenCode**: JavaScript/TypeScript plugins with event hooks and custom tools API
+
+### OpenCode's Agent System
+
+- **Primary agents**: Build (default, full access) and Plan (restricted, read-only)
+- **Subagents**: General (research, searching, multi-step tasks)
+- **Invocation**: Automatic dispatch by primary agents OR manual `@mention` syntax
+- **Configuration**: Custom agents in `opencode.json` or `~/.config/opencode/agent/`
+
+## Architecture
+
+### High-Level Structure
+
+1. **Shared Core Module** (`lib/skills-core.js`)
+ - Common skill discovery and parsing logic
+ - Used by both Codex and OpenCode implementations
+
+2. **Platform-Specific Wrappers**
+ - Codex: CLI script (`.codex/superpowers-codex`)
+ - OpenCode: Plugin module (`.opencode/plugin/superpowers.js`)
+
+3. **Skill Directories**
+ - Core: `~/.config/opencode/superpowers/skills/` (or installed location)
+ - Personal: `~/.config/opencode/skills/` (shadows core skills)
+
+### Code Reuse Strategy
+
+Extract common functionality from `.codex/superpowers-codex` into shared module:
+
+```javascript
+// lib/skills-core.js
+module.exports = {
+ extractFrontmatter(filePath), // Parse name + description from YAML
+ findSkillsInDir(dir, maxDepth), // Recursive SKILL.md discovery
+ findAllSkills(dirs), // Scan multiple directories
+ resolveSkillPath(skillName, dirs), // Handle shadowing (personal > core)
+ checkForUpdates(repoDir) // Git fetch/status check
+};
+```
+
+### Skill Frontmatter Format
+
+Current format (no `when_to_use` field):
+
+```yaml
+---
+name: skill-name
+description: Use when [condition] - [what it does]; [additional context]
+---
+```
+
+## OpenCode Plugin Implementation
+
+### Custom Tools
+
+**Tool 1: `use_skill`**
+
+Loads a specific skill's content into the conversation (equivalent to Claude's Skill tool).
+
+```javascript
+{
+ name: 'use_skill',
+ description: 'Load and read a specific skill to guide your work',
+ schema: z.object({
+ skill_name: z.string().describe('Name of skill (e.g., "superpowers:brainstorming")')
+ }),
+ execute: async ({ skill_name }) => {
+ const { skillPath, content, frontmatter } = resolveAndReadSkill(skill_name);
+ const skillDir = path.dirname(skillPath);
+
+ return `# ${frontmatter.name}
+# ${frontmatter.description}
+# Supporting tools and docs are in ${skillDir}
+# ============================================
+
+${content}`;
+ }
+}
+```
+
+**Tool 2: `find_skills`**
+
+Lists all available skills with metadata.
+
+```javascript
+{
+ name: 'find_skills',
+ description: 'List all available skills',
+ schema: z.object({}),
+ execute: async () => {
+ const skills = discoverAllSkills();
+ return skills.map(s =>
+ `${s.namespace}:${s.name}
+ ${s.description}
+ Directory: ${s.directory}
+`).join('\n');
+ }
+}
+```
+
+### Session Startup Hook
+
+When a new session starts (`session.started` event):
+
+1. **Inject using-superpowers content**
+ - Full content of the using-superpowers skill
+ - Establishes mandatory workflows
+
+2. **Run find_skills automatically**
+ - Display full list of available skills upfront
+ - Include skill directories for each
+
+3. **Inject tool mapping instructions**
+ ```markdown
+ **Tool Mapping for OpenCode:**
+ When skills reference tools you don't have, substitute:
+ - `TodoWrite` → `update_plan`
+ - `Task` with subagents → Use OpenCode subagent system (@mention)
+ - `Skill` tool → `use_skill` custom tool
+ - Read, Write, Edit, Bash → Your native equivalents
+
+ **Skill directories contain:**
+ - Supporting scripts (run with bash)
+ - Additional documentation (read with read tool)
+ - Utilities specific to that skill
+ ```
+
+4. **Check for updates** (non-blocking)
+ - Quick git fetch with timeout
+ - Notify if updates available
+
+### Plugin Structure
+
+```javascript
+// .opencode/plugin/superpowers.js
+const skillsCore = require('../../lib/skills-core');
+const path = require('path');
+const fs = require('fs');
+const { z } = require('zod');
+
+export const SuperpowersPlugin = async ({ client, directory, $ }) => {
+ const superpowersDir = path.join(process.env.HOME, '.config/opencode/superpowers');
+ const personalDir = path.join(process.env.HOME, '.config/opencode/skills');
+
+ return {
+ 'session.started': async () => {
+ const usingSuperpowers = await readSkill('using-superpowers');
+ const skillsList = await findAllSkills();
+ const toolMapping = getToolMappingInstructions();
+
+ return {
+ context: `${usingSuperpowers}\n\n${skillsList}\n\n${toolMapping}`
+ };
+ },
+
+ tools: [
+ {
+ name: 'use_skill',
+ description: 'Load and read a specific skill',
+ schema: z.object({
+ skill_name: z.string()
+ }),
+ execute: async ({ skill_name }) => {
+ // Implementation using skillsCore
+ }
+ },
+ {
+ name: 'find_skills',
+ description: 'List all available skills',
+ schema: z.object({}),
+ execute: async () => {
+ // Implementation using skillsCore
+ }
+ }
+ ]
+ };
+};
+```
+
+## File Structure
+
+```
+superpowers/
+├── lib/
+│ └── skills-core.js # NEW: Shared skill logic
+├── .codex/
+│ ├── superpowers-codex # UPDATED: Use skills-core
+│ ├── superpowers-bootstrap.md
+│ └── INSTALL.md
+├── .opencode/
+│ ├── plugin/
+│ │ └── superpowers.js # NEW: OpenCode plugin
+│ └── INSTALL.md # NEW: Installation guide
+└── skills/ # Unchanged
+```
+
+## Implementation Plan
+
+### Phase 1: Refactor Shared Core
+
+1. Create `lib/skills-core.js`
+ - Extract frontmatter parsing from `.codex/superpowers-codex`
+ - Extract skill discovery logic
+ - Extract path resolution (with shadowing)
+ - Update to use only `name` and `description` (no `when_to_use`)
+
+2. Update `.codex/superpowers-codex` to use shared core
+ - Import from `../lib/skills-core.js`
+ - Remove duplicated code
+ - Keep CLI wrapper logic
+
+3. Test Codex implementation still works
+ - Verify bootstrap command
+ - Verify use-skill command
+ - Verify find-skills command
+
+### Phase 2: Build OpenCode Plugin
+
+1. Create `.opencode/plugin/superpowers.js`
+ - Import shared core from `../../lib/skills-core.js`
+ - Implement plugin function
+ - Define custom tools (use_skill, find_skills)
+ - Implement session.started hook
+
+2. Create `.opencode/INSTALL.md`
+ - Installation instructions
+ - Directory setup
+ - Configuration guidance
+
+3. Test OpenCode implementation
+ - Verify session startup bootstrap
+ - Verify use_skill tool works
+ - Verify find_skills tool works
+ - Verify skill directories are accessible
+
+### Phase 3: Documentation & Polish
+
+1. Update README with OpenCode support
+2. Add OpenCode installation to main docs
+3. Update RELEASE-NOTES
+4. Test both Codex and OpenCode work correctly
+
+## Next Steps
+
+1. **Create isolated workspace** (using git worktrees)
+ - Branch: `feature/opencode-support`
+
+2. **Follow TDD where applicable**
+ - Test shared core functions
+ - Test skill discovery and parsing
+ - Integration tests for both platforms
+
+3. **Incremental implementation**
+ - Phase 1: Refactor shared core + update Codex
+ - Verify Codex still works before moving on
+ - Phase 2: Build OpenCode plugin
+ - Phase 3: Documentation and polish
+
+4. **Testing strategy**
+ - Manual testing with real OpenCode installation
+ - Verify skill loading, directories, scripts work
+ - Test both Codex and OpenCode side-by-side
+ - Verify tool mappings work correctly
+
+5. **PR and merge**
+ - Create PR with complete implementation
+ - Test in clean environment
+ - Merge to main
+
+## Benefits
+
+- **Code reuse**: Single source of truth for skill discovery/parsing
+- **Maintainability**: Bug fixes apply to both platforms
+- **Extensibility**: Easy to add future platforms (Cursor, Windsurf, etc.)
+- **Native integration**: Uses OpenCode's plugin system properly
+- **Consistency**: Same skill experience across all platforms