Skip to content

An agentic skills framework & software development methodology that works.

Phase C: alphabetize README platform listings + spec

Jesse Vincent1681f58a3fb5
diff --git a/README.md b/README.md
index 1175de61d..80bb94e34 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ If this sounds like someone you know, definitely send them our way.
## Quickstart
-Give your agent Superpowers: [Claude Code](#claude-code), [Codex CLI](#codex-cli), [Codex App](#codex-app), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [OpenCode](#opencode), [Cursor](#cursor), [GitHub Copilot CLI](#github-copilot-cli).
+Give your agent Superpowers: [Claude Code](#claude-code), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [OpenCode](#opencode).
## How it works
@@ -67,6 +67,14 @@ The Superpowers marketplace provides Superpowers and some other related plugins
/plugin install superpowers@superpowers-marketplace
```
+### Codex App
+
+Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
+
+- In the Codex app, click on Plugins in the sidebar.
+- You should see `Superpowers` in the Coding section.
+- Click the `+` next to Superpowers and follow the prompts.
+
### Codex CLI
Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
@@ -85,13 +93,15 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
- Select `Install Plugin`.
-### Codex App
+### Cursor
-Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
+- In Cursor Agent chat, install from marketplace:
-- In the Codex app, click on Plugins in the sidebar.
-- You should see `Superpowers` in the Coding section.
-- Click the `+` next to Superpowers and follow the prompts.
+ ```text
+ /add-plugin superpowers
+ ```
+
+- Or search for "superpowers" in the plugin marketplace.
### Factory Droid
@@ -121,29 +131,6 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
gemini extensions update superpowers
```
-### OpenCode
-
-OpenCode uses its own plugin install; install Superpowers separately even if you
-already use it in another harness.
-
-- Tell OpenCode:
-
- ```
- Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
- ```
-
-- Detailed docs: [docs/README.opencode.md](docs/README.opencode.md)
-
-### Cursor
-
-- In Cursor Agent chat, install from marketplace:
-
- ```text
- /add-plugin superpowers
- ```
-
-- Or search for "superpowers" in the plugin marketplace.
-
### GitHub Copilot CLI
- Register the marketplace:
@@ -158,6 +145,19 @@ already use it in another harness.
copilot plugin install superpowers@superpowers-marketplace
```
+### OpenCode
+
+OpenCode uses its own plugin install; install Superpowers separately even if you
+already use it in another harness.
+
+- Tell OpenCode:
+
+ ```
+ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
+ ```
+
+- Detailed docs: [docs/README.opencode.md](docs/README.opencode.md)
+
## The Basic Workflow
1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
diff --git a/docs/superpowers/specs/2026-05-05-platform-neutral-readme-design.md b/docs/superpowers/specs/2026-05-05-platform-neutral-readme-design.md
new file mode 100644
index 000000000..d6492ec83
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-05-platform-neutral-readme-design.md
@@ -0,0 +1,47 @@
+# Platform-neutral README ordering — Phase C design
+
+## Background
+
+Phases A and B (see `2026-05-05-platform-neutral-prose-design.md` and `2026-05-05-platform-neutral-config-refs-design.md`) already neutralized generic Claude prose and config-file references in the README. The remaining platform-leaning signal is layout: the README's two platform listings put Claude Code first and aren't strictly alphabetical elsewhere.
+
+This phase fixes the ordering. No prose changes.
+
+## In scope
+
+1. **Quickstart platform list** (`README.md:7`) — the inline link list of supported harnesses
+2. **Installation section ordering** (`README.md:35–152`) — the per-harness install sub-sections
+
+## Out of scope
+
+- Prose, marketplace names, plugin IDs, URLs — all factually correct as-is.
+- Visual weight of the Claude Code section (which has two sub-sections — official Anthropic marketplace and Superpowers marketplace). Both are real install paths; collapsing them would hide accurate info.
+- Section headings and content within each install block — only the ordering of the blocks changes.
+
+## Substitution
+
+Both listings reorder to strict alphabetical:
+
+| Old order | New order |
+|-----------|-----------|
+| Claude Code | Claude Code |
+| Codex CLI | Codex App |
+| Codex App | Codex CLI |
+| Factory Droid | Cursor |
+| Gemini CLI | Factory Droid |
+| OpenCode | Gemini CLI |
+| Cursor | GitHub Copilot CLI |
+| GitHub Copilot CLI | OpenCode |
+
+Three moves: Codex App swaps with Codex CLI; Cursor moves up two slots; GitHub Copilot CLI moves up one.
+
+Claude Code remains first by alphabetical chance (`Cl…` precedes `Co…`).
+
+## Commit plan
+
+One atomic commit covering both listings, since changing one without the other would create inconsistency between the quickstart and the installation section.
+
+## Verification
+
+- Quickstart anchors (`#claude-code`, `#codex-app`, etc.) still resolve to existing `### …` headings — no headings renamed.
+- Each install sub-section's body is byte-identical pre/post; only positions changed.
+- `git diff README.md` shows section moves only, no content edits.