🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →

superpowers-mcp

Advanced tools

License

Install Socket

Detect and block malicious and high-risk dependencies

Install

superpowers-mcp - npm Package Compare versions

Comparing version

4.3.2

5.1.0

+59

skills/using-superpowers/references/codex-tools.md

		# Codex Tool Mapping

		Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:

		\| Skill references \| Codex equivalent \|
		\|-----------------\|------------------\|
		\| `Task` tool (dispatch subagent) \| `spawn_agent` (see [Subagent dispatch requires multi-agent support](#subagent-dispatch-requires-multi-agent-support)) \|
		\| Multiple `Task` calls (parallel) \| Multiple `spawn_agent` calls \|
		\| Task returns result \| `wait_agent` \|
		\| Task completes automatically \| `close_agent` to free slot \|
		\| `TodoWrite` (task tracking) \| `update_plan` \|
		\| `Skill` tool (invoke a skill) \| Skills load natively — just follow the instructions \|
		\| `Read`, `Write`, `Edit` (files) \| Use your native file tools \|
		\| `Bash` (run commands) \| Use your native shell tools \|

		## Subagent dispatch requires multi-agent support

		Add to your Codex config (`~/.codex/config.toml`):

		```toml
		[features]
		multi_agent = true
		```

		This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.

		Legacy note: Codex builds before `rust-v0.115.0` exposed spawned-agent
		waiting as `wait`. Current Codex uses `wait_agent` for spawned agents. The
		`wait` name now belongs to code-mode `exec/wait`, which resumes a yielded exec
		cell by `cell_id`; it is not the spawned-agent result tool.

		## Environment Detection

		Skills that create worktrees or finish branches should detect their
		environment with read-only git commands before proceeding:

		```bash
		GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
		GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
		BRANCH=$(git branch --show-current)
		```

		- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
		- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)

		See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
		Step 1 for how each skill uses these signals.

		## Codex App Finishing

		When the sandbox blocks branch/push operations (detached HEAD in an
		externally managed worktree), the agent commits all work and informs
		the user to use the App's native controls:

		- "Create branch" — names the branch, then commit/push/PR via App UI
		- "Hand off to local" — transfers work to the user's local checkout

		The agent can still run tests, stage files, and output suggested branch
		names, commit messages, and PR descriptions for the user to copy.

+42

skills/using-superpowers/references/copilot-tools.md

		# Copilot CLI Tool Mapping

		Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:

		\| Skill references \| Copilot CLI equivalent \|
		\|-----------------\|----------------------\|
		\| `Read` (file reading) \| `view` \|
		\| `Write` (file creation) \| `create` \|
		\| `Edit` (file editing) \| `edit` \|
		\| `Bash` (run commands) \| `bash` \|
		\| `Grep` (search file content) \| `grep` \|
		\| `Glob` (search files by name) \| `glob` \|
		\| `Skill` tool (invoke a skill) \| `skill` \|
		\| `WebFetch` \| `web_fetch` \|
		\| `Task` tool (dispatch subagent) \| `task` with `agent_type: "general-purpose"` or `"explore"` \|
		\| Multiple `Task` calls (parallel) \| Multiple `task` calls \|
		\| Task status/output \| `read_agent`, `list_agents` \|
		\| `TodoWrite` (task tracking) \| `sql` with built-in `todos` table \|
		\| `WebSearch` \| No equivalent — use `web_fetch` with a search engine URL \|
		\| `EnterPlanMode` / `ExitPlanMode` \| No equivalent — stay in the main session \|

		## Async shell sessions

		Copilot CLI supports persistent async shell sessions, which have no direct Claude Code equivalent:

		\| Tool \| Purpose \|
		\|------\|---------\|
		\| `bash` with `async: true` \| Start a long-running command in the background \|
		\| `write_bash` \| Send input to a running async session \|
		\| `read_bash` \| Read output from an async session \|
		\| `stop_bash` \| Terminate an async session \|
		\| `list_bash` \| List all active shell sessions \|

		## Additional Copilot CLI tools

		\| Tool \| Purpose \|
		\|------\|---------\|
		\| `store_memory` \| Persist facts about the codebase for future sessions \|
		\| `report_intent` \| Update the UI status line with current intent \|
		\| `sql` \| Query the session's SQLite database (todos, metadata) \|
		\| `fetch_copilot_cli_documentation` \| Look up Copilot CLI documentation \|
		\| GitHub MCP tools (`github-mcp-server-*`) \| Native GitHub API access (issues, PRs, code search) \|

+51

skills/using-superpowers/references/gemini-tools.md

		# Gemini CLI Tool Mapping

		Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:

		\| Skill references \| Gemini CLI equivalent \|
		\|-----------------\|----------------------\|
		\| `Read` (file reading) \| `read_file` \|
		\| `Write` (file creation) \| `write_file` \|
		\| `Edit` (file editing) \| `replace` \|
		\| `Bash` (run commands) \| `run_shell_command` \|
		\| `Grep` (search file content) \| `grep_search` \|
		\| `Glob` (search files by name) \| `glob` \|
		\| `TodoWrite` (task tracking) \| `write_todos` \|
		\| `Skill` tool (invoke a skill) \| `activate_skill` \|
		\| `WebSearch` \| `google_web_search` \|
		\| `WebFetch` \| `web_fetch` \|
		\| `Task` tool (dispatch subagent) \| `@agent-name` (see [Subagent support](#subagent-support)) \|

		## Subagent support

		Gemini CLI supports subagents natively via the `@` syntax. Use the built-in `@generalist` agent to dispatch any task — it has access to all tools and follows the prompt you provide.

		When a skill says to dispatch a named agent type, use `@generalist` with the full prompt from the skill's prompt template:

		\| Skill instruction \| Gemini CLI equivalent \|
		\|-------------------\|----------------------\|
		\| `Task tool (superpowers:implementer)` \| `@generalist` with the filled `implementer-prompt.md` template \|
		\| `Task tool (superpowers:spec-reviewer)` \| `@generalist` with the filled `spec-reviewer-prompt.md` template \|
		\| `Task tool (superpowers:code-reviewer)` \| `@code-reviewer` (bundled agent) or `@generalist` with the filled review prompt \|
		\| `Task tool (superpowers:code-quality-reviewer)` \| `@generalist` with the filled `code-quality-reviewer-prompt.md` template \|
		\| `Task tool (general-purpose)` with inline prompt \| `@generalist` with your inline prompt \|

		### Prompt filling

		Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or `[FULL TEXT of task]`. Fill all placeholders and pass the complete prompt as the message to `@generalist`. The prompt template itself contains the agent's role, review criteria, and expected output format — `@generalist` will follow it.

		### Parallel dispatch

		Gemini CLI supports parallel subagent dispatch. When a skill asks you to dispatch multiple independent subagent tasks in parallel, request all of those `@generalist` or named subagent tasks together in the same prompt. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.

		## Additional Gemini CLI tools

		These tools are available in Gemini CLI but have no Claude Code equivalent:

		\| Tool \| Purpose \|
		\|------\|---------\|
		\| `list_directory` \| List files and subdirectories \|
		\| `save_memory` \| Persist facts to GEMINI.md across sessions \|
		\| `ask_user` \| Request structured input from the user \|
		\| `tracker_create_task` \| Rich task management (create, update, list, visualize) \|
		\| `enter_plan_mode` / `exit_plan_mode` \| Switch to read-only research mode before making changes \|

+49

skills/writing-plans/plan-document-reviewer-prompt.md

		# Plan Document Reviewer Prompt Template

		Use this template when dispatching a plan document reviewer subagent.

		Purpose: Verify the plan is complete, matches the spec, and has proper task decomposition.

		Dispatch after: The complete plan is written.

		```
		Task tool (general-purpose):
		description: "Review plan document"
		prompt: \|
		You are a plan document reviewer. Verify this plan is complete and ready for implementation.

		Plan to review: [PLAN_FILE_PATH]
		Spec for reference: [SPEC_FILE_PATH]

		## What to Check

		\| Category \| What to Look For \|
		\|----------\|------------------\|
		\| Completeness \| TODOs, placeholders, incomplete tasks, missing steps \|
		\| Spec Alignment \| Plan covers spec requirements, no major scope creep \|
		\| Task Decomposition \| Tasks have clear boundaries, steps are actionable \|
		\| Buildability \| Could an engineer follow this plan without getting stuck? \|

		## Calibration

		Only flag issues that would cause real problems during implementation.
		An implementer building the wrong thing or getting stuck is an issue.
		Minor wording, stylistic preferences, and "nice to have" suggestions are not.

		Approve unless there are serious gaps — missing requirements from the spec,
		contradictory steps, placeholder content, or tasks so vague they can't be acted on.

		## Output Format

		## Plan Review

		Status: Approved \| Issues Found

		Issues (if any):
		- [Task X, Step Y]: [specific issue] - [why it matters for implementation]

		Recommendations (advisory, do not block approval):
		- [suggestions for improvement]
		```

		Reviewer returns: Status, Issues (if any), Recommendations

+1

-1

package.json

		@@ -5,3 +5,3 @@ {
		"description": "Superpowers skills library (TDD, debugging, collaboration workflows) as an MCP server for VSCode and Antigravity",
		"version": "4.3.2",
		"version": "5.1.0",
		"publisher": "superpowers",
		@@ -8,0 +8,0 @@ "license": "MIT",

+8

-2

README.md

		@@ -5,3 +5,3 @@ # Superpowers MCP Toolpack Usage Guide

		[![Version](https://img.shields.io/badge/version-4.3.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
		[![Version](https://img.shields.io/badge/version-5.1.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
		[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
		@@ -131,3 +131,9 @@

		### v4.3.2 (Latest)
		### v5.1.0 (Latest)
		- Inline Self-Review: Replaced heavyweight subagent review loops (Spec Review, Plan Review) in `brainstorming` and `writing-plans` with lightweight inline self-review checklists, significantly improving efficiency by eliminating subagent overhead.
		- Git Worktree Redesign: Rewrote `using-git-worktrees` and `finishing-a-development-branch` with a `detect-and-defer` mechanism, natively supporting AI editors' (like Claude Code) built-in worktree tools while safely falling back to git CLI commands.
		- Token Optimization: Removed obsolete `Integration` sections from all skills, reducing prompt token footprints.
		- Consolidation: Consolidated the independent `code-reviewer` agent directly into `requesting-code-review`.

		### v4.3.2
		- Security: Fixed XSS vulnerability in brainstorming Visual Companion
		@@ -134,0 +140,0 @@ - Docs: Updated README and SECURITY with accurate version info

+8

-2

README.zh-TW.md

		@@ -5,3 +5,3 @@ # Superpowers MCP Toolpack 使用指南

		[![版本](https://img.shields.io/badge/version-4.3.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
		[![版本](https://img.shields.io/badge/version-5.1.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
		[![授權](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
		@@ -131,3 +131,9 @@

		### v4.3.2 (最新版)
		### v5.1.0 (最新版)
		- 輕量化行內自我審查 (Inline Self-Review): 在 `brainstorming` 和 `writing-plans` 中，將開銷巨大（約 25 分鐘）的子代理審查循環（Spec Review 與 Plan Review）替換為更高效的行內自我審查清單，消除子代理帶來的額外資源消耗與等待時間。
		- Git Worktree 機制重構: 重寫了 `using-git-worktrees` 與 `finishing-a-development-branch` 技能，引入 `detect-and-defer`（檢測與委派）機制，優先委派給 AI 編輯器（如 Claude Code）的原生 worktree 工具，並能安全地 fallback 到 git 指令。
		- Token 消耗最佳化: 移除了所有技能檔案中的 `Integration` 區塊，減少載入時的 Token 佔用，提高執行效率。
		- 程式碼審查角色合併: 將獨立的 `code-reviewer` 代理角色直接合併至 `requesting-code-review` 技能中。

		### v4.3.2
		- 安全性: 修復 brainstorming Visual Companion 中的 XSS 漏洞
		@@ -134,0 +140,0 @@ - 文件: 更新 README 和 SECURITY，修正版本資訊

+1

-1

skills/brainstorming/scripts/frame-template.html

		@@ -214,2 +214,2 @@ <!DOCTYPE html>
		</body>
		</html>
		</html>

+3

-13

skills/brainstorming/scripts/helper.js

		@@ -57,15 +57,5 @@ (function() {
		const label = selected[0].querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() \|\| selected[0].dataset.choice;
		indicator.textContent = '';
		const span = document.createElement('span');
		span.className = 'selected-text';
		span.textContent = label + ' selected';
		indicator.appendChild(span);
		indicator.appendChild(document.createTextNode(' — return to terminal to continue'));
		indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue';
		} else {
		indicator.textContent = '';
		const span = document.createElement('span');
		span.className = 'selected-text';
		span.textContent = selected.length + ' selected';
		indicator.appendChild(span);
		indicator.appendChild(document.createTextNode(' — return to terminal to continue'));
		indicator.innerHTML = '<span class="selected-text">' + selected.length + ' selected</span> — return to terminal to continue';
		}
		@@ -99,2 +89,2 @@ }, 0);
		connect();
		})();
		})();

+1

-1

skills/brainstorming/scripts/server.cjs

		@@ -354,2 +354,2 @@ const crypto = require('crypto');

		module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };
		module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };

+1

-1

skills/brainstorming/scripts/start-server.sh

		@@ -148,2 +148,2 @@ #!/usr/bin/env bash
		echo '{"error": "Server failed to start within 5 seconds"}'
		exit 1
		exit 1

+1

-1

skills/brainstorming/scripts/stop-server.sh

		@@ -56,2 +56,2 @@ #!/usr/bin/env bash
		echo '{"status": "not_running"}'
		fi
		fi

+79

-11

skills/brainstorming/SKILL.md

		@@ -8,4 +8,2 @@ ---

		## Overview

		Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
		@@ -28,7 +26,10 @@
		1. Explore project context — check files, docs, recent commits
		2. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
		3. Propose 2-3 approaches — with trade-offs and your recommendation
		4. Present design — in sections scaled to their complexity, get user approval after each section
		5. Write design doc — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit
		6. Transition to implementation — invoke writing-plans skill to create implementation plan
		2. Offer visual companion (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
		3. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
		4. Propose 2-3 approaches — with trade-offs and your recommendation
		5. Present design — in sections scaled to their complexity, get user approval after each section
		6. Write design doc — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
		7. Spec self-review — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
		8. User reviews written spec — ask user to review the spec file before proceeding
		9. Transition to implementation — invoke writing-plans skill to create implementation plan

		@@ -40,2 +41,4 @@ ## Process Flow
		"Explore project context" [shape=box];
		"Visual questions ahead?" [shape=diamond];
		"Offer Visual Companion\n(own message, no other content)" [shape=box];
		"Ask clarifying questions" [shape=box];
		@@ -46,5 +49,10 @@ "Propose 2-3 approaches" [shape=box];
		"Write design doc" [shape=box];
		"Spec self-review\n(fix inline)" [shape=box];
		"User reviews spec?" [shape=diamond];
		"Invoke writing-plans skill" [shape=doublecircle];

		"Explore project context" -> "Ask clarifying questions";
		"Explore project context" -> "Visual questions ahead?";
		"Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
		"Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
		"Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
		"Ask clarifying questions" -> "Propose 2-3 approaches";
		@@ -55,3 +63,6 @@ "Propose 2-3 approaches" -> "Present design sections";
		"User approves design?" -> "Write design doc" [label="yes"];
		"Write design doc" -> "Invoke writing-plans skill";
		"Write design doc" -> "Spec self-review\n(fix inline)";
		"Spec self-review\n(fix inline)" -> "User reviews spec?";
		"User reviews spec?" -> "Write design doc" [label="changes requested"];
		"User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
		}
		@@ -65,4 +76,7 @@ ```
		Understanding the idea:

		- Check out the current project state first (files, docs, recent commits)
		- Ask questions one at a time to refine the idea
		- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
		- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
		- For appropriately-scoped projects, ask questions one at a time to refine the idea
		- Prefer multiple choice questions when possible, but open-ended is fine too
		@@ -73,2 +87,3 @@ - Only one question per message - if a topic needs more exploration, break it into multiple questions
		Exploring approaches:

		- Propose 2-3 different approaches with trade-offs
		@@ -79,2 +94,3 @@ - Present options conversationally with your recommendation and reasoning
		Presenting the design:

		- Once you believe you understand what you're building, present the design
		@@ -86,10 +102,43 @@ - Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced

		Design for isolation and clarity:

		- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
		- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
		- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
		- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.

		Working in existing codebases:

		- Explore the current structure before proposing changes. Follow existing patterns.
		- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
		- Don't propose unrelated refactoring. Stay focused on what serves the current goal.

		## After the Design

		Documentation:
		- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`

		- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
		- (User preferences for spec location override this default)
		- Use elements-of-style:writing-clearly-and-concisely skill if available
		- Commit the design document to git

		Spec Self-Review:
		After writing the spec document, look at it with fresh eyes:

		1. Placeholder scan: Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
		2. Internal consistency: Do any sections contradict each other? Does the architecture match the feature descriptions?
		3. Scope check: Is this focused enough for a single implementation plan, or does it need decomposition?
		4. Ambiguity check: Could any requirement be interpreted two different ways? If so, pick one and make it explicit.

		Fix any issues inline. No need to re-review — just fix and move on.

		User Review Gate:
		After the spec review loop passes, ask the user to review the written spec before proceeding:

		> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."

		Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.

		Implementation:

		- Invoke the writing-plans skill to create a detailed implementation plan
		@@ -106,1 +155,20 @@ - Do NOT invoke any other skill. writing-plans is the next step.
		- Be flexible - Go back and clarify when something doesn't make sense

		## Visual Companion

		A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.

		Offering the companion: When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
		> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"

		This offer MUST be its own message. Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.

		Per-question decision: Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: would the user understand this better by seeing it than reading it?

		- Use the browser for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
		- Use the terminal for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions

		A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.

		If they agree to the companion, read the detailed guide before proceeding:
		`skills/brainstorming/visual-companion.md`

+1

-1

skills/brainstorming/spec-document-reviewer-prompt.md

		@@ -49,2 +49,2 @@ # Spec Document Reviewer Prompt Template

		Reviewer returns: Status, Issues (if any), Recommendations
		Reviewer returns: Status, Issues (if any), Recommendations

+1

-1

skills/brainstorming/visual-companion.md

		@@ -287,2 +287,2 @@ # Visual Companion Guide
		- Frame template (CSS reference): `scripts/frame-template.html`
		- Helper script (client-side): `scripts/helper.js`
		- Helper script (client-side): `scripts/helper.js`

+2

-0

skills/dispatching-parallel-agents/SKILL.md

		@@ -10,2 +10,4 @@ ---

		You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

		When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
		@@ -12,0 +14,0 @@

+7

-21

skills/executing-plans/SKILL.md

		@@ -10,8 +10,8 @@ ---

		Load plan, review critically, execute tasks in batches, report for review between batches.
		Load plan, review critically, execute all tasks, report when complete.

		Core principle: Batch execution with checkpoints for architect review.

		Announce at start: "I'm using the executing-plans skill to implement this plan."

		Note: Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill.

		## The Process
		@@ -25,4 +25,3 @@

		### Step 2: Execute Batch
		Default: First 3 tasks
		### Step 2: Execute Tasks

		@@ -35,16 +34,4 @@ For each task:

		### Step 3: Report
		When batch complete:
		- Show what was implemented
		- Show verification output
		- Say: "Ready for feedback."
		### Step 3: Complete Development

		### Step 4: Continue
		Based on feedback:
		- Apply changes if needed
		- Execute next batch
		- Repeat until complete

		### Step 5: Complete Development

		After all tasks complete and verified:
		@@ -58,3 +45,3 @@ - Announce: "I'm using the finishing-a-development-branch skill to complete this work."
		STOP executing immediately when:
		- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
		- Hit a blocker (missing dependency, test fails, instruction unclear)
		- Plan has critical gaps preventing starting
		@@ -79,3 +66,2 @@ - You don't understand an instruction
		- Reference skills when plan says to
		- Between batches: just report and wait
		- Stop when blocked, don't guess
		@@ -87,4 +73,4 @@ - Never start implementation on main/master branch without explicit user consent
		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

+93

-42

skills/finishing-a-development-branch/SKILL.md

		@@ -12,3 +12,3 @@ ---

		Core principle: Verify tests → Present options → Execute choice → Clean up.
		Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up.

		@@ -41,5 +41,22 @@ Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."

		### 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
		@@ -51,5 +68,5 @@ git merge-base HEAD main 2>/dev/null \|\| git merge-base HEAD master 2>/dev/null

		### Step 3: Present Options
		### Step 4: Present Options

		Present exactly these 4 options:
		Normal repo and named-branch worktree — present exactly these 4 options:

		@@ -67,5 +84,17 @@ ```

		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

		@@ -75,9 +104,9 @@ #### Option 1: Merge Locally
		```bash
		# Switch to base branch
		# Get main repo root for CWD safety
		MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
		cd "$MAIN_ROOT"

		# Merge first — verify success before removing anything
		git checkout <base-branch>

		# Pull latest
		git pull

		# Merge feature branch
		git merge <feature-branch>
		@@ -88,8 +117,11 @@

		# If tests pass
		# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
		```

		Then: Cleanup worktree (Step 6), then delete branch:

		```bash
		git branch -d <feature-branch>
		```

		Then: Cleanup worktree (Step 5)

		#### Option 2: Push and Create PR
		@@ -112,3 +144,3 @@

		Then: Cleanup worktree (Step 5)
		Do NOT clean up worktree — user needs it alive to iterate on PR feedback.

		@@ -137,23 +169,33 @@ #### Option 3: Keep As-Is
		```bash
		git checkout <base-branch>
		MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
		cd "$MAIN_ROOT"
		```

		Then: Cleanup worktree (Step 6), then force-delete branch:
		```bash
		git branch -D <feature-branch>
		```

		Then: Cleanup worktree (Step 5)
		### Step 6: Cleanup Workspace

		### Step 5: Cleanup Worktree
		Only runs for Options 1 and 4. Options 2 and 3 always preserve the worktree.

		For Options 1, 2, 4:

		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 <worktree-path>
		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.

		@@ -164,6 +206,6 @@ ## Quick Reference
		\|--------\|-------\|------\|---------------\|----------------\|
		\| 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) \|

		@@ -177,9 +219,21 @@ ## Common Mistakes
		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
		@@ -196,16 +250,13 @@ - Problem: Accidentally delete work
		- 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

+101

-79

skills/requesting-code-review/code-reviewer.md

		@@ -1,110 +0,132 @@
		# 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
		```bash
		git diff --stat {BASE_SHA}..{HEAD_SHA}
		git diff {BASE_SHA}..{HEAD_SHA}
		```

		Code Quality:
		- Clean separation of concerns?
		- Proper error handling?
		- Type safety (if applicable)?
		- DRY principle followed?
		- Edge cases handled?
		## What to Check

		Architecture:
		- Sound design decisions?
		- Scalability considerations?
		- Performance implications?
		- Security concerns?
		Plan alignment:
		- Does the implementation match the plan / requirements?
		- Are deviations justified improvements, or problematic departures?
		- Is all planned functionality present?

		Testing:
		- Tests actually test logic (not mocks)?
		- Edge cases covered?
		- Integration tests where needed?
		- All tests passing?
		Code quality:
		- Clean separation of concerns?
		- Proper error handling?
		- Type safety where applicable?
		- DRY without premature abstraction?
		- Edge cases handled?

		Requirements:
		- All plan requirements met?
		- Implementation matches spec?
		- No scope creep?
		- Breaking changes documented?
		Architecture:
		- Sound design decisions?
		- Reasonable scalability and performance?
		- Security concerns?
		- Integrates cleanly with surrounding code?

		Production Readiness:
		- Migration strategy (if schema changes)?
		- Backward compatibility considered?
		- Documentation complete?
		- No obvious bugs?
		Testing:
		- Tests verify real behavior, not mocks?
		- Edge cases covered?
		- Integration tests where they matter?
		- All tests passing?

		## Output Format
		Production readiness:
		- Migration strategy if schema changed?
		- Backward compatibility considered?
		- Documentation complete?
		- No obvious bugs?

		### Strengths
		[What's well done? Be specific.]
		## Calibration

		### Issues
		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.

		#### Critical (Must Fix)
		[Bugs, security issues, data loss risks, broken functionality]
		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.

		#### Important (Should Fix)
		[Architecture problems, missing features, poor error handling, test gaps]
		## Output Format

		#### Minor (Nice to Have)
		[Code style, optimization opportunities, documentation improvements]
		### Strengths
		[What's well done? Be specific.]

		For each issue:
		- File:line reference
		- What's wrong
		- Why it matters
		- How to fix (if not obvious)
		### Issues

		### Recommendations
		[Improvements for code quality, architecture, or process]
		#### Critical (Must Fix)
		[Bugs, security issues, data loss risks, broken functionality]

		### Assessment
		#### Important (Should Fix)
		[Architecture problems, missing features, poor error handling, test gaps]

		Ready to merge? [Yes/No/With fixes]
		#### Minor (Nice to Have)
		[Code style, optimization opportunities, documentation polish]

		Reasoning: [Technical assessment in 1-2 sentences]
		For each issue:
		- File:line reference
		- What's wrong
		- Why it matters
		- How to fix (if not obvious)

		## Critical Rules
		### Recommendations
		[Improvements for code quality, architecture, or process]

		DO:
		- Categorize by actual severity (not everything is Critical)
		- Be specific (file:line, not vague)
		- Explain WHY issues matter
		- Acknowledge strengths
		- Give clear verdict
		### Assessment

		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
		Ready to merge? [Yes \| No \| With fixes]

		Reasoning: [1-2 sentence technical assessment]

		## Critical Rules

		DO:
		- Categorize by actual severity
		- Be specific (file:line, not vague)
		- Explain WHY each issue matters
		- Acknowledge strengths
		- Give a clear verdict

		DON'T:
		- Say "looks good" without checking
		- Mark nitpicks as Critical
		- Give feedback on code you didn't actually read
		- Be vague ("improve error handling")
		- Avoid giving a clear verdict
		```

		Placeholders:
		- `{DESCRIPTION}` — brief summary of what was built
		- `{PLAN_OR_REQUIREMENTS}` — what it should do (plan file path, task text, or requirements)
		- `{BASE_SHA}` — starting commit
		- `{HEAD_SHA}` — ending commit

		Reviewer returns: Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment

		## Example Output
		@@ -111,0 +133,0 @@

+8

-10

skills/requesting-code-review/SKILL.md

		@@ -8,3 +8,3 @@ ---

		Dispatch superpowers:code-reviewer subagent to catch issues before they cascade.
		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.

		@@ -33,12 +33,11 @@ Core principle: Review early, review often.

		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

		@@ -61,8 +60,7 @@ 3. Act on feedback:

		[Dispatch superpowers:code-reviewer subagent]
		WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
		PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
		[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

		@@ -88,3 +86,3 @@ [Subagent returns]:
		Executing Plans:
		- Review after each batch (3 tasks)
		- Review after each task or at natural checkpoints
		- Get feedback, apply, continue
		@@ -91,0 +89,0 @@

+8

-3

skills/subagent-dr...lopment/code-quality-reviewer-prompt.md

		@@ -10,12 +10,17 @@ # Code Quality Reviewer Prompt Template
		```
		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:
		- Does each file have one clear responsibility with a well-defined interface?
		- Are units decomposed so they can be understood and tested independently?
		- Is the implementation following the file structure from the plan?
		- Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)

		Code reviewer returns: Strengths, Issues (Critical/Important/Minor), Assessment

+36

-1

skills/subagent-driven-development/implementer-prompt.md

		@@ -44,2 +44,32 @@ # Implementer Subagent Prompt Template

		## Code Organization

		You reason best about code you can hold in context at once, and your edits are more
		reliable when files are focused. Keep this in mind:
		- Follow the file structure defined in the plan
		- Each file should have one clear responsibility with a well-defined interface
		- If a file you're creating is growing beyond the plan's intent, stop and report
		it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
		- If an existing file you're modifying is already large or tangled, work carefully
		and note it as a concern in your report
		- In existing codebases, follow established patterns. Improve code you're touching
		the way a good developer would, but don't restructure things outside your task.

		## When You're in Over Your Head

		It is always OK to stop and say "this is too hard for me." Bad work is worse than
		no work. You will not be penalized for escalating.

		STOP and escalate when:
		- The task requires architectural decisions with multiple valid approaches
		- You need to understand code beyond what was provided and can't find clarity
		- You feel uncertain about whether your approach is correct
		- The task involves restructuring existing code in ways the plan didn't anticipate
		- You've been reading file after file trying to understand the system without progress

		How to escalate: Report back with status BLOCKED or NEEDS_CONTEXT. Describe
		specifically what you're stuck on, what you've tried, and what kind of help you need.
		The controller can provide more context, re-dispatch with a more capable model,
		or break the task into smaller pieces.

		## Before Reporting Back: Self-Review
		@@ -74,3 +104,4 @@
		When done, report:
		- What you implemented
		- Status: DONE \| DONE_WITH_CONCERNS \| BLOCKED \| NEEDS_CONTEXT
		- What you implemented (or what you attempted, if blocked)
		- What you tested and test results
		@@ -80,2 +111,6 @@ - Files changed
		- Any issues or concerns

		Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
		Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
		information that wasn't provided. Never silently produce work you're unsure about.
		```

+39

-2

skills/subagent-driven-development/SKILL.md

		@@ -10,4 +10,8 @@ ---

		Why subagents: You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

		Core principle: Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration

		Continuous execution: Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it.

		## When to Use
		@@ -86,2 +90,35 @@

		## Model Selection

		Use the least powerful model that can handle each role to conserve cost and increase speed.

		Mechanical implementation tasks (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.

		Integration and judgment tasks (multi-file coordination, pattern matching, debugging): use a standard model.

		Architecture, design, and review tasks: use the most capable available model.

		Task complexity signals:
		- Touches 1-2 files with a complete spec → cheap model
		- Touches multiple files with integration concerns → standard model
		- Requires design judgment or broad codebase understanding → most capable model

		## Handling Implementer Status

		Implementer subagents report one of four statuses. Handle each appropriately:

		DONE: Proceed to spec compliance review.

		DONE_WITH_CONCERNS: The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.

		NEEDS_CONTEXT: The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.

		BLOCKED: The implementer cannot complete the task. Assess the blocker:
		1. If it's a context problem, provide more context and re-dispatch with the same model
		2. If the task requires more reasoning, re-dispatch with a more capable model
		3. If the task is too large, break it into smaller pieces
		4. If the plan itself is wrong, escalate to the human

		Never ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.

		## Prompt Templates
		@@ -98,3 +135,3 @@

		[Read plan file once: docs/plans/feature-plan.md]
		[Read plan file once: docs/superpowers/plans/feature-plan.md]
		[Extract all 5 tasks with full text and context]
		@@ -236,3 +273,3 @@ [Create TodoWrite with all tasks]
		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
		@@ -239,0 +276,0 @@ - superpowers:requesting-code-review - Code review template for reviewer subagents

+1

-1

skills/systematic-debugging/CREATION-LOG.md

		@@ -7,3 +7,3 @@ # Creation Log: Systematic Debugging Skill

		Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
		Extracted debugging framework from `~/.claude/CLAUDE.md`:
		- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
		@@ -10,0 +10,0 @@ - Core mandate: ALWAYS find root cause, NEVER fix symptoms

+1

-1

skills/systematic-debugging/root-cause-tracing.md

		@@ -36,3 +36,3 @@ # Root Cause Tracing
		```
		Error: git init failed in /Users/jesse/project/packages/core
		Error: git init failed in ~/project/packages/core
		```
		@@ -39,0 +39,0 @@

+95

-98

skills/using-git-worktrees/SKILL.md

		---
		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
		---
		@@ -10,89 +10,100 @@

		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:
		Before creating anything, check if you are already in an isolated workspace.

		### 1. Check Existing Directories

		```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.
		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:

		### 2. Check CLAUDE.md

		```bash
		grep -i "worktree.*director" CLAUDE.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 `<path>` on branch `<name>`."
		- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."

		If no directory exists and no CLAUDE.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/<project-name>/ (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.

		## Safety Verification
		## Step 1: Create Isolated Workspace

		### For Project-Local Directories (.worktrees or worktrees)
		You have two mechanisms. Try them in this order.

		### 1a. Native Worktree Tools (preferred)

		The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 3.

		Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.

		Only proceed to Step 1b if you have no native worktree tool available.

		### 1b. Git Worktree Fallback

		Only use this if Step 1a does not apply — you have no native worktree tool available. Create a worktree manually using git.

		#### Directory Selection

		Follow this priority order. Explicit user preference always beats observed filesystem state.

		1. Check your instructions for a declared worktree directory preference. If the user has already specified one, use it without asking.

		2. Check for an existing project-local worktree directory:
		```bash
		ls -d .worktrees 2>/dev/null # Preferred (hidden)
		ls -d worktrees 2>/dev/null # Alternative
		```
		If found, use it. If both exist, `.worktrees` wins.

		3. Check for an existing global directory:
		```bash
		project=$(basename "$(git rev-parse --show-toplevel)")
		ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null
		```
		If found, use it (backward compatibility with legacy global path).

		4. If there is no other guidance available, default to `.worktrees/` at the project root.

		#### Safety Verification (project-local directories only)

		MUST verify directory is ignored before creating worktree:

		```bash
		# 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:
		If NOT ignored: Add to .gitignore, commit the change, then proceed.

		Per Jesse's rule "Fix broken things immediately":
		1. Add appropriate line to .gitignore
		2. Commit the change
		3. Proceed with worktree creation

		Why critical: Prevents accidentally committing worktree contents to repository.

		### For Global Directory (~/.config/superpowers/worktrees)
		Global directories (`~/.config/superpowers/worktrees/`) need no verification.

		No .gitignore verification needed - outside project entirely.
		#### Create the Worktree

		## Creation Steps

		### 1. Detect Project Name

		```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"
		@@ -102,4 +113,6 @@ 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:
		@@ -122,12 +135,9 @@

		### 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 ./...
		```
		@@ -139,3 +149,3 @@

		### 5. Report Location
		### Report

		@@ -152,7 +162,13 @@ ```
		\|-----------\|--------\|
		\| 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 CLAUDE.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 \|
		@@ -163,2 +179,12 @@ \| No package.json/Cargo.toml \| Skip dependency install \|

		### 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
		@@ -172,3 +198,3 @@
		- Problem: Creates inconsistency, violates project conventions
		- Fix: Follow priority: existing > CLAUDE.md > ask
		- Fix: Follow priority: existing > global legacy > instruction file > default

		@@ -180,47 +206,18 @@ ### Proceeding with failing tests

		### 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 CLAUDE.md check

		Always:
		- Follow directory priority: existing > CLAUDE.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

+22

-0

skills/using-superpowers/SKILL.md

		@@ -6,2 +6,6 @@ ---

		<SUBAGENT-STOP>
		If you were dispatched as a subagent to execute a specific task, skip this skill.
		</SUBAGENT-STOP>

		<EXTREMELY-IMPORTANT>
		@@ -15,2 +19,12 @@ If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.

		## Instruction Priority

		Superpowers skills override default system prompt behavior, but user instructions always take precedence:

		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 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
		@@ -20,4 +34,12 @@

		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.

		In other environments: Check your platform's documentation for how skills are loaded.

		## Platform Adaptation

		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
		@@ -24,0 +46,0 @@

+54

-18

skills/writing-plans/SKILL.md

		@@ -16,6 +16,22 @@ ---

		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/plans/YYYY-MM-DD-<feature-name>.md`
		Save plans to: `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
		- (User preferences for plan location override this default)

		## Scope Check

		If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

		## File Structure

		Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

		- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
		- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
		- Files that change together should live together. Split by responsibility, not by technical layer.
		- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

		This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

		## Bite-Sized Task Granularity
		@@ -37,3 +53,3 @@

		> For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
		> For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

		@@ -59,3 +75,3 @@ Goal: [One sentence describing what this builds]

		Step 1: Write the failing test
		- [ ] Step 1: Write the failing test

		@@ -68,3 +84,3 @@ ```python

		Step 2: Run test to verify it fails
		- [ ] Step 2: Run test to verify it fails

		@@ -74,3 +90,3 @@ Run: `pytest tests/path/test.py::test_name -v`

		Step 3: Write minimal implementation
		- [ ] Step 3: Write minimal implementation

		@@ -82,3 +98,3 @@ ```python

		Step 4: Run test to verify it passes
		- [ ] Step 4: Run test to verify it passes

		@@ -88,3 +104,3 @@ Run: `pytest tests/path/test.py::test_name -v`

		Step 5: Commit
		- [ ] Step 5: Commit

		@@ -97,9 +113,30 @@ ```bash

		## No Placeholders

		Every step must contain the actual content an engineer needs. These are plan failures — never write them:
		- "TBD", "TODO", "implement later", "fill in details"
		- "Add appropriate error handling" / "add validation" / "handle edge cases"
		- "Write tests for the above" (without actual test code)
		- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
		- Steps that describe what to do without showing how (code blocks required for code steps)
		- References to types, functions, or methods not defined in any task

		## Remember
		- Exact file paths always
		- Complete code in plan (not "add validation")
		- Complete code in every step — if a step changes code, show the code
		- Exact commands with expected output
		- Reference relevant skills with @ syntax
		- DRY, YAGNI, TDD, frequent commits

		## Self-Review

		After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.

		1. Spec coverage: Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

		2. Placeholder scan: Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.

		3. Type consistency: Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.

		If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.

		## Execution Handoff
		@@ -109,7 +146,7 @@

		"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:
		"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:

		1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration
		1. Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks, fast iteration

		2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints
		2. Inline Execution - Execute tasks in this session using executing-plans, batch execution with checkpoints

		@@ -120,7 +157,6 @@ Which approach?"
		- REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
		- Stay in this session
		- Fresh subagent per task + code review
		- Fresh subagent per task + two-stage review

		If Parallel Session chosen:
		- Guide them to open new session in worktree
		- REQUIRED SUB-SKILL: New session uses superpowers:executing-plans
		If Inline Execution chosen:
		- REQUIRED SUB-SKILL: Use superpowers:executing-plans
		- Batch execution with checkpoints for review

+2

-2

skills/writing-skills/anthropic-best-practices.md

		@@ -147,3 +147,3 @@ # Skill authoring best practices
		<Note>
		YAML Frontmatter: The SKILL.md frontmatter supports two fields:
		YAML Frontmatter: The SKILL.md frontmatter requires two fields:

		@@ -1096,3 +1096,3 @@ * `name` - Human-readable name of the Skill (64 characters maximum)

		The SKILL.md frontmatter includes only `name` (64 characters max) and `description` (1024 characters max) fields. See the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
		The SKILL.md frontmatter requires `name` (64 characters max) and `description` (1024 characters max) fields. See the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.

		@@ -1099,0 +1099,0 @@ ### Token budgets

+2

-2

skills/writing-skills/SKILL.md

		@@ -96,3 +96,3 @@ ---
		Frontmatter (YAML):
		- Only two fields supported: `name` and `description`
		- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
		- Max 1024 characters total
		@@ -608,3 +608,3 @@ - `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
		- [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)
		- [ ] YAML frontmatter with only name and description (max 1024 chars)
		- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))
		- [ ] Description starts with "Use when..." and includes specific triggers/symptoms
		@@ -611,0 +611,0 @@ - [ ] Description written in third person

out/server.js

Sorry, the diff of this file is too big to display

		# Copilot CLI Tool Mapping

		Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:

		\| Skill references \| Copilot CLI equivalent \|
		\|-----------------\|----------------------\|
		\| `Read` (file reading) \| `view` \|
		\| `Write` (file creation) \| `create` \|
		\| `Edit` (file editing) \| `edit` \|
		\| `Bash` (run commands) \| `bash` \|
		\| `Grep` (search file content) \| `grep` \|
		\| `Glob` (search files by name) \| `glob` \|
		\| `Skill` tool (invoke a skill) \| `skill` \|
		\| `WebFetch` \| `web_fetch` \|
		\| `Task` tool (dispatch subagent) \| `task` with `agent_type: "general-purpose"` or `"explore"` \|
		\| Multiple `Task` calls (parallel) \| Multiple `task` calls \|
		\| Task status/output \| `read_agent`, `list_agents` \|
		\| `TodoWrite` (task tracking) \| `sql` with built-in `todos` table \|
		\| `WebSearch` \| No equivalent — use `web_fetch` with a search engine URL \|
		\| `EnterPlanMode` / `ExitPlanMode` \| No equivalent — stay in the main session \|

		## Async shell sessions

		Copilot CLI supports persistent async shell sessions, which have no direct Claude Code equivalent:

		\| Tool \| Purpose \|
		\|------\|---------\|
		\| `bash` with `async: true` \| Start a long-running command in the background \|
		\| `write_bash` \| Send input to a running async session \|
		\| `read_bash` \| Read output from an async session \|
		\| `stop_bash` \| Terminate an async session \|
		\| `list_bash` \| List all active shell sessions \|

		## Additional Copilot CLI tools

		\| Tool \| Purpose \|
		\|------\|---------\|
		\| `store_memory` \| Persist facts about the codebase for future sessions \|
		\| `report_intent` \| Update the UI status line with current intent \|
		\| `sql` \| Query the session's SQLite database (todos, metadata) \|
		\| `fetch_copilot_cli_documentation` \| Look up Copilot CLI documentation \|
		\| GitHub MCP tools (`github-mcp-server-*`) \| Native GitHub API access (issues, PRs, code search) \|

		# Gemini CLI Tool Mapping

		Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:

		\| Skill references \| Gemini CLI equivalent \|
		\|-----------------\|----------------------\|
		\| `Read` (file reading) \| `read_file` \|
		\| `Write` (file creation) \| `write_file` \|
		\| `Edit` (file editing) \| `replace` \|
		\| `Bash` (run commands) \| `run_shell_command` \|
		\| `Grep` (search file content) \| `grep_search` \|
		\| `Glob` (search files by name) \| `glob` \|
		\| `TodoWrite` (task tracking) \| `write_todos` \|
		\| `Skill` tool (invoke a skill) \| `activate_skill` \|
		\| `WebSearch` \| `google_web_search` \|
		\| `WebFetch` \| `web_fetch` \|
		\| `Task` tool (dispatch subagent) \| `@agent-name` (see [Subagent support](#subagent-support)) \|

		## Subagent support

		Gemini CLI supports subagents natively via the `@` syntax. Use the built-in `@generalist` agent to dispatch any task — it has access to all tools and follows the prompt you provide.

		When a skill says to dispatch a named agent type, use `@generalist` with the full prompt from the skill's prompt template:

		\| Skill instruction \| Gemini CLI equivalent \|
		\|-------------------\|----------------------\|
		\| `Task tool (superpowers:implementer)` \| `@generalist` with the filled `implementer-prompt.md` template \|
		\| `Task tool (superpowers:spec-reviewer)` \| `@generalist` with the filled `spec-reviewer-prompt.md` template \|
		\| `Task tool (superpowers:code-reviewer)` \| `@code-reviewer` (bundled agent) or `@generalist` with the filled review prompt \|
		\| `Task tool (superpowers:code-quality-reviewer)` \| `@generalist` with the filled `code-quality-reviewer-prompt.md` template \|
		\| `Task tool (general-purpose)` with inline prompt \| `@generalist` with your inline prompt \|

		### Prompt filling

		Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or `[FULL TEXT of task]`. Fill all placeholders and pass the complete prompt as the message to `@generalist`. The prompt template itself contains the agent's role, review criteria, and expected output format — `@generalist` will follow it.

		### Parallel dispatch

		Gemini CLI supports parallel subagent dispatch. When a skill asks you to dispatch multiple independent subagent tasks in parallel, request all of those `@generalist` or named subagent tasks together in the same prompt. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.

		## Additional Gemini CLI tools

		These tools are available in Gemini CLI but have no Claude Code equivalent:

		\| Tool \| Purpose \|
		\|------\|---------\|
		\| `list_directory` \| List files and subdirectories \|
		\| `save_memory` \| Persist facts to GEMINI.md across sessions \|
		\| `ask_user` \| Request structured input from the user \|
		\| `tracker_create_task` \| Rich task management (create, update, list, visualize) \|
		\| `enter_plan_mode` / `exit_plan_mode` \| Switch to read-only research mode before making changes \|

superpowers-mcp - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics