From 556340f49dd29ea660ecefe42e7447acf9ad60f5 Mon Sep 17 00:00:00 2001 From: Jon Langevin Date: Sat, 25 Apr 2026 06:04:07 -0400 Subject: [PATCH 1/4] docs(cross-llm): coverage tables + final integration (PR-E) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/cross-llm-coverage.md: host capability matrix — SKILL.md import, sub-agents, Agent Teams, background agents, MCP, slash commands, plan mode, task list, AGENTS.md, skill discovery paths, model tiers (Claude Code / Codex / OpenCode / Cursor with ✅/⚠️/❌ ratings) - tests/cross-llm-coverage.md: per-skill host-conditional audit — 17 skills classified as host-conditional (have blocks) or host-neutral (no forbidden tokens, no blocks needed) - README.md: add links to both coverage files from Cross-LLM Compatibility section Integration checks passed: - tests/skill-content-grep.sh: PASS - agents/team-conventions.md: coherent (Sequential Mode + Agent Teams) - .codex/INSTALL.md: coherent (host declaration + explanation) - .opencode/INSTALL.md: coherent (tool mapping + host declaration) Marker smoke test (requesting-code-review, subagent-driven-development, pr-monitoring): all / pairs syntactically uniform — consistent space-after-colon form, consistent close tag. --- README.md | 3 +++ docs/cross-llm-coverage.md | 38 +++++++++++++++++++++++++++++++++++++ tests/cross-llm-coverage.md | 34 +++++++++++++++++++++++++++++++++ 3 files changed, 75 insertions(+) create mode 100644 docs/cross-llm-coverage.md create mode 100644 tests/cross-llm-coverage.md diff --git a/README.md b/README.md index 40fd124..086b4bd 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,9 @@ Superpowers skills run on any host that supports the SKILL.md format. Host-speci | OpenCode | `~/.config/opencode/skills/superpowers/` | yes | Tool mapping documented in `.opencode/INSTALL.md` | | Cursor | manual reference | partial | Plugin manifest stub; install path TBD | +Full capability matrix: [docs/cross-llm-coverage.md](docs/cross-llm-coverage.md) +Per-skill host-conditional audit: [tests/cross-llm-coverage.md](tests/cross-llm-coverage.md) + ## 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/cross-llm-coverage.md b/docs/cross-llm-coverage.md new file mode 100644 index 0000000..84589f1 --- /dev/null +++ b/docs/cross-llm-coverage.md @@ -0,0 +1,38 @@ +# Cross-LLM Capability Coverage + +Host-by-host capability matrix for the Superpowers skills system. + +`✅` = fully supported `⚠️` = partial / workaround required `❌` = not supported + +| Capability | Claude Code | Codex CLI | OpenCode | Cursor | +|---|---|---|---|---| +| SKILL.md import | ✅ native | ✅ native | ✅ native | ⚠️ plugin manifest stub; install path TBD | +| Sub-agent dispatch | ✅ `Agent` tool | ✅ natural language | ⚠️ `@mention` to peer sessions | ❌ not documented | +| Agent Teams (persistent multi-agent DM) | ✅ experimental flag | ❌ | ❌ | ❌ | +| Background agents | ✅ `run_in_background` | ⚠️ thread-based; no explicit background flag | ❌ not documented | ❌ not documented | +| MCP servers | ✅ | ✅ `config.toml` | ✅ | ⚠️ partial | +| Slash commands | ✅ | ✅ 30+ built-ins incl. `/plan`, `/agent`, `/review` | ✅ | ✅ | +| Plan mode | ✅ `EnterPlanMode` + Shift-Tab | ✅ `/plan` slash | ⚠️ not documented; use prose planning | ⚠️ built-in Composer; not slash-invokable | +| Task list / TodoWrite | ✅ built-in | ❌ no documented equivalent | ⚠️ `update_plan` mapping (see `.opencode/INSTALL.md`) | ⚠️ unknown | +| AGENTS.md / project context | CLAUDE.md | AGENTS.md (+ `.override.md`) | AGENTS.md | n/a | +| Host declaration for skill conditionals | `Host: claude-code` in CLAUDE.md | `Host: codex` in `~/.codex/AGENTS.md` | `Host: opencode` in AGENTS.md | n/a | +| Skill discovery path (user scope) | `~/.claude/skills/` | `~/.agents/skills/` | `~/.config/opencode/skills/` | unknown | +| Model tier vocabulary | Haiku / balanced / frontier | gpt-5.x / gpt-5.x-mini / gpt-5.x-codex | model-string pass-through | model-string pass-through | + +## Notes + +**Sub-agent dispatch (Codex):** Codex uses natural-language spawn ("spawn one agent per X") rather than an explicit `Agent` tool call. The `` blocks in skills provide the correct phrasing. + +**Agent Teams:** The `TeamCreate` / `SendMessage` persistent-chat pattern is exclusive to Claude Code (experimental flag). Skills fall back to **Sequential Mode** (one sub-agent at a time) on all other hosts — see `skills/subagent-driven-development/SKILL.md`. + +**Task list (Codex):** No built-in task-tracking tool is documented in Codex CLI. Skills that reference `TodoWrite` wrap those references in `` blocks; the host-neutral path uses prose checklists. + +**Cursor:** The `.cursor-plugin/plugin.json` manifest is present but the install path and skill-discovery mechanism are not yet fully documented. Treat Cursor support as best-effort until confirmed. + +## Related files + +- `tests/cross-llm-coverage.md` — per-skill host-conditional vs host-neutral audit +- `tests/skill-content-grep.sh` — CI guard: fails if forbidden tokens appear outside `` blocks +- `.codex/INSTALL.md` — Codex setup instructions +- `.opencode/INSTALL.md` — OpenCode setup instructions +- `agents/model-tiers.md` — role-to-model-name resolution table (fast / balanced / frontier / coding-specialist) diff --git a/tests/cross-llm-coverage.md b/tests/cross-llm-coverage.md new file mode 100644 index 0000000..9f43801 --- /dev/null +++ b/tests/cross-llm-coverage.md @@ -0,0 +1,34 @@ +# Cross-LLM Skill Coverage + +A snapshot of which skills have host-conditional content and which are +host-neutral. Updated whenever a skill changes. + +| Skill | Claude Code | Codex | OpenCode | Cursor | Notes | +|---|---|---|---|---|---| +| alignment-check | host-conditional | host-conditional | host-conditional | host-conditional | spawn block in ``; prose fallback outside | +| brainstorming | host-conditional | host-conditional | host-conditional | host-conditional | `AskUserQuestion` in ``; numbered-list fallback in `` | +| dispatching-parallel-agents | host-neutral | host-neutral | host-neutral | host-neutral | generic parallel-dispatch pattern; no tool-specific refs | +| executing-plans | host-conditional | host-conditional | host-conditional | host-conditional | tool-use block in ``; prose fallback in `` | +| finishing-a-development-branch | host-neutral | host-neutral | host-neutral | host-neutral | audited clean — no forbidden tokens; bash-based throughout | +| pr-monitoring | host-conditional | host-conditional | host-conditional | host-conditional | Agent spawn block in ``; poll-loop prose outside | +| receiving-code-review | host-neutral | host-neutral | host-neutral | host-neutral | audited clean — pattern-based guidance, no tool refs | +| requesting-code-review | host-neutral | host-neutral | host-neutral | host-neutral | already portable (Group I) | +| runtime-launch-validation | host-neutral | host-neutral | host-neutral | host-neutral | already portable (Group I) | +| subagent-driven-development | host-conditional | host-conditional | host-conditional | host-conditional | Agent Teams setup in ``; Sequential Mode is host-neutral default | +| systematic-debugging | host-neutral | host-neutral | host-neutral | host-neutral | already portable (Group I) | +| test-driven-development | host-neutral | host-neutral | host-neutral | host-neutral | already portable (Group I) | +| using-git-worktrees | host-neutral | host-neutral | host-neutral | host-neutral | already portable (Group I) | +| using-superpowers | host-neutral | host-neutral | host-neutral | host-neutral | host-access phrasing is prose-based ("In Claude Code: … In other environments: …"); no forbidden tokens | +| verification-before-completion | host-neutral | host-neutral | host-neutral | host-neutral | already portable (Group I) | +| writing-plans | host-neutral | host-neutral | host-neutral | host-neutral | Plan Mode reference is prose-based ("If you are running in Claude Code…"); no `` blocks needed | +| writing-skills | host-conditional | host-conditional | host-conditional | host-conditional | `TodoWrite` checklist and tier-brand names wrapped in `` blocks | + +## Audit cadence + +Re-run `./tests/skill-content-grep.sh` and update this table whenever a skill +is added or rewritten. The grep guard catches forbidden tokens; this table +records intent. + +## Related + +- `docs/cross-llm-coverage.md` — host capability matrix (what each host supports natively) From c6386ade5a79baa8a1ecea3a97f114dc94b65fe8 Mon Sep 17 00:00:00 2001 From: Jon Langevin Date: Sat, 25 Apr 2026 06:09:05 -0400 Subject: [PATCH 2/4] fix(cross-llm-pr-e): address 4 Copilot review findings on capability matrix - Cursor SKILL.md import: update from stub to full plugin (skills/agents/commands/hooks + /plugin-add install) - OpenCode host declaration: add correct path (~/.config/opencode/AGENTS.md) - Model tier vocabulary: align with agents/model-tiers.md role-based vocabulary - Cursor notes section: update to reflect actual plugin.json capability definition - README.md: update Cursor row from 'stub' to documented marketplace install --- README.md | 2 +- docs/cross-llm-coverage.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 086b4bd..a8d0764 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ Superpowers skills run on any host that supports the SKILL.md format. Host-speci | 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 | +| Cursor | `/plugin-add superpowers` | yes (via plugin) | Plugin manifest defines skills/agents/commands/hooks | Full capability matrix: [docs/cross-llm-coverage.md](docs/cross-llm-coverage.md) Per-skill host-conditional audit: [tests/cross-llm-coverage.md](tests/cross-llm-coverage.md) diff --git a/docs/cross-llm-coverage.md b/docs/cross-llm-coverage.md index 84589f1..4fb3c8f 100644 --- a/docs/cross-llm-coverage.md +++ b/docs/cross-llm-coverage.md @@ -6,7 +6,7 @@ Host-by-host capability matrix for the Superpowers skills system. | Capability | Claude Code | Codex CLI | OpenCode | Cursor | |---|---|---|---|---| -| SKILL.md import | ✅ native | ✅ native | ✅ native | ⚠️ plugin manifest stub; install path TBD | +| SKILL.md import | ✅ native | ✅ native | ✅ native | ✅ plugin manifest defines skills/agents/commands/hooks; install via `/plugin-add superpowers` | | Sub-agent dispatch | ✅ `Agent` tool | ✅ natural language | ⚠️ `@mention` to peer sessions | ❌ not documented | | Agent Teams (persistent multi-agent DM) | ✅ experimental flag | ❌ | ❌ | ❌ | | Background agents | ✅ `run_in_background` | ⚠️ thread-based; no explicit background flag | ❌ not documented | ❌ not documented | @@ -15,9 +15,9 @@ Host-by-host capability matrix for the Superpowers skills system. | Plan mode | ✅ `EnterPlanMode` + Shift-Tab | ✅ `/plan` slash | ⚠️ not documented; use prose planning | ⚠️ built-in Composer; not slash-invokable | | Task list / TodoWrite | ✅ built-in | ❌ no documented equivalent | ⚠️ `update_plan` mapping (see `.opencode/INSTALL.md`) | ⚠️ unknown | | AGENTS.md / project context | CLAUDE.md | AGENTS.md (+ `.override.md`) | AGENTS.md | n/a | -| Host declaration for skill conditionals | `Host: claude-code` in CLAUDE.md | `Host: codex` in `~/.codex/AGENTS.md` | `Host: opencode` in AGENTS.md | n/a | +| Host declaration for skill conditionals | `Host: claude-code` in CLAUDE.md | `Host: codex` in `~/.codex/AGENTS.md` | `Host: opencode` in `~/.config/opencode/AGENTS.md` | n/a | | Skill discovery path (user scope) | `~/.claude/skills/` | `~/.agents/skills/` | `~/.config/opencode/skills/` | unknown | -| Model tier vocabulary | Haiku / balanced / frontier | gpt-5.x / gpt-5.x-mini / gpt-5.x-codex | model-string pass-through | model-string pass-through | +| Model tier vocabulary | role names → `haiku`/`sonnet`/`opus` (see `agents/model-tiers.md`) | role names → `gpt-5.4-mini`/`gpt-5.4`/`gpt-5.5` | role names → host-pass-through | role names → host-pass-through | ## Notes @@ -27,7 +27,7 @@ Host-by-host capability matrix for the Superpowers skills system. **Task list (Codex):** No built-in task-tracking tool is documented in Codex CLI. Skills that reference `TodoWrite` wrap those references in `` blocks; the host-neutral path uses prose checklists. -**Cursor:** The `.cursor-plugin/plugin.json` manifest is present but the install path and skill-discovery mechanism are not yet fully documented. Treat Cursor support as best-effort until confirmed. +**Cursor:** The `.cursor-plugin/plugin.json` manifest defines `skills`, `agents`, `commands`, and `hooks`. Installation is via `/plugin-add superpowers` in the Cursor agent chat (same marketplace mechanism as Claude Code). Skill discovery path (user scope) is managed through the plugin; no manual symlink required. ## Related files From 9190cc853d3f7e42ca33c6fddf6ecaaf4eaa610a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 25 Apr 2026 10:12:55 +0000 Subject: [PATCH 3/4] fix(cross-llm-coverage): update Cursor skill discovery path from unknown to via plugin Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/5435a1f1-c11d-4549-9f5e-6ba6ac6d84b8 Co-authored-by: intel352 <77607+intel352@users.noreply.github.com> --- docs/cross-llm-coverage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cross-llm-coverage.md b/docs/cross-llm-coverage.md index 4fb3c8f..60fa30a 100644 --- a/docs/cross-llm-coverage.md +++ b/docs/cross-llm-coverage.md @@ -16,7 +16,7 @@ Host-by-host capability matrix for the Superpowers skills system. | Task list / TodoWrite | ✅ built-in | ❌ no documented equivalent | ⚠️ `update_plan` mapping (see `.opencode/INSTALL.md`) | ⚠️ unknown | | AGENTS.md / project context | CLAUDE.md | AGENTS.md (+ `.override.md`) | AGENTS.md | n/a | | Host declaration for skill conditionals | `Host: claude-code` in CLAUDE.md | `Host: codex` in `~/.codex/AGENTS.md` | `Host: opencode` in `~/.config/opencode/AGENTS.md` | n/a | -| Skill discovery path (user scope) | `~/.claude/skills/` | `~/.agents/skills/` | `~/.config/opencode/skills/` | unknown | +| Skill discovery path (user scope) | `~/.claude/skills/` | `~/.agents/skills/` | `~/.config/opencode/skills/` | via plugin (no manual symlink) | | Model tier vocabulary | role names → `haiku`/`sonnet`/`opus` (see `agents/model-tiers.md`) | role names → `gpt-5.4-mini`/`gpt-5.4`/`gpt-5.5` | role names → host-pass-through | role names → host-pass-through | ## Notes From 6c7aaeb5cd75ff4024abfe3c0aabb7960a291ebe Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 25 Apr 2026 10:15:08 +0000 Subject: [PATCH 4/4] fix(cross-llm-coverage): clarify Claude Code skill discovery vs marketplace install path Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/1582f604-1b7b-4edb-aac1-013a4b416909 Co-authored-by: intel352 <77607+intel352@users.noreply.github.com> --- docs/cross-llm-coverage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cross-llm-coverage.md b/docs/cross-llm-coverage.md index 60fa30a..a107232 100644 --- a/docs/cross-llm-coverage.md +++ b/docs/cross-llm-coverage.md @@ -16,7 +16,7 @@ Host-by-host capability matrix for the Superpowers skills system. | Task list / TodoWrite | ✅ built-in | ❌ no documented equivalent | ⚠️ `update_plan` mapping (see `.opencode/INSTALL.md`) | ⚠️ unknown | | AGENTS.md / project context | CLAUDE.md | AGENTS.md (+ `.override.md`) | AGENTS.md | n/a | | Host declaration for skill conditionals | `Host: claude-code` in CLAUDE.md | `Host: codex` in `~/.codex/AGENTS.md` | `Host: opencode` in `~/.config/opencode/AGENTS.md` | n/a | -| Skill discovery path (user scope) | `~/.claude/skills/` | `~/.agents/skills/` | `~/.config/opencode/skills/` | via plugin (no manual symlink) | +| Skill discovery path (user scope) | `~/.claude/skills/` (personal skills); superpowers installed to `~/.claude/plugins/marketplace/superpowers/` via marketplace | `~/.agents/skills/` | `~/.config/opencode/skills/` | via plugin (no manual symlink) | | Model tier vocabulary | role names → `haiku`/`sonnet`/`opus` (see `agents/model-tiers.md`) | role names → `gpt-5.4-mini`/`gpt-5.4`/`gpt-5.5` | role names → host-pass-through | role names → host-pass-through | ## Notes