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

.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "superpowers-dev",
+  "description": "Development marketplace for Superpowers core skills library",
+  "owner": {
+    "name": "Jesse Vincent",
+    "email": "jesse@fsck.com"
+  },
+  "plugins": [
+    {
+      "name": "superpowers",
+      "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
+      "version": "3.2.2",
+      "source": "./",
+      "author": {
+        "name": "Jesse Vincent",
+        "email": "jesse@fsck.com"
+      }
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers",
   "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "3.0.1",
+  "version": "3.2.3",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

README.md

@@ -1,29 +1,19 @@
 # Superpowers
 
-Give Claude Code superpowers with a comprehensive skills library of proven techniques, patterns, and tools.
-
-## Architecture
-
-The superpowers plugin is a minimal shim that:
-- Clones/updates the [superpowers-skills](https://github.com/obra/superpowers-skills) repository to `~/.config/superpowers/skills/`
-- Registers hooks that load skills from the local repository
-- Offers users the option to fork the skills repo for contributions
-
-All skills, scripts, and documentation live in the separate [superpowers-skills](https://github.com/obra/superpowers-skills) repository. Edit skills locally, commit changes, and contribute back via pull requests.
-
-**Skills Repository:** https://github.com/obra/superpowers-skills
+Give Claude Code superpowers with a comprehensive skills library of proven techniques, patterns, and workflows.
 
 ## What You Get
 
 - **Testing Skills** - TDD, async testing, anti-patterns
 - **Debugging Skills** - Systematic debugging, root cause tracing, verification
 - **Collaboration Skills** - Brainstorming, planning, code review, parallel agents
-- **Meta Skills** - Creating, testing, and contributing skills
+- **Development Skills** - Git worktrees, finishing branches, subagent workflows
+- **Meta Skills** - Creating, testing, and sharing skills
 
 Plus:
-- **Slash Commands** - `/brainstorm`, `/write-plan`, `/execute-plan`
-- **Skills Search** - Grep-powered discovery of relevant skills
-- **Gap Tracking** - Failed searches logged for skill creation
+- **Slash Commands** - `/superpowers:brainstorm`, `/superpowers:write-plan`, `/superpowers:execute-plan`
+- **Automatic Integration** - Skills activate automatically when relevant
+- **Consistent Workflows** - Systematic approaches to common engineering tasks
 
 ## Learn More
 
@@ -39,8 +29,6 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/
 /plugin install superpowers@superpowers-marketplace
 ```
 
-The plugin automatically handles skills repository setup on first run.
-
 ### Verify Installation
 
 ```bash
@@ -48,110 +36,83 @@ The plugin automatically handles skills repository setup on first run.
 /help
 
 # Should see:
-# /brainstorm - Interactive design refinement
-# /write-plan - Create implementation plan
-# /execute-plan - Execute plan in batches
+# /superpowers:brainstorm - Interactive design refinement
+# /superpowers:write-plan - Create implementation plan
+# /superpowers:execute-plan - Execute plan in batches
 ```
 
-## Updating Skills
-
-The plugin fetches and fast-forwards your local skills repository on each session start. If your local branch has diverged, Claude notifies you to use the pulling-updates-from-skills-repository skill.
-
-## Contributing Skills
-
-If you forked the skills repository during setup, you can contribute improvements:
-
-1. Edit skills in `~/.config/superpowers/skills/`
-2. Commit your changes
-3. Push to your fork
-4. Open a PR to `obra/superpowers-skills`
-
 ## Quick Start
 
-### Finding Skills
-
-Find skills before starting any task:
-
-```bash
-${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills              # All skills with descriptions
-${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills test         # Filter by pattern
-${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills 'TDD|debug'  # Regex pattern
-```
-
 ### Using Slash Commands
 
 **Brainstorm a design:**
 ```
-/brainstorm
+/superpowers:brainstorm
 ```
 
 **Create an implementation plan:**
 ```
-/write-plan
+/superpowers:write-plan
 ```
 
 **Execute the plan:**
 ```
-/execute-plan
+/superpowers:execute-plan
 ```
 
+### Automatic Skill Activation
+
+Skills activate automatically when relevant. For example:
+- `test-driven-development` activates when implementing features
+- `systematic-debugging` activates when debugging issues
+- `verification-before-completion` activates before claiming work is done
+
 ## What's Inside
 
 ### Skills Library
 
 **Testing** (`skills/testing/`)
-- test-driven-development - RED-GREEN-REFACTOR cycle
-- condition-based-waiting - Async test patterns
-- testing-anti-patterns - Common pitfalls to avoid
+- **test-driven-development** - RED-GREEN-REFACTOR cycle
+- **condition-based-waiting** - Async test patterns
+- **testing-anti-patterns** - Common pitfalls to avoid
 
 **Debugging** (`skills/debugging/`)
-- systematic-debugging - 4-phase root cause process
-- root-cause-tracing - Find the real problem
-- verification-before-completion - Ensure it's actually fixed
-- defense-in-depth - Multiple validation layers
+- **systematic-debugging** - 4-phase root cause process
+- **root-cause-tracing** - Find the real problem
+- **verification-before-completion** - Ensure it's actually fixed
+- **defense-in-depth** - Multiple validation layers
 
 **Collaboration** (`skills/collaboration/`)
-- brainstorming - Socratic design refinement
-- writing-plans - Detailed implementation plans
-- executing-plans - Batch execution with checkpoints
-- dispatching-parallel-agents - Concurrent subagent workflows
-- remembering-conversations - Search past work
-- using-git-worktrees - Parallel development branches
-- requesting-code-review - Pre-review checklist
-- receiving-code-review - Responding to feedback
+- **brainstorming** - Socratic design refinement
+- **writing-plans** - Detailed implementation plans
+- **executing-plans** - Batch execution with checkpoints
+- **dispatching-parallel-agents** - Concurrent subagent workflows
+- **requesting-code-review** - Pre-review checklist
+- **receiving-code-review** - Responding to feedback
+- **using-git-worktrees** - Parallel development branches
+- **finishing-a-development-branch** - Merge/PR decision workflow
+- **subagent-driven-development** - Fast iteration with quality gates
 
 **Meta** (`skills/meta/`)
-- writing-skills - TDD for documentation, create new skills
-- sharing-skills - Contribute skills back via branch and PR
-- testing-skills-with-subagents - Validate skill quality
-- pulling-updates-from-skills-repository - Sync with upstream
-- gardening-skills-wiki - Maintain and improve skills
+- **writing-skills** - Create new skills following best practices
+- **sharing-skills** - Contribute skills back via branch and PR
+- **testing-skills-with-subagents** - Validate skill quality
+- **using-superpowers** - Introduction to the skills system
 
 ### Commands
 
-- **brainstorm.md** - Interactive design refinement using Socratic method
-- **write-plan.md** - Create detailed implementation plans
-- **execute-plan.md** - Execute plans in batches with review checkpoints
+All commands are thin wrappers that activate the corresponding skill:
 
-### Tools
-
-- **find-skills** - Unified skill discovery with descriptions
-- **skill-run** - Generic runner for any skill script
-- **search-conversations** - Semantic search of past Claude sessions (in remembering-conversations skill)
-
-**Using tools:**
-```bash
-${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills              # Show all skills
-${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills pattern      # Search skills
-${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/skill-run <path> [args]  # Run any skill script
-```
+- **brainstorm.md** - Activates the `brainstorming` skill
+- **write-plan.md** - Activates the `writing-plans` skill
+- **execute-plan.md** - Activates the `executing-plans` skill
 
 ## How It Works
 
-1. **SessionStart Hook** - Clone/update skills repo, inject skills context
-2. **Skills Discovery** - `find-skills` shows all available skills with descriptions
-3. **Mandatory Workflow** - Skills become required when they exist for your task
-4. **Gap Tracking** - Failed searches logged for skill development
+1. **SessionStart Hook** - Loads the `using-superpowers` skill at session start
+2. **Skills System** - Uses Claude Code's first-party skills system
+3. **Automatic Discovery** - Claude finds and uses relevant skills for your task
+4. **Mandatory Workflows** - When a skill exists for your task, using it becomes required
 
 ## Philosophy
 
@@ -161,6 +122,26 @@ ${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/skill-run <path> [args]  # Run an
 - **Evidence over claims** - Verify before declaring success
 - **Domain over implementation** - Work at problem level, not solution level
 
+## Contributing
+
+Skills live directly in this repository. To contribute:
+
+1. Fork the repository
+2. Create a branch for your skill
+3. Follow the `writing-skills` skill for creating new skills
+4. Use the `testing-skills-with-subagents` skill to validate quality
+5. Submit a PR
+
+See `skills/meta/writing-skills/SKILL.md` for the complete guide.
+
+## Updating
+
+Skills update automatically when you update the plugin:
+
+```bash
+/plugin update superpowers
+```
+
 ## License
 
 MIT License - see LICENSE file for details

RELEASE-NOTES.md

@@ -1,5 +1,90 @@
 # Superpowers Release Notes
 
+## v3.2.3 (2025-10-23)
+
+### Improvements
+
+**Updated using-superpowers skill to use Skill tool instead of Read tool**
+- Changed skill invocation instructions from Read tool to Skill tool
+- Updated description: "using Read tool" → "using Skill tool"
+- Updated step 3: "Use the Read tool" → "Use the Skill tool to read and run"
+- Updated rationalization list: "Read the current version" → "Run the current version"
+
+The Skill tool is the proper mechanism for invoking skills in Claude Code. This update corrects the bootstrap instructions to guide agents toward the correct tool.
+
+### Files Changed
+- Updated: `skills/using-superpowers/SKILL.md` - Changed tool references from Read to Skill
+
+## v3.2.2 (2025-10-21)
+
+### Improvements
+
+**Strengthened using-superpowers skill against agent rationalization**
+- Added EXTREMELY-IMPORTANT block with absolute language about mandatory skill checking
+  - "If even 1% chance a skill applies, you MUST read it"
+  - "You do not have a choice. You cannot rationalize your way out."
+- Added MANDATORY FIRST RESPONSE PROTOCOL checklist
+  - 5-step process agents must complete before any response
+  - Explicit "responding without this = failure" consequence
+- Added Common Rationalizations section with 8 specific evasion patterns
+  - "This is just a simple question" → WRONG
+  - "I can check files quickly" → WRONG
+  - "Let me gather information first" → WRONG
+  - Plus 5 more common patterns observed in agent behavior
+
+These changes address observed agent behavior where they rationalize around skill usage despite clear instructions. The forceful language and pre-emptive counter-arguments aim to make non-compliance harder.
+
+### Files Changed
+- Updated: `skills/using-superpowers/SKILL.md` - Added three layers of enforcement to prevent skill-skipping rationalization
+
+## v3.2.1 (2025-10-20)
+
+### New Features
+
+**Code reviewer agent now included in plugin**
+- Added `superpowers:code-reviewer` agent to plugin's `agents/` directory
+- Agent provides systematic code review against plans and coding standards
+- Previously required users to have personal agent configuration
+- All skill references updated to use namespaced `superpowers:code-reviewer`
+- Fixes #55
+
+### Files Changed
+- New: `agents/code-reviewer.md` - Agent definition with review checklist and output format
+- Updated: `skills/requesting-code-review/SKILL.md` - References to `superpowers:code-reviewer`
+- Updated: `skills/subagent-driven-development/SKILL.md` - References to `superpowers:code-reviewer`
+
+## v3.2.0 (2025-10-18)
+
+### New Features
+
+**Design documentation in brainstorming workflow**
+- Added Phase 4: Design Documentation to brainstorming skill
+- Design documents now written to `docs/plans/YYYY-MM-DD-<topic>-design.md` before implementation
+- Restores functionality from original brainstorming command that was lost during skill conversion
+- Documents written before worktree setup and implementation planning
+- Tested with subagent to verify compliance under time pressure
+
+### Breaking Changes
+
+**Skill reference namespace standardization**
+- All internal skill references now use `superpowers:` namespace prefix
+- Updated format: `superpowers:test-driven-development` (previously just `test-driven-development`)
+- Affects all REQUIRED SUB-SKILL, RECOMMENDED SUB-SKILL, and REQUIRED BACKGROUND references
+- Aligns with how skills are invoked using the Skill tool
+- Files updated: brainstorming, executing-plans, subagent-driven-development, systematic-debugging, testing-skills-with-subagents, writing-plans, writing-skills
+
+### Improvements
+
+**Design vs implementation plan naming**
+- Design documents use `-design.md` suffix to prevent filename collisions
+- Implementation plans continue using existing `YYYY-MM-DD-<feature-name>.md` format
+- Both stored in `docs/plans/` directory with clear naming distinction
+
+## v3.1.1 (2025-10-17)
+
+### Bug Fixes
+
+- **Fixed command syntax in README** (#44) - Updated all command references to use correct namespaced syntax (`/superpowers:brainstorm` instead of `/brainstorm`). Plugin-provided commands are automatically namespaced by Claude Code to avoid conflicts between plugins.
 
 ## v3.1.0 (2025-10-17)
 

agents/code-reviewer.md

@@ -0,0 +1,47 @@
+---
+name: code-reviewer
+description: Use this agent when a major project step has been completed and needs to be reviewed against the original plan and coding standards. Examples: <example>Context: The user is creating a code-review agent that should be called after a logical chunk of code is written. user: "I've finished implementing the user authentication system as outlined in step 3 of our plan" assistant: "Great work! Now let me use the code-reviewer agent to review the implementation against our plan and coding standards" <commentary>Since a major project step has been completed, use the code-reviewer agent to validate the work against the plan and identify any issues.</commentary></example> <example>Context: User has completed a significant feature implementation. user: "The API endpoints for the task management system are now complete - that covers step 2 from our architecture document" assistant: "Excellent! Let me have the code-reviewer agent examine this implementation to ensure it aligns with our plan and follows best practices" <commentary>A numbered step from the planning document has been completed, so the code-reviewer agent should review the work.</commentary></example>
+model: sonnet
+---
+
+You are a Senior Code Reviewer with expertise in software architecture, design patterns, and best practices. Your role is to review completed project steps against original plans and ensure code quality standards are met.
+
+When reviewing completed work, you will:
+
+1. **Plan Alignment Analysis**:
+   - Compare the implementation against the original planning document or step description
+   - Identify any deviations from the planned approach, architecture, or requirements
+   - Assess whether deviations are justified improvements or problematic departures
+   - Verify that all planned functionality has been implemented
+
+2. **Code Quality Assessment**:
+   - Review code for adherence to established patterns and conventions
+   - Check for proper error handling, type safety, and defensive programming
+   - Evaluate code organization, naming conventions, and maintainability
+   - Assess test coverage and quality of test implementations
+   - Look for potential security vulnerabilities or performance issues
+
+3. **Architecture and Design Review**:
+   - Ensure the implementation follows SOLID principles and established architectural patterns
+   - Check for proper separation of concerns and loose coupling
+   - Verify that the code integrates well with existing systems
+   - Assess scalability and extensibility considerations
+
+4. **Documentation and Standards**:
+   - Verify that code includes appropriate comments and documentation
+   - Check that file headers, function documentation, and inline comments are present and accurate
+   - Ensure adherence to project-specific coding standards and conventions
+
+5. **Issue Identification and Recommendations**:
+   - Clearly categorize issues as: Critical (must fix), Important (should fix), or Suggestions (nice to have)
+   - For each issue, provide specific examples and actionable recommendations
+   - When you identify plan deviations, explain whether they're problematic or beneficial
+   - Suggest specific improvements with code examples when helpful
+
+6. **Communication Protocol**:
+   - If you find significant deviations from the plan, ask the coding agent to review and confirm the changes
+   - If you identify issues with the original plan itself, recommend plan updates
+   - For implementation problems, provide clear guidance on fixes needed
+   - Always acknowledge what was done well before highlighting issues
+
+Your output should be structured, actionable, and focused on helping maintain high code quality while ensuring project goals are met. Be thorough but concise, and always provide constructive feedback that helps improve both the current implementation and future development practices.

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

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// 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');
+
+// Utility functions
+function extractFrontmatter(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const lines = content.split('\n');
+
+        let inFrontmatter = false;
+        let name = '';
+        let description = '';
+        let whenToUse = '';
+
+        for (const line of lines) {
+            if (line.trim() === '---') {
+                if (inFrontmatter) break;
+                inFrontmatter = true;
+                continue;
+            }
+
+            if (inFrontmatter) {
+                const match = line.match(/^(\w+):\s*(.*)$/);
+                if (match) {
+                    const [, key, value] = match;
+                    switch (key) {
+                        case 'name': name = value.trim(); break;
+                        case 'description': description = value.trim(); break;
+                        case 'when_to_use': whenToUse = value.trim(); break;
+                    }
+                }
+            }
+        }
+
+        return { name, description, whenToUse };
+    } catch (error) {
+        return { name: '', description: '', whenToUse: '' };
+    }
+}
+
+function printSkill(skillPath, sourceType) {
+    const skillFile = path.join(skillPath, 'SKILL.md');
+    const relPath = sourceType === 'personal'
+        ? path.relative(personalSkillsDir, skillPath)
+        : path.relative(superpowersSkillsDir, skillPath);
+
+    // Print skill name with namespace
+    if (sourceType === 'personal') {
+        console.log(relPath.replace(/\\/g, '/')); // Personal skills are not namespaced
+    } else {
+        console.log(`superpowers:${relPath.replace(/\\/g, '/')}`); // Superpowers skills get superpowers namespace
+    }
+
+    // Extract and print metadata
+    const { name, description, whenToUse } = extractFrontmatter(skillFile);
+
+    if (description) console.log(`  ${description}`);
+    if (whenToUse) console.log(`  When to use: ${whenToUse}`);
+    console.log('');
+}
+
+function findSkillsInDir(dir, sourceType, maxDepth = 1) {
+    const skills = [];
+
+    if (!fs.existsSync(dir)) return skills;
+
+    function searchDir(currentDir, currentDepth) {
+        if (currentDepth > maxDepth) return;
+
+        try {
+            const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const skillDir = path.join(currentDir, entry.name);
+                    const skillFile = path.join(skillDir, 'SKILL.md');
+
+                    if (fs.existsSync(skillFile)) {
+                        skills.push(skillDir);
+                    }
+
+                    // For personal skills, search deeper (category/skill structure)
+                    if (sourceType === 'personal' && currentDepth < maxDepth) {
+                        searchDir(skillDir, currentDepth + 1);
+                    }
+                }
+            }
+        } catch (error) {
+            // Ignore permission errors or other issues
+        }
+    }
+
+    searchDir(dir, 0);
+    return skills;
+}
+
+// Commands
+function runFindSkills() {
+    console.log('Available skills:');
+    console.log('==================');
+    console.log('');
+
+    const foundSkills = new Set();
+
+    // Find personal skills first (these take precedence)
+    const personalSkills = findSkillsInDir(personalSkillsDir, 'personal', 2);
+    for (const skillPath of personalSkills) {
+        const relPath = path.relative(personalSkillsDir, skillPath);
+        foundSkills.add(relPath);
+        printSkill(skillPath, 'personal');
+    }
+
+    // Find superpowers skills (only if not already found in personal)
+    const superpowersSkills = findSkillsInDir(superpowersSkillsDir, 'superpowers', 1);
+    for (const skillPath of superpowersSkills) {
+        const relPath = path.relative(superpowersSkillsDir, skillPath);
+        if (!foundSkills.has(relPath)) {
+            printSkill(skillPath, 'superpowers');
+        }
+    }
+
+    console.log('Usage:');
+    console.log('  superpowers-codex use-skill <skill-name>   # Load a specific skill');
+    console.log('');
+    console.log('Skill naming:');
+    console.log('  Superpowers skills: superpowers:skill-name (from ~/.codex/superpowers/skills/)');
+    console.log('  Personal skills: skill-name (from ~/.codex/skills/)');
+    console.log('  Personal skills override superpowers skills when names match.');
+    console.log('');
+    console.log('Note: All skills are disclosed at session start via bootstrap.');
+}
+
+function runBootstrap() {
+    console.log('# Superpowers Bootstrap for Codex');
+    console.log('# ================================');
+    console.log('');
+
+    // Show the bootstrap instructions
+    if (fs.existsSync(bootstrapFile)) {
+        console.log('## Bootstrap Instructions:');
+        console.log('');
+        try {
+            const content = fs.readFileSync(bootstrapFile, 'utf8');
+            console.log(content);
+        } catch (error) {
+            console.log(`Error reading bootstrap file: ${error.message}`);
+        }
+        console.log('');
+        console.log('---');
+        console.log('');
+    }
+
+    // Run find-skills to show available skills
+    console.log('## Available Skills:');
+    console.log('');
+    runFindSkills();
+
+    console.log('');
+    console.log('---');
+    console.log('');
+
+    // Load the using-superpowers skill automatically
+    console.log('## Auto-loading superpowers:using-superpowers skill:');
+    console.log('');
+    runUseSkill('superpowers:using-superpowers');
+
+    console.log('');
+    console.log('---');
+    console.log('');
+    console.log('# Bootstrap Complete!');
+    console.log('# You now have access to all superpowers skills.');
+    console.log('# Use "superpowers-codex use-skill <skill>" to load and apply skills.');
+    console.log('# Remember: If a skill applies to your task, you MUST use it!');
+}
+
+function runUseSkill(skillName) {
+    if (!skillName) {
+        console.log('Usage: superpowers-codex use-skill <skill-name>');
+        console.log('Examples:');
+        console.log('  superpowers-codex use-skill superpowers:brainstorming  # Load superpowers skill');
+        console.log('  superpowers-codex use-skill brainstorming              # Load personal skill (or superpowers if not found)');
+        console.log('  superpowers-codex use-skill my-custom-skill            # Load personal skill');
+        return;
+    }
+
+    // Handle namespaced skill names
+    let actualSkillPath;
+    let forceSuperpowers = false;
+
+    if (skillName.startsWith('superpowers:')) {
+        // Remove the superpowers: namespace prefix
+        actualSkillPath = skillName.substring('superpowers:'.length);
+        forceSuperpowers = true;
+    } else {
+        actualSkillPath = skillName;
+    }
+
+    // Remove "skills/" prefix if present
+    if (actualSkillPath.startsWith('skills/')) {
+        actualSkillPath = actualSkillPath.substring('skills/'.length);
+    }
+
+    // Function to find skill file
+    function findSkillFile(searchPath) {
+        // Check for exact match with SKILL.md
+        const skillMdPath = path.join(searchPath, 'SKILL.md');
+        if (fs.existsSync(skillMdPath)) {
+            return skillMdPath;
+        }
+
+        // Check for direct SKILL.md file
+        if (searchPath.endsWith('SKILL.md') && fs.existsSync(searchPath)) {
+            return searchPath;
+        }
+
+        return null;
+    }
+
+    let skillFile = null;
+
+    // If superpowers: namespace was used, only check superpowers skills
+    if (forceSuperpowers) {
+        if (fs.existsSync(superpowersSkillsDir)) {
+            const superpowersPath = path.join(superpowersSkillsDir, actualSkillPath);
+            skillFile = findSkillFile(superpowersPath);
+        }
+    } else {
+        // First check personal skills directory (takes precedence)
+        if (fs.existsSync(personalSkillsDir)) {
+            const personalPath = path.join(personalSkillsDir, actualSkillPath);
+            skillFile = findSkillFile(personalPath);
+            if (skillFile) {
+                console.log(`# Loading personal skill: ${actualSkillPath}`);
+                console.log(`# Source: ${skillFile}`);
+                console.log('');
+            }
+        }
+
+        // If not found in personal, check superpowers skills
+        if (!skillFile && fs.existsSync(superpowersSkillsDir)) {
+            const superpowersPath = path.join(superpowersSkillsDir, actualSkillPath);
+            skillFile = findSkillFile(superpowersPath);
+            if (skillFile) {
+                console.log(`# Loading superpowers skill: superpowers:${actualSkillPath}`);
+                console.log(`# Source: ${skillFile}`);
+                console.log('');
+            }
+        }
+    }
+
+    // If still not found, error
+    if (!skillFile) {
+        console.log(`Error: Skill not found: ${actualSkillPath}`);
+        console.log('');
+        console.log('Available skills:');
+        runFindSkills();
+        return;
+    }
+
+    // Extract frontmatter and content
+    let content, frontmatter;
+    try {
+        const fullContent = fs.readFileSync(skillFile, 'utf8');
+        const { name, description, whenToUse } = extractFrontmatter(skillFile);
+
+        // Extract just the content after frontmatter
+        const lines = fullContent.split('\n');
+        let inFrontmatter = false;
+        let frontmatterEnded = false;
+        const contentLines = [];
+
+        for (const line of lines) {
+            if (line.trim() === '---') {
+                if (inFrontmatter) {
+                    frontmatterEnded = true;
+                    continue;
+                }
+                inFrontmatter = true;
+                continue;
+            }
+
+            if (frontmatterEnded || !inFrontmatter) {
+                contentLines.push(line);
+            }
+        }
+
+        content = contentLines.join('\n').trim();
+        frontmatter = { name, description, whenToUse };
+    } catch (error) {
+        console.log(`Error reading skill file: ${error.message}`);
+        return;
+    }
+
+    // Display skill header with clean info
+    const displayName = forceSuperpowers ? `superpowers:${actualSkillPath}` :
+                       (skillFile.includes(personalSkillsDir) ? actualSkillPath : `superpowers:${actualSkillPath}`);
+
+    const skillDirectory = path.dirname(skillFile);
+
+    console.log(`# ${frontmatter.name || displayName}`);
+    if (frontmatter.description) {
+        console.log(`# ${frontmatter.description}`);
+    }
+    if (frontmatter.whenToUse) {
+        console.log(`# When to use: ${frontmatter.whenToUse}`);
+    }
+    console.log(`# Supporting tools and docs are in ${skillDirectory}`);
+    console.log('# ============================================');
+    console.log('');
+
+    // Display the skill content (without frontmatter)
+    console.log(content);
+
+}
+
+// Main CLI
+const command = process.argv[2];
+const arg = process.argv[3];
+
+switch (command) {
+    case 'bootstrap':
+        runBootstrap();
+        break;
+    case 'use-skill':
+        runUseSkill(arg);
+        break;
+    case 'find-skills':
+        runFindSkills();
+        break;
+    default:
+        console.log('Superpowers for Codex');
+        console.log('Usage:');
+        console.log('  superpowers-codex bootstrap              # Run complete bootstrap with all skills');
+        console.log('  superpowers-codex use-skill <skill-name> # Load a specific skill');
+        console.log('  superpowers-codex find-skills            # List all available skills');
+        console.log('');
+        console.log('Examples:');
+        console.log('  superpowers-codex bootstrap');
+        console.log('  superpowers-codex use-skill superpowers:brainstorming');
+        console.log('  superpowers-codex use-skill my-custom-skill');
+        break;
+}

skills/brainstorming/SKILL.md

@@ -20,8 +20,9 @@ Transform rough ideas into fully-formed designs through structured questioning a
 | **1. Understanding** | Ask questions (one at a time) | AskUserQuestion for choices | Purpose, constraints, criteria |
 | **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs |
 | **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation |
-| **4. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment |
-| **5. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown |
+| **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ |
+| **5. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment |
+| **6. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown |
 
 ## The Process
 
@@ -32,8 +33,9 @@ Brainstorming Progress:
 - [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
 - [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
 - [ ] Phase 3: Design Presentation (design validated in sections)
-- [ ] Phase 4: Worktree Setup (if implementing)
-- [ ] Phase 5: Planning Handoff (if implementing)
+- [ ] Phase 4: Design Documentation (design written to docs/plans/)
+- [ ] Phase 5: Worktree Setup (if implementing)
+- [ ] Phase 6: Planning Handoff (if implementing)
 ```
 
 ### Phase 1: Understanding
@@ -72,19 +74,26 @@ Options:
 - Ask after each section: "Does this look right so far?" (open-ended)
 - Use open-ended questions here to allow freeform feedback
 
-### Phase 4: Worktree Setup (for implementation)
+### Phase 4: Design Documentation
+After design is validated, write it to a permanent document:
+- **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.md` (use actual date and descriptive topic)
+- **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
+- **Content:** Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation
+- Commit the design document to git before proceeding
+
+### Phase 5: Worktree Setup (for implementation)
 When design is approved and implementation will follow:
 - Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace."
-- **REQUIRED SUB-SKILL:** Use using-git-worktrees
+- **REQUIRED SUB-SKILL:** Use superpowers:using-git-worktrees
 - Follow that skill's process for directory selection, safety verification, and setup
 - Return here when worktree ready
 
-### Phase 5: Planning Handoff
+### Phase 6: Planning Handoff
 Ask: "Ready to create the implementation plan?"
 
 When your human partner confirms (any affirmative response):
 - Announce: "I'm using the writing-plans skill to create the implementation plan."
-- **REQUIRED SUB-SKILL:** Use writing-plans
+- **REQUIRED SUB-SKILL:** Use superpowers:writing-plans
 - Create detailed plan in the worktree
 
 ## Question Patterns

skills/executing-plans/SKILL.md

@@ -46,7 +46,7 @@ Based on feedback:
 
 After all tasks complete and verified:
 - Announce: "I'm using the finishing-a-development-branch skill to complete this work."
-- **REQUIRED SUB-SKILL:** Use finishing-a-development-branch
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
 - Follow that skill to verify tests, present options, execute choice
 
 ## When to Stop and Ask for Help

skills/requesting-code-review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: requesting-code-review
-description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches code-reviewer subagent to review implementation against plan or requirements before proceeding
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches superpowers:code-reviewer subagent to review implementation against plan or requirements before proceeding
 ---
 
 # Requesting Code Review
 
-Dispatch code-reviewer subagent to catch issues before they cascade.
+Dispatch superpowers:code-reviewer subagent to catch issues before they cascade.
 
 **Core principle:** Review early, review often.
 
@@ -31,7 +31,7 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 **2. Dispatch code-reviewer subagent:**
 
-Use Task tool with code-reviewer type, fill template at `code-reviewer.md`
+Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md`
 
 **Placeholders:**
 - `{WHAT_WAS_IMPLEMENTED}` - What you just built
@@ -56,7 +56,7 @@ You: Let me request code review before proceeding.
 BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
 HEAD_SHA=$(git rev-parse HEAD)
 
-[Dispatch code-reviewer subagent]
+[Dispatch superpowers:code-reviewer subagent]
   WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
   PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
   BASE_SHA: a7981ec

skills/subagent-driven-development/SKILL.md

@@ -62,7 +62,7 @@ Task tool (general-purpose):
 
 **Dispatch code-reviewer subagent:**
 ```
-Task tool (code-reviewer):
+Task tool (superpowers:code-reviewer):
   Use template at requesting-code-review/code-reviewer.md
 
   WHAT_WAS_IMPLEMENTED: [from subagent's report]
@@ -103,7 +103,7 @@ After all tasks complete, dispatch final code-reviewer:
 
 After final review passes:
 - Announce: "I'm using the finishing-a-development-branch skill to complete this work."
-- **REQUIRED SUB-SKILL:** Use finishing-a-development-branch
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
 - Follow that skill to verify tests, present options, execute choice
 
 ## Example Workflow

skills/systematic-debugging/SKILL.md

@@ -111,7 +111,7 @@ You MUST complete each phase before proceeding to the next.
 
    **WHEN error is deep in call stack:**
 
-   **REQUIRED SUB-SKILL:** Use root-cause-tracing for backward tracing technique
+   **REQUIRED SUB-SKILL:** Use superpowers:root-cause-tracing for backward tracing technique
 
    **Quick version:**
    - Where does bad value originate?
@@ -176,7 +176,7 @@ You MUST complete each phase before proceeding to the next.
    - Automated test if possible
    - One-off test script if no framework
    - MUST have before fixing
-   - **REQUIRED SUB-SKILL:** Use test-driven-development for writing proper failing tests
+   - **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development for writing proper failing tests
 
 2. **Implement Single Fix**
    - Address the root cause identified

skills/testing-skills-with-subagents/SKILL.md

@@ -13,7 +13,7 @@ You run scenarios without the skill (RED - watch agent fail), write skill addres
 
 **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.
 
-**REQUIRED BACKGROUND:** You MUST understand test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
+**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
 
 **Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants.
 

skills/using-superpowers/SKILL.md

@@ -1,26 +1,48 @@
 ---
 name: using-superpowers
-description: Use when starting any conversation - establishes mandatory workflows for finding and using skills, including using Read tool before announcing usage, following brainstorming before coding, and creating TodoWrite todos for checklists
+description: Use when starting any conversation - establishes mandatory workflows for finding and using skills, including using Skill tool before announcing usage, following brainstorming before coding, and creating TodoWrite todos for checklists
 ---
 
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST read the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
 # Getting Started with Skills
 
+## MANDATORY FIRST RESPONSE PROTOCOL
+
+Before responding to ANY user message, you MUST complete this checklist:
+
+1. ☐ List available skills in your mind
+2. ☐ Ask yourself: "Does ANY skill match this request?"
+3. ☐ If yes → Use the Skill tool to read and run the skill file
+4. ☐ Announce which skill you're using
+5. ☐ Follow the skill exactly
+
+**Responding WITHOUT completing this checklist = automatic failure.**
+
 ## Critical Rules
 
 1. **Follow mandatory workflows.** Brainstorming before coding. Check for relevant skills before ANY task.
 
 2. Execute skills with the Skill tool
 
-## Mandatory: Before ANY Task
+## Common Rationalizations That Mean You're About To Fail
 
-**1. If a relevant skill exists, YOU MUST use it:**
+If you catch yourself thinking ANY of these thoughts, STOP. You are rationalizing. Check for and use the skill.
 
-- Announce: "I've read [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.
-- "This doesn't count as a task" - It counts. Find and read skills.
+- "This is just a simple question" → WRONG. Questions are tasks. Check for skills.
+- "I can check git/files quickly" → WRONG. Files don't have conversation context. Check for skills.
+- "Let me gather information first" → WRONG. Skills tell you HOW to gather information. Check for skills.
+- "This doesn't need a formal skill" → WRONG. If a skill exists for it, use it.
+- "I remember this skill" → WRONG. Skills evolve. Run the current version.
+- "This doesn't count as a task" → WRONG. If you're taking action, it's a task. Check for skills.
+- "The skill is overkill for this" → WRONG. Skills exist because simple things become complex. Use it.
+- "I'll just do this one thing first" → WRONG. Check for skills BEFORE doing anything.
 
 **Why:** Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.
 

skills/writing-plans/SKILL.md

@@ -33,7 +33,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 ```markdown
 # [Feature Name] Implementation Plan
 
-> **For Claude:** REQUIRED SUB-SKILL: Use executing-plans to implement this plan task-by-task.
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 
 **Goal:** [One sentence describing what this builds]
 
@@ -107,10 +107,10 @@ After saving the plan, offer execution choice:
 **Which approach?"**
 
 **If Subagent-Driven chosen:**
-- **REQUIRED SUB-SKILL:** Use subagent-driven-development
+- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
 - Stay in this session
 - Fresh subagent per task + code review
 
 **If Parallel Session chosen:**
 - Guide them to open new session in worktree
-- **REQUIRED SUB-SKILL:** New session uses executing-plans
+- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans

skills/writing-skills/SKILL.md

@@ -15,7 +15,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel
 
 **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
 
-**REQUIRED BACKGROUND:** You MUST understand test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
+**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
 
 **Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
 
@@ -253,8 +253,8 @@ wc -w skills/path/SKILL.md
 **When writing documentation that references other skills:**
 
 Use skill name only, with explicit requirement markers:
-- ✅ Good: `**REQUIRED SUB-SKILL:** Use test-driven-development`
-- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand systematic-debugging`
+- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`
+- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`
 - ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
 - ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
 
@@ -357,7 +357,7 @@ Edit skill without testing? Same violation.
 - Don't "adapt" while running tests
 - Delete means delete
 
-**REQUIRED BACKGROUND:** The test-driven-development skill explains why this matters. Same principles apply to documentation.
+**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.
 
 ## Testing All Skill Types
 
@@ -520,7 +520,7 @@ Run same scenarios WITH skill. Agent should now comply.
 
 Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
 
-**REQUIRED SUB-SKILL:** Use testing-skills-with-subagents for the complete testing methodology:
+**REQUIRED SUB-SKILL:** Use superpowers:testing-skills-with-subagents for the complete testing methodology:
 - How to write pressure scenarios
 - Pressure types (time, sunk cost, authority, exhaustion)
 - Plugging holes systematically