Recommend Superpowers as first agent skill

[Zitzak]

Recommend Superpowers as Inverter's first agent skill

Adds a mechanism so anyone in the company — using any of our approved AI agents — discovers and installs Superpowers when they open this repo with their agent. Sets up the same delivery pipeline for any future Inverter-approved skills.

Why

The Inverter AI Standard catalogues approved tools and skills, but until now there was no mechanism for recommendations to actually reach an agent's context. Cloning the repo gave you docs to read; the agent itself learned nothing. This PR fixes that: any agent that indexes this repo now sees the recommendation auto-loaded into its session, and Claude Code users get a one-command install via a curated Inverter plugin marketplace.

Superpowers is the first skill we're recommending because it enforces a workflow we actively want for non-trivial dev work — brainstorm → plan → TDD → review → finish. Future Inverter-approved skills land in the same pipeline without restructuring.

Approach

Three layered mechanisms, each using its native ecosystem convention:

1. AGENTS.md at repo root — the cross-tool standard read by Codex, Cursor, Copilot, OpenCode, Aider, and Gemini. Contains the per-agent install table (one row per supported agent) and brief framing of why Superpowers is recommended.
2. CLAUDE.md at repo root → one-line @AGENTS.md import — Claude Code only auto-loads files literally named CLAUDE.md, but supports an @path import directive. The shim is the pattern Anthropic explicitly documents for repos using AGENTS.md for other agents. Single source of truth, zero duplication.
3. .claude-plugin/marketplace.json — Inverter-curated Claude Code plugin marketplace (inverter-standard) listing Superpowers v5.0.7 (MIT, source obra/superpowers). Gives Claude users a one-command install (/plugin install superpowers@inverter-standard). Other agents install via their own plugin systems because there's no cross-tool marketplace standard. Framed in docs as a Claude convenience, not the canonical recommendation.

Alternatives considered

Approach	Why not
Flat documentation .md only	Doesn't reach the agent's context. Anyone has to manually read the doc and decide to install. Loses the "indexing the repo recommends the skill" property entirely.
Git submodule (vendoring obra/superpowers)	Originally proposed because the existing excalidraw-diagram skill uses this pattern and the contribution guide has an "Importing Submodules" section. Rejected after subagent review: (a) Superpowers is loaded by agents from their own plugin systems, not from a vendored path here — vendoring is purely documentary; (b) upstream is a multi-platform plugin distribution (~2.5 MB of hooks, marketplace JSON, Codex/Cursor/Gemini wrappers, release notes) that's runtime-irrelevant to a docs repo; (c) the existing excalidraw submodule is uninitialised on fresh clones — the precedent is already silently failing.
CLAUDE.md at root, no AGENTS.md	First attempt. Caught in review: privileges Claude Code over the rest of the approved-tools roster (Cursor, ChatGPT, Codex). The repo's own framing is multi-tool; the discovery mechanism should match.
AGENTS.md only, no CLAUDE.md	Claude Code does not read AGENTS.md (confirmed in Anthropic's memory docs). Without the shim, Claude Code users would silently miss the recommendation.
Symlink CLAUDE.md → AGENTS.md	Works on Linux/macOS, breaks on Windows. The @AGENTS.md import is portable.

Verification

• Schema: .claude-plugin/marketplace.json validates as JSON; structure matches the working example at obra/superpowers-marketplace.
• @import syntax: Verified against Anthropic's memory docs. Documented, supports relative/absolute paths, recursive up to 5 hops; imports inside the project tree don't trigger the approval dialog. The @AGENTS.md shim is given as the canonical example for multi-agent repos.
• Walk-up-the-tree rule (from ai/skills/contributing/adding-content.md): every README between ai/skills/workflows/superpowers.md and ai/README.md has been updated.
• Independent review: An adversarial subagent review of the initial submodule-based approach surfaced the vendoring-vs-documentation distinction and confirmed the marketplace-plus-AGENTS.md shape.

Files changed

New

• AGENTS.md — cross-tool recommendation + per-agent install table
• CLAUDE.md — single-line @AGENTS.md import
• .claude-plugin/marketplace.json — Inverter Claude Code marketplace listing Superpowers
• ai/skills/workflows/README.md — workflow skills area README
• ai/skills/workflows/superpowers.md — catalog entry (why, when to use/skip, install, audit notes)

Modified

• ai/README.md — multi-tool callout under Skills + Workflows row in the domain table
• ai/skills/README.md — Workflows section linking marketplace and new skill

Known issues / follow-ups (out of scope here)

• Excalidraw submodule is broken on fresh clones. ai/skills/diagramming/excalidraw-diagram is a gitlink to coleam00/excalidraw-diagram-skill but was never submodule update --init-ed, so the link in ai/README.md 404s for new contributors. Pre-existing; flagged so it doesn't get conflated with the Workflows mechanism. Worth a separate PR.
• Pinning is loose. The marketplace entry tracks upstream main (no ref field, matching obra's own marketplace pattern). For stricter supply-chain control, add "ref": "<sha-or-tag>" to plugins[0].source. Bump audit guidance is in ai/skills/workflows/superpowers.md.
• owner.email omitted in marketplace.json — set to a team address (team@inverter.network?) if desired.
• Contribution guide doesn't yet mention the marketplace pattern. A follow-up to ai/skills/contributing/adding-content.md should cover how to add a new plugin to .claude-plugin/marketplace.json.

Reviewer asks

1. Is the tool-agnostic posture right, or should some agents be deprioritised in the install table?
2. Acceptable marketplace name (inverter-standard vs. inverter vs. inverter-network)?
3. Fill in owner.email now, or leave omitted?
4. Pin the Superpowers entry to a specific commit/tag now, or accept upstream-main tracking and pin later when there's a clear audit cadence?

🤖 Generated with Claude Code