diff options
Diffstat (limited to 'codex')
| -rw-r--r-- | codex/INSTALL.md | 135 | ||||
| -rw-r--r-- | codex/superpowers-bootstrap.md | 131 |
2 files changed, 266 insertions, 0 deletions
diff --git a/codex/INSTALL.md b/codex/INSTALL.md new file mode 100644 index 0000000..76c71ca --- /dev/null +++ b/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
\ No newline at end of file diff --git a/codex/superpowers-bootstrap.md b/codex/superpowers-bootstrap.md new file mode 100644 index 0000000..a320e9a --- /dev/null +++ b/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 + +---
\ No newline at end of file |
