diff --git a/codex/skills/executing-plans/SKILL.md b/codex/skills/executing-plans/SKILL.md deleted file mode 100644 index a5918627..00000000 --- a/codex/skills/executing-plans/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -name: executing-plans -description: Use when you have a written implementation plan to execute in a separate session with review checkpoints ---- - -# Executing Plans - -## Overview - -Load plan, review critically, execute all tasks, report when complete. - -**Announce at start:** "I'm using the executing-plans skill to implement this plan." - -**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill. - -## The Process - -### Step 1: Load and Review Plan -1. Read plan file -2. Review critically - identify any questions or concerns about the plan -3. If concerns: Raise them with your human partner before starting -4. If no concerns: Create TodoWrite and proceed - -### Step 2: Execute Tasks - -For each task: -1. Mark as in_progress -2. Follow each step exactly (plan has bite-sized steps) -3. Run verifications as specified -4. Mark as completed - -### Step 3: Complete Development - -After all tasks complete and verified: -- Announce: "I'm using the finishing-a-development-branch skill to complete this work." -- **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 - -**STOP executing immediately when:** -- Hit a blocker (missing dependency, test fails, instruction unclear) -- Plan has critical gaps preventing starting -- You don't understand an instruction -- Verification fails repeatedly - -**Ask for clarification rather than guessing.** - -## When to Revisit Earlier Steps - -**Return to Review (Step 1) when:** -- Partner updates the plan based on your feedback -- Fundamental approach needs rethinking - -**Don't force through blockers** - stop and ask. - -## Remember -- Review plan critically first -- Follow plan steps exactly -- Don't skip verifications -- Reference skills when plan says to -- Stop when blocked, don't guess -- Never start implementation on main/master branch without explicit user consent - -## Integration - -**Required workflow skills:** -- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing) -- **superpowers:writing-plans** - Creates the plan this skill executes -- **superpowers:finishing-a-development-branch** - Complete development after all tasks diff --git a/codex/skills/finishing-a-development-branch/SKILL.md b/codex/skills/finishing-a-development-branch/SKILL.md deleted file mode 100644 index 43da0ae1..00000000 --- a/codex/skills/finishing-a-development-branch/SKILL.md +++ /dev/null @@ -1,251 +0,0 @@ ---- -name: finishing-a-development-branch -description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup ---- - -# Finishing a Development Branch - -## Overview - -Guide completion of development work by presenting clear options and handling chosen workflow. - -**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up. - -**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work." - -## The Process - -### Step 1: Verify Tests - -**Before presenting options, verify tests pass:** - -```bash -# Run project's test suite -npm test / cargo test / pytest / go test ./... -``` - -**If tests fail:** -``` -Tests failing ( failures). Must fix before completing: - -[Show failures] - -Cannot proceed with merge/PR until tests pass. -``` - -Stop. Don't proceed to Step 2. - -**If tests pass:** Continue to Step 2. - -### Step 2: Detect Environment - -**Determine workspace state before presenting options:** - -```bash -GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) -GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P) -``` - -This determines which menu to show and how cleanup works: - -| State | Menu | Cleanup | -|-------|------|---------| -| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up | -| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) | -| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) | - -### Step 3: Determine Base Branch - -```bash -# Try common base branches -git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null -``` - -Or ask: "This branch split from main - is that correct?" - -### Step 4: Present Options - -**Normal repo and named-branch worktree — present exactly these 4 options:** - -``` -Implementation complete. What would you like to do? - -1. Merge back to locally -2. Push and create a Pull Request -3. Keep the branch as-is (I'll handle it later) -4. Discard this work - -Which option? -``` - -**Detached HEAD — present exactly these 3 options:** - -``` -Implementation complete. You're on a detached HEAD (externally managed workspace). - -1. Push as new branch and create a Pull Request -2. Keep as-is (I'll handle it later) -3. Discard this work - -Which option? -``` - -**Don't add explanation** - keep options concise. - -### Step 5: Execute Choice - -#### Option 1: Merge Locally - -```bash -# Get main repo root for CWD safety -MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) -cd "$MAIN_ROOT" - -# Merge first — verify success before removing anything -git checkout -git pull -git merge - -# Verify tests on merged result - - -# Only after merge succeeds: cleanup worktree (Step 6), then delete branch -``` - -Then: Cleanup worktree (Step 6), then delete branch: - -```bash -git branch -d -``` - -#### Option 2: Push and Create PR - -```bash -# Push branch -git push -u origin - -# Create PR -gh pr create --title "" --body "$(cat <<'EOF' -## Summary -<2-3 bullets of what changed> - -## Test Plan -- [ ] <verification steps> -EOF -)" -``` - -**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback. - -#### Option 3: Keep As-Is - -Report: "Keeping branch <name>. Worktree preserved at <path>." - -**Don't cleanup worktree.** - -#### Option 4: Discard - -**Confirm first:** -``` -This will permanently delete: -- Branch <name> -- All commits: <commit-list> -- Worktree at <path> - -Type 'discard' to confirm. -``` - -Wait for exact confirmation. - -If confirmed: -```bash -MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) -cd "$MAIN_ROOT" -``` - -Then: Cleanup worktree (Step 6), then force-delete branch: -```bash -git branch -D <feature-branch> -``` - -### Step 6: Cleanup Workspace - -**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree. - -```bash -GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) -GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P) -WORKTREE_PATH=$(git rev-parse --show-toplevel) -``` - -**If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done. - -**If worktree path is under `.worktrees/`, `worktrees/`, or `~/.config/superpowers/worktrees/`:** Superpowers created this worktree — we own cleanup. - -```bash -MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) -cd "$MAIN_ROOT" -git worktree remove "$WORKTREE_PATH" -git worktree prune # Self-healing: clean up any stale registrations -``` - -**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place. - -## Quick Reference - -| Option | Merge | Push | Keep Worktree | Cleanup Branch | -|--------|-------|------|---------------|----------------| -| 1. Merge locally | yes | - | - | yes | -| 2. Create PR | - | yes | yes | - | -| 3. Keep as-is | - | - | yes | - | -| 4. Discard | - | - | - | yes (force) | - -## Common Mistakes - -**Skipping test verification** -- **Problem:** Merge broken code, create failing PR -- **Fix:** Always verify tests before offering options - -**Open-ended questions** -- **Problem:** "What should I do next?" is ambiguous -- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD) - -**Cleaning up worktree for Option 2** -- **Problem:** Remove worktree user needs for PR iteration -- **Fix:** Only cleanup for Options 1 and 4 - -**Deleting branch before removing worktree** -- **Problem:** `git branch -d` fails because worktree still references the branch -- **Fix:** Merge first, remove worktree, then delete branch - -**Running git worktree remove from inside the worktree** -- **Problem:** Command fails silently when CWD is inside the worktree being removed -- **Fix:** Always `cd` to main repo root before `git worktree remove` - -**Cleaning up harness-owned worktrees** -- **Problem:** Removing a worktree the harness created causes phantom state -- **Fix:** Only clean up worktrees under `.worktrees/`, `worktrees/`, or `~/.config/superpowers/worktrees/` - -**No confirmation for discard** -- **Problem:** Accidentally delete work -- **Fix:** Require typed "discard" confirmation - -## Red Flags - -**Never:** -- Proceed with failing tests -- Merge without verifying tests on result -- Delete work without confirmation -- Force-push without explicit request -- Remove a worktree before confirming merge success -- Clean up worktrees you didn't create (provenance check) -- Run `git worktree remove` from inside the worktree - -**Always:** -- Verify tests before offering options -- Detect environment before presenting menu -- Present exactly 4 options (or 3 for detached HEAD) -- Get typed confirmation for Option 4 -- Clean up worktree for Options 1 & 4 only -- `cd` to main repo root before worktree removal -- Run `git worktree prune` after removal diff --git a/codex/skills/requesting-code-review/SKILL.md b/codex/skills/requesting-code-review/SKILL.md deleted file mode 100644 index 34b83404..00000000 --- a/codex/skills/requesting-code-review/SKILL.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -name: requesting-code-review -description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements ---- - -# Requesting Code Review - -Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work. - -**Core principle:** Review early, review often. - -## When to Request Review - -**Mandatory:** -- After each task in subagent-driven development -- After completing major feature -- Before merge to main - -**Optional but valuable:** -- When stuck (fresh perspective) -- Before refactoring (baseline check) -- After fixing complex bug - -## How to Request - -**1. Get git SHAs:** -```bash -BASE_SHA=$(git rev-parse HEAD~1) # or origin/main -HEAD_SHA=$(git rev-parse HEAD) -``` - -**2. Dispatch code reviewer subagent:** - -Use Task tool with `general-purpose` type, fill template at `code-reviewer.md` - -**Placeholders:** -- `{DESCRIPTION}` - Brief summary of what you built -- `{PLAN_OR_REQUIREMENTS}` - What it should do -- `{BASE_SHA}` - Starting commit -- `{HEAD_SHA}` - Ending commit - -**3. Act on feedback:** -- Fix Critical issues immediately -- Fix Important issues before proceeding -- Note Minor issues for later -- Push back if reviewer is wrong (with reasoning) - -## Example - -``` -[Just completed Task 2: Add verification function] - -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] - DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types - PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md - BASE_SHA: a7981ec - HEAD_SHA: 3df7661 - -[Subagent returns]: - Strengths: Clean architecture, real tests - Issues: - Important: Missing progress indicators - Minor: Magic number (100) for reporting interval - Assessment: Ready to proceed - -You: [Fix progress indicators] -[Continue to Task 3] -``` - -## Integration with Workflows - -**Subagent-Driven Development:** -- Review after EACH task -- Catch issues before they compound -- Fix before moving to next task - -**Executing Plans:** -- Review after each task or at natural checkpoints -- Get feedback, apply, continue - -**Ad-Hoc Development:** -- Review before merge -- Review when stuck - -## Red Flags - -**Never:** -- Skip review because "it's simple" -- Ignore Critical issues -- Proceed with unfixed Important issues -- Argue with valid technical feedback - -**If reviewer wrong:** -- Push back with technical reasoning -- Show code/tests that prove it works -- Request clarification - -See template at: requesting-code-review/code-reviewer.md diff --git a/codex/skills/requesting-code-review/code-reviewer.md b/codex/skills/requesting-code-review/code-reviewer.md deleted file mode 100644 index 525e4b47..00000000 --- a/codex/skills/requesting-code-review/code-reviewer.md +++ /dev/null @@ -1,168 +0,0 @@ -# Code Reviewer Prompt Template - -Use this template when dispatching a code reviewer subagent. - -**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work. - -``` -Task tool (general-purpose): - description: "Review code changes" - prompt: | - You are a Senior Code Reviewer with expertise in software architecture, - design patterns, and best practices. Your job is to review completed work - against its plan or requirements and identify issues before they cascade. - - ## What Was Implemented - - {DESCRIPTION} - - ## Requirements / Plan - - {PLAN_OR_REQUIREMENTS} - - ## Git Range to Review - - **Base:** {BASE_SHA} - **Head:** {HEAD_SHA} - - ```bash - git diff --stat {BASE_SHA}..{HEAD_SHA} - git diff {BASE_SHA}..{HEAD_SHA} - ``` - - ## What to Check - - **Plan alignment:** - - Does the implementation match the plan / requirements? - - Are deviations justified improvements, or problematic departures? - - Is all planned functionality present? - - **Code quality:** - - Clean separation of concerns? - - Proper error handling? - - Type safety where applicable? - - DRY without premature abstraction? - - Edge cases handled? - - **Architecture:** - - Sound design decisions? - - Reasonable scalability and performance? - - Security concerns? - - Integrates cleanly with surrounding code? - - **Testing:** - - Tests verify real behavior, not mocks? - - Edge cases covered? - - Integration tests where they matter? - - All tests passing? - - **Production readiness:** - - Migration strategy if schema changed? - - Backward compatibility considered? - - Documentation complete? - - No obvious bugs? - - ## Calibration - - Categorize issues by actual severity. Not everything is Critical. - Acknowledge what was done well before listing issues — accurate praise - helps the implementer trust the rest of the feedback. - - If you find significant deviations from the plan, flag them specifically - so the implementer can confirm whether the deviation was intentional. - If you find issues with the plan itself rather than the implementation, - say so. - - ## Output Format - - ### Strengths - [What's well done? Be specific.] - - ### Issues - - #### Critical (Must Fix) - [Bugs, security issues, data loss risks, broken functionality] - - #### Important (Should Fix) - [Architecture problems, missing features, poor error handling, test gaps] - - #### Minor (Nice to Have) - [Code style, optimization opportunities, documentation polish] - - For each issue: - - File:line reference - - What's wrong - - Why it matters - - How to fix (if not obvious) - - ### Recommendations - [Improvements for code quality, architecture, or process] - - ### Assessment - - **Ready to merge?** [Yes | No | With fixes] - - **Reasoning:** [1-2 sentence technical assessment] - - ## Critical Rules - - **DO:** - - Categorize by actual severity - - Be specific (file:line, not vague) - - Explain WHY each issue matters - - Acknowledge strengths - - Give a clear verdict - - **DON'T:** - - Say "looks good" without checking - - Mark nitpicks as Critical - - Give feedback on code you didn't actually read - - Be vague ("improve error handling") - - Avoid giving a clear verdict -``` - -**Placeholders:** -- `{DESCRIPTION}` — brief summary of what was built -- `{PLAN_OR_REQUIREMENTS}` — what it should do (plan file path, task text, or requirements) -- `{BASE_SHA}` — starting commit -- `{HEAD_SHA}` — ending commit - -**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment - -## Example Output - -``` -### Strengths -- Clean database schema with proper migrations (db.ts:15-42) -- Comprehensive test coverage (18 tests, all edge cases) -- Good error handling with fallbacks (summarizer.ts:85-92) - -### Issues - -#### Important -1. **Missing help text in CLI wrapper** - - File: index-conversations:1-31 - - Issue: No --help flag, users won't discover --concurrency - - Fix: Add --help case with usage examples - -2. **Date validation missing** - - File: search.ts:25-27 - - Issue: Invalid dates silently return no results - - Fix: Validate ISO format, throw error with example - -#### Minor -1. **Progress indicators** - - File: indexer.ts:130 - - Issue: No "X of Y" counter for long operations - - Impact: Users don't know how long to wait - -### Recommendations -- Add progress reporting for user experience -- Consider config file for excluded projects (portability) - -### Assessment - -**Ready to merge: With fixes** - -**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality. -``` diff --git a/codex/skills/subagent-driven-development/SKILL.md b/codex/skills/subagent-driven-development/SKILL.md deleted file mode 100644 index ea7ac8fd..00000000 --- a/codex/skills/subagent-driven-development/SKILL.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -name: subagent-driven-development -description: Use when executing implementation plans with independent tasks in the current session ---- - -# Subagent-Driven Development - -Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review. - -**Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work. - -**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration - -**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it. - -## When to Use - -```dot -digraph when_to_use { - "Have implementation plan?" [shape=diamond]; - "Tasks mostly independent?" [shape=diamond]; - "Stay in this session?" [shape=diamond]; - "subagent-driven-development" [shape=box]; - "executing-plans" [shape=box]; - "Manual execution or brainstorm first" [shape=box]; - - "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"]; - "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"]; - "Tasks mostly independent?" -> "Stay in this session?" [label="yes"]; - "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"]; - "Stay in this session?" -> "subagent-driven-development" [label="yes"]; - "Stay in this session?" -> "executing-plans" [label="no - parallel session"]; -} -``` - -**vs. Executing Plans (parallel session):** -- Same session (no context switch) -- Fresh subagent per task (no context pollution) -- Two-stage review after each task: spec compliance first, then code quality -- Faster iteration (no human-in-loop between tasks) - -## The Process - -```dot -digraph process { - rankdir=TB; - - subgraph cluster_per_task { - label="Per Task"; - "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box]; - "Implementer subagent asks questions?" [shape=diamond]; - "Answer questions, provide context" [shape=box]; - "Implementer subagent implements, tests, commits, self-reviews" [shape=box]; - "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box]; - "Spec reviewer subagent confirms code matches spec?" [shape=diamond]; - "Implementer subagent fixes spec gaps" [shape=box]; - "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box]; - "Code quality reviewer subagent approves?" [shape=diamond]; - "Implementer subagent fixes quality issues" [shape=box]; - "Mark task complete in TodoWrite" [shape=box]; - } - - "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box]; - "More tasks remain?" [shape=diamond]; - "Dispatch final code reviewer subagent for entire implementation" [shape=box]; - "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; - - "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)"; - "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?"; - "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"]; - "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)"; - "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"]; - "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)"; - "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?"; - "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"]; - "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"]; - "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"]; - "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?"; - "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"]; - "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"]; - "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"]; - "Mark task complete in TodoWrite" -> "More tasks remain?"; - "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"]; - "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"]; - "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch"; -} -``` - -## Model Selection - -Use the least powerful model that can handle each role to conserve cost and increase speed. - -**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified. - -**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model. - -**Architecture, design, and review tasks**: use the most capable available model. - -**Task complexity signals:** -- Touches 1-2 files with a complete spec → cheap model -- Touches multiple files with integration concerns → standard model -- Requires design judgment or broad codebase understanding → most capable model - -## Handling Implementer Status - -Implementer subagents report one of four statuses. Handle each appropriately: - -**DONE:** Proceed to spec compliance review. - -**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review. - -**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch. - -**BLOCKED:** The implementer cannot complete the task. Assess the blocker: -1. If it's a context problem, provide more context and re-dispatch with the same model -2. If the task requires more reasoning, re-dispatch with a more capable model -3. If the task is too large, break it into smaller pieces -4. If the plan itself is wrong, escalate to the human - -**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change. - -## Prompt Templates - -- `./implementer-prompt.md` - Dispatch implementer subagent -- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent -- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent - -## Example Workflow - -``` -You: I'm using Subagent-Driven Development to execute this plan. - -[Read plan file once: docs/superpowers/plans/feature-plan.md] -[Extract all 5 tasks with full text and context] -[Create TodoWrite with all tasks] - -Task 1: Hook installation script - -[Get Task 1 text and context (already extracted)] -[Dispatch implementation subagent with full task text + context] - -Implementer: "Before I begin - should the hook be installed at user or system level?" - -You: "User level (~/.config/superpowers/hooks/)" - -Implementer: "Got it. Implementing now..." -[Later] Implementer: - - Implemented install-hook command - - Added tests, 5/5 passing - - Self-review: Found I missed --force flag, added it - - Committed - -[Dispatch spec compliance reviewer] -Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra - -[Get git SHAs, dispatch code quality reviewer] -Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved. - -[Mark Task 1 complete] - -Task 2: Recovery modes - -[Get Task 2 text and context (already extracted)] -[Dispatch implementation subagent with full task text + context] - -Implementer: [No questions, proceeds] -Implementer: - - Added verify/repair modes - - 8/8 tests passing - - Self-review: All good - - Committed - -[Dispatch spec compliance reviewer] -Spec reviewer: ❌ Issues: - - Missing: Progress reporting (spec says "report every 100 items") - - Extra: Added --json flag (not requested) - -[Implementer fixes issues] -Implementer: Removed --json flag, added progress reporting - -[Spec reviewer reviews again] -Spec reviewer: ✅ Spec compliant now - -[Dispatch code quality reviewer] -Code reviewer: Strengths: Solid. Issues (Important): Magic number (100) - -[Implementer fixes] -Implementer: Extracted PROGRESS_INTERVAL constant - -[Code reviewer reviews again] -Code reviewer: ✅ Approved - -[Mark Task 2 complete] - -... - -[After all tasks] -[Dispatch final code-reviewer] -Final reviewer: All requirements met, ready to merge - -Done! -``` - -## Advantages - -**vs. Manual execution:** -- Subagents follow TDD naturally -- Fresh context per task (no confusion) -- Parallel-safe (subagents don't interfere) -- Subagent can ask questions (before AND during work) - -**vs. Executing Plans:** -- Same session (no handoff) -- Continuous progress (no waiting) -- Review checkpoints automatic - -**Efficiency gains:** -- No file reading overhead (controller provides full text) -- Controller curates exactly what context is needed -- Subagent gets complete information upfront -- Questions surfaced before work begins (not after) - -**Quality gates:** -- Self-review catches issues before handoff -- Two-stage review: spec compliance, then code quality -- Review loops ensure fixes actually work -- Spec compliance prevents over/under-building -- Code quality ensures implementation is well-built - -**Cost:** -- More subagent invocations (implementer + 2 reviewers per task) -- Controller does more prep work (extracting all tasks upfront) -- Review loops add iterations -- But catches issues early (cheaper than debugging later) - -## Red Flags - -**Never:** -- Start implementation on main/master branch without explicit user consent -- Skip reviews (spec compliance OR code quality) -- Proceed with unfixed issues -- Dispatch multiple implementation subagents in parallel (conflicts) -- Make subagent read plan file (provide full text instead) -- Skip scene-setting context (subagent needs to understand where task fits) -- Ignore subagent questions (answer before letting them proceed) -- Accept "close enough" on spec compliance (spec reviewer found issues = not done) -- Skip review loops (reviewer found issues = implementer fixes = review again) -- Let implementer self-review replace actual review (both are needed) -- **Start code quality review before spec compliance is ✅** (wrong order) -- Move to next task while either review has open issues - -**If subagent asks questions:** -- Answer clearly and completely -- Provide additional context if needed -- Don't rush them into implementation - -**If reviewer finds issues:** -- Implementer (same subagent) fixes them -- Reviewer reviews again -- Repeat until approved -- Don't skip the re-review - -**If subagent fails task:** -- Dispatch fix subagent with specific instructions -- Don't try to fix manually (context pollution) - -## Integration - -**Required workflow skills:** -- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing) -- **superpowers:writing-plans** - Creates the plan this skill executes -- **superpowers:requesting-code-review** - Code review template for reviewer subagents -- **superpowers:finishing-a-development-branch** - Complete development after all tasks - -**Subagents should use:** -- **superpowers:test-driven-development** - Subagents follow TDD for each task - -**Alternative workflow:** -- **superpowers:executing-plans** - Use for parallel session instead of same-session execution diff --git a/codex/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/codex/skills/subagent-driven-development/code-quality-reviewer-prompt.md deleted file mode 100644 index 51f901a5..00000000 --- a/codex/skills/subagent-driven-development/code-quality-reviewer-prompt.md +++ /dev/null @@ -1,25 +0,0 @@ -# Code Quality Reviewer Prompt Template - -Use this template when dispatching a code quality reviewer subagent. - -**Purpose:** Verify implementation is well-built (clean, tested, maintainable) - -**Only dispatch after spec compliance review passes.** - -``` -Task tool (general-purpose): - Use template at requesting-code-review/code-reviewer.md - - DESCRIPTION: [task summary, from implementer's report] - PLAN_OR_REQUIREMENTS: Task N from [plan-file] - BASE_SHA: [commit before task] - HEAD_SHA: [current commit] -``` - -**In addition to standard code quality concerns, the reviewer should check:** -- Does each file have one clear responsibility with a well-defined interface? -- Are units decomposed so they can be understood and tested independently? -- Is the implementation following the file structure from the plan? -- Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.) - -**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment diff --git a/codex/skills/systematic-debugging/CREATION-LOG.md b/codex/skills/systematic-debugging/CREATION-LOG.md deleted file mode 100644 index 9aa03092..00000000 --- a/codex/skills/systematic-debugging/CREATION-LOG.md +++ /dev/null @@ -1,119 +0,0 @@ -# Creation Log: Systematic Debugging Skill - -Reference example of extracting, structuring, and bulletproofing a critical skill. - -## Source Material - -Extracted debugging framework from `~/.claude/CLAUDE.md`: -- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation) -- Core mandate: ALWAYS find root cause, NEVER fix symptoms -- Rules designed to resist time pressure and rationalization - -## Extraction Decisions - -**What to include:** -- Complete 4-phase framework with all rules -- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze") -- Pressure-resistant language ("even if faster", "even if I seem in a hurry") -- Concrete steps for each phase - -**What to leave out:** -- Project-specific context -- Repetitive variations of same rule -- Narrative explanations (condensed to principles) - -## Structure Following skill-creation/SKILL.md - -1. **Rich when_to_use** - Included symptoms and anti-patterns -2. **Type: technique** - Concrete process with steps -3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation" -4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes -5. **Phase-by-phase breakdown** - Scannable checklist format -6. **Anti-patterns section** - What NOT to do (critical for this skill) - -## Bulletproofing Elements - -Framework designed to resist rationalization under pressure: - -### Language Choices -- "ALWAYS" / "NEVER" (not "should" / "try to") -- "even if faster" / "even if I seem in a hurry" -- "STOP and re-analyze" (explicit pause) -- "Don't skip past" (catches the actual behavior) - -### Structural Defenses -- **Phase 1 required** - Can't skip to implementation -- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes -- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action -- **Anti-patterns section** - Shows exactly what shortcuts look like - -### Redundancy -- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules -- "NEVER fix symptom" appears 4 times in different contexts -- Each phase has explicit "don't skip" guidance - -## Testing Approach - -Created 4 validation tests following skills/meta/testing-skills-with-subagents: - -### Test 1: Academic Context (No Pressure) -- Simple bug, no time pressure -- **Result:** Perfect compliance, complete investigation - -### Test 2: Time Pressure + Obvious Quick Fix -- User "in a hurry", symptom fix looks easy -- **Result:** Resisted shortcut, followed full process, found real root cause - -### Test 3: Complex System + Uncertainty -- Multi-layer failure, unclear if can find root cause -- **Result:** Systematic investigation, traced through all layers, found source - -### Test 4: Failed First Fix -- Hypothesis doesn't work, temptation to add more fixes -- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun) - -**All tests passed.** No rationalizations found. - -## Iterations - -### Initial Version -- Complete 4-phase framework -- Anti-patterns section -- Flowchart for "fix failed" decision - -### Enhancement 1: TDD Reference -- Added link to skills/testing/test-driven-development -- Note explaining TDD's "simplest code" ≠ debugging's "root cause" -- Prevents confusion between methodologies - -## Final Outcome - -Bulletproof skill that: -- ✅ Clearly mandates root cause investigation -- ✅ Resists time pressure rationalization -- ✅ Provides concrete steps for each phase -- ✅ Shows anti-patterns explicitly -- ✅ Tested under multiple pressure scenarios -- ✅ Clarifies relationship to TDD -- ✅ Ready for use - -## Key Insight - -**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction. - -## Usage Example - -When encountering a bug: -1. Load skill: skills/debugging/systematic-debugging -2. Read overview (10 sec) - reminded of mandate -3. Follow Phase 1 checklist - forced investigation -4. If tempted to skip - see anti-pattern, stop -5. Complete all phases - root cause found - -**Time investment:** 5-10 minutes -**Time saved:** Hours of symptom-whack-a-mole - ---- - -*Created: 2025-10-03* -*Purpose: Reference example for skill extraction and bulletproofing* diff --git a/codex/skills/systematic-debugging/root-cause-tracing.md b/codex/skills/systematic-debugging/root-cause-tracing.md deleted file mode 100644 index 12ef5222..00000000 --- a/codex/skills/systematic-debugging/root-cause-tracing.md +++ /dev/null @@ -1,169 +0,0 @@ -# Root Cause Tracing - -## Overview - -Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom. - -**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source. - -## When to Use - -```dot -digraph when_to_use { - "Bug appears deep in stack?" [shape=diamond]; - "Can trace backwards?" [shape=diamond]; - "Fix at symptom point" [shape=box]; - "Trace to original trigger" [shape=box]; - "BETTER: Also add defense-in-depth" [shape=box]; - - "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"]; - "Can trace backwards?" -> "Trace to original trigger" [label="yes"]; - "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"]; - "Trace to original trigger" -> "BETTER: Also add defense-in-depth"; -} -``` - -**Use when:** -- Error happens deep in execution (not at entry point) -- Stack trace shows long call chain -- Unclear where invalid data originated -- Need to find which test/code triggers the problem - -## The Tracing Process - -### 1. Observe the Symptom -``` -Error: git init failed in ~/project/packages/core -``` - -### 2. Find Immediate Cause -**What code directly causes this?** -```typescript -await execFileAsync('git', ['init'], { cwd: projectDir }); -``` - -### 3. Ask: What Called This? -```typescript -WorktreeManager.createSessionWorktree(projectDir, sessionId) - → called by Session.initializeWorkspace() - → called by Session.create() - → called by test at Project.create() -``` - -### 4. Keep Tracing Up -**What value was passed?** -- `projectDir = ''` (empty string!) -- Empty string as `cwd` resolves to `process.cwd()` -- That's the source code directory! - -### 5. Find Original Trigger -**Where did empty string come from?** -```typescript -const context = setupCoreTest(); // Returns { tempDir: '' } -Project.create('name', context.tempDir); // Accessed before beforeEach! -``` - -## Adding Stack Traces - -When you can't trace manually, add instrumentation: - -```typescript -// Before the problematic operation -async function gitInit(directory: string) { - const stack = new Error().stack; - console.error('DEBUG git init:', { - directory, - cwd: process.cwd(), - nodeEnv: process.env.NODE_ENV, - stack, - }); - - await execFileAsync('git', ['init'], { cwd: directory }); -} -``` - -**Critical:** Use `console.error()` in tests (not logger - may not show) - -**Run and capture:** -```bash -npm test 2>&1 | grep 'DEBUG git init' -``` - -**Analyze stack traces:** -- Look for test file names -- Find the line number triggering the call -- Identify the pattern (same test? same parameter?) - -## Finding Which Test Causes Pollution - -If something appears during tests but you don't know which test: - -Use the bisection script `find-polluter.sh` in this directory: - -```bash -./find-polluter.sh '.git' 'src/**/*.test.ts' -``` - -Runs tests one-by-one, stops at first polluter. See script for usage. - -## Real Example: Empty projectDir - -**Symptom:** `.git` created in `packages/core/` (source code) - -**Trace chain:** -1. `git init` runs in `process.cwd()` ← empty cwd parameter -2. WorktreeManager called with empty projectDir -3. Session.create() passed empty string -4. Test accessed `context.tempDir` before beforeEach -5. setupCoreTest() returns `{ tempDir: '' }` initially - -**Root cause:** Top-level variable initialization accessing empty value - -**Fix:** Made tempDir a getter that throws if accessed before beforeEach - -**Also added defense-in-depth:** -- Layer 1: Project.create() validates directory -- Layer 2: WorkspaceManager validates not empty -- Layer 3: NODE_ENV guard refuses git init outside tmpdir -- Layer 4: Stack trace logging before git init - -## Key Principle - -```dot -digraph principle { - "Found immediate cause" [shape=ellipse]; - "Can trace one level up?" [shape=diamond]; - "Trace backwards" [shape=box]; - "Is this the source?" [shape=diamond]; - "Fix at source" [shape=box]; - "Add validation at each layer" [shape=box]; - "Bug impossible" [shape=doublecircle]; - "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white]; - - "Found immediate cause" -> "Can trace one level up?"; - "Can trace one level up?" -> "Trace backwards" [label="yes"]; - "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"]; - "Trace backwards" -> "Is this the source?"; - "Is this the source?" -> "Trace backwards" [label="no - keeps going"]; - "Is this the source?" -> "Fix at source" [label="yes"]; - "Fix at source" -> "Add validation at each layer"; - "Add validation at each layer" -> "Bug impossible"; -} -``` - -**NEVER fix just where the error appears.** Trace back to find the original trigger. - -## Stack Trace Tips - -**In tests:** Use `console.error()` not logger - logger may be suppressed -**Before operation:** Log before the dangerous operation, not after it fails -**Include context:** Directory, cwd, environment variables, timestamps -**Capture stack:** `new Error().stack` shows complete call chain - -## Real-World Impact - -From debugging session (2025-10-03): -- Found root cause through 5-level trace -- Fixed at source (getter validation) -- Added 4 layers of defense -- 1847 tests passed, zero pollution diff --git a/codex/skills/using-git-worktrees/SKILL.md b/codex/skills/using-git-worktrees/SKILL.md deleted file mode 100644 index 134d3714..00000000 --- a/codex/skills/using-git-worktrees/SKILL.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -name: using-git-worktrees -description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback ---- - -# Using Git Worktrees - -## Overview - -Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available. - -**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness. - -**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace." - -## Step 0: Detect Existing Isolation - -**Before creating anything, check if you are already in an isolated workspace.** - -```bash -GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) -GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P) -BRANCH=$(git branch --show-current) -``` - -**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule: - -```bash -# If this returns a path, you're in a submodule, not a worktree — treat as normal repo -git rev-parse --show-superproject-working-tree 2>/dev/null -``` - -**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree. - -Report with branch state: -- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`." -- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time." - -**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout. - -Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree: - -> "Would you like me to set up an isolated worktree? It protects your current branch from changes." - -Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 3. - -## Step 1: Create Isolated Workspace - -**You have two mechanisms. Try them in this order.** - -### 1a. Native Worktree Tools (preferred) - -The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 3. - -Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage. - -Only proceed to Step 1b if you have no native worktree tool available. - -### 1b. Git Worktree Fallback - -**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git. - -#### Directory Selection - -Follow this priority order. Explicit user preference always beats observed filesystem state. - -1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking. - -2. **Check for an existing project-local worktree directory:** - ```bash - ls -d .worktrees 2>/dev/null # Preferred (hidden) - ls -d worktrees 2>/dev/null # Alternative - ``` - If found, use it. If both exist, `.worktrees` wins. - -3. **Check for an existing global directory:** - ```bash - project=$(basename "$(git rev-parse --show-toplevel)") - ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null - ``` - If found, use it (backward compatibility with legacy global path). - -4. **If there is no other guidance available**, default to `.worktrees/` at the project root. - -#### Safety Verification (project-local directories only) - -**MUST verify directory is ignored before creating worktree:** - -```bash -git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null -``` - -**If NOT ignored:** Add to .gitignore, commit the change, then proceed. - -**Why critical:** Prevents accidentally committing worktree contents to repository. - -Global directories (`~/.config/superpowers/worktrees/`) need no verification. - -#### Create the Worktree - -```bash -project=$(basename "$(git rev-parse --show-toplevel)") - -# Determine path based on chosen location -# For project-local: path="$LOCATION/$BRANCH_NAME" -# For global: path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME" - -git worktree add "$path" -b "$BRANCH_NAME" -cd "$path" -``` - -**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place. - -## Step 3: Project Setup - -Auto-detect and run appropriate setup: - -```bash -# Node.js -if [ -f package.json ]; then npm install; fi - -# Rust -if [ -f Cargo.toml ]; then cargo build; fi - -# Python -if [ -f requirements.txt ]; then pip install -r requirements.txt; fi -if [ -f pyproject.toml ]; then poetry install; fi - -# Go -if [ -f go.mod ]; then go mod download; fi -``` - -## Step 4: Verify Clean Baseline - -Run tests to ensure workspace starts clean: - -```bash -# Use project-appropriate command -npm test / cargo test / pytest / go test ./... -``` - -**If tests fail:** Report failures, ask whether to proceed or investigate. - -**If tests pass:** Report ready. - -### Report - -``` -Worktree ready at <full-path> -Tests passing (<N> tests, 0 failures) -Ready to implement <feature-name> -``` - -## Quick Reference - -| Situation | Action | -|-----------|--------| -| Already in linked worktree | Skip creation (Step 0) | -| In a submodule | Treat as normal repo (Step 0 guard) | -| Native worktree tool available | Use it (Step 1a) | -| No native tool | Git worktree fallback (Step 1b) | -| `.worktrees/` exists | Use it (verify ignored) | -| `worktrees/` exists | Use it (verify ignored) | -| Both exist | Use `.worktrees/` | -| Neither exists | Check instruction file, then default `.worktrees/` | -| Global path exists | Use it (backward compat) | -| Directory not ignored | Add to .gitignore + commit | -| Permission error on create | Sandbox fallback, work in place | -| Tests fail during baseline | Report failures + ask | -| No package.json/Cargo.toml | Skip dependency install | - -## Common Mistakes - -### Fighting the harness - -- **Problem:** Using `git worktree add` when the platform already provides isolation -- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools. - -### Skipping detection - -- **Problem:** Creating a nested worktree inside an existing one -- **Fix:** Always run Step 0 before creating anything - -### Skipping ignore verification - -- **Problem:** Worktree contents get tracked, pollute git status -- **Fix:** Always use `git check-ignore` before creating project-local worktree - -### Assuming directory location - -- **Problem:** Creates inconsistency, violates project conventions -- **Fix:** Follow priority: existing > global legacy > instruction file > default - -### Proceeding with failing tests - -- **Problem:** Can't distinguish new bugs from pre-existing issues -- **Fix:** Report failures, get explicit permission to proceed - -## Red Flags - -**Never:** -- Create a worktree when Step 0 detects existing isolation -- Use `git worktree add` when you have a native worktree tool (e.g., `EnterWorktree`). This is the #1 mistake — if you have it, use it. -- Skip Step 1a by jumping straight to Step 1b's git commands -- Create worktree without verifying it's ignored (project-local) -- Skip baseline test verification -- Proceed with failing tests without asking - -**Always:** -- Run Step 0 detection first -- Prefer native tools over git fallback -- Follow directory priority: existing > global legacy > instruction file > default -- Verify directory is ignored for project-local -- Auto-detect and run project setup -- Verify clean test baseline diff --git a/codex/skills/using-superpowers/references/codex-tools.md b/codex/skills/using-superpowers/references/codex-tools.md deleted file mode 100644 index f50d40d4..00000000 --- a/codex/skills/using-superpowers/references/codex-tools.md +++ /dev/null @@ -1,59 +0,0 @@ -# Codex Tool Mapping - -Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent: - -| Skill references | Codex equivalent | -|-----------------|------------------| -| `Task` tool (dispatch subagent) | `spawn_agent` (see [Subagent dispatch requires multi-agent support](#subagent-dispatch-requires-multi-agent-support)) | -| Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls | -| Task returns result | `wait_agent` | -| Task completes automatically | `close_agent` to free slot | -| `TodoWrite` (task tracking) | `update_plan` | -| `Skill` tool (invoke a skill) | Skills load natively — just follow the instructions | -| `Read`, `Write`, `Edit` (files) | Use your native file tools | -| `Bash` (run commands) | Use your native shell tools | - -## Subagent dispatch requires multi-agent support - -Add to your Codex config (`~/.codex/config.toml`): - -```toml -[features] -multi_agent = true -``` - -This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. - -Legacy note: Codex builds before `rust-v0.115.0` exposed spawned-agent -waiting as `wait`. Current Codex uses `wait_agent` for spawned agents. The -`wait` name now belongs to code-mode `exec/wait`, which resumes a yielded exec -cell by `cell_id`; it is not the spawned-agent result tool. - -## Environment Detection - -Skills that create worktrees or finish branches should detect their -environment with read-only git commands before proceeding: - -```bash -GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) -GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P) -BRANCH=$(git branch --show-current) -``` - -- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation) -- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox) - -See `using-git-worktrees` Step 0 and `finishing-a-development-branch` -Step 1 for how each skill uses these signals. - -## Codex App Finishing - -When the sandbox blocks branch/push operations (detached HEAD in an -externally managed worktree), the agent commits all work and informs -the user to use the App's native controls: - -- **"Create branch"** — names the branch, then commit/push/PR via App UI -- **"Hand off to local"** — transfers work to the user's local checkout - -The agent can still run tests, stage files, and output suggested branch -names, commit messages, and PR descriptions for the user to copy. diff --git a/codex/skills/using-superpowers/references/copilot-tools.md b/codex/skills/using-superpowers/references/copilot-tools.md deleted file mode 100644 index ae3cf5a6..00000000 --- a/codex/skills/using-superpowers/references/copilot-tools.md +++ /dev/null @@ -1,42 +0,0 @@ -# Copilot CLI Tool Mapping - -Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent: - -| Skill references | Copilot CLI equivalent | -|-----------------|----------------------| -| `Read` (file reading) | `view` | -| `Write` (file creation) | `create` | -| `Edit` (file editing) | `edit` | -| `Bash` (run commands) | `bash` | -| `Grep` (search file content) | `grep` | -| `Glob` (search files by name) | `glob` | -| `Skill` tool (invoke a skill) | `skill` | -| `WebFetch` | `web_fetch` | -| `Task` tool (dispatch subagent) | `task` with `agent_type: "general-purpose"` or `"explore"` | -| Multiple `Task` calls (parallel) | Multiple `task` calls | -| Task status/output | `read_agent`, `list_agents` | -| `TodoWrite` (task tracking) | `sql` with built-in `todos` table | -| `WebSearch` | No equivalent — use `web_fetch` with a search engine URL | -| `EnterPlanMode` / `ExitPlanMode` | No equivalent — stay in the main session | - -## Async shell sessions - -Copilot CLI supports persistent async shell sessions, which have no direct Claude Code equivalent: - -| Tool | Purpose | -|------|---------| -| `bash` with `async: true` | Start a long-running command in the background | -| `write_bash` | Send input to a running async session | -| `read_bash` | Read output from an async session | -| `stop_bash` | Terminate an async session | -| `list_bash` | List all active shell sessions | - -## Additional Copilot CLI tools - -| Tool | Purpose | -|------|---------| -| `store_memory` | Persist facts about the codebase for future sessions | -| `report_intent` | Update the UI status line with current intent | -| `sql` | Query the session's SQLite database (todos, metadata) | -| `fetch_copilot_cli_documentation` | Look up Copilot CLI documentation | -| GitHub MCP tools (`github-mcp-server-*`) | Native GitHub API access (issues, PRs, code search) | diff --git a/codex/skills/using-superpowers/references/gemini-tools.md b/codex/skills/using-superpowers/references/gemini-tools.md deleted file mode 100644 index 91ef4049..00000000 --- a/codex/skills/using-superpowers/references/gemini-tools.md +++ /dev/null @@ -1,51 +0,0 @@ -# Gemini CLI Tool Mapping - -Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent: - -| Skill references | Gemini CLI equivalent | -|-----------------|----------------------| -| `Read` (file reading) | `read_file` | -| `Write` (file creation) | `write_file` | -| `Edit` (file editing) | `replace` | -| `Bash` (run commands) | `run_shell_command` | -| `Grep` (search file content) | `grep_search` | -| `Glob` (search files by name) | `glob` | -| `TodoWrite` (task tracking) | `write_todos` | -| `Skill` tool (invoke a skill) | `activate_skill` | -| `WebSearch` | `google_web_search` | -| `WebFetch` | `web_fetch` | -| `Task` tool (dispatch subagent) | `@agent-name` (see [Subagent support](#subagent-support)) | - -## Subagent support - -Gemini CLI supports subagents natively via the `@` syntax. Use the built-in `@generalist` agent to dispatch any task — it has access to all tools and follows the prompt you provide. - -When a skill says to dispatch a named agent type, use `@generalist` with the full prompt from the skill's prompt template: - -| Skill instruction | Gemini CLI equivalent | -|-------------------|----------------------| -| `Task tool (superpowers:implementer)` | `@generalist` with the filled `implementer-prompt.md` template | -| `Task tool (superpowers:spec-reviewer)` | `@generalist` with the filled `spec-reviewer-prompt.md` template | -| `Task tool (superpowers:code-reviewer)` | `@code-reviewer` (bundled agent) or `@generalist` with the filled review prompt | -| `Task tool (superpowers:code-quality-reviewer)` | `@generalist` with the filled `code-quality-reviewer-prompt.md` template | -| `Task tool (general-purpose)` with inline prompt | `@generalist` with your inline prompt | - -### Prompt filling - -Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or `[FULL TEXT of task]`. Fill all placeholders and pass the complete prompt as the message to `@generalist`. The prompt template itself contains the agent's role, review criteria, and expected output format — `@generalist` will follow it. - -### Parallel dispatch - -Gemini CLI supports parallel subagent dispatch. When a skill asks you to dispatch multiple independent subagent tasks in parallel, request all of those `@generalist` or named subagent tasks together in the same prompt. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history. - -## Additional Gemini CLI tools - -These tools are available in Gemini CLI but have no Claude Code equivalent: - -| Tool | Purpose | -|------|---------| -| `list_directory` | List files and subdirectories | -| `save_memory` | Persist facts to GEMINI.md across sessions | -| `ask_user` | Request structured input from the user | -| `tracker_create_task` | Rich task management (create, update, list, visualize) | -| `enter_plan_mode` / `exit_plan_mode` | Switch to read-only research mode before making changes | diff --git a/codex/skills/writing-plans/SKILL.md b/codex/skills/writing-plans/SKILL.md deleted file mode 100644 index 847412ec..00000000 --- a/codex/skills/writing-plans/SKILL.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -name: writing-plans -description: Use when you have a spec or requirements for a multi-step task, before touching code ---- - -# Writing Plans - -## Overview - -Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. - -Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well. - -**Announce at start:** "I'm using the writing-plans skill to create the implementation plan." - -**Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time. - -**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md` -- (User preferences for plan location override this default) - -## Scope Check - -If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own. - -## File Structure - -Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in. - -- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility. -- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much. -- Files that change together should live together. Split by responsibility, not by technical layer. -- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable. - -This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently. - -## Bite-Sized Task Granularity - -**Each step is one action (2-5 minutes):** -- "Write the failing test" - step -- "Run it to make sure it fails" - step -- "Implement the minimal code to make the test pass" - step -- "Run the tests and make sure they pass" - step -- "Commit" - step - -## Plan Document Header - -**Every plan MUST start with this header:** - -```markdown -# [Feature Name] Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** [One sentence describing what this builds] - -**Architecture:** [2-3 sentences about approach] - -**Tech Stack:** [Key technologies/libraries] - ---- -``` - -## Task Structure - -````markdown -### Task N: [Component Name] - -**Files:** -- Create: `exact/path/to/file.py` -- Modify: `exact/path/to/existing.py:123-145` -- Test: `tests/exact/path/to/test.py` - -- [ ] **Step 1: Write the failing test** - -```python -def test_specific_behavior(): - result = function(input) - assert result == expected -``` - -- [ ] **Step 2: Run test to verify it fails** - -Run: `pytest tests/path/test.py::test_name -v` -Expected: FAIL with "function not defined" - -- [ ] **Step 3: Write minimal implementation** - -```python -def function(input): - return expected -``` - -- [ ] **Step 4: Run test to verify it passes** - -Run: `pytest tests/path/test.py::test_name -v` -Expected: PASS - -- [ ] **Step 5: Commit** - -```bash -git add tests/path/test.py src/path/file.py -git commit -m "feat: add specific feature" -``` -```` - -## No Placeholders - -Every step must contain the actual content an engineer needs. These are **plan failures** — never write them: -- "TBD", "TODO", "implement later", "fill in details" -- "Add appropriate error handling" / "add validation" / "handle edge cases" -- "Write tests for the above" (without actual test code) -- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order) -- Steps that describe what to do without showing how (code blocks required for code steps) -- References to types, functions, or methods not defined in any task - -## Remember -- Exact file paths always -- Complete code in every step — if a step changes code, show the code -- Exact commands with expected output -- DRY, YAGNI, TDD, frequent commits - -## Self-Review - -After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch. - -**1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps. - -**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them. - -**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug. - -If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task. - -## Execution Handoff - -After saving the plan, offer execution choice: - -**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:** - -**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration - -**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints - -**Which approach?"** - -**If Subagent-Driven chosen:** -- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development -- Fresh subagent per task + two-stage review - -**If Inline Execution chosen:** -- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans -- Batch execution with checkpoints for review