diff options
| author | Jesse Vincent <jesse@fsck.com> | 2025-10-28 00:23:47 +0000 |
|---|---|---|
| committer | Jesse Vincent <jesse@fsck.com> | 2025-10-28 00:23:47 +0000 |
| commit | 113d18ec28c8a4b6226f40d4a218990d8b9aed50 (patch) | |
| tree | 6eccc85306133e4a0c1f95e95d9e393c21158766 /codex/superpowers-bootstrap.md | |
| parent | 19e2997334eef29d0b4ab3c40a4bc124d200d1fb (diff) | |
Add Codex superpowers integrationf/codex
- 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
Diffstat (limited to 'codex/superpowers-bootstrap.md')
| -rw-r--r-- | codex/superpowers-bootstrap.md | 131 |
1 files changed, 131 insertions, 0 deletions
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 |
