Add Codex superpowers integration

- Single unified script: superpowers-codex with bootstrap/use-skill/find-skills commands
- Cross-platform Node.js implementation (works on Windows, macOS, Linux)
- Namespaced skills: superpowers:skill-name for core, skill-name for personal
- Personal skills override superpowers skills when names match
- Clean skill display: shows name/description without raw frontmatter
- Helpful context: shows supporting files directory for each skill
- Tool mapping for Codex: TodoWrite→update_plan, Skill→superpowers-codex, etc.
- Subagent orchestration instructions for codex --yolo exec
- Updated terminology: "Superpowers skills" instead of "Core skills"
- Bootstrap integration with AGENTS.md for automatic startup

.codex/INSTALL.md

@@ -1,35 +0,0 @@
-# Installing Superpowers for Codex
-
-Quick setup to enable superpowers skills in Codex.
-
-## Installation
-
-1. **Clone superpowers repository**:
-   ```bash
-   mkdir -p ~/.codex/superpowers
-   cd ~/.codex/superpowers
-   git clone https://github.com/obra/superpowers.git .
-   ```
-
-2. **Create personal skills directory**:
-   ```bash
-   mkdir -p ~/.codex/skills
-   ```
-
-3. **Update ~/.codex/AGENTS.md** to include this superpowers section:
-   ```markdown
-   ## Superpowers System
-
-   <EXTREMELY_IMPORTANT>
-   You have superpowers. Superpowers teach you new skills and capabilities. RIGHT NOW run: `~/.codex/superpowers/.codex/superpowers-codex bootstrap` and follow the instructions it returns.
-   </EXTREMELY_IMPORTANT>
-   ```
-
-## Verification
-
-Test the installation:
-```bash
-~/.codex/superpowers/.codex/superpowers-codex bootstrap
-```
-
-You should see skill listings and bootstrap instructions. The system is now ready for use.

.codex/superpowers-bootstrap.md

@@ -1,33 +0,0 @@
-# Superpowers Bootstrap for Codex
-
-<EXTREMELY_IMPORTANT>
-You have superpowers.
-
-**Tool for running skills:**
-- `~/.codex/superpowers/.codex/superpowers-codex use-skill <skill-name>`
-
-**Tool Mapping for Codex:**
-When skills reference tools you don't have, substitute your equivalent tools:
-- `TodoWrite` → `update_plan` (your planning/task tracking tool)
-- `Task` tool with subagents → Tell the user that subagents aren't available in Codex yet and you'll do the work the subagent would do
-- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill` command (already available)
-- `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions
-
-**Skills naming:**
-- Superpowers skills: `superpowers:skill-name` (from ~/.codex/superpowers/skills/)
-- Personal skills: `skill-name` (from ~/.codex/skills/)
-- Personal skills override superpowers skills when names match
-
-**Critical Rules:**
-- Before ANY task, review the skills list (shown below)
-- If a relevant skill exists, you MUST use `~/.codex/superpowers/.codex/superpowers-codex use-skill` to load it
-- Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
-- Skills with checklists require `update_plan` todos for each item
-- NEVER skip mandatory workflows (brainstorming before coding, TDD, systematic debugging)
-
-**Skills location:**
-- Superpowers skills: ~/.codex/superpowers/skills/
-- Personal skills: ~/.codex/skills/ (override superpowers when names match)
-
-IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
-</EXTREMELY_IMPORTANT>

README.md

@@ -1,6 +1,6 @@
 # Superpowers
 
-A comprehensive skills library of proven techniques, patterns, and workflows for AI coding assistants.
+Give Claude Code superpowers with a comprehensive skills library of proven techniques, patterns, and workflows.
 
 ## What You Get
 
@@ -21,7 +21,7 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/
 
 ## Installation
 
-### Claude Code (via Plugin Marketplace)
+### Via Plugin Marketplace (Recommended)
 
 ```bash
 # In Claude Code
@@ -41,12 +41,6 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/
 # /superpowers:execute-plan - Execute plan in batches
 ```
 
-### Codex (Experimental)
-
-**Note:** Codex support is experimental and may require refinement based on user feedback.
-
-Tell Codex to fetch https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md and follow the instructions.
-
 ## Quick Start
 
 ### Using Slash Commands

