An agentic skills framework & software development methodology that works.
Auto-register skills from plugin, simplify OpenCode install to one line
jessef4b54a17171e
diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.mdindex 0cbda0745..2dc2b238a 100644--- a/.opencode/INSTALL.md+++ b/.opencode/INSTALL.md@@ -3,107 +3,71 @@## Prerequisites- [OpenCode.ai](https://opencode.ai) installed-- Git installed-## Installation Steps+## Installation-### 1. Clone Superpowers+Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):-```bash-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers+```json+{+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]+}```-### 2. Register the Plugin+Restart OpenCode. That's it — the plugin auto-installs and registers all skills.-Create a symlink so OpenCode discovers the plugin:+Verify by asking: "Tell me about your superpowers"-```bash-mkdir -p ~/.config/opencode/plugins-rm -f ~/.config/opencode/plugins/superpowers.js-ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js-```+## Migrating from the old symlink-based install-### 3. Symlink Skills--Create a symlink so OpenCode's native skill tool discovers superpowers skills:+If you previously installed superpowers using `git clone` and symlinks, remove the old setup:```bash-mkdir -p ~/.config/opencode/skills+# Remove old symlinks+rm -f ~/.config/opencode/plugins/superpowers.jsrm -rf ~/.config/opencode/skills/superpowers-ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers-```-### 4. Restart OpenCode+# Optionally remove the cloned repo+rm -rf ~/.config/opencode/superpowers-Restart OpenCode. The plugin will automatically inject superpowers context.+# Remove skills.paths from opencode.json if you added one for superpowers+```-Verify by asking: "do you have superpowers?"+Then follow the installation steps above.## Usage-### Finding Skills--Use OpenCode's native `skill` tool to list available skills:+Use OpenCode's native `skill` tool:```use skill tool to list skills-```--### Loading a Skill--Use OpenCode's native `skill` tool to load a specific skill:--```use skill tool to load superpowers/brainstorming```-### Personal Skills--Create your own skills in `~/.config/opencode/skills/`:--```bash-mkdir -p ~/.config/opencode/skills/my-skill-```--Create `~/.config/opencode/skills/my-skill/SKILL.md`:--```markdown-----name: my-skill-description: Use when [condition] - [what it does]------# My Skill--[Your skill content here]-```--### Project Skills--Create project-specific skills in `.opencode/skills/` within your project.+## Updating-**Skill Priority:** Project skills > Personal skills > Superpowers skills+Superpowers updates automatically when you restart OpenCode.-## Updating+To pin a specific version:-```bash-cd ~/.config/opencode/superpowers-git pull+```json+{+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]+}```## Troubleshooting### Plugin not loading-1. Check plugin symlink: `ls -l ~/.config/opencode/plugins/superpowers.js`-2. Check source exists: `ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`-3. Check OpenCode logs for errors+1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`+2. Verify the plugin line in your `opencode.json`+3. Make sure you're running a recent version of OpenCode### Skills not found-1. Check skills symlink: `ls -l ~/.config/opencode/skills/superpowers`-2. Verify it points to: `~/.config/opencode/superpowers/skills`-3. Use `skill` tool to list what's discovered+1. Use `skill` tool to list what's discovered+2. Check that the plugin is loading (see above)### Tool mappingdiff --git a/.opencode/plugins/superpowers.js b/.opencode/plugins/superpowers.jsindex 886669bae..5e7833b62 100644--- a/.opencode/plugins/superpowers.js+++ b/.opencode/plugins/superpowers.js@@ -2,7 +2,7 @@* Superpowers plugin for OpenCode.ai** Injects superpowers bootstrap context via system prompt transform.- * Skills are discovered via OpenCode's native skill tool from symlinked directory.+ * Auto-registers skills directory via config hook (no symlinks needed).*/import path from 'path';@@ -84,6 +84,18 @@ ${toolMapping}};return {+ // Inject skills path into live config so OpenCode discovers superpowers skills+ // without requiring manual symlinks or config file edits.+ // This works because Config.get() returns a cached singleton — modifications+ // here are visible when skills are lazily discovered later.+ config: async (config) => {+ config.skills = config.skills || {};+ config.skills.paths = config.skills.paths || [];+ if (!config.skills.paths.includes(superpowersSkillsDir)) {+ config.skills.paths.push(superpowersSkillsDir);+ }+ },+// Use system prompt transform to inject bootstrap (fixes #226 agent reset bug)'experimental.chat.system.transform': async (_input, output) => {const bootstrap = getBootstrapContent();diff --git a/docs/README.opencode.md b/docs/README.opencode.mdindex 7f1ed304c..71b74c52a 100644--- a/docs/README.opencode.md+++ b/docs/README.opencode.md@@ -2,169 +2,36 @@Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).-## Quick Install+## Installation-Tell OpenCode:+Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):-```-Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js to ~/.config/opencode/plugins/superpowers.js, then symlink ~/.config/opencode/superpowers/skills to ~/.config/opencode/skills/superpowers, then restart opencode.+```json+{+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]+}```-## Manual Installation+Restart OpenCode. The plugin auto-installs via Bun and registers all skills automatically.-### Prerequisites+Verify by asking: "Tell me about your superpowers"-- [OpenCode.ai](https://opencode.ai) installed-- Git installed+### Migrating from the old symlink-based install-### macOS / Linux+If you previously installed superpowers using `git clone` and symlinks, remove the old setup:```bash-# 1. Install Superpowers (or update existing)-if [ -d ~/.config/opencode/superpowers ]; then- cd ~/.config/opencode/superpowers && git pull-else- git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers-fi--# 2. Create directories-mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills--# 3. Remove old symlinks/directories if they exist+# Remove old symlinksrm -f ~/.config/opencode/plugins/superpowers.jsrm -rf ~/.config/opencode/skills/superpowers-# 4. Create symlinks-ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js-ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers--# 5. Restart OpenCode-```--#### Verify Installation--```bash-ls -l ~/.config/opencode/plugins/superpowers.js-ls -l ~/.config/opencode/skills/superpowers-```--Both should show symlinks pointing to the superpowers directory.--### Windows--**Prerequisites:**-- Git installed-- Either **Developer Mode** enabled OR **Administrator privileges**- - Windows 10: Settings → Update & Security → For developers- - Windows 11: Settings → System → For developers--Pick your shell below: [Command Prompt](#command-prompt) | [PowerShell](#powershell) | [Git Bash](#git-bash)--#### Command Prompt--Run as Administrator, or with Developer Mode enabled:--```cmd-:: 1. Install Superpowers-git clone https://github.com/obra/superpowers.git "%USERPROFILE%\.config\opencode\superpowers"--:: 2. Create directories-mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul-mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul--:: 3. Remove existing links (safe for reinstalls)-del "%USERPROFILE%\.config\opencode\plugins\superpowers.js" 2>nul-rmdir "%USERPROFILE%\.config\opencode\skills\superpowers" 2>nul--:: 4. Create plugin symlink (requires Developer Mode or Admin)-mklink "%USERPROFILE%\.config\opencode\plugins\superpowers.js" "%USERPROFILE%\.config\opencode\superpowers\.opencode\plugins\superpowers.js"--:: 5. Create skills junction (works without special privileges)-mklink /J "%USERPROFILE%\.config\opencode\skills\superpowers" "%USERPROFILE%\.config\opencode\superpowers\skills"--:: 6. Restart OpenCode-```--#### PowerShell--Run as Administrator, or with Developer Mode enabled:--```powershell-# 1. Install Superpowers-git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\superpowers"--# 2. Create directories-New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"-New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"--# 3. Remove existing links (safe for reinstalls)-Remove-Item "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue-Remove-Item "$env:USERPROFILE\.config\opencode\skills\superpowers" -Force -ErrorAction SilentlyContinue--# 4. Create plugin symlink (requires Developer Mode or Admin)-New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugins\superpowers.js"--# 5. Create skills junction (works without special privileges)-New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\superpowers" -Target "$env:USERPROFILE\.config\opencode\superpowers\skills"--# 6. Restart OpenCode-```--#### Git Bash--Note: Git Bash's native `ln` command copies files instead of creating symlinks. Use `cmd //c mklink` instead (the `//c` is Git Bash syntax for `/c`).+# Optionally remove the cloned repo+rm -rf ~/.config/opencode/superpowers-```bash-# 1. Install Superpowers-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers--# 2. Create directories-mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills--# 3. Remove existing links (safe for reinstalls)-rm -f ~/.config/opencode/plugins/superpowers.js 2>/dev/null-rm -rf ~/.config/opencode/skills/superpowers 2>/dev/null--# 4. Create plugin symlink (requires Developer Mode or Admin)-cmd //c "mklink \"$(cygpath -w ~/.config/opencode/plugins/superpowers.js)\" \"$(cygpath -w ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js)\""--# 5. Create skills junction (works without special privileges)-cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""--# 6. Restart OpenCode+# Remove skills.paths from opencode.json if you added one for superpowers```-#### WSL Users--If running OpenCode inside WSL, use the [macOS / Linux](#macos--linux) instructions instead.--#### Verify Installation--**Command Prompt:**-```cmd-dir /AL "%USERPROFILE%\.config\opencode\plugins"-dir /AL "%USERPROFILE%\.config\opencode\skills"-```--**PowerShell:**-```powershell-Get-ChildItem "$env:USERPROFILE\.config\opencode\plugins" | Where-Object { $_.LinkType }-Get-ChildItem "$env:USERPROFILE\.config\opencode\skills" | Where-Object { $_.LinkType }-```--Look for `<SYMLINK>` or `<JUNCTION>` in the output.--#### Troubleshooting Windows--**"You do not have sufficient privilege" error:**-- Enable Developer Mode in Windows Settings, OR-- Right-click your terminal → "Run as Administrator"--**"Cannot create a file when that file already exists":**-- Run the removal commands (step 3) first, then retry--**Symlinks not working after git clone:**-- Run `git config --global core.symlinks true` and re-clone+Then follow the installation steps above.## Usage@@ -178,8 +45,6 @@ use skill tool to list skills### Loading a Skill-Use OpenCode's native `skill` tool to load a specific skill:-```use skill tool to load superpowers/brainstorming```@@ -207,124 +72,59 @@ description: Use when [condition] - [what it does]### Project Skills-Create project-specific skills in your OpenCode project:+Create project-specific skills in `.opencode/skills/` within your project.-```bash-# In your OpenCode project-mkdir -p .opencode/skills/my-project-skill-```+**Skill Priority:** Project skills > Personal skills > Superpowers skills-Create `.opencode/skills/my-project-skill/SKILL.md`:+## Updating-```markdown-----name: my-project-skill-description: Use when [condition] - [what it does]----+Superpowers updates automatically when you restart OpenCode. The plugin is re-installed from the git repository on each launch.-# My Project Skill+To pin a specific version, use a branch or tag:-[Your skill content here]+```json+{+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]+}```-## Skill Locations--OpenCode discovers skills from these locations:--1. **Project skills** (`.opencode/skills/`) - Highest priority-2. **Personal skills** (`~/.config/opencode/skills/`)-3. **Superpowers skills** (`~/.config/opencode/skills/superpowers/`) - via symlink+## How It Works-## Features+The plugin does two things:-### Automatic Context Injection--The plugin automatically injects superpowers context via the `experimental.chat.system.transform` hook. This adds the "using-superpowers" skill content to the system prompt on every request.--### Native Skills Integration--Superpowers uses OpenCode's native `skill` tool for skill discovery and loading. Skills are symlinked into `~/.config/opencode/skills/superpowers/` so they appear alongside your personal and project skills.+1. **Injects bootstrap context** via the `experimental.chat.system.transform` hook, adding superpowers awareness to every conversation.+2. **Registers the skills directory** via the `config` hook, so OpenCode discovers all superpowers skills without symlinks or manual config.### Tool Mapping-Skills written for Claude Code are automatically adapted for OpenCode. The bootstrap provides mapping instructions:+Skills written for Claude Code are automatically adapted for OpenCode:- `TodoWrite` → `todowrite`- `Task` with subagents → OpenCode's `@mention` system- `Skill` tool → OpenCode's native `skill` tool- File operations → Native OpenCode tools-## Architecture--### Plugin Structure--**Location:** `~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`--**Components:**-- `experimental.chat.system.transform` hook for bootstrap injection-- Reads and injects the "using-superpowers" skill content--### Skills--**Location:** `~/.config/opencode/skills/superpowers/` (symlink to `~/.config/opencode/superpowers/skills/`)--Skills are discovered by OpenCode's native skill system. Each skill has a `SKILL.md` file with YAML frontmatter.--## Updating--```bash-cd ~/.config/opencode/superpowers-git pull-```--Restart OpenCode to load the updates.-## Troubleshooting### Plugin not loading-1. Check plugin exists: `ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`-2. Check symlink/junction: `ls -l ~/.config/opencode/plugins/` (macOS/Linux) or `dir /AL %USERPROFILE%\.config\opencode\plugins` (Windows)-3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG`-4. Look for plugin loading message in logs+1. Check OpenCode logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`+2. Verify the plugin line in your `opencode.json` is correct+3. Make sure you're running a recent version of OpenCode### Skills not found-1. Verify skills symlink: `ls -l ~/.config/opencode/skills/superpowers` (should point to superpowers/skills/)-2. Use OpenCode's `skill` tool to list available skills-3. Check skill structure: each skill needs a `SKILL.md` file with valid frontmatter--### Windows: Module not found error--If you see `Cannot find module` errors on Windows:-- **Cause:** Git Bash `ln -sf` copies files instead of creating symlinks-- **Fix:** Use `mklink /J` directory junctions instead (see Windows installation steps)+1. Use OpenCode's `skill` tool to list available skills+2. Check that the plugin is loading (see above)+3. Each skill needs a `SKILL.md` file with valid YAML frontmatter### Bootstrap not appearing-1. Verify using-superpowers skill exists: `ls ~/.config/opencode/superpowers/skills/using-superpowers/SKILL.md`-2. Check OpenCode version supports `experimental.chat.system.transform` hook-3. Restart OpenCode after plugin changes+1. Check OpenCode version supports `experimental.chat.system.transform` hook+2. Restart OpenCode after config changes## Getting Help- Report issues: https://github.com/obra/superpowers/issues- Main documentation: https://github.com/obra/superpowers- OpenCode docs: https://opencode.ai/docs/--## Testing--Verify your installation:--```bash-# Check plugin loads-opencode run --print-logs "hello" 2>&1 | grep -i superpowers--# Check skills are discoverable-opencode run "use skill tool to list all skills" 2>&1 | grep -i superpowers--# Check bootstrap injection-opencode run "what superpowers do you have?"-```--The agent should mention having superpowers and be able to list skills from `superpowers/`.