An agentic skills framework & software development methodology that works.
docs: reorganize platform installation docs with inline quick-start and detailed guides
Jesse Vincentf5a4002daf28
diff --git a/README.md b/README.mdindex d651d26c6..8aa9856bf 100644--- a/README.md+++ b/README.md@@ -50,26 +50,25 @@ Check that commands appear:# /superpowers:execute-plan - Execute plan in batches```-### Codex (Experimental)+### Codex-**Note:** Codex support is experimental and may require refinement based on user feedback.+Tell Codex:-Tell Codex to fetch https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md and follow the instructions.+```+Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md+```++**Detailed docs:** [docs/README.codex.md](docs/README.codex.md)### OpenCode-Superpowers works with [OpenCode.ai](https://opencode.ai) through a native JavaScript plugin.+Tell OpenCode:-**Installation:** See [.opencode/INSTALL.md](.opencode/INSTALL.md)+```+Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugin, then symlink ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js to ~/.config/opencode/plugin/superpowers.js, then restart opencode.+```-**Features:**-- Custom tools: `use_skill` and `find_skills`-- Automatic context injection via chat.message hook-- Message insertion pattern for skill persistence across compaction-- Three-tier skill priority: project > personal > superpowers-- Project-local skills support (`.opencode/skills/`)-- Auto re-injection on session.compacted events-- Supporting files and scripts access+**Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md)## Quick Startdiff --git a/docs/README.codex.md b/docs/README.codex.mdnew file mode 100644index 000000000..e43004f42--- /dev/null+++ b/docs/README.codex.md@@ -0,0 +1,153 @@+# Superpowers for Codex++Complete guide for using Superpowers with OpenAI Codex.++## Quick Install++Tell Codex:++```+Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md+```++## Manual Installation++### Prerequisites++- OpenAI Codex access+- Shell access to install files++### Installation Steps++#### 1. Clone Superpowers++```bash+mkdir -p ~/.codex/superpowers+git clone https://github.com/obra/superpowers.git ~/.codex/superpowers+```++#### 2. Install Bootstrap++The bootstrap file is included in the repository at `.codex/superpowers-bootstrap.md`. Codex will automatically use it from the cloned location.++#### 3. Verify Installation++Tell Codex:++```+Run ~/.codex/superpowers/.codex/superpowers-codex find-skills to show available skills+```++You should see a list of available skills with descriptions.++## Usage++### Finding Skills++```+Run ~/.codex/superpowers/.codex/superpowers-codex find-skills+```++### Loading a Skill++```+Run ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming+```++### Bootstrap All Skills++```+Run ~/.codex/superpowers/.codex/superpowers-codex bootstrap+```++This loads the complete bootstrap with all skill information.++### Personal Skills++Create your own skills in `~/.codex/skills/`:++```bash+mkdir -p ~/.codex/skills/my-skill+```++Create `~/.codex/skills/my-skill/SKILL.md`:++```markdown+---+name: my-skill+description: Use when [condition] - [what it does]+---++# My Skill++[Your skill content here]+```++Personal skills override superpowers skills with the same name.++## Architecture++### Codex CLI Tool++**Location:** `~/.codex/superpowers/.codex/superpowers-codex`++A Node.js CLI script that provides three commands:+- `bootstrap` - Load complete bootstrap with all skills+- `use-skill <name>` - Load a specific skill+- `find-skills` - List all available skills++### Shared Core Module++**Location:** `~/.codex/superpowers/lib/skills-core.js`++The Codex implementation uses the shared `skills-core` module (ES module format) for skill discovery and parsing. This is the same module used by the OpenCode plugin, ensuring consistent behavior across platforms.++### Tool Mapping++Skills written for Claude Code are adapted for Codex with these mappings:++- `TodoWrite` → `update_plan`+- `Task` with subagents → Tell user subagents aren't available, do work directly+- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill`+- File operations → Native Codex tools++## Updating++```bash+cd ~/.codex/superpowers+git pull+```++## Troubleshooting++### Skills not found++1. Verify installation: `ls ~/.codex/superpowers/skills`+2. Check CLI works: `~/.codex/superpowers/.codex/superpowers-codex find-skills`+3. Verify skills have SKILL.md files++### CLI script not executable++```bash+chmod +x ~/.codex/superpowers/.codex/superpowers-codex+```++### Node.js errors++The CLI script requires Node.js. Verify:++```bash+node --version+```++Should show v14 or higher (v18+ recommended for ES module support).++## Getting Help++- Report issues: https://github.com/obra/superpowers/issues+- Main documentation: https://github.com/obra/superpowers+- Blog post: https://blog.fsck.com/2025/10/27/skills-for-openai-codex/++## Note++Codex support is experimental and may require refinement based on user feedback. If you encounter issues, please report them on GitHub.diff --git a/docs/README.opencode.md b/docs/README.opencode.mdnew file mode 100644index 000000000..122fe55ea--- /dev/null+++ b/docs/README.opencode.md@@ -0,0 +1,234 @@+# Superpowers for OpenCode++Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).++## Quick Install++Tell OpenCode:++```+Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugin, then symlink ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js to ~/.config/opencode/plugin/superpowers.js, then restart opencode.+```++## Manual Installation++### Prerequisites++- [OpenCode.ai](https://opencode.ai) installed+- Node.js installed+- Git installed++### Installation Steps++#### 1. Install Superpowers++```bash+mkdir -p ~/.config/opencode/superpowers+git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers+```++#### 2. Register the Plugin++OpenCode discovers plugins from `~/.config/opencode/plugin/`. Create a symlink:++```bash+mkdir -p ~/.config/opencode/plugin+ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js+```++Alternatively, for project-local installation:++```bash+# In your OpenCode project+mkdir -p .opencode/plugin+ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js .opencode/plugin/superpowers.js+```++#### 3. Restart OpenCode++Restart OpenCode to load the plugin. Superpowers 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:brainstorming"+```++Skills are automatically inserted into the conversation and persist across context compaction.++### 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 your OpenCode project:++```bash+# In your OpenCode project+mkdir -p .opencode/skills/my-project-skill+```++Create `.opencode/skills/my-project-skill/SKILL.md`:++```markdown+---+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 skills** (`~/.config/opencode/superpowers/skills/`)++You can force resolution to a specific level:+- `project:skill-name` - Force project skill+- `skill-name` - Search project → personal → superpowers+- `superpowers:skill-name` - Force superpowers skill++## Features++### Automatic Context Injection++The plugin automatically injects superpowers context via the chat.message hook on every session. 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 bootstrap to maintain functionality after context compaction.++### Tool Mapping++Skills written for Claude Code are automatically adapted for OpenCode. The plugin provides mapping instructions:++- `TodoWrite` → `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/.opencode/plugin/superpowers.js`++**Components:**+- Two custom tools: `use_skill`, `find_skills`+- chat.message hook 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/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++```bash+cd ~/.config/opencode/superpowers+git pull+```++Restart OpenCode to load the updates.++## Troubleshooting++### Plugin not loading++1. Check plugin file exists: `ls ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js`+2. Check symlink: `ls -l ~/.config/opencode/plugin/superpowers.js`+3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG`+4. Look for: `service=plugin path=file:///.../superpowers.js loading plugin`++### Skills not found++1. Verify skills directory: `ls ~/.config/opencode/superpowers/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/plugin/superpowers.js').then(m => console.log(Object.keys(m)))"`++### Context not injecting++1. Check if chat.message hook is working+2. Verify using-superpowers skill exists+3. Check OpenCode version (requires recent version with plugin support)++## Getting Help++- Report issues: https://github.com/obra/superpowers/issues+- Main documentation: https://github.com/obra/superpowers+- OpenCode docs: https://opencode.ai/docs/++## Testing++The implementation includes an automated test suite at `tests/opencode/`:++```bash+# 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