README Marketplace Installation Design

Date: 2026-04-10

Goal

Rewrite the repository README installation guidance so it matches the marketplace-oriented style used by obra/superpowers, while limiting changes to README.md only.

Current State

• The installation section is organized as one heading per agent.
• Some entries point to install docs instead of marketplace or manifest entrypoints.
• The Codex entry references a .codex/INSTALL.md file that does not exist in this checkout.
• The repository already contains platform-facing artifacts that are better README targets:
  • .claude-plugin/marketplace.json
  • plugins/entire/.codex-plugin/plugin.json
  • .cursor-plugin/plugin.json
  • .opencode/INSTALL.md
  • gemini-extension.json
  • GEMINI.md

Chosen Approach

Replace the current per-agent install-doc wording in README.md with a marketplace-oriented installation section that points each platform at its primary package or manifest entrypoint.

Design Details

Installation section structure

The README installation section should remain concise and should:

• open with a short sentence that installation differs by agent platform
• list each supported platform with the artifact or package reference users should start from
• prefer marketplace/manifests over secondary install docs

Platform guidance

• Claude Code: point to .claude-plugin/marketplace.json
• Codex: point to plugins/entire/.codex-plugin/plugin.json
• Cursor: point to .cursor-plugin/plugin.json
• OpenCode: reference the package-based install flow already described in .opencode/INSTALL.md
• Gemini: point to gemini-extension.json and GEMINI.md

Non-goals

• No changes to any install docs or plugin manifests
• No new platform support
• No attempt to standardize installation mechanics across all agents in this pass

Verification

• Confirm README.md no longer refers to .codex/INSTALL.md
• Confirm the installation section references marketplace or manifest entrypoints for Claude, Codex, Cursor, and Gemini
• Confirm OpenCode wording references its package-style install path without modifying .opencode/INSTALL.md

README Marketplace Installation Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Update README.md so the installation section references marketplace and manifest entrypoints in the style of Superpowers without changing any underlying install files.

Architecture: This is a README-only documentation change. The implementation will replace stale per-agent install-doc references with the actual package, marketplace, and manifest surfaces already present in the repository.

Tech Stack: Markdown

Task 1: Rewrite README Installation Guidance

Files:

• Modify: README.md

Step 1: Write the failing test

Run: rg -n '\.codex/INSTALL\.md|\.claude-plugin/marketplace\.json|plugins/entire/\.codex-plugin/plugin\.json|\.cursor-plugin/plugin\.json|gemini-extension\.json|GEMINI\.md' README.md Expected: output includes .codex/INSTALL.md, but is missing one or more marketplace/manifest references that should appear after the rewrite

Step 2: Run test to verify it fails

Run: sed -n '35,90p' README.md Expected: the installation section still uses the old per-agent wording and includes the stale Codex install-doc reference

Step 3: Write minimal implementation

Update only the installation section in README.md so it:

• introduces installation as platform-specific
• points Claude Code to .claude-plugin/marketplace.json
• points Codex to plugins/entire/.codex-plugin/plugin.json
• points Cursor to .cursor-plugin/plugin.json
• points OpenCode to the package-based flow documented in .opencode/INSTALL.md
• points Gemini to gemini-extension.json and GEMINI.md

Step 4: Run test to verify it passes

Run: rg -n '\.codex/INSTALL\.md' README.md Expected: no output

Run: rg -n '\.claude-plugin/marketplace\.json|plugins/entire/\.codex-plugin/plugin\.json|\.cursor-plugin/plugin\.json|gemini-extension\.json|GEMINI\.md|\.opencode/INSTALL\.md' README.md Expected: all required references are present

Step 5: Commit

git add README.md  
git commit -m "docs: rewrite readme install section for marketplaces"  

Task 2: Final Verification

Files:

• Verify: README.md

Step 1: Write the failing test

Run: sed -n '1,120p' README.md Expected: if any install guidance still points to the stale Codex doc or lacks marketplace/manifests, the task is incomplete

Step 2: Run test to verify the final state

Run: rg -n '\.codex/INSTALL\.md' README.md && false || true Expected: command succeeds with no matches

Run: rg -n '\.claude-plugin/marketplace\.json|plugins/entire/\.codex-plugin/plugin\.json|\.cursor-plugin/plugin\.json|gemini-extension\.json|GEMINI\.md|\.opencode/INSTALL\.md' README.md Expected: output covers each platform reference intended by the design

Step 3: Write minimal implementation

If verification fails, adjust only README.md and rerun the verification commands.

Step 4: Run test to verify it passes

Run: git status --short Expected: only README.md is changed for this task, aside from unrelated pre-existing user changes

Step 5: Commit

git add README.md  
git commit -m "docs: point readme installs at marketplace entrypoints"