From cbc1afb357c0effbec6f858de97502e0bb3079c8 Mon Sep 17 00:00:00 2001 From: Jon Langevin Date: Sat, 25 Apr 2026 05:51:27 -0400 Subject: [PATCH 1/5] docs: cross-LLM compatibility matrix + fix obra repo refs in docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: add Cross-LLM Compatibility section with 4-host install matrix - docs/README.codex.md: fix obra/superpowers → GoCodeAlone/claude-superpowers refs throughout; add Cross-LLM Behavior section with host declaration guidance - docs/README.opencode.md: same obra ref fix; add Cross-LLM Behavior section Co-Authored-By: Claude Sonnet 4.6 --- README.md | 11 +++++++++++ docs/README.codex.md | 32 ++++++++++++++++++++++---------- docs/README.opencode.md | 26 +++++++++++++++++++------- 3 files changed, 52 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 58c621a..40fd124 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,17 @@ Fetch and follow instructions from https://raw.githubusercontent.com/GoCodeAlone Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant superpowers skill. +## Cross-LLM Compatibility + +Superpowers skills run on any host that supports the SKILL.md format. Host-specific tools (like Agent Teams) are conditioned with `` blocks so other hosts skip them gracefully. + +| Host | Install path | Native skill discovery | Notes | +|---|---|---|---| +| Claude Code | `~/.claude/plugins/marketplace/superpowers/` | yes | Full Agent Teams support (experimental flag) | +| Codex | `~/.agents/skills/superpowers/` | yes | Sequential sub-agent dispatch; `/plan` slash; `/agent` switching | +| OpenCode | `~/.config/opencode/skills/superpowers/` | yes | Tool mapping documented in `.opencode/INSTALL.md` | +| Cursor | manual reference | partial | Plugin manifest stub; install path TBD | + ## The Basic Workflow 1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document. diff --git a/docs/README.codex.md b/docs/README.codex.md index 04e261a..ce73bc1 100644 --- a/docs/README.codex.md +++ b/docs/README.codex.md @@ -7,7 +7,7 @@ Guide for using Superpowers with OpenAI Codex via native skill discovery. Tell Codex: ``` -Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md +Fetch and follow instructions from https://raw.githubusercontent.com/GoCodeAlone/claude-superpowers/refs/heads/main/.codex/INSTALL.md ``` ## Manual Installation @@ -21,13 +21,13 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp 1. Clone the repo: ```bash - git clone https://github.com/obra/superpowers.git ~/.codex/superpowers + git clone https://github.com/GoCodeAlone/claude-superpowers.git ~/.codex/superpowers ``` 2. Create the skills symlink: ```bash mkdir -p ~/.agents/skills - ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers + ln -s ~/.codex/claude-superpowers/skills ~/.agents/skills/superpowers ``` 3. Restart Codex. @@ -38,7 +38,7 @@ Use a junction instead of a symlink (works without Developer Mode): ```powershell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills" -cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills" +cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\claude-superpowers\skills" ``` ## How It Works @@ -46,7 +46,7 @@ cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE Codex has native skill discovery — it scans `~/.agents/skills/` at startup, parses SKILL.md frontmatter, and loads skills on demand. Superpowers skills are made visible through a single symlink: ``` -~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/ +~/.agents/skills/superpowers/ → ~/.codex/claude-superpowers/skills/ ``` The `using-superpowers` skill is discovered automatically and enforces skill usage discipline — no additional configuration needed. @@ -84,7 +84,7 @@ The `description` field is how Codex decides when to activate a skill automatica ## Updating ```bash -cd ~/.codex/superpowers && git pull +cd ~/.codex/claude-superpowers && git pull ``` Skills update instantly through the symlink. @@ -100,21 +100,33 @@ rm ~/.agents/skills/superpowers Remove-Item "$env:USERPROFILE\.agents\skills\superpowers" ``` -Optionally delete the clone: `rm -rf ~/.codex/superpowers` (Windows: `Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"`). +Optionally delete the clone: `rm -rf ~/.codex/claude-superpowers` (Windows: `Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\claude-superpowers"`). ## Troubleshooting ### Skills not showing up 1. Verify the symlink: `ls -la ~/.agents/skills/superpowers` -2. Check skills exist: `ls ~/.codex/superpowers/skills` +2. Check skills exist: `ls ~/.codex/claude-superpowers/skills` 3. Restart Codex — skills are discovered at startup ### Windows junction issues Junctions normally work without special permissions. If creation fails, try running PowerShell as administrator. +## Cross-LLM Behavior + +Superpowers skills use `` blocks to gate content that only applies to Claude Code (Agent Teams, specific tool names, etc.). On Codex, those blocks are skipped — the rest of the skill runs as-is. + +To let skills detect that they are running on Codex, add a host declaration to your `~/.codex/AGENTS.md`: + +```markdown +Host: codex +``` + +This single line enables host-conditional skill logic. See `.codex/INSTALL.md` for the full declaration snippet. + ## Getting Help -- Report issues: https://github.com/obra/superpowers/issues -- Main documentation: https://github.com/obra/superpowers +- Report issues: https://github.com/GoCodeAlone/claude-superpowers/issues +- Main documentation: https://github.com/GoCodeAlone/claude-superpowers diff --git a/docs/README.opencode.md b/docs/README.opencode.md index 38bbe16..ba3bd91 100644 --- a/docs/README.opencode.md +++ b/docs/README.opencode.md @@ -7,7 +7,7 @@ Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai). Tell OpenCode: ``` -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. +Clone https://github.com/GoCodeAlone/claude-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. ``` ## Manual Installation @@ -24,7 +24,7 @@ Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, the if [ -d ~/.config/opencode/superpowers ]; then cd ~/.config/opencode/superpowers && git pull else - git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers + git clone https://github.com/GoCodeAlone/claude-superpowers.git ~/.config/opencode/superpowers fi # 2. Create directories @@ -66,7 +66,7 @@ Run as Administrator, or with Developer Mode enabled: ```cmd :: 1. Install Superpowers -git clone https://github.com/obra/superpowers.git "%USERPROFILE%\.config\opencode\superpowers" +git clone https://github.com/GoCodeAlone/claude-superpowers.git "%USERPROFILE%\.config\opencode\superpowers" :: 2. Create directories mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul @@ -91,7 +91,7 @@ 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" +git clone https://github.com/GoCodeAlone/claude-superpowers.git "$env:USERPROFILE\.config\opencode\superpowers" # 2. Create directories New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins" @@ -116,7 +116,7 @@ Note: Git Bash's native `ln` command copies files instead of creating symlinks. ```bash # 1. Install Superpowers -git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers +git clone https://github.com/GoCodeAlone/claude-superpowers.git ~/.config/opencode/superpowers # 2. Create directories mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills @@ -306,10 +306,22 @@ If you see `Cannot find module` errors on Windows: 2. Check OpenCode version supports `experimental.chat.system.transform` hook 3. Restart OpenCode after plugin changes +## Cross-LLM Behavior + +Superpowers skills use `` blocks to gate content that only applies to Claude Code (Agent Teams, specific tool names, etc.). On OpenCode, those blocks are skipped — the rest of the skill runs as-is. + +To let skills detect that they are running on OpenCode, add a host declaration to your `~/.config/opencode/AGENTS.md`: + +```markdown +Host: opencode +``` + +This single line enables host-conditional skill logic. See `.opencode/INSTALL.md` for the full declaration snippet. + ## Getting Help -- Report issues: https://github.com/obra/superpowers/issues -- Main documentation: https://github.com/obra/superpowers +- Report issues: https://github.com/GoCodeAlone/claude-superpowers/issues +- Main documentation: https://github.com/GoCodeAlone/claude-superpowers - OpenCode docs: https://opencode.ai/docs/ ## Testing From 2e8d53b42b5f7dd22f9d72b8e7ec023599f362b4 Mon Sep 17 00:00:00 2001 From: Jon Langevin Date: Sat, 25 Apr 2026 05:51:34 -0400 Subject: [PATCH 2/5] docs: add Modes section + host declaration instructions to INSTALL files - agents/team-conventions.md: insert Modes paragraph describing Sequential and Agent Teams execution modes - .codex/INSTALL.md: fix clone URL; append Cross-LLM Behavior section with AGENTS.md host declaration snippet - .opencode/INSTALL.md: fix clone URL; append Cross-LLM Behavior section with AGENTS.md host declaration snippet; fix help links Co-Authored-By: Claude Sonnet 4.6 --- .codex/INSTALL.md | 15 ++++++++++++++- .opencode/INSTALL.md | 19 ++++++++++++++++--- agents/team-conventions.md | 7 +++++++ 3 files changed, 37 insertions(+), 4 deletions(-) diff --git a/.codex/INSTALL.md b/.codex/INSTALL.md index c415e2e..270b925 100644 --- a/.codex/INSTALL.md +++ b/.codex/INSTALL.md @@ -10,7 +10,7 @@ Enable superpowers skills in Codex via native skill discovery. Just clone and sy 1. **Clone the superpowers repository:** ```bash - git clone https://github.com/obra/superpowers.git ~/.codex/superpowers + git clone https://github.com/GoCodeAlone/claude-superpowers.git ~/.codex/superpowers ``` 2. **Create the skills symlink:** @@ -65,3 +65,16 @@ rm ~/.agents/skills/superpowers ``` Optionally delete the clone: `rm -rf ~/.codex/superpowers`. + +## Cross-LLM Behavior + +Superpowers skills use `` blocks to gate Claude Code-only content. Codex skips those blocks automatically; no configuration needed. + +To enable host-conditional logic inside skills (so skills can adapt behavior per host), declare your host in `~/.codex/AGENTS.md`: + +```markdown +# Superpowers host declaration +Host: codex +``` + +Add this block once. Skills that inspect the host context will use it to pick the right execution path. diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md index 55e41c2..bf5fa68 100644 --- a/.opencode/INSTALL.md +++ b/.opencode/INSTALL.md @@ -10,7 +10,7 @@ ### 1. Clone Superpowers ```bash -git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers +git clone https://github.com/GoCodeAlone/claude-superpowers.git ~/.config/opencode/superpowers ``` ### 2. Register the Plugin @@ -113,7 +113,20 @@ When skills reference Claude Code tools: - `Skill` tool → OpenCode's native `skill` tool - File operations → your native tools +## Cross-LLM Behavior + +Superpowers skills use `` blocks to gate Claude Code-only content. OpenCode skips those blocks automatically; no configuration needed. + +To enable host-conditional logic inside skills (so skills can adapt behavior per host), declare your host in `~/.config/opencode/AGENTS.md`: + +```markdown +# Superpowers host declaration +Host: opencode +``` + +Add this block once. Skills that inspect the host context will use it to pick the right execution path. + ## Getting Help -- Report issues: https://github.com/obra/superpowers/issues -- Full documentation: https://github.com/obra/superpowers/blob/main/docs/README.opencode.md +- Report issues: https://github.com/GoCodeAlone/claude-superpowers/issues +- Full documentation: https://github.com/GoCodeAlone/claude-superpowers/blob/main/docs/README.opencode.md diff --git a/agents/team-conventions.md b/agents/team-conventions.md index aeea979..86c4ef0 100644 --- a/agents/team-conventions.md +++ b/agents/team-conventions.md @@ -47,6 +47,13 @@ them. (or REVERT-AND-REWRITE after max rounds). - Reflexive approval is forbidden. +## Modes + +Team conventions apply identically in both execution modes: + +- **Sequential Mode** (all hosts): orchestrator dispatches one sub-agent at a time; reviewers run between tasks. +- **Agent Teams Mode** (Claude Code only, opt-in): persistent named teammates in a shared chat surface; reviewers run in parallel after each task. + ## All agents - DRY: when re-stating a convention, prefer "per ``" over From f6f2b7a83441d3c9e627518646b3988feaf5f9b6 Mon Sep 17 00:00:00 2001 From: Jon Langevin Date: Sat, 25 Apr 2026 05:51:41 -0400 Subject: [PATCH 3/5] ci: add skill-content-check workflow wiring tests/skill-content-grep.sh Runs on push when skills/**, agents/**, or tests/skill-content-grep.sh change, and on workflow_dispatch. Enforces that no host-specific tokens (TodoWrite, Sonnet, etc.) appear in skill markdown outside blocks. Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/skill-content-check.yml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 .github/workflows/skill-content-check.yml diff --git a/.github/workflows/skill-content-check.yml b/.github/workflows/skill-content-check.yml new file mode 100644 index 0000000..bdad768 --- /dev/null +++ b/.github/workflows/skill-content-check.yml @@ -0,0 +1,20 @@ +name: Skill Content Check + +on: + push: + paths: + - 'skills/**' + - 'agents/**' + - 'tests/skill-content-grep.sh' + workflow_dispatch: + +permissions: + contents: read + +jobs: + skill-content-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Check skill content for host-specific tokens + run: bash tests/skill-content-grep.sh From bc9f21e0e6c3ec4471b3cce9412a60d44a4edae1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 25 Apr 2026 09:54:14 +0000 Subject: [PATCH 4/5] fix(docs): correct inconsistent clone path refs in README.codex.md Symlink target, update path, uninstall path, and troubleshooting path were changed to ~/.codex/claude-superpowers while the clone destination remained ~/.codex/superpowers. Restore consistency: all local paths now reference ~/.codex/superpowers to match the git clone command. Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/7ff4116b-ea0a-4ea8-9e61-12175da23721 Co-authored-by: intel352 <77607+intel352@users.noreply.github.com> --- docs/README.codex.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/README.codex.md b/docs/README.codex.md index ce73bc1..c098b72 100644 --- a/docs/README.codex.md +++ b/docs/README.codex.md @@ -27,7 +27,7 @@ Fetch and follow instructions from https://raw.githubusercontent.com/GoCodeAlone 2. Create the skills symlink: ```bash mkdir -p ~/.agents/skills - ln -s ~/.codex/claude-superpowers/skills ~/.agents/skills/superpowers + ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers ``` 3. Restart Codex. @@ -38,7 +38,7 @@ Use a junction instead of a symlink (works without Developer Mode): ```powershell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills" -cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\claude-superpowers\skills" +cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills" ``` ## How It Works @@ -46,7 +46,7 @@ cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE Codex has native skill discovery — it scans `~/.agents/skills/` at startup, parses SKILL.md frontmatter, and loads skills on demand. Superpowers skills are made visible through a single symlink: ``` -~/.agents/skills/superpowers/ → ~/.codex/claude-superpowers/skills/ +~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/ ``` The `using-superpowers` skill is discovered automatically and enforces skill usage discipline — no additional configuration needed. @@ -84,7 +84,7 @@ The `description` field is how Codex decides when to activate a skill automatica ## Updating ```bash -cd ~/.codex/claude-superpowers && git pull +cd ~/.codex/superpowers && git pull ``` Skills update instantly through the symlink. @@ -100,14 +100,14 @@ rm ~/.agents/skills/superpowers Remove-Item "$env:USERPROFILE\.agents\skills\superpowers" ``` -Optionally delete the clone: `rm -rf ~/.codex/claude-superpowers` (Windows: `Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\claude-superpowers"`). +Optionally delete the clone: `rm -rf ~/.codex/superpowers` (Windows: `Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"`). ## Troubleshooting ### Skills not showing up 1. Verify the symlink: `ls -la ~/.agents/skills/superpowers` -2. Check skills exist: `ls ~/.codex/claude-superpowers/skills` +2. Check skills exist: `ls ~/.codex/superpowers/skills` 3. Restart Codex — skills are discovered at startup ### Windows junction issues From a34213b641022997edcba5c253895352ab8775fa Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 25 Apr 2026 09:56:45 +0000 Subject: [PATCH 5/5] ci: add pull_request trigger + workflow self-reference to skill-content-check - Add pull_request trigger with same path filters so the check runs on PRs - Add .github/workflows/skill-content-check.yml to the paths list so changes to the guard/workflow itself are validated by the workflow Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/8cf5ed69-edc1-4f84-b005-69dd59d4198c Co-authored-by: intel352 <77607+intel352@users.noreply.github.com> --- .github/workflows/skill-content-check.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/skill-content-check.yml b/.github/workflows/skill-content-check.yml index bdad768..4dc79e4 100644 --- a/.github/workflows/skill-content-check.yml +++ b/.github/workflows/skill-content-check.yml @@ -6,6 +6,13 @@ on: - 'skills/**' - 'agents/**' - 'tests/skill-content-grep.sh' + - '.github/workflows/skill-content-check.yml' + pull_request: + paths: + - 'skills/**' + - 'agents/**' + - 'tests/skill-content-grep.sh' + - '.github/workflows/skill-content-check.yml' workflow_dispatch: permissions: