# 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**  
```bash  
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**  
```bash  
git add README.md  
git commit -m "docs: point readme installs at marketplace entrypoints"  
```