superpowers/codex/superpowers-bootstrap.md

Superpowers Bootstrap for Codex

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

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:

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:

# 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

---