Skip to content

README.opencode.md

Latest commit

 

History

History
237 lines (157 loc) · 6.5 KB

README.opencode.md

File metadata and controls

237 lines (157 loc) · 6.5 KB

Superpowers-BD for OpenCode

Complete guide for using Superpowers-BD with OpenCode.ai.

Quick Install

Tell OpenCode:

Clone https://github.com/schlenks/superpowers-bd to ~/.config/opencode/superpowers-bd, run npm install in ~/.config/opencode/superpowers-bd/.opencode, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers-bd/.opencode/plugins/superpowers-bd.js to ~/.config/opencode/plugins/superpowers-bd.js, then restart opencode.

Manual Installation

Prerequisites

  • OpenCode.ai installed
  • Node.js installed
  • Git installed

Installation Steps

1. Install Superpowers-BD

mkdir -p ~/.config/opencode/superpowers-bd
git clone https://github.com/schlenks/superpowers-bd.git ~/.config/opencode/superpowers-bd
cd ~/.config/opencode/superpowers-bd/.opencode
npm install

2. Register the Plugin

OpenCode discovers plugins from ~/.config/opencode/plugins/. Create a symlink:

mkdir -p ~/.config/opencode/plugins
ln -sf ~/.config/opencode/superpowers-bd/.opencode/plugins/superpowers-bd.js ~/.config/opencode/plugins/superpowers-bd.js

Alternatively, for project-local installation:

# In your OpenCode project
mkdir -p .opencode/plugins
ln -sf ~/.config/opencode/superpowers-bd/.opencode/plugins/superpowers-bd.js .opencode/plugins/superpowers-bd.js

3. Restart OpenCode

Restart OpenCode to load the plugin. Superpowers-BD will automatically activate.

Usage

Finding Skills

Use the find_skills tool to list all available skills:

use find_skills tool

Loading a Skill

Use the use_skill tool to load a specific skill:

use use_skill tool with skill_name: "superpowers-bd:brainstorming"

Skills are automatically inserted into the conversation and persist across context compaction.

Personal Skills

Create your own skills in ~/.config/opencode/skills/:

mkdir -p ~/.config/opencode/skills/my-skill

Create ~/.config/opencode/skills/my-skill/SKILL.md:

---
name: my-skill
description: Use when [condition] - [what it does]
---

# My Skill

[Your skill content here]

Project Skills

Create project-specific skills in your OpenCode project:

# In your OpenCode project
mkdir -p .opencode/skills/my-project-skill

Create .opencode/skills/my-project-skill/SKILL.md:

---
name: my-project-skill
description: Use when [condition] - [what it does]
---

# My Project Skill

[Your skill content here]

Skill Priority

Skills are resolved with this priority order:

  1. Project skills (.opencode/skills/) - Highest priority
  2. Personal skills (~/.config/opencode/skills/)
  3. Superpowers-BD skills (~/.config/opencode/superpowers-bd/skills/)

You can force resolution to a specific level:

  • project:skill-name - Force project skill
  • skill-name - Search project → personal → Superpowers-BD
  • superpowers-bd:skill-name - Force Superpowers-BD skill

Features

Automatic Context Injection

The plugin automatically injects Superpowers-BD context when OpenCode emits session.created. No manual configuration needed.

Message Insertion Pattern

When you load a skill with use_skill, it's inserted as a user message with noReply: true. This ensures skills persist throughout long conversations, even when OpenCode compacts context.

Compaction Resilience

The plugin listens for session.compacted events and automatically re-injects the core Superpowers-BD bootstrap to maintain functionality after context compaction.

Tool Mapping

Skills written for Claude Code are automatically adapted for OpenCode. The plugin provides mapping instructions:

  • TaskCreate, TaskUpdate, TaskList, TaskGet → update_plan
  • TodoWrite (legacy) → update_plan
  • Task with subagents → OpenCode's @mention system
  • Skill tool → use_skill custom tool
  • File operations → Native OpenCode tools

Architecture

Plugin Structure

Location: ~/.config/opencode/superpowers-bd/.opencode/plugins/superpowers-bd.js

Components:

  • Two custom tools: use_skill, find_skills
  • session.created event handler for initial context injection
  • event handler for session.compacted re-injection
  • Uses shared lib/skills-core.js module (also used by Codex)

Shared Core Module

Location: ~/.config/opencode/superpowers-bd/lib/skills-core.js

Functions:

  • extractFrontmatter() - Parse skill metadata
  • stripFrontmatter() - Remove metadata from content
  • findSkillsInDir() - Recursive skill discovery
  • resolveSkillPath() - Skill resolution with shadowing
  • checkForUpdates() - Git update detection

This module is shared between OpenCode and Codex implementations for code reuse.

Updating

cd ~/.config/opencode/superpowers-bd
git pull

Restart OpenCode to load the updates.

Troubleshooting

Plugin not loading

  1. Check plugin file exists: ls ~/.config/opencode/superpowers-bd/.opencode/plugins/superpowers-bd.js
  2. Check symlink: ls -l ~/.config/opencode/plugins/superpowers-bd.js
  3. Check OpenCode logs: opencode run "test" --print-logs --log-level DEBUG
  4. Look for: service=plugin path=file:///.../superpowers-bd.js loading plugin

Skills not found

  1. Verify skills directory: ls ~/.config/opencode/superpowers-bd/skills
  2. Use find_skills tool to see what's discovered
  3. Check skill structure: each skill needs a SKILL.md file

Tools not working

  1. Verify plugin loaded: Check OpenCode logs for plugin loading message
  2. Check Node.js version: The plugin requires Node.js for ES modules
  3. Test plugin manually: node --input-type=module -e "import('file://~/.config/opencode/plugins/superpowers-bd.js').then(m => console.log(Object.keys(m)))"

Context not injecting

  1. Check whether session.created events are reaching the plugin
  2. Verify using-superpowers skill exists
  3. Check OpenCode version (requires recent version with plugin support)

Getting Help

Testing

The implementation includes an automated test suite at tests/opencode/:

# Run all tests
./tests/opencode/run-tests.sh --integration --verbose

# Run specific test
./tests/opencode/run-tests.sh --test test-tools.sh

Tests verify:

  • Plugin loading
  • Skills-core library functionality
  • Tool execution (use_skill, find_skills)
  • Skill priority resolution
  • Proper isolation with temp HOME