tamirs-superpowers — agent entrypoint

A multi-platform agent plugin: bundled skills, specialist agents, worktree hooks, and MCP server stubs, shipped to five platforms and, underneath them, six supported runtime surfaces: Claude (Claude Code, Claude Desktop), Codex (Codex CLI), Cursor (Cursor IDE), Gemini (Gemini CLI, gemini-extension.json), and OpenCode (OpenCode CLI). The four non-Claude platforms each have a further surface — the Codex IDE extension, the Cursor CLI, Gemini Code Assist, the OpenCode desktop app — that has never been measured here; claim nothing about them in either direction. It is not a Node/Python/Go app — no build step, no package.json, no compiled output. All content is Markdown, JSON, and Bash.

This file is a thin entrypoint, not the policy. Canonical policy lives in core/ and rules/; this page tells you which of those to read and gives you the commands. When this file and a canonical rule disagree, the canonical rule wins — say so rather than following the stale copy.

Read this first

The full index, including the hard-invariant vs configurable-policy split and the adapter map, is rules/README.md.

Work model in one paragraph

A user objective decomposes into worker tasks (a DAG). Each task runs in its own worktree on worker/<slug>/NNN, ends at commit + handoff, and never opens a PR. Workers compose into one integration worktree on objective/<slug>, which is where cross-worker review and full validation happen, and where the single PR is opened. Which provider ran a task is metadata recorded in .dev-files/objectives/<id>/, never encoded in a path or a branch name. Worker validation is targeted (Tier 1); full validation runs once at integration (Tier 2); CI is the final authority (Tier 3).

Commands

make validate           # shellcheck + JSON + skill frontmatter + repo contract + doc claims + Claude-only distribution check
make check-claude-dist  # build the Claude-only distribution to a temp dir and hold it to the plugin directory's rules
make lint               # shellcheck only
make test               # same as validate
make test-repo-contract # scaffold-gold (app-gold) + scaffold-plugin-gold (plugin-gold)
bash scripts/doctor.sh  # detected platform, version, dependencies, available capabilities
make install            # bootstrap Claude machine settings + agents (from a clone)
make update
make uninstall

Claude Code marketplace install:

/plugin marketplace add Tamircohen28/tamirs-marketplace
/plugin install tamirs-superpowers@tamirs-marketplace

Per-surface install guides: docs/user/install/ — one per supported surface, none for an unverified one. The machine-readable target list is platform-targets.json; the machine-readable capability list is core/capabilities/platforms.json.

Repo-specific expectations

These are true of this repository and are not in core/:

• All JSON must parse (jq empty) — checked by make validate.
• All .sh must pass shellcheck at -S warning — make lint.
• Every SKILL.md must validate against the portable schema, core/schemas/skill-frontmatter.json, enforced by scripts/validate-skill-frontmatter.py. Claude-specific fields are a documented extension of that schema, not a universal requirement — see rules/dev/skill-quality-standards.md.
• The version lives in one file, plugin-version.json. Never hand-edit a manifest, badge, or platform-targets.json version — run bash scripts/check-version-truth.sh --sync.
• Commit format <type>(<scope>): <description> — types feat, fix, chore, docs, refactor; scopes skills, hooks, core, rules, marketplace, ci, docs.
• Never add runs-on: [self-hosted] to a workflow — use ubuntu-latest.
• Never commit secrets — .mcp.json uses ${ENV_VAR} placeholders only.
• Never add employer-internal references (internal domains, private orgs, internal tooling names).
• Never add a marketplace.json here — publication goes through the separate Tamircohen28/tamirs-marketplace catalog.
• Never modify hooks/lib/worktree-common.sh without running shellcheck and testing both capture-task-slug.sh and worktree-create.sh.
• Never hand-write a SKILL.md — use the skill-creator skill.
• No install step for plugin content; make install only bootstraps machine settings and agents.

Surface skills at the moment they apply

When a situation arises that a bundled skill covers, either invoke the skill or tell the user in one line that it exists — do not silently hand-roll the work. One suggestion per situation per session; never repeat a declined suggestion.

Why the rule and not just good trigger descriptions: skill_auto_invocation in core/capabilities/platforms.json is partial on Cursor and unknown on Codex, Gemini CLI and OpenCode. Description-based auto-triggering only fires reliably on Claude Code and Claude Desktop, and the UserPromptSubmit hook that reinforces it (hooks/skill-suggest.sh) is unsupported on OpenCode. This rule is the only surfacing mechanism that works on every supported surface, which is why it is written down rather than left to the matcher.

Key paths

Cloud and headless runbook

Applies to Cursor Cloud, Codex sandboxes, Claude Code remote sessions, Gemini CLI, and CI — any non-interactive shell.

There is no app server or build output. "Running" this repo means exercising the validation harness:

Gotchas:

• scripts/statusline.sh reads JSON from stdin. With no piped input it blocks in non-interactive shells — always pipe or redirect (</dev/null). smoke.sh inherits stdin, so run it as smoke.sh </dev/null. The non-blocking requirement for new scripts is in user-facing-script-standards.md §4.
• shellcheck is required for shell coverage in make lint/make validate; if absent those targets skip shellcheck rather than failing. Install it via your system package manager.
• make check-manifest-versions needs network to compare against the latest release tag; it works offline against the current checkout.
• Cursor Cloud agents boot a fresh Linux VM — install shellcheck and pip install -r scripts/requirements-validate.txt first.

Platform-specific addenda: CLAUDE.md (Claude Code / Desktop), .cursor/rules/*.mdc (Cursor IDE), .codex/config.toml (Codex), docs/user/install/gemini.md (Gemini CLI), docs/user/install/opencode.md (OpenCode — note what does not port). Host-version notes — what each host release changed and what this repo adopted or declined because of it — live in docs/engineering/host-notes/, not in the platform files; the evidence-bearing record stays platform-targets.json.