summaryrefslogtreecommitdiff
path: root/codex/superpowers-bootstrap.md
diff options
context:
space:
mode:
authorJesse Vincent <jesse@fsck.com>2025-10-28 00:23:47 +0000
committerJesse Vincent <jesse@fsck.com>2025-10-28 00:23:47 +0000
commit113d18ec28c8a4b6226f40d4a218990d8b9aed50 (patch)
tree6eccc85306133e4a0c1f95e95d9e393c21158766 /codex/superpowers-bootstrap.md
parent19e2997334eef29d0b4ab3c40a4bc124d200d1fb (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.md131
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