RELEASE-NOTES.md

@@ -1,33 +1,5 @@
 # Superpowers Release Notes
 
-## v3.3.0 (2025-10-28)
-
-### New Features
-
-**Experimental Codex Support**
-- Added unified `superpowers-codex` script with bootstrap/use-skill/find-skills commands
-- Cross-platform Node.js implementation (works on Windows, macOS, Linux)
-- Namespaced skills: `superpowers:skill-name` for superpowers skills, `skill-name` for personal
-- Personal skills override superpowers skills when names match
-- Clean skill display: shows name/description without raw frontmatter
-- Helpful context: shows supporting files directory for each skill
-- Tool mapping for Codex: TodoWrite→update_plan, subagents→manual fallback, etc.
-- Bootstrap integration with minimal AGENTS.md for automatic startup
-- Complete installation guide and bootstrap instructions specific to Codex
-
-**Key differences from Claude Code integration:**
-- Single unified script instead of separate tools
-- Tool substitution system for Codex-specific equivalents
-- Simplified subagent handling (manual work instead of delegation)
-- Updated terminology: "Superpowers skills" instead of "Core skills"
-
-### Files Added
-- `codex/INSTALL.md` - Installation guide for Codex users
-- `codex/superpowers-bootstrap.md` - Bootstrap instructions with Codex adaptations
-- `scripts/superpowers-codex` - Unified Node.js executable with all functionality
-
-**Note:** Codex support is experimental. The integration provides core superpowers functionality but may require refinement based on user feedback.
-
 ## v3.2.3 (2025-10-23)
 
 ### Improvements

codex/INSTALL.md

