<p align="center"> <img src="assets/banner.png" alt="tamirs-superpowers" width="600" /> </p> <p align="center"> <a href="https://github.com/Tamircohen28"><img src="https://img.shields.io/badge/author-Tamir%20Cohen-181717?logo=github" alt="Author" /></a> <a href="https://github.com/Tamircohen28/tamirs-superpowers/actions/workflows/ci.yml"><img src="https://github.com/Tamircohen28/tamirs-superpowers/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a> <a href="plugin-version.json"><img src="https://img.shields.io/badge/version-4.11.11-blue" alt="Version" /></a> </p> <p align="center"> <a href="docs/engineering/build-and-release/platform-targets.json"><img src="https://img.shields.io/badge/Claude%20Code-2.1.287-blueviolet" alt="Claude Code" /></a> <a href="docs/engineering/build-and-release/platform-targets.json"><img src="https://img.shields.io/badge/Cursor-3.22.7-000000" alt="Cursor" /></a> <a href="docs/engineering/build-and-release/platform-targets.json"><img src="https://img.shields.io/badge/Codex-0.156.0-412991" alt="Codex" /></a> <a href="docs/engineering/build-and-release/platform-targets.json"><img src="https://img.shields.io/badge/Gemini%20CLI-0.60.0-4285F4" alt="Gemini CLI" /></a> <a href="docs/engineering/build-and-release/platform-targets.json"><img src="https://img.shields.io/badge/OpenCode-2.0.14-fab283" alt="OpenCode" /></a> </p>

tamirs-superpowers

A portable agent toolkit: 29 skills, 10 role-based agents, worktree hooks, and MCP stubs, shipped from one canonical source to six agent surfaces across five platforms.

What problem it solves

Agent harnesses disagree about everything — skill frontmatter, subagents, hooks, install mechanics, where global config lives — so multi-platform setups duplicate content until it drifts, or claim features a platform does not have. And one feature request typically lands as five disconnected pull requests with no place the combined diff is ever reviewed.

• One canonical source, thin adapters. Skills, roles, rules, and policies live once under skills/, core/, and rules/; per-platform files are generated, and drift fails CI.
• Honest capability degradation. core/capabilities/platforms.json records what each surface actually supports — unknown and unsupported included — and every skill states its fallback instead of pretending.
• One objective = one pull request. Work is decomposed into tasks that end at commit + handoff, merged onto one integration branch, reviewed as one diff, delivered once.
• Your machine is rendered from the repo. make setup writes the same global rules into all five platforms' own config formats; nothing is hand-copied per platform.

Supported platforms

Five platforms. Each one has more than one surface — a terminal client, a desktop app, an editor extension — and they do not all behave alike, so the surface is what carries a support status, an install path, and a capability row. Six surfaces are supported: those are the ones this repo installs into and validates. The rest are listed because they are real surfaces users ask about; nothing has been measured on them, in either direction.

Claude

One plugin, one marketplace listing, both surfaces.

| Surface | Registry id | Kind | Status | Install | |---|---|---|---|---| | Claude Code | claude_code | CLI | ✅ supported — validated 2.1.287 | guide | | Claude Desktop | claude_desktop | desktop | ✅ supported — same plugin, different runtime surface | guide |

Codex

Installed from the plugin marketplace; the CLI is the measured surface.

| Surface | Registry id | Kind | Status | Install | |---|---|---|---|---| | Codex CLI | codex | CLI | ✅ supported — validated 0.156.0 | guide | | Codex IDE extension | codex_ide | IDE | ⚠️ unverified — reads the same AGENTS.md and manifest, but the plugin has never been installed or a skill invoked there | — |

Cursor

Added as a plugin source in Cursor, then installed from it.

| Surface | Registry id | Kind | Status | Install | |---|---|---|---|---| | Cursor IDE | cursor | IDE | ✅ supported — validated 3.22.7 | guide | | Cursor CLI | cursor_cli | CLI | ⚠️ unverified — shares the plugin manifest with the IDE, but no CLI run has been recorded here | — |

Gemini

Two commands: the extension carries context and MCP, skills install separately.

| Surface | Registry id | Kind | Status | Install | |---|---|---|---|---| | Gemini CLI | gemini_cli | CLI | ✅ supported — validated 0.60.0 | guide | | Gemini Code Assist | gemini_code_assist | IDE | ⚠️ unverified — a different host that does not install CLI extensions, so the .gemini/ mirror has no established install path there | — |

OpenCode

Installed by path — opencode.json's skills array pointed at this checkout (v2 shape; v1 used skills.paths).

