diff --git a/README.md b/README.md index 40fd124..a8d0764 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,10 @@ 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) ## The Basic Workflow diff --git a/docs/cross-llm-coverage.md b/docs/cross-llm-coverage.md new file mode 100644 index 0000000..a107232 --- /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 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 | +| 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 `~/.config/opencode/AGENTS.md` | n/a | +| 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 + +**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 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 + +- `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)