@@ -0,0 +1,135 @@
+# Installing Superpowers for Codex
+
+This guide will help you install and set up the Superpowers skill system for Codex.
+
+## Quick Installation
+
+1. **Clone Superpowers to ~/.codex/superpowers/**:
+   ```bash
+   mkdir -p ~/.codex/superpowers
+   cd ~/.codex/superpowers
+   git clone https://github.com/obra/superpowers.git .
+   ```
+
+2. **Create personal skills directory**:
+   ```bash
+   mkdir -p ~/.codex/skills
+   ```
+
+3. **Add script paths to your environment** (optional but recommended):
+   ```bash
+   echo 'export PATH="$HOME/.codex/superpowers/scripts:$PATH"' >> ~/.bashrc
+   source ~/.bashrc
+   ```
+
+## Directory Structure
+
+After installation, you'll have:
+
+```
+~/.codex/
+├── superpowers/           # Core superpowers repository
+│   ├── skills/           # Core skills (brainstorming, TDD, etc.)
+│   ├── scripts/          # find-skills and skill-run tools
+│   └── .codex/           # Codex-specific configuration
+└── skills/               # Your personal skills (override core)
+    └── category/
+        └── skill-name/
+            └── SKILL.md
+```
+
+## Tool Usage
+
+### Finding Skills
+```bash
+find-skills                    # List all available skills
+find-skills brainstorm        # Filter skills by pattern
+```
+
+### Running Skills
+```bash
+skill-run brainstorming              # Load a skill
+skill-run skills/brainstorming       # Same thing
+```
+
+## Skill Override System
+
+Personal skills in `~/.codex/skills/` take precedence over core skills:
+
+- **Core skill**: `~/.codex/superpowers/skills/brainstorming/SKILL.md`
+- **Personal override**: `~/.codex/skills/brainstorming/SKILL.md` ← This wins
+
+## Bootstrap Setup
+
+The bootstrap system ensures Codex automatically:
+
+1. Reads the superpowers-bootstrap.md on startup
+2. Runs find-skills to show available skills
+3. Knows how to use the skill tools
+
+See `~/.codex/AGENTS.md` for the bootstrap configuration.
+
+## Troubleshooting
+
+### Scripts not found
+```bash
+# Add to PATH or use full paths:
+~/.codex/superpowers/scripts/find-skills
+~/.codex/superpowers/scripts/skill-run
+```
+
+### No skills showing
+```bash
+# Check directory structure:
+ls ~/.codex/superpowers/skills/
+ls ~/.codex/skills/
+```
+
+### Permission errors
+```bash
+# Make scripts executable:
+chmod +x ~/.codex/superpowers/scripts/*
+```
+
+## Creating Personal Skills
+
+1. Create directory structure:
+   ```bash
+   mkdir -p ~/.codex/skills/my-category/my-skill
+   ```
+
+2. Create SKILL.md with frontmatter:
+   ```markdown
+   ---
+   name: My Skill Name
+   description: What this skill does
+   when_to_use: When to apply this skill
+   ---
+
+   # My Skill
+
+   Skill content here...
+   ```
+
+3. Test it:
+   ```bash
+   find-skills my-skill
+   skill-run my-skill
+   ```
+
+## Integration with Codex
+
+Once installed, Codex will automatically have access to:
+
+- **find-skills**: Discover available skills
+- **skill-run**: Load and apply skills
+- **Mandatory workflows**: Brainstorming before coding, systematic debugging, etc.
+- **TodoWrite integration**: Checklist tracking from skills
+
+The bootstrap ensures these tools are available from the first Codex session.
+
+## Compatibility Notes
+
+- Scripts are compatible with bash 3.2+ (works on macOS and Linux)
+- No external dependencies required
+- Works with existing Codex configuration

codex/superpowers-bootstrap.md

@@ -0,0 +1,131 @@
+# Superpowers Bootstrap for Codex
+
+<EXTREMELY_IMPORTANT>
+You have superpowers.
+
+**Tool path for running skills:**
+- superpowers-codex: ~/.codex/superpowers/scripts/superpowers-codex
+
+**Important:** ALL AVAILABLE SKILLS ARE DISCLOSED ABOVE. You have complete visibility into every skill at session start.
+
+**Tool Mapping for Codex:**
+When skills reference tools you don't have, substitute your equivalent tools:
+- `TodoWrite` → `update_plan` (your planning/task tracking tool)
+- `Task` tool with subagents → `codex --yolo exec "prompt"` (see subagent section below)
+- `Skill` tool → `superpowers-codex use-skill` command (already available)
+- `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions
+</EXTREMELY_IMPORTANT>
+
+## Getting Started with Skills
+
+Two skill libraries work together:
+- **Superpowers skills** at `~/.codex/superpowers/skills/` (from superpowers repository)
+- **Personal skills** at `~/.codex/skills/` (yours to create and share)
+
+Personal skills shadow superpowers skills when names match.
+
+## Critical Rules
+
+1. **Use skill-run before announcing skill usage.** The bootstrap does NOT read skills for you. Announcing without calling skill-run = lying.
+
+2. **Follow mandatory workflows.** Brainstorming before coding. Check for skills before ANY task.
+
+3. **Create TodoWrite todos for checklists.** Mental tracking = steps get skipped. Every time.
+
+## Mandatory Workflow: Before ANY Task
+
+**1. Review skills list** (completely disclosed above - no searching needed).
+
+**2. If relevant skill exists, YOU MUST use it:**
+
+- Use superpowers-codex: `~/.codex/superpowers/scripts/superpowers-codex use-skill superpowers:skill-name`
+- Read ENTIRE output, not just summary
+- Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
+- Follow it exactly
+
+**Don't rationalize:**
+- "I remember this skill" - Skills evolve. Read the current version.
+- "Bootstrap showed it to me" - That was just the list. Read the actual skill.
+- "This doesn't count as a task" - It counts. Find and read skills.
+
+**Why:** Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.
+
+## Skills with Checklists
+
+If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item.
+
+**Don't:**
+- Work through checklist mentally
+- Skip creating todos "to save time"
+- Batch multiple items into one todo
+- Mark complete without doing them
+
+**Why:** Checklists without TodoWrite tracking = steps get skipped. Every time.
+
+## How to Use skill-run
+
+Every skill has the same structure:
+
+1. **Frontmatter** - `when_to_use` tells you if this skill matches your situation
+2. **Overview** - Core principle in 1-2 sentences
+3. **Quick Reference** - Scan for your specific pattern
+4. **Implementation** - Full details and examples
+5. **Supporting files** - Load only when implementing
+
+**Many skills contain rigid rules (TDD, debugging, verification).** Follow them exactly. Don't adapt away the discipline.
+
+**Some skills are flexible patterns (architecture, naming).** Adapt core principles to your context.
+
+## Instructions ≠ Permission to Skip Workflows
+
+Your human partner's specific instructions describe WHAT to do, not HOW.
+
+"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.
+
+## Summary
+
+**Starting any task:**
+1. Run find-skills to check for relevant skills
+2. If relevant skill exists → Use skill-run with full path
+3. Announce you're using it
+4. Follow what it says
+
+**Skill has checklist?** TodoWrite for every item.
+
+**Finding a relevant skill = mandatory to read and use it. Not optional.**
+
+## Subagent Orchestration for Codex
+
+When skills reference dispatching subagents or parallel agents, use Codex's subagent capabilities:
+
+**Launch subagents with:**
+```bash
+codex --yolo exec "your detailed prompt here"
+```
+
+**Key guidelines:**
+1. **Always quote/escape prompts** - avoid unescaped backticks or `$()` that shell might interpolate
+2. **Set timeout for long tasks** - use `timeout_ms: 1800000` (30 minutes) in your bash calls
+3. **Parallel execution** - use background jobs (`& ... & wait`) but check individual logs for completion
+4. **Lightweight prompts** - subagents inherit CLI defaults, so keep prompts focused and clear
+
+**Example:**
+```bash
+# Single subagent
+codex --yolo exec "Debug the authentication bug in user.py and propose a fix"
+
+# Parallel subagents
+codex --yolo exec "Test the API endpoints" &
+codex --yolo exec "Review the database schema" &
+wait
+
+# Using superpowers skills in subagents
+codex --yolo exec "Use superpowers:systematic-debugging to find the root cause of the login failure"
+```
+
+**When to use subagents:**
+- Skills mention "dispatching parallel agents"
+- Tasks that can be broken into independent work
+- Code review, testing, or investigation that benefits from fresh perspective
+
+---

scripts/superpowers-codex

@@ -3,40 +3,14 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync } = require('child_process');
 
 // Paths
 const homeDir = os.homedir();
 const superpowersSkillsDir = path.join(homeDir, '.codex', 'superpowers', 'skills');
 const personalSkillsDir = path.join(homeDir, '.codex', 'skills');
-const bootstrapFile = path.join(homeDir, '.codex', 'superpowers', '.codex', 'superpowers-bootstrap.md');
+const bootstrapFile = path.join(homeDir, '.codex', 'superpowers', 'codex', 'superpowers-bootstrap.md');
-const superpowersRepoDir = path.join(homeDir, '.codex', 'superpowers');
 
 // Utility functions
-function checkForUpdates() {
-    try {
-        // Quick check with 3 second timeout to avoid delays if network is down
-        const output = execSync('git fetch origin && git status --porcelain=v1 --branch', {
-            cwd: superpowersRepoDir,
-            timeout: 3000,
-            encoding: 'utf8',
-            stdio: 'pipe'
-        });
-
-        // Parse git status output to see if we're behind
-        const statusLines = output.split('\n');
-        for (const line of statusLines) {
-            if (line.startsWith('## ') && line.includes('[behind ')) {
-                return true; // We're behind remote
-            }
-        }
-        return false; // Up to date
-    } catch (error) {
-        // Network down, git error, timeout, etc. - don't block bootstrap
-        return false;
-    }
-}
-
 function extractFrontmatter(filePath) {
     try {
         const content = fs.readFileSync(filePath, 'utf8');
@@ -170,17 +144,6 @@ function runBootstrap() {
     console.log('# ================================');
     console.log('');
 
-    // Check for updates (with timeout protection)
-    if (checkForUpdates()) {
-        console.log('## Update Available');
-        console.log('');
-        console.log('⚠️  Your superpowers installation is behind the latest version.');
-        console.log('To update, run: `cd ~/.codex/superpowers && git pull`');
-        console.log('');
-        console.log('---');
-        console.log('');
-    }
-
     // Show the bootstrap instructions
     if (fs.existsSync(bootstrapFile)) {
         console.log('## Bootstrap Instructions:');