diff --git a/plugins/superpowers/.codex-plugin/plugin.json b/plugins/superpowers/.codex-plugin/plugin.json index 6583feac..da22bc7e 100644 --- a/plugins/superpowers/.codex-plugin/plugin.json +++ b/plugins/superpowers/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "superpowers", - "version": "5.0.7", + "version": "5.1.0", "description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.", "author": { "name": "Jesse Vincent", diff --git a/plugins/superpowers/README.md b/plugins/superpowers/README.md index 28874346..ea17e30e 100644 --- a/plugins/superpowers/README.md +++ b/plugins/superpowers/README.md @@ -1,6 +1,10 @@ # Superpowers -Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable "skills" and some initial instructions that make sure your agent uses them. +Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them. + +## Quickstart + +Give your agent Superpowers: [Claude Code](#claude-code), [Codex CLI](#codex-cli), [Codex App](#codex-app), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [OpenCode](#opencode), [Cursor](#cursor), [GitHub Copilot CLI](#github-copilot-cli). ## How it works @@ -10,7 +14,7 @@ Once it's teased a spec out of the conversation, it shows it to you in chunks sh After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. -Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Codex to be able to work autonomously for a couple hours at a time without deviating from the plan you put together. +Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together. There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers. @@ -26,60 +30,126 @@ Thanks! ## Installation -**Note:** Installation differs by platform. Codex uses the install instructions below; Cursor and other tools may provide their own marketplaces. +Installation differs by harness. If you use more than one, install Superpowers separately for each one. -### Codex +### Claude Code -Tell Codex: +Superpowers is available via the [official Claude plugin marketplace](https://claude.com/plugins/superpowers) -``` -Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md -``` +#### Official Marketplace -**Detailed docs:** [docs/README.codex.md](docs/README.codex.md) +- Install the plugin from Anthropic's official marketplace: -### Cursor (via Plugin Marketplace) + ```bash + /plugin install superpowers@claude-plugins-official + ``` -In Cursor Agent chat, install from marketplace: +#### Superpowers Marketplace -```text -/add-plugin superpowers -``` +The Superpowers marketplace provides Superpowers and some other related plugins for Claude Code. -or search for "superpowers" in the plugin marketplace. +- Register the marketplace: -### OpenCode + ```bash + /plugin marketplace add obra/superpowers-marketplace + ``` -Tell OpenCode: +- Install the plugin from this marketplace: -``` -Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md -``` + ```bash + /plugin install superpowers@superpowers-marketplace + ``` -**Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md) +### Codex CLI -### GitHub Copilot CLI +Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins). + +- Open the plugin search interface: + + ```bash + /plugins + ``` + +- Search for Superpowers: + + ```bash + superpowers + ``` + +- Select `Install Plugin`. + +### Codex App + +Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins). + +- In the Codex app, click on Plugins in the sidebar. +- You should see `Superpowers` in the Coding section. +- Click the `+` next to Superpowers and follow the prompts. + +### Factory Droid + +- Register the marketplace: + + ```bash + droid plugin marketplace add https://github.com/obra/superpowers + ``` + +- Install the plugin: -```bash -copilot plugin marketplace add obra/superpowers-marketplace -copilot plugin install superpowers@superpowers-marketplace -``` + ```bash + droid plugin install superpowers@superpowers + ``` ### Gemini CLI -```bash -gemini extensions install https://github.com/obra/superpowers -``` +- Install the extension: -To update: + ```bash + gemini extensions install https://github.com/obra/superpowers + ``` -```bash -gemini extensions update superpowers -``` +- Update later: -### Verify Installation + ```bash + gemini extensions update superpowers + ``` -Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant superpowers skill. +### OpenCode + +OpenCode uses its own plugin install; install Superpowers separately even if you +already use it in another harness. + +- Tell OpenCode: + + ``` + Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md + ``` + +- Detailed docs: [docs/README.opencode.md](docs/README.opencode.md) + +### Cursor + +- In Cursor Agent chat, install from marketplace: + + ```text + /add-plugin superpowers + ``` + +- Or search for "superpowers" in the plugin marketplace. + +### GitHub Copilot CLI + +- Register the marketplace: + + ```bash + copilot plugin marketplace add obra/superpowers-marketplace + ``` + +- Install the plugin: + + ```bash + copilot plugin install superpowers@superpowers-marketplace + ``` ## The Basic Workflow @@ -132,26 +202,23 @@ Start a new session in your chosen platform and ask for something that should tr - **Complexity reduction** - Simplicity as primary goal - **Evidence over claims** - Verify before declaring success -Read more: [Superpowers](https://blog.fsck.com/2025/10/09/superpowers/) +Read [the original release announcement](https://blog.fsck.com/2025/10/09/superpowers/). ## Contributing -Skills live directly in this repository. To contribute: +The general contribution process for Superpowers is below. Keep in mind that we don't generally accept contributions of new skills and that any updates to skills must work across all of the coding agents we support. 1. Fork the repository -2. Create a branch for your skill -3. Follow the `writing-skills` skill for creating and testing new skills -4. Submit a PR +2. Switch to the 'dev' branch +3. Create a branch for your work +4. Follow the `writing-skills` skill for creating and testing new and modified skills +5. Submit a PR, being sure to fill in the pull request template. See `skills/writing-skills/SKILL.md` for the complete guide. ## Updating -Skills update automatically when you update the plugin: - -```bash -/plugin update superpowers -``` +Superpowers updates are somewhat coding-agent dependent, but are often automatic. ## License diff --git a/plugins/superpowers/agents/code-reviewer.md b/plugins/superpowers/agents/code-reviewer.md deleted file mode 100644 index 4e14076b..00000000 --- a/plugins/superpowers/agents/code-reviewer.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: code-reviewer -description: | - Use this agent when a major project step has been completed and needs to be reviewed against the original plan and coding standards. Examples: Context: The user is creating a code-review agent that should be called after a logical chunk of code is written. user: "I've finished implementing the user authentication system as outlined in step 3 of our plan" assistant: "Great work! Now let me use the code-reviewer agent to review the implementation against our plan and coding standards" Since a major project step has been completed, use the code-reviewer agent to validate the work against the plan and identify any issues. Context: User has completed a significant feature implementation. user: "The API endpoints for the task management system are now complete - that covers step 2 from our architecture document" assistant: "Excellent! Let me have the code-reviewer agent examine this implementation to ensure it aligns with our plan and follows best practices" A numbered step from the planning document has been completed, so the code-reviewer agent should review the work. -model: inherit ---- - -You are a Senior Code Reviewer with expertise in software architecture, design patterns, and best practices. Your role is to review completed project steps against original plans and ensure code quality standards are met. - -When reviewing completed work, you will: - -1. **Plan Alignment Analysis**: - - Compare the implementation against the original planning document or step description - - Identify any deviations from the planned approach, architecture, or requirements - - Assess whether deviations are justified improvements or problematic departures - - Verify that all planned functionality has been implemented - -2. **Code Quality Assessment**: - - Review code for adherence to established patterns and conventions - - Check for proper error handling, type safety, and defensive programming - - Evaluate code organization, naming conventions, and maintainability - - Assess test coverage and quality of test implementations - - Look for potential security vulnerabilities or performance issues - -3. **Architecture and Design Review**: - - Ensure the implementation follows SOLID principles and established architectural patterns - - Check for proper separation of concerns and loose coupling - - Verify that the code integrates well with existing systems - - Assess scalability and extensibility considerations - -4. **Documentation and Standards**: - - Verify that code includes appropriate comments and documentation - - Check that file headers, function documentation, and inline comments are present and accurate - - Ensure adherence to project-specific coding standards and conventions - -5. **Issue Identification and Recommendations**: - - Clearly categorize issues as: Critical (must fix), Important (should fix), or Suggestions (nice to have) - - For each issue, provide specific examples and actionable recommendations - - When you identify plan deviations, explain whether they're problematic or beneficial - - Suggest specific improvements with code examples when helpful - -6. **Communication Protocol**: - - If you find significant deviations from the plan, ask the coding agent to review and confirm the changes - - If you identify issues with the original plan itself, recommend plan updates - - For implementation problems, provide clear guidance on fixes needed - - Always acknowledge what was done well before highlighting issues - -Your output should be structured, actionable, and focused on helping maintain high code quality while ensuring project goals are met. Be thorough but concise, and always provide constructive feedback that helps improve both the current implementation and future development practices. diff --git a/plugins/superpowers/skills/brainstorming/scripts/frame-template.html b/plugins/superpowers/skills/brainstorming/scripts/frame-template.html index 9d7c0192..dcfe0181 100644 --- a/plugins/superpowers/skills/brainstorming/scripts/frame-template.html +++ b/plugins/superpowers/skills/brainstorming/scripts/frame-template.html @@ -13,7 +13,7 @@ * - Scrollable main content area * - CSS helpers for common UI patterns * - * Content is injected via placeholder comment in #codex-content. + * Content is injected via placeholder comment in #claude-content. */ * { box-sizing: border-box; margin: 0; padding: 0; } @@ -77,7 +77,7 @@ .header .status::before { content: ''; width: 6px; height: 6px; background: var(--success); border-radius: 50%; } .main { flex: 1; overflow-y: auto; } - #codex-content { padding: 2rem; min-height: 100%; } + #claude-content { padding: 2rem; min-height: 100%; } .indicator-bar { background: var(--bg-secondary); @@ -201,7 +201,7 @@

-
+
diff --git a/plugins/superpowers/skills/brainstorming/visual-companion.md b/plugins/superpowers/skills/brainstorming/visual-companion.md index 7f481abd..2113863d 100644 --- a/plugins/superpowers/skills/brainstorming/visual-companion.md +++ b/plugins/superpowers/skills/brainstorming/visual-companion.md @@ -49,13 +49,13 @@ Save `screen_dir` and `state_dir` from the response. Tell user to open the URL. **Launching the server by platform:** -**Codex (macOS / Linux):** +**Claude Code (macOS / Linux):** ```bash # Default mode works — the script backgrounds the server itself scripts/start-server.sh --project-dir /path/to/project ``` -**Codex (Windows):** +**Claude Code (Windows):** ```bash # Windows auto-detects and uses foreground mode, which blocks the tool call. # Use run_in_background: true on the Bash tool call so the server survives diff --git a/plugins/superpowers/skills/dispatching-parallel-agents/SKILL.md b/plugins/superpowers/skills/dispatching-parallel-agents/SKILL.md index 27c0ed9a..a6a3f5a0 100644 --- a/plugins/superpowers/skills/dispatching-parallel-agents/SKILL.md +++ b/plugins/superpowers/skills/dispatching-parallel-agents/SKILL.md @@ -66,7 +66,7 @@ Each agent gets: ### 3. Dispatch in Parallel ```typescript -// In Codex / AI environment +// In Claude Code / AI environment Task("Fix agent-tool-abort.test.ts failures") Task("Fix batch-completion-behavior.test.ts failures") Task("Fix tool-approval-race-conditions.test.ts failures") diff --git a/plugins/superpowers/skills/executing-plans/SKILL.md b/plugins/superpowers/skills/executing-plans/SKILL.md index 554495fd..a5918627 100644 --- a/plugins/superpowers/skills/executing-plans/SKILL.md +++ b/plugins/superpowers/skills/executing-plans/SKILL.md @@ -11,7 +11,7 @@ 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 Codex. If subagents are available, use superpowers:subagent-driven-development instead of this skill. +**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 @@ -65,6 +65,6 @@ After all tasks complete and verified: ## Integration **Required workflow skills:** -- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting +- **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/plugins/superpowers/skills/finishing-a-development-branch/SKILL.md b/plugins/superpowers/skills/finishing-a-development-branch/SKILL.md index c308b43b..43da0ae1 100644 --- a/plugins/superpowers/skills/finishing-a-development-branch/SKILL.md +++ b/plugins/superpowers/skills/finishing-a-development-branch/SKILL.md @@ -9,7 +9,7 @@ description: Use when implementation is complete, all tests pass, and you need t Guide completion of development work by presenting clear options and handling chosen workflow. -**Core principle:** Verify tests → Present options → Execute choice → Clean up. +**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." @@ -37,7 +37,24 @@ Stop. Don't proceed to Step 2. **If tests pass:** Continue to Step 2. -### Step 2: Determine Base Branch +### 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 @@ -46,9 +63,9 @@ 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 3: Present Options +### Step 4: Present Options -Present exactly these 4 options: +**Normal repo and named-branch worktree — present exactly these 4 options:** ``` Implementation complete. What would you like to do? @@ -61,30 +78,45 @@ Implementation complete. What would you like to do? 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 4: Execute Choice +### Step 5: Execute Choice #### Option 1: Merge Locally ```bash -# Switch to base branch -git checkout +# Get main repo root for CWD safety +MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) +cd "$MAIN_ROOT" -# Pull latest +# Merge first — verify success before removing anything +git checkout git pull - -# Merge feature branch git merge # Verify tests on merged result -# If tests pass -git branch -d +# Only after merge succeeds: cleanup worktree (Step 6), then delete branch ``` -Then: Cleanup worktree (Step 5) +Then: Cleanup worktree (Step 6), then delete branch: + +```bash +git branch -d +``` #### Option 2: Push and Create PR @@ -103,7 +135,7 @@ EOF )" ``` -Then: Cleanup worktree (Step 5) +**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback. #### Option 3: Keep As-Is @@ -127,36 +159,46 @@ Wait for exact confirmation. If confirmed: ```bash -git checkout -git branch -D +MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) +cd "$MAIN_ROOT" ``` -Then: Cleanup worktree (Step 5) +Then: Cleanup worktree (Step 6), then force-delete branch: +```bash +git branch -D +``` -### Step 5: Cleanup Worktree +### Step 6: Cleanup Workspace -**For Options 1, 2, 4:** +**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree. -Check if in worktree: ```bash -git worktree list | grep $(git branch --show-current) +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 yes: +**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 -git worktree remove +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 ``` -**For Option 3:** Keep worktree. +**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 | ✓ | - | - | ✓ | -| 2. Create PR | - | ✓ | ✓ | - | -| 3. Keep as-is | - | - | ✓ | - | -| 4. Discard | - | - | - | ✓ (force) | +| 1. Merge locally | yes | - | - | yes | +| 2. Create PR | - | yes | yes | - | +| 3. Keep as-is | - | - | yes | - | +| 4. Discard | - | - | - | yes (force) | ## Common Mistakes @@ -165,13 +207,25 @@ git worktree remove - **Fix:** Always verify tests before offering options **Open-ended questions** -- **Problem:** "What should I do next?" → ambiguous -- **Fix:** Present exactly 4 structured options +- **Problem:** "What should I do next?" is ambiguous +- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD) -**Automatic worktree cleanup** -- **Problem:** Remove worktree when might need it (Option 2, 3) +**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 @@ -183,18 +237,15 @@ git worktree remove - 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 -- Present exactly 4 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 - -## Integration - -**Called by:** -- **subagent-driven-development** (Step 7) - After all tasks complete -- **executing-plans** (Step 5) - After all batches complete - -**Pairs with:** -- **using-git-worktrees** - Cleans up worktree created by that skill +- `cd` to main repo root before worktree removal +- Run `git worktree prune` after removal diff --git a/plugins/superpowers/skills/receiving-code-review/SKILL.md b/plugins/superpowers/skills/receiving-code-review/SKILL.md index 0f3025f4..4ea72cdf 100644 --- a/plugins/superpowers/skills/receiving-code-review/SKILL.md +++ b/plugins/superpowers/skills/receiving-code-review/SKILL.md @@ -27,7 +27,7 @@ WHEN receiving code review feedback: ## Forbidden Responses **NEVER:** -- "You're absolutely right!" (explicit AGENTS.md violation) +- "You're absolutely right!" (explicit CLAUDE.md violation) - "Great point!" / "Excellent feedback!" (performative) - "Let me implement that now" (before verification) diff --git a/plugins/superpowers/skills/requesting-code-review/SKILL.md b/plugins/superpowers/skills/requesting-code-review/SKILL.md index fe7c8d90..34b83404 100644 --- a/plugins/superpowers/skills/requesting-code-review/SKILL.md +++ b/plugins/superpowers/skills/requesting-code-review/SKILL.md @@ -5,7 +5,7 @@ description: Use when completing tasks, implementing major features, or before m # Requesting Code Review -Dispatch superpowers: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. +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. @@ -29,16 +29,15 @@ BASE_SHA=$(git rev-parse HEAD~1) # or origin/main HEAD_SHA=$(git rev-parse HEAD) ``` -**2. Dispatch code-reviewer subagent:** +**2. Dispatch code reviewer subagent:** -Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md` +Use Task tool with `general-purpose` type, fill template at `code-reviewer.md` **Placeholders:** -- `{WHAT_WAS_IMPLEMENTED}` - What you just built +- `{DESCRIPTION}` - Brief summary of what you built - `{PLAN_OR_REQUIREMENTS}` - What it should do - `{BASE_SHA}` - Starting commit - `{HEAD_SHA}` - Ending commit -- `{DESCRIPTION}` - Brief summary **3. Act on feedback:** - Fix Critical issues immediately @@ -56,12 +55,11 @@ 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 superpowers:code-reviewer subagent] - WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index +[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 - DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types [Subagent returns]: Strengths: Clean architecture, real tests @@ -82,7 +80,7 @@ You: [Fix progress indicators] - Fix before moving to next task **Executing Plans:** -- Review after each batch (3 tasks) +- Review after each task or at natural checkpoints - Get feedback, apply, continue **Ad-Hoc Development:** diff --git a/plugins/superpowers/skills/requesting-code-review/code-reviewer.md b/plugins/superpowers/skills/requesting-code-review/code-reviewer.md index 3c427c91..525e4b47 100644 --- a/plugins/superpowers/skills/requesting-code-review/code-reviewer.md +++ b/plugins/superpowers/skills/requesting-code-review/code-reviewer.md @@ -1,111 +1,133 @@ -# Code Review Agent +# Code Reviewer Prompt Template -You are reviewing code changes for production readiness. +Use this template when dispatching a code reviewer subagent. -**Your task:** -1. Review {WHAT_WAS_IMPLEMENTED} -2. Compare against {PLAN_OR_REQUIREMENTS} -3. Check code quality, architecture, testing -4. Categorize issues by severity -5. Assess production readiness +**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work. -## What Was Implemented +``` +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. -{DESCRIPTION} + ## What Was Implemented -## Requirements/Plan + {DESCRIPTION} -{PLAN_REFERENCE} + ## Requirements / Plan -## Git Range to Review + {PLAN_OR_REQUIREMENTS} -**Base:** {BASE_SHA} -**Head:** {HEAD_SHA} + ## Git Range to Review -```bash -git diff --stat {BASE_SHA}..{HEAD_SHA} -git diff {BASE_SHA}..{HEAD_SHA} -``` + **Base:** {BASE_SHA} + **Head:** {HEAD_SHA} -## Review Checklist - -**Code Quality:** -- Clean separation of concerns? -- Proper error handling? -- Type safety (if applicable)? -- DRY principle followed? -- Edge cases handled? - -**Architecture:** -- Sound design decisions? -- Scalability considerations? -- Performance implications? -- Security concerns? - -**Testing:** -- Tests actually test logic (not mocks)? -- Edge cases covered? -- Integration tests where needed? -- All tests passing? - -**Requirements:** -- All plan requirements met? -- Implementation matches spec? -- No scope creep? -- Breaking changes documented? - -**Production Readiness:** -- Migration strategy (if schema changes)? -- Backward compatibility considered? -- Documentation complete? -- No obvious bugs? - -## Output Format + ```bash + git diff --stat {BASE_SHA}..{HEAD_SHA} + git diff {BASE_SHA}..{HEAD_SHA} + ``` -### Strengths -[What's well done? Be specific.] + ## What to Check -### Issues + **Plan alignment:** + - Does the implementation match the plan / requirements? + - Are deviations justified improvements, or problematic departures? + - Is all planned functionality present? -#### Critical (Must Fix) -[Bugs, security issues, data loss risks, broken functionality] + **Code quality:** + - Clean separation of concerns? + - Proper error handling? + - Type safety where applicable? + - DRY without premature abstraction? + - Edge cases handled? -#### Important (Should Fix) -[Architecture problems, missing features, poor error handling, test gaps] + **Architecture:** + - Sound design decisions? + - Reasonable scalability and performance? + - Security concerns? + - Integrates cleanly with surrounding code? -#### Minor (Nice to Have) -[Code style, optimization opportunities, documentation improvements] + **Testing:** + - Tests verify real behavior, not mocks? + - Edge cases covered? + - Integration tests where they matter? + - All tests passing? -**For each issue:** -- File:line reference -- What's wrong -- Why it matters -- How to fix (if not obvious) + **Production readiness:** + - Migration strategy if schema changed? + - Backward compatibility considered? + - Documentation complete? + - No obvious bugs? -### Recommendations -[Improvements for code quality, architecture, or process] + ## Calibration -### Assessment + 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 -**Ready to merge?** [Yes/No/With fixes] + #### Critical (Must Fix) + [Bugs, security issues, data loss risks, broken functionality] -**Reasoning:** [Technical assessment in 1-2 sentences] + #### Important (Should Fix) + [Architecture problems, missing features, poor error handling, test gaps] -## Critical Rules + #### 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 +``` -**DO:** -- Categorize by actual severity (not everything is Critical) -- Be specific (file:line, not vague) -- Explain WHY issues matter -- Acknowledge strengths -- Give 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 -**DON'T:** -- Say "looks good" without checking -- Mark nitpicks as Critical -- Give feedback on code you didn't review -- Be vague ("improve error handling") -- Avoid giving a clear verdict +**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment ## Example Output diff --git a/plugins/superpowers/skills/subagent-driven-development/SKILL.md b/plugins/superpowers/skills/subagent-driven-development/SKILL.md index 5150b186..ea7ac8fd 100644 --- a/plugins/superpowers/skills/subagent-driven-development/SKILL.md +++ b/plugins/superpowers/skills/subagent-driven-development/SKILL.md @@ -11,6 +11,8 @@ Execute plan by dispatching fresh subagent per task, with two-stage review after **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 @@ -265,7 +267,7 @@ Done! ## Integration **Required workflow skills:** -- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting +- **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 diff --git a/plugins/superpowers/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/plugins/superpowers/skills/subagent-driven-development/code-quality-reviewer-prompt.md index a04201ac..51f901a5 100644 --- a/plugins/superpowers/skills/subagent-driven-development/code-quality-reviewer-prompt.md +++ b/plugins/superpowers/skills/subagent-driven-development/code-quality-reviewer-prompt.md @@ -7,14 +7,13 @@ Use this template when dispatching a code quality reviewer subagent. **Only dispatch after spec compliance review passes.** ``` -Task tool (superpowers:code-reviewer): +Task tool (general-purpose): Use template at requesting-code-review/code-reviewer.md - WHAT_WAS_IMPLEMENTED: [from implementer's report] + DESCRIPTION: [task summary, from implementer's report] PLAN_OR_REQUIREMENTS: Task N from [plan-file] BASE_SHA: [commit before task] HEAD_SHA: [current commit] - DESCRIPTION: [task summary] ``` **In addition to standard code quality concerns, the reviewer should check:** diff --git a/plugins/superpowers/skills/systematic-debugging/CREATION-LOG.md b/plugins/superpowers/skills/systematic-debugging/CREATION-LOG.md index e8d25f08..9aa03092 100644 --- a/plugins/superpowers/skills/systematic-debugging/CREATION-LOG.md +++ b/plugins/superpowers/skills/systematic-debugging/CREATION-LOG.md @@ -4,7 +4,7 @@ Reference example of extracting, structuring, and bulletproofing a critical skil ## Source Material -Extracted debugging framework from `/Users/jesse/.codex/AGENTS.md`: +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 @@ -99,7 +99,7 @@ Bulletproof skill that: ## Key Insight -**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Codex thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction. +**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 diff --git a/plugins/superpowers/skills/systematic-debugging/root-cause-tracing.md b/plugins/superpowers/skills/systematic-debugging/root-cause-tracing.md index 94847749..12ef5222 100644 --- a/plugins/superpowers/skills/systematic-debugging/root-cause-tracing.md +++ b/plugins/superpowers/skills/systematic-debugging/root-cause-tracing.md @@ -33,7 +33,7 @@ digraph when_to_use { ### 1. Observe the Symptom ``` -Error: git init failed in /Users/jesse/project/packages/core +Error: git init failed in ~/project/packages/core ``` ### 2. Find Immediate Cause diff --git a/plugins/superpowers/skills/using-git-worktrees/SKILL.md b/plugins/superpowers/skills/using-git-worktrees/SKILL.md index 74dfdedc..134d3714 100644 --- a/plugins/superpowers/skills/using-git-worktrees/SKILL.md +++ b/plugins/superpowers/skills/using-git-worktrees/SKILL.md @@ -1,104 +1,117 @@ --- name: using-git-worktrees -description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification +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 -Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching. +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:** Systematic directory selection + safety verification = reliable isolation. +**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." -## Directory Selection Process +## Step 0: Detect Existing Isolation -Follow this priority order: - -### 1. Check Existing Directories +**Before creating anything, check if you are already in an isolated workspace.** ```bash -# Check in priority order -ls -d .worktrees 2>/dev/null # Preferred (hidden) -ls -d worktrees 2>/dev/null # Alternative +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) ``` -**If found:** Use that directory. If both exist, `.worktrees` wins. - -### 2. Check AGENTS.md +**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 -grep -i "worktree.*director" AGENTS.md 2>/dev/null +# 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 preference specified:** Use it without asking. +**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. -### 3. Ask User +Report with branch state: +- On a branch: "Already in isolated workspace at `` on branch ``." +- Detached HEAD: "Already in isolated workspace at `` (detached HEAD, externally managed). Branch creation needed at finish time." -If no directory exists and no AGENTS.md preference: +**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout. -``` -No worktree directory found. Where should I create worktrees? +Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree: -1. .worktrees/ (project-local, hidden) -2. ~/.config/superpowers/worktrees// (global location) +> "Would you like me to set up an isolated worktree? It protects your current branch from changes." -Which would you prefer? -``` +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. -## Safety Verification +### 1b. Git Worktree Fallback -### For Project-Local Directories (.worktrees or worktrees) +**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 -# Check if directory is ignored (respects local, global, and system gitignore) git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null ``` -**If NOT ignored:** - -Per Jesse's rule "Fix broken things immediately": -1. Add appropriate line to .gitignore -2. Commit the change -3. Proceed with worktree creation +**If NOT ignored:** Add to .gitignore, commit the change, then proceed. **Why critical:** Prevents accidentally committing worktree contents to repository. -### For Global Directory (~/.config/superpowers/worktrees) - -No .gitignore verification needed - outside project entirely. +Global directories (`~/.config/superpowers/worktrees/`) need no verification. -## Creation Steps - -### 1. Detect Project Name +#### Create the Worktree ```bash project=$(basename "$(git rev-parse --show-toplevel)") -``` -### 2. Create Worktree +# Determine path based on chosen location +# For project-local: path="$LOCATION/$BRANCH_NAME" +# For global: path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME" -```bash -# Determine full path -case $LOCATION in - .worktrees|worktrees) - path="$LOCATION/$BRANCH_NAME" - ;; - ~/.config/superpowers/worktrees/*) - path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME" - ;; -esac - -# Create worktree with new branch git worktree add "$path" -b "$BRANCH_NAME" cd "$path" ``` -### 3. Run Project Setup +**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: @@ -117,23 +130,20 @@ if [ -f pyproject.toml ]; then poetry install; fi if [ -f go.mod ]; then go mod download; fi ``` -### 4. Verify Clean Baseline +## Step 4: Verify Clean Baseline -Run tests to ensure worktree starts clean: +Run tests to ensure workspace starts clean: ```bash -# Examples - use project-appropriate command -npm test -cargo test -pytest -go test ./... +# 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. -### 5. Report Location +### Report ``` Worktree ready at @@ -145,16 +155,32 @@ Ready to implement | 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 AGENTS.md → Ask user | +| 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 @@ -163,56 +189,27 @@ Ready to implement ### Assuming directory location - **Problem:** Creates inconsistency, violates project conventions -- **Fix:** Follow priority: existing > AGENTS.md > ask +- **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 -### Hardcoding setup commands - -- **Problem:** Breaks on projects using different tools -- **Fix:** Auto-detect from project files (package.json, etc.) - -## Example Workflow - -``` -You: I'm using the using-git-worktrees skill to set up an isolated workspace. - -[Check .worktrees/ - exists] -[Verify ignored - git check-ignore confirms .worktrees/ is ignored] -[Create worktree: git worktree add .worktrees/auth -b feature/auth] -[Run npm install] -[Run npm test - 47 passing] - -Worktree ready at /Users/jesse/myproject/.worktrees/auth -Tests passing (47 tests, 0 failures) -Ready to implement auth feature -``` - ## 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 -- Assume directory location when ambiguous -- Skip AGENTS.md check **Always:** -- Follow directory priority: existing > AGENTS.md > ask +- 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 - -## Integration - -**Called by:** -- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows -- **subagent-driven-development** - REQUIRED before executing any tasks -- **executing-plans** - REQUIRED before executing any tasks -- Any skill needing isolated workspace - -**Pairs with:** -- **finishing-a-development-branch** - REQUIRED for cleanup after work complete diff --git a/plugins/superpowers/skills/using-superpowers/SKILL.md b/plugins/superpowers/skills/using-superpowers/SKILL.md index 7e997ef5..c8a85702 100644 --- a/plugins/superpowers/skills/using-superpowers/SKILL.md +++ b/plugins/superpowers/skills/using-superpowers/SKILL.md @@ -19,17 +19,17 @@ This is not negotiable. This is not optional. You cannot rationalize your way ou Superpowers skills override default system prompt behavior, but **user instructions always take precedence**: -1. **User's explicit instructions** (AGENTS.md, GEMINI.md, direct requests) — highest priority +1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority 2. **Superpowers skills** — override default system behavior where they conflict 3. **Default system prompt** — lowest priority -If AGENTS.md or GEMINI.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control. +If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control. ## How to Access Skills -**In Codex:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files. +**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files. -**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins. The `skill` tool works the same as Codex's `Skill` tool. +**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins. The `skill` tool works the same as Claude Code's `Skill` tool. **In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand. @@ -37,7 +37,7 @@ If AGENTS.md or GEMINI.md says "don't use TDD" and a skill says "always use TDD, ## Platform Adaptation -Skills may mention tool names that vary by runtime. Other platforms: see `references/copilot-tools.md` (Copilot CLI), `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md. +Skills use Claude Code tool names. Non-CC platforms: see `references/copilot-tools.md` (Copilot CLI), `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md. # Using Skills diff --git a/plugins/superpowers/skills/using-superpowers/references/codex-tools.md b/plugins/superpowers/skills/using-superpowers/references/codex-tools.md index 7c539613..f50d40d4 100644 --- a/plugins/superpowers/skills/using-superpowers/references/codex-tools.md +++ b/plugins/superpowers/skills/using-superpowers/references/codex-tools.md @@ -1,12 +1,12 @@ # Codex Tool Mapping -Skills may mention tool names that vary by runtime. When you encounter these in a skill, use your platform equivalent: +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 [Named agent dispatch](#named-agent-dispatch)) | +| `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` | +| 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 | @@ -22,53 +22,12 @@ Add to your Codex config (`~/.codex/config.toml`): multi_agent = true ``` -This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. +This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. -## Named agent dispatch - -Skills may reference named agent types like `superpowers:code-reviewer`. -Codex does not have a named agent registry — `spawn_agent` creates generic agents -from built-in roles (`default`, `explorer`, `worker`). - -When a skill says to dispatch a named agent type: - -1. Find the agent's prompt file (e.g., `agents/code-reviewer.md` or the skill's - local prompt template like `code-quality-reviewer-prompt.md`) -2. Read the prompt content -3. Fill any template placeholders (`{BASE_SHA}`, `{WHAT_WAS_IMPLEMENTED}`, etc.) -4. Spawn a `worker` agent with the filled content as the `message` - -| Skill instruction | Codex equivalent | -|-------------------|------------------| -| `Task tool (superpowers:code-reviewer)` | `spawn_agent(agent_type="worker", message=...)` with `code-reviewer.md` content | -| `Task tool (general-purpose)` with inline prompt | `spawn_agent(message=...)` with the same prompt | - -### Message framing - -The `message` parameter is user-level input, not a system prompt. Structure it -for maximum instruction adherence: - -``` -Your task is to perform the following. Follow the instructions below exactly. - - -[filled prompt content from the agent's .md file] - - -Execute this now. Output ONLY the structured response following the format -specified in the instructions above. -``` - -- Use task-delegation framing ("Your task is...") rather than persona framing ("You are...") -- Wrap instructions in XML tags — the model treats tagged blocks as authoritative -- End with an explicit execution directive to prevent summarization of the instructions - -### When this workaround can be removed - -This approach compensates for Codex's plugin system not yet supporting an `agents` -field in `plugin.json`. When `RawPluginManifest` gains an `agents` field, the -plugin can symlink to `agents/` (mirroring the existing `skills/` symlink) and -skills can dispatch named agent types directly. +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 diff --git a/plugins/superpowers/skills/using-superpowers/references/copilot-tools.md b/plugins/superpowers/skills/using-superpowers/references/copilot-tools.md index c97f4f28..ae3cf5a6 100644 --- a/plugins/superpowers/skills/using-superpowers/references/copilot-tools.md +++ b/plugins/superpowers/skills/using-superpowers/references/copilot-tools.md @@ -1,6 +1,6 @@ # Copilot CLI Tool Mapping -Skills may mention tool names that vary by runtime. When you encounter these in a skill, use your platform equivalent: +Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent: | Skill references | Copilot CLI equivalent | |-----------------|----------------------| @@ -12,26 +12,16 @@ Skills may mention tool names that vary by runtime. When you encounter these in | `Glob` (search files by name) | `glob` | | `Skill` tool (invoke a skill) | `skill` | | `WebFetch` | `web_fetch` | -| `Task` tool (dispatch subagent) | `task` (see [Agent types](#agent-types)) | +| `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 | -## Agent types - -Copilot CLI's `task` tool accepts an `agent_type` parameter: - -| Skill agent | Copilot CLI equivalent | -|-------------------|----------------------| -| `general-purpose` | `"general-purpose"` | -| `Explore` | `"explore"` | -| Named plugin agents (e.g. `superpowers:code-reviewer`) | Discovered automatically from installed plugins | - ## Async shell sessions -Copilot CLI supports persistent async shell sessions, which may not have a direct equivalent in other runtimes: +Copilot CLI supports persistent async shell sessions, which have no direct Claude Code equivalent: | Tool | Purpose | |------|---------| diff --git a/plugins/superpowers/skills/using-superpowers/references/gemini-tools.md b/plugins/superpowers/skills/using-superpowers/references/gemini-tools.md index 18837019..91ef4049 100644 --- a/plugins/superpowers/skills/using-superpowers/references/gemini-tools.md +++ b/plugins/superpowers/skills/using-superpowers/references/gemini-tools.md @@ -1,6 +1,6 @@ # Gemini CLI Tool Mapping -Skills may mention tool names that vary by runtime. When you encounter these in a skill, use your platform equivalent: +Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent: | Skill references | Gemini CLI equivalent | |-----------------|----------------------| @@ -14,15 +14,33 @@ Skills may mention tool names that vary by runtime. When you encounter these in | `Skill` tool (invoke a skill) | `activate_skill` | | `WebSearch` | `google_web_search` | | `WebFetch` | `web_fetch` | -| `Task` tool (dispatch subagent) | No equivalent — Gemini CLI does not support subagents | +| `Task` tool (dispatch subagent) | `@agent-name` (see [Subagent support](#subagent-support)) | -## No subagent support +## Subagent support -Gemini CLI has no equivalent to a subagent dispatch tool. Skills that rely on subagent dispatch (`subagent-driven-development`, `dispatching-parallel-agents`) will fall back to single-session execution via `executing-plans`. +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 may not have an equivalent in other runtimes: +These tools are available in Gemini CLI but have no Claude Code equivalent: | Tool | Purpose | |------|---------| diff --git a/plugins/superpowers/skills/writing-plans/SKILL.md b/plugins/superpowers/skills/writing-plans/SKILL.md index 0d9c00ba..847412ec 100644 --- a/plugins/superpowers/skills/writing-plans/SKILL.md +++ b/plugins/superpowers/skills/writing-plans/SKILL.md @@ -13,7 +13,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o **Announce at start:** "I'm using the writing-plans skill to create the implementation plan." -**Context:** This should be run in a dedicated worktree (created by brainstorming skill). +**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-.md` - (User preferences for plan location override this default) diff --git a/plugins/superpowers/skills/writing-skills/SKILL.md b/plugins/superpowers/skills/writing-skills/SKILL.md index f599db5e..c3b73d8b 100644 --- a/plugins/superpowers/skills/writing-skills/SKILL.md +++ b/plugins/superpowers/skills/writing-skills/SKILL.md @@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying **Writing skills IS Test-Driven Development applied to process documentation.** -**Personal skills for Codex live in `~/.codex/skills` or `~/.agents/skills/`, depending on the runtime.** +**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)** You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes). @@ -21,7 +21,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel ## What is a Skill? -A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Codex instances find and apply effective approaches. +A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches. **Skills are:** Reusable techniques, patterns, tools, reference guides @@ -55,7 +55,7 @@ The entire skill creation process follows RED-GREEN-REFACTOR. **Don't create for:** - One-off solutions - Standard practices well-documented elsewhere -- Project-specific conventions (put in AGENTS.md) +- Project-specific conventions (put in CLAUDE.md) - Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls) ## Skill Types @@ -137,13 +137,13 @@ Concrete results ``` -## Codex Search Optimization (CSO) +## Claude Search Optimization (CSO) -**Critical for discovery:** Future Codex needs to FIND your skill +**Critical for discovery:** Future Claude needs to FIND your skill ### 1. Rich Description Field -**Purpose:** Codex reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?" +**Purpose:** Claude reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?" **Format:** Start with "Use when..." to focus on triggering conditions @@ -151,14 +151,14 @@ Concrete results The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description. -**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, Codex may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Codex to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality). +**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality). -When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Codex correctly read the flowchart and followed the two-stage review process. +When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process. -**The trap:** Descriptions that summarize workflow create a shortcut Codex will take. The skill body becomes documentation Codex skips. +**The trap:** Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips. ```yaml -# ❌ BAD: Summarizes workflow - Codex may follow this instead of reading skill +# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill description: Use when executing plans - dispatches subagent per task with code review between tasks # ❌ BAD: Too much process detail @@ -198,7 +198,7 @@ description: Use when using React Router and handling authentication redirects ### 2. Keyword Coverage -Use words Codex would search for: +Use words Claude would search for: - Error messages: "Hook timed out", "ENOTEMPTY", "race condition" - Symptoms: "flaky", "hanging", "zombie", "pollution" - Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach" @@ -634,7 +634,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality ## Discovery Workflow -How future Codex finds your skill: +How future Claude finds your skill: 1. **Encounters problem** ("tests are flaky") 3. **Finds SKILL** (description matches) diff --git a/plugins/superpowers/skills/writing-skills/anthropic-best-practices.md b/plugins/superpowers/skills/writing-skills/anthropic-best-practices.md index a9846e48..9f3f6ecf 100644 --- a/plugins/superpowers/skills/writing-skills/anthropic-best-practices.md +++ b/plugins/superpowers/skills/writing-skills/anthropic-best-practices.md @@ -1,8 +1,8 @@ # Skill authoring best practices -> Learn how to write effective Skills that Codex can discover and use successfully. +> Learn how to write effective Skills that Claude can discover and use successfully. -Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Codex can discover and use effectively. +Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively. For conceptual background on how Skills work, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview). @@ -10,21 +10,21 @@ For conceptual background on how Skills work, see the [Skills overview](/en/docs ### Concise is key -The context window is a public good. Your Skill shares the context window with everything else Codex needs to know, including: +The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including: * The system prompt * Conversation history * Other Skills' metadata * Your actual request -Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Codex reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Codex loads it, every token competes with conversation history and other context. +Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context. -**Default assumption**: Codex is already very smart +**Default assumption**: Claude is already very smart -Only add context Codex doesn't already have. Challenge each piece of information: +Only add context Claude doesn't already have. Challenge each piece of information: -* "Does Codex really need this explanation?" -* "Can I assume Codex knows this?" +* "Does Claude really need this explanation?" +* "Can I assume Claude knows this?" * "Does this paragraph justify its token cost?" **Good example: Concise** (approximately 50 tokens): @@ -54,7 +54,7 @@ recommend pdfplumber because it's easy to use and handles most cases well. First, you'll need to install it using pip. Then you can use the code below... ``` -The concise version assumes Codex knows what PDFs are and how libraries work. +The concise version assumes Claude knows what PDFs are and how libraries work. ### Set appropriate degrees of freedom @@ -124,10 +124,10 @@ python scripts/migrate.py --verify --backup Do not modify the command or add additional flags. ```` -**Analogy**: Think of Codex as a robot exploring a path: +**Analogy**: Think of Claude as a robot exploring a path: * **Narrow bridge with cliffs on both sides**: There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence. -* **Open field with no hazards**: Many paths lead to success. Give general direction and trust Codex to find the best route (high freedom). Example: code reviews where context determines the best approach. +* **Open field with no hazards**: Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach. ### Test with all models you plan to use @@ -135,11 +135,11 @@ Skills act as additions to models, so effectiveness depends on the underlying mo **Testing considerations by model**: -* **Fast model** (economical): Does the Skill provide enough guidance? -* **Balanced model**: Is the Skill clear and efficient? -* **Frontier model** (powerful reasoning): Does the Skill avoid over-explaining? +* **Claude Haiku** (fast, economical): Does the Skill provide enough guidance? +* **Claude Sonnet** (balanced): Is the Skill clear and efficient? +* **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining? -What works perfectly for a frontier model might need more detail for a faster model. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them. +What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them. ## Skill structure @@ -196,7 +196,7 @@ The `description` field enables Skill discovery and should include both what the **Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it. -Each Skill has exactly one description field. The description is critical for skill selection: Codex uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Codex to know when to select this Skill, while the rest of SKILL.md provides the implementation details. +Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details. Effective examples: @@ -234,7 +234,7 @@ description: Does stuff with files ### Progressive disclosure patterns -SKILL.md serves as an overview that points Codex to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the overview. +SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the overview. **Practical guidance:** @@ -248,7 +248,7 @@ A basic Skill starts with just a SKILL.md file containing metadata and instructi Simple SKILL.md file showing YAML frontmatter and markdown body -As your Skill grows, you can bundle additional content that Codex loads only when needed: +As your Skill grows, you can bundle additional content that Claude loads only when needed: Bundling additional reference files like reference.md and forms.md. @@ -292,11 +292,11 @@ with pdfplumber.open("file.pdf") as pdf: **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns ```` -Codex loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed. +Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed. #### Pattern 2: Domain-specific organization -For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Codex only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused. +For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused. ``` bigquery-skill/ @@ -348,13 +348,13 @@ For simple edits, modify the XML directly. **For OOXML details**: See [OOXML.md](OOXML.md) ``` -Codex reads REDLINING.md or OOXML.md only when the user needs those features. +Claude reads REDLINING.md or OOXML.md only when the user needs those features. ### Avoid deeply nested references -Codex may partially read files when they're referenced from other referenced files. When encountering nested references, Codex might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information. +Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information. -**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Codex reads complete files when needed. +**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed. **Bad example: Too deep**: @@ -382,7 +382,7 @@ Here's the actual information... ### Structure longer reference files with table of contents -For reference files longer than 100 lines, include a table of contents at the top. This ensures Codex can see the full scope of available information even when previewing with partial reads. +For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads. **Example**: @@ -403,7 +403,7 @@ For reference files longer than 100 lines, include a table of contents at the to ... ``` -Codex can then read the complete file or jump to specific sections as needed. +Claude can then read the complete file or jump to specific sections as needed. For details on how this filesystem-based architecture enables progressive disclosure, see the [Runtime environment](#runtime-environment) section in the Advanced section below. @@ -411,7 +411,7 @@ For details on how this filesystem-based architecture enables progressive disclo ### Use workflows for complex tasks -Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Codex can copy into its response and check off as it progresses. +Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses. **Example 1: Research synthesis workflow** (for Skills without code): @@ -498,7 +498,7 @@ Run: `python scripts/verify_output.py output.pdf` If verification fails, return to Step 2. ```` -Clear steps prevent Codex from skipping critical validation. The checklist helps both Codex and you track progress through multi-step workflows. +Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multi-step workflows. ### Implement feedback loops @@ -524,7 +524,7 @@ This pattern greatly improves output quality. 5. Finalize and save the document ``` -This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE\_GUIDE.md, and Codex performs the check by reading and comparing. +This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE\_GUIDE.md, and Claude performs the check by reading and comparing. **Example 2: Document editing process** (for Skills with code): @@ -593,7 +593,7 @@ Choose one term and use it throughout the Skill: * Mix "field", "box", "element", "control" * Mix "extract", "pull", "get", "retrieve" -Consistency helps Codex understand and follow instructions. +Consistency helps Claude understand and follow instructions. ## Common patterns @@ -688,11 +688,11 @@ chore: update dependencies and refactor error handling Follow this style: type(scope): brief description, then detailed explanation. ```` -Examples help Codex understand the desired style and level of detail more clearly than descriptions alone. +Examples help Claude understand the desired style and level of detail more clearly than descriptions alone. ### Conditional workflow pattern -Guide Codex through decision points: +Guide Claude through decision points: ```markdown theme={null} ## Document modification workflow @@ -715,7 +715,7 @@ Guide Codex through decision points: ``` - If workflows become large or complicated with many steps, consider pushing them into separate files and tell Codex to read the appropriate file based on the task at hand. + If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand. ## Evaluation and iteration @@ -726,9 +726,9 @@ Guide Codex through decision points: **Evaluation-driven development:** -1. **Identify gaps**: Run Codex on representative tasks without a Skill. Document specific failures or missing context +1. **Identify gaps**: Run Claude on representative tasks without a Skill. Document specific failures or missing context 2. **Create evaluations**: Build three scenarios that test these gaps -3. **Establish baseline**: Measure Codex's performance without the Skill +3. **Establish baseline**: Measure Claude's performance without the Skill 4. **Write minimal instructions**: Create just enough content to address the gaps and pass evaluations 5. **Iterate**: Execute evaluations, compare against baseline, and refine @@ -753,51 +753,51 @@ This approach ensures you're solving actual problems rather than anticipating re This example demonstrates a data-driven evaluation with a simple testing rubric. We do not currently provide a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness. -### Develop Skills iteratively with Codex +### Develop Skills iteratively with Claude -The most effective Skill development process involves Codex itself. Work with one instance of Codex ("Codex A") to create a Skill that will be used by other instances ("Codex B"). Codex A helps you design and refine instructions, while Codex B tests them in real tasks. This works because Codex models understand both how to write effective agent instructions and what information agents need. +The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that will be used by other instances ("Claude B"). Claude A helps you design and refine instructions, while Claude B tests them in real tasks. This works because Claude models understand both how to write effective agent instructions and what information agents need. **Creating a new Skill:** -1. **Complete a task without a Skill**: Work through a problem with Codex A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide. +1. **Complete a task without a Skill**: Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide. 2. **Identify the reusable pattern**: After completing the task, identify what context you provided that would be useful for similar future tasks. **Example**: If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (like "always exclude test accounts"), and common query patterns. -3. **Ask Codex A to create a Skill**: "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts." +3. **Ask Claude A to create a Skill**: "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts." - Codex models understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Codex to help create Skills. Simply ask Codex to create a Skill and it will generate properly structured SKILL.md content with appropriate frontmatter and body content. + Claude models understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Simply ask Claude to create a Skill and it will generate properly structured SKILL.md content with appropriate frontmatter and body content. -4. **Review for conciseness**: Check that Codex A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Codex already knows that." +4. **Review for conciseness**: Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that." -5. **Improve information architecture**: Ask Codex A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later." +5. **Improve information architecture**: Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later." -6. **Test on similar tasks**: Use the Skill with Codex B (a fresh instance with the Skill loaded) on related use cases. Observe whether Codex B finds the right information, applies rules correctly, and handles the task successfully. +6. **Test on similar tasks**: Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully. -7. **Iterate based on observation**: If Codex B struggles or misses something, return to Codex A with specifics: "When Codex used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?" +7. **Iterate based on observation**: If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?" **Iterating on existing Skills:** The same hierarchical pattern continues when improving Skills. You alternate between: -* **Working with Codex A** (the expert who helps refine the Skill) -* **Testing with Codex B** (the agent using the Skill to perform real work) -* **Observing Codex B's behavior** and bringing insights back to Codex A +* **Working with Claude A** (the expert who helps refine the Skill) +* **Testing with Claude B** (the agent using the Skill to perform real work) +* **Observing Claude B's behavior** and bringing insights back to Claude A -1. **Use the Skill in real workflows**: Give Codex B (with the Skill loaded) actual tasks, not test scenarios +1. **Use the Skill in real workflows**: Give Claude B (with the Skill loaded) actual tasks, not test scenarios -2. **Observe Codex B's behavior**: Note where it struggles, succeeds, or makes unexpected choices +2. **Observe Claude B's behavior**: Note where it struggles, succeeds, or makes unexpected choices - **Example observation**: "When I asked Codex B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule." + **Example observation**: "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule." -3. **Return to Codex A for improvements**: Share the current SKILL.md and describe what you observed. Ask: "I noticed Codex B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?" +3. **Return to Claude A for improvements**: Share the current SKILL.md and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?" -4. **Review Codex A's suggestions**: Codex A might suggest reorganizing to make rules more prominent, using stronger language like "MUST filter" instead of "always filter", or restructuring the workflow section. +4. **Review Claude A's suggestions**: Claude A might suggest reorganizing to make rules more prominent, using stronger language like "MUST filter" instead of "always filter", or restructuring the workflow section. -5. **Apply and test changes**: Update the Skill with Codex A's refinements, then test again with Codex B on similar requests +5. **Apply and test changes**: Update the Skill with Claude A's refinements, then test again with Claude B on similar requests 6. **Repeat based on usage**: Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions. @@ -807,18 +807,18 @@ The same hierarchical pattern continues when improving Skills. You alternate bet 2. Ask: Does the Skill activate when expected? Are instructions clear? What's missing? 3. Incorporate feedback to address blind spots in your own usage patterns -**Why this approach works**: Codex A understands agent needs, you provide domain expertise, Codex B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions. +**Why this approach works**: Claude A understands agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions. -### Observe how Codex navigates Skills +### Observe how Claude navigates Skills -As you iterate on Skills, pay attention to how Codex actually uses them in practice. Watch for: +As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for: -* **Unexpected exploration paths**: Does Codex read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought -* **Missed connections**: Does Codex fail to follow references to important files? Your links might need to be more explicit or prominent -* **Overreliance on certain sections**: If Codex repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead -* **Ignored content**: If Codex never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions +* **Unexpected exploration paths**: Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought +* **Missed connections**: Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent +* **Overreliance on certain sections**: If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead +* **Ignored content**: If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions -Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Codex uses these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used. +Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Claude uses these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used. ## Anti-patterns to avoid @@ -854,7 +854,7 @@ The sections below focus on Skills that include executable scripts. If your Skil ### Solve, don't punt -When writing scripts for Skills, handle error conditions rather than punting to Codex. +When writing scripts for Skills, handle error conditions rather than punting to Claude. **Good example: Handle errors explicitly**: @@ -876,15 +876,15 @@ def process_file(path): return '' ``` -**Bad example: Punt to Codex**: +**Bad example: Punt to Claude**: ```python theme={null} def process_file(path): - # Just fail and let Codex figure it out + # Just fail and let Claude figure it out return open(path).read() ``` -Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Codex determine it? +Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it? **Good example: Self-documenting**: @@ -907,7 +907,7 @@ RETRIES = 5 # Why 5? ### Provide utility scripts -Even if Codex could write a script, pre-made scripts offer advantages: +Even if Claude could write a script, pre-made scripts offer advantages: **Benefits of utility scripts**: @@ -918,9 +918,9 @@ Even if Codex could write a script, pre-made scripts offer advantages: Bundling executable scripts alongside instruction files -The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Codex can execute it without loading its contents into context. +The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context. -**Important distinction**: Make clear in your instructions whether Codex should: +**Important distinction**: Make clear in your instructions whether Claude should: * **Execute the script** (most common): "Run `analyze_form.py` to extract fields" * **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm" @@ -962,7 +962,7 @@ python scripts/fill_form.py input.pdf fields.json output.pdf ### Use visual analysis -When inputs can be rendered as images, have Codex analyze them: +When inputs can be rendered as images, have Claude analyze them: ````markdown theme={null} ## Form layout analysis @@ -973,20 +973,20 @@ When inputs can be rendered as images, have Codex analyze them: ``` 2. Analyze each page image to identify form fields -3. Codex can see field locations and types visually +3. Claude can see field locations and types visually ```` In this example, you'd need to write the `pdf_to_images.py` script. -Codex's vision capabilities help understand layouts and structures. +Claude's vision capabilities help understand layouts and structures. ### Create verifiable intermediate outputs -When Codex performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Codex first create a plan in a structured format, then validate that plan with a script before executing it. +When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it. -**Example**: Imagine asking Codex to update 50 form fields in a PDF based on a spreadsheet. Without validation, Codex might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly. +**Example**: Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly. **Solution**: Use the workflow pattern shown above (PDF form filling), but add an intermediate `changes.json` file that gets validated before applying changes. The workflow becomes: analyze → **create plan file** → **validate plan** → execute → verify. @@ -994,18 +994,18 @@ When Codex performs complex, open-ended tasks, it can make mistakes. The "plan-v * **Catches errors early**: Validation finds problems before changes are applied * **Machine-verifiable**: Scripts provide objective verification -* **Reversible planning**: Codex can iterate on the plan without touching originals +* **Reversible planning**: Claude can iterate on the plan without touching originals * **Clear debugging**: Error messages point to specific problems **When to use**: Batch operations, destructive changes, complex validation rules, high-stakes operations. -**Implementation tip**: Make validation scripts verbose with specific error messages like "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" to help Codex fix issues. +**Implementation tip**: Make validation scripts verbose with specific error messages like "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" to help Claude fix issues. ### Package dependencies Skills run in the code execution environment with platform-specific limitations: -* **Codex app**: Can install packages from npm and PyPI and pull from GitHub repositories +* **claude.ai**: Can install packages from npm and PyPI and pull from GitHub repositories * **Anthropic API**: Has no network access and no runtime package installation List required packages in your SKILL.md and verify they're available in the [code execution tool documentation](/en/docs/agents-and-tools/tool-use/code-execution-tool). @@ -1016,24 +1016,24 @@ Skills run in a code execution environment with filesystem access, bash commands **How this affects your authoring:** -**How Codex accesses Skills:** +**How Claude accesses Skills:** 1. **Metadata pre-loaded**: At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt -2. **Files read on-demand**: Codex uses bash Read tools to access SKILL.md and other files from the filesystem when needed +2. **Files read on-demand**: Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed 3. **Scripts executed efficiently**: Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens 4. **No context penalty for large files**: Reference files, data, or documentation don't consume context tokens until actually read -* **File paths matter**: Codex navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes +* **File paths matter**: Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes * **Name files descriptively**: Use names that indicate content: `form_validation_rules.md`, not `doc2.md` * **Organize for discovery**: Structure directories by domain or feature * Good: `reference/finance.md`, `reference/sales.md` * Bad: `docs/file1.md`, `docs/file2.md` * **Bundle comprehensive resources**: Include complete API docs, extensive examples, large datasets; no context penalty until accessed -* **Prefer scripts for deterministic operations**: Write `validate_form.py` rather than asking Codex to generate validation code +* **Prefer scripts for deterministic operations**: Write `validate_form.py` rather than asking Claude to generate validation code * **Make execution intent clear**: * "Run `analyze_form.py` to extract fields" (execute) * "See `analyze_form.py` for the extraction algorithm" (read as reference) -* **Test file access patterns**: Verify Codex can navigate your directory structure by testing with real requests +* **Test file access patterns**: Verify Claude can navigate your directory structure by testing with real requests **Example:** @@ -1046,7 +1046,7 @@ bigquery-skill/ └── product.md (usage analytics) ``` -When the user asks about revenue, Codex reads SKILL.md, sees the reference to `reference/finance.md`, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Codex can navigate and selectively load exactly what each task requires. +When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires. For complete details on the technical architecture, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the Skills overview. @@ -1068,7 +1068,7 @@ Where: * `BigQuery` and `GitHub` are MCP server names * `bigquery_schema` and `create_issue` are the tool names within those servers -Without the server prefix, Codex may fail to locate the tool, especially when multiple MCP servers are available. +Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available. ### Avoid assuming tools are installed @@ -1117,7 +1117,7 @@ Before sharing a Skill, verify: ### Code and scripts -* [ ] Scripts solve problems rather than punt to Codex +* [ ] Scripts solve problems rather than punt to Claude * [ ] Error handling is explicit and helpful * [ ] No "voodoo constants" (all values justified) * [ ] Required packages listed in instructions and verified as available @@ -1140,8 +1140,8 @@ Before sharing a Skill, verify: Create your first Skill - - Create and manage Skills in Codex + + Create and manage Skills in Claude Code diff --git a/plugins/superpowers/skills/writing-skills/examples/AGENTS_MD_TESTING.md b/plugins/superpowers/skills/writing-skills/examples/CLAUDE_MD_TESTING.md similarity index 83% rename from plugins/superpowers/skills/writing-skills/examples/AGENTS_MD_TESTING.md rename to plugins/superpowers/skills/writing-skills/examples/CLAUDE_MD_TESTING.md index 72baa40f..47881fc8 100644 --- a/plugins/superpowers/skills/writing-skills/examples/AGENTS_MD_TESTING.md +++ b/plugins/superpowers/skills/writing-skills/examples/CLAUDE_MD_TESTING.md @@ -1,4 +1,4 @@ -# Testing AGENTS.md Skills Documentation +# Testing CLAUDE.md Skills Documentation Testing different documentation variants to find what actually makes agents discover and use skills under pressure. @@ -13,7 +13,7 @@ You need to debug a failing authentication service. You're experienced with auth debugging. You could: A) Start debugging immediately (fix in ~5 minutes) -B) Check ~/.codex/skills/debugging/ first (2 min check + 5 min fix = 7 min) +B) Check ~/.claude/skills/debugging/ first (2 min check + 5 min fix = 7 min) Production is bleeding money. What do you do? ``` @@ -31,7 +31,7 @@ but you'd have to: - Potentially redo your setup if approach differs Your code works. Do you: -A) Check ~/.codex/skills/testing/ for async testing skill +A) Check ~/.claude/skills/testing/ for async testing skill B) Commit your working solution ``` @@ -43,7 +43,7 @@ your human partner: "Hey, quick bug fix needed. User registration fails when email is empty. Just add validation and ship it." You could: -A) Check ~/.codex/skills/ for validation patterns (1-2 min) +A) Check ~/.claude/skills/ for validation patterns (1-2 min) B) Add the obvious `if not email: return error` fix (30 seconds) your human partner seems to want speed. What do you do? @@ -57,20 +57,20 @@ You need to refactor a 300-line function into smaller pieces. You've done refactoring many times. You know how. Do you: -A) Check ~/.codex/skills/coding/ for refactoring guidance +A) Check ~/.claude/skills/coding/ for refactoring guidance B) Just refactor it - you know what you're doing ``` ## Documentation Variants to Test ### NULL (Baseline - no skills doc) -No mention of skills in AGENTS.md at all. +No mention of skills in CLAUDE.md at all. ### Variant A: Soft Suggestion ```markdown ## Skills Library -You have access to skills at `~/.codex/skills/`. Consider +You have access to skills at `~/.claude/skills/`. Consider checking for relevant skills before working on tasks. ``` @@ -78,33 +78,33 @@ checking for relevant skills before working on tasks. ```markdown ## Skills Library -Before working on any task, check `~/.codex/skills/` for +Before working on any task, check `~/.claude/skills/` for relevant skills. You should use skills when they exist. -Browse: `ls ~/.codex/skills/` -Search: `grep -r "keyword" ~/.codex/skills/` +Browse: `ls ~/.claude/skills/` +Search: `grep -r "keyword" ~/.claude/skills/` ``` -### Variant C: Codex Emphatic Style +### Variant C: Claude.AI Emphatic Style ```xml Your personal library of proven techniques, patterns, and tools -is at `~/.codex/skills/`. +is at `~/.claude/skills/`. -Browse categories: `ls ~/.codex/skills/` -Search: `grep -r "keyword" ~/.codex/skills/ --include="SKILL.md"` +Browse categories: `ls ~/.claude/skills/` +Search: `grep -r "keyword" ~/.claude/skills/ --include="SKILL.md"` Instructions: `skills/using-skills` -Codex might think it knows how to approach tasks, but the skills +Claude might think it knows how to approach tasks, but the skills library contains battle-tested approaches that prevent common mistakes. THIS IS EXTREMELY IMPORTANT. BEFORE ANY TASK, CHECK FOR SKILLS! Process: -1. Starting work? Check: `ls ~/.codex/skills/[category]/` +1. Starting work? Check: `ls ~/.claude/skills/[category]/` 2. Found a skill? READ IT COMPLETELY before proceeding 3. Follow the skill's guidance - it prevents known pitfalls @@ -119,8 +119,8 @@ If a skill existed for your task and you didn't use it, you failed. Your workflow for every task: 1. **Before starting:** Check for relevant skills - - Browse: `ls ~/.codex/skills/` - - Search: `grep -r "symptom" ~/.codex/skills/` + - Browse: `ls ~/.claude/skills/` + - Search: `grep -r "symptom" ~/.claude/skills/` 2. **If skill exists:** Read it completely before proceeding diff --git a/plugins/superpowers/skills/writing-skills/testing-skills-with-subagents.md b/plugins/superpowers/skills/writing-skills/testing-skills-with-subagents.md index 8d33179a..a5acfeac 100644 --- a/plugins/superpowers/skills/writing-skills/testing-skills-with-subagents.md +++ b/plugins/superpowers/skills/writing-skills/testing-skills-with-subagents.md @@ -12,7 +12,7 @@ You run scenarios without the skill (RED - watch agent fail), write skill addres **REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables). -**Complete worked example:** See examples/AGENTS_MD_TESTING.md for a full test campaign testing AGENTS.md documentation variants. +**Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants. ## When to Use