| Surface | Registry id | Kind | Status | Install | |---|---|---|---|---| | OpenCode CLI | opencode | CLI | ✅ supported — validated 2.0.14 (v2; @opencode/cli). Config and all 10 agent adapters confirmed live; per-skill discovery unverified — v2 removed debug skill | guide | guide | | OpenCode desktop app | opencode_desktop | desktop | ⚠️ unverified — whether it reads the same skills.paths this repo installs into has not been checked | — |

⚠️ unverified is not a negative result. Those surfaces carry no capability claims at all; core/capabilities/platforms.json records why each one was never measured rather than guessing from its sibling.

Capabilities differ per surface, sometimes a lot. The honest, registry-generated comparison is docs/user/platform-differences.md.

Prerequisites

To use the plugin. git 2.30+ and jq. gh is optional and only used by the PR and issue workflows. Nothing on the user path needs Node, Python, or a build step — the skills are shell and markdown. Each surface's install guide lists anything that surface adds on top; Gemini is the one that needs a second command, because its skills ship as a generated flat mirror installed with --path.

To contribute. make validate is the same gate CI runs, and it needs three things the user path does not:

| Tool | Needed by | |------|-----------| | shellcheck | make lint — shellchecks every tracked *.sh, at any depth | | Node 22 (pinned in .nvmrc) | builds the scaffold-plugin-gold contract fixture | | Python 3 + pyyaml>=6.0 | pip install -r scripts/requirements-validate.txt — SKILL.md frontmatter and the portable skill contract |

make plugin-validate and make test-mods (the mod's validator and tests) additionally want the claude CLI (2.1.287+ for the mod); make validate does not run them. Confirm a machine is ready with bash scripts/doctor.sh ..

Install in 5 minutes

1. Install the plugin. Pick your platform and surface from the tables above — each supported surface's guide covers install, verify, update, and uninstall. On Claude you can also add it from Anthropic's plugin directory, which tracks a Claude-only distribution this repository builds on every release (how); PRIVACY.md says what the plugin sends, and only when you opt in. Gemini alone takes two commands: the extension carries context and MCP, while skills come from a generated flat mirror at .gemini/skills/ that must be installed with --path. Why.

2. Configure your machine — optional, and now the part that changed. make setup renders this repo's canonical config into the config directory of every agent CLI it detects: ~/.claude, ~/.codex, ~/.cursor, ~/.gemini, ~/.config/opencode. One set of global rules, one permissions policy, in each platform's own format.

git clone https://github.com/Tamircohen28/tamirs-superpowers.git
cd tamirs-superpowers
make setup-plan     # detect targets, print every change, write nothing
make setup          # diff → confirm → write, one change at a time

It merges into what is already there, shows a diff before each write, defaults to No, and bash scripts/setup.sh remove undoes it. This supersedes make install, which configured only Claude Code, only partially, and rewrote ~/.claude/settings.json wholesale — the old path is now a thin shim over the same engine. Read setup before the first apply: it will switch off plugins the canonical set records as deliberately disabled. The other four platforms: platform setup.

Check the result with bash scripts/doctor.sh .; the requirements are listed under Prerequisites above.

Contributing to this repo is a different setup — git clone, then make validate. See contributor bootstrap.

Core workflow

/orchestrate-dev  →  task graph  →  workers (commit + handoff)  →  integration branch
                                          →  combined-diff review  →  ONE PR  →  /pr-dev

| Skill | Does | |---|---| | /plan-dev | Turn a request into phases and issues | | /orchestrate-dev | Own an objective: task graph, dispatch, integrate, deliver one PR | | /worker-dev | Execute one task; end at commit + handoff, never a PR | | /deliver-dev | Review the integrated diff, run the gates, open the one PR | | /pr-dev | Drive that PR to merge | | /start-dev | Compatibility front door — routes to the above |

Orchestration works with no subagents at all: same task graph, same handoffs, same one PR, run sequentially. See docs/user/orchestration.md.

What the mod does

On Claude Code 2.1.287+ the plugin ships one mod (mod/register.tsx). It makes no network call.

• Reads (local, never sent anywhere): objective, task and handoff JSON under .dev-files/objectives, your project's CLAUDE.md (only to find the commit-trailer line), and .git/HEAD.
• Prompts it submits: none. The rate-limit band only displays "type /switch-dev handoff"; the mod makes no prompt.submit call.
• command.run hook: answers /objective with the current objective summary. It changes nothing.
• agent.spawn hooks (2): count workers in flight for the spinner and the objective pane. The spawn always passes through unchanged.
• Optional semantic_skill_suggest (off by default): see PRIVACY.md.

Links

• Getting started · Setup · Platform setup · Capture · Configuration · Troubleshooting
• Concepts · Skills · Agents · Orchestration · Platform differences
• Engineering docs — architecture, capability model, adapter contract, skill schema, release process
• Changelog · Contributing · Contributor bootstrap · License

---

MIT © Tamir Cohen