Bump superpowers-evals submodule

.codex-plugin/plugin.json

@@ -21,7 +21,6 @@
     "workflow"
   ],
   "skills": "./skills/",
-  "hooks": "./hooks/hooks-codex.json",
   "interface": {
     "displayName": "Superpowers",
     "shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",

.github/ISSUE_TEMPLATE/bug_report.md

@@ -12,17 +12,14 @@ add a comment or reaction to the existing one instead.
 
 - [ ] I searched existing issues and this is not a duplicate
 
-## Environment (required)
-<!-- Required. We assume an agent filed this report — tell us which one and
-     where it ran. We weigh reports by what produced them. -->
+## Environment
 
 | Field | Value |
 |-------|-------|
 | Superpowers version | |
 | Harness (Claude Code, Cursor, etc.) | |
 | Harness version | |
-| Your model + version | |
-| All plugins installed | |
+| Model | |
 | OS + shell | |
 
 ## Is this a Superpowers issue or a platform issue?

.github/ISSUE_TEMPLATE/feature_request.md

@@ -30,18 +30,5 @@ progress, and some were intentionally declined.
      of project? If this is specific to your domain, workflow, or a
      third-party tool, it may belong as its own plugin instead. -->
 
-## Environment (required)
-<!-- Required. We assume an agent wrote this request — tell us which one and
-     where it ran. We weigh proposals reasoned from documentation differently
-     than ones grounded in a real session where the problem actually came up. -->
-
-| Field | Value |
-|-------|-------|
-| Superpowers version | |
-| Harness (Claude Code, Cursor, etc.) | |
-| Harness version | |
-| Your model + version | |
-| All plugins installed | |
-
 ## Context
-<!-- Optional: the workflow where you hit this, links, transcripts. -->
+<!-- Optional: version info, harness, model, workflow where you hit this. -->

.github/ISSUE_TEMPLATE/platform_support.md

@@ -21,14 +21,3 @@ requested or discussed.
 ## Have you tried manual installation?
 <!-- Many tools work with Superpowers through manual setup even without
      official support. Did you try? What happened? -->
-
-## Environment (required)
-<!-- Required. We assume an agent wrote this request — tell us which one and
-     where it ran. -->
-
-| Field | Value |
-|-------|-------|
-| Harness you currently use (Claude Code, Cursor, etc.) | |
-| Harness version | |
-| Your model + version | |
-| All plugins installed | |

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,23 +4,6 @@ sections blank, contain multiple unrelated changes, or show no evidence
 of human involvement will be closed without review.
 -->
 
-> **This PR MUST target the `dev` branch, not `main`.** `main` is the
-> released branch; active work lands on `dev` first. PRs opened against
-> `main` will be asked to retarget `dev` before review.
-
-## Who is submitting this PR? (required)
-<!-- Required. PRs that omit this will be closed. We assume an agent wrote
-     this PR — tell us which one and where it ran. We weigh contributions by
-     what produced them: content reasoned from documentation is held to a
-     different bar than work grounded in a real session. -->
-
-| Field | Value |
-|-------|-------|
-| Your model + version | |
-| Harness + version | |
-| All plugins installed | |
-| Human partner who reviewed this diff | |
-
 ## What problem are you trying to solve?
 <!-- Describe the specific problem you encountered. If this was a session
      issue, include: what you were doing, what went wrong, the model's

.kimi-plugin/plugin.json

@@ -1,38 +0,0 @@
-{
-  "name": "superpowers",
-  "version": "5.1.0",
-  "description": "An agentic skills framework and software development methodology.",
-  "author": {
-    "name": "Jesse Vincent",
-    "email": "jesse@fsck.com"
-  },
-  "homepage": "https://github.com/obra/superpowers",
-  "license": "MIT",
-  "keywords": [
-    "brainstorming",
-    "subagent-driven-development",
-    "skills",
-    "planning",
-    "tdd",
-    "debugging",
-    "code-review",
-    "workflow"
-  ],
-  "skills": "./skills/",
-  "sessionStart": {
-    "skill": "using-superpowers"
-  },
-  "skillInstructions": "Kimi Code tool mapping for Superpowers skills:\n\n- When a Superpowers skill says to ask the user, ask clarifying questions, ask one question at a time, present multiple-choice options, use the terminal for a question, or wait for the user's choice, call Kimi Code's `AskUserQuestion` tool. Do not render those choices as plain assistant text unless `AskUserQuestion` is unavailable or the session is in auto permission mode.\n- For `AskUserQuestion`, provide 1 question with 2-4 concrete options when possible. Put the recommended option first and suffix its label with `(Recommended)`.\n- When a Superpowers skill refers to `TodoWrite`, use Kimi Code's `TodoList` tool.\n- When a Superpowers skill says `Task tool (general-purpose)` or asks you to dispatch an implementer/reviewer subagent, use Kimi Code's `Agent` tool with a Kimi subagent type. Do not pass `general-purpose` as `subagent_type`.\n- For implementation, code review, spec review, quality review, and filled Superpowers subagent prompt templates, call `Agent` with `subagent_type: \"coder\"`, paste the fully filled prompt into `prompt`, and provide a short `description`.\n- For read-only codebase exploration that would take several searches, use `Agent` with `subagent_type: \"explore\"`.\n- For read-only planning or architecture design, use `Agent` with `subagent_type: \"plan\"`.\n- Keep dependent Superpowers subagent steps sequential. Use multiple `Agent` calls, or `run_in_background: true` only when the work is independent and background agents are available.\n- When a Superpowers skill refers to the `Skill` tool, use Kimi Code's native `Skill` tool.\n- Use Kimi Code's `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`, `FetchURL`, `WebSearch`, and MCP tools by their actual exposed names.\n- When a skill asks to search file contents, use `Grep`; when it asks to find files by path or pattern, use `Glob`; when it asks to fetch a URL, use `FetchURL`; when it asks to search the web, use `WebSearch`.",
-  "interface": {
-    "displayName": "Superpowers",
-    "shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",
-    "longDescription": "Use Superpowers to guide agent work through brainstorming, implementation planning, test-driven development, systematic debugging, parallel execution, code review, and finish-the-branch workflows.",
-    "developerName": "Jesse Vincent",
-    "capabilities": [
-      "Interactive",
-      "Read",
-      "Write"
-    ],
-    "websiteURL": "https://github.com/obra/superpowers"
-  }
-}

.opencode/INSTALL.md

@@ -45,7 +45,7 @@ Use OpenCode's native `skill` tool:
 
 ```
 use skill tool to list skills
-use skill tool to load brainstorming
+use skill tool to load superpowers/brainstorming
 ```
 
 ## Updating
@@ -98,16 +98,11 @@ Then use the installed package path in `opencode.json`:
 
 ### Tool mapping
 
-Skills speak in actions ("create a todo", "dispatch a subagent", "read a file"). On OpenCode these resolve to:
-
-- "Create a todo" / "mark complete in todo list" → `todowrite`
-- `Subagent (general-purpose):` template → `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
-- "Invoke a skill" → OpenCode's native `skill` tool
-- "Read a file" → `read`
-- "Create a file" / "edit a file" / "delete a file" → `apply_patch`
-- "Run a shell command" → `bash`
-- "Search file contents" / "find files by name" → `grep`, `glob`
-- "Fetch a URL" → `webfetch`
+When skills reference Claude Code tools:
+- `TodoWrite` → `todowrite`
+- `Task` with subagents → `@mention` syntax
+- `Skill` tool → OpenCode's native `skill` tool
+- File operations → your native tools
 
 ## Getting Help
 

.opencode/plugins/superpowers.js

@@ -1,7 +1,7 @@
 /**
  * Superpowers plugin for OpenCode.ai
  *
- * Injects superpowers bootstrap context via message transform.
+ * Injects superpowers bootstrap context via system prompt transform.
  * Auto-registers skills directory via config hook (no symlinks needed).
  */
 
@@ -74,15 +74,11 @@ export const SuperpowersPlugin = async ({ client, directory }) => {
     const { content } = extractAndStripFrontmatter(fullContent);
 
     const toolMapping = `**Tool Mapping for OpenCode:**
-When skills request actions, substitute OpenCode equivalents:
-- Create or update todos → \`todowrite\`
-- \`Subagent (general-purpose):\` → \`task\` with \`subagent_type: "general"\`
-- Invoke a skill → OpenCode's native \`skill\` tool
-- Read files → \`read\`
-- Create, edit, or delete files → \`apply_patch\`
-- Run shell commands → \`bash\`
-- Search files → \`grep\`, \`glob\`
-- Fetch a URL → \`webfetch\`
+When skills reference tools you don't have, substitute OpenCode equivalents:
+- \`TodoWrite\` → \`todowrite\`
+- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
+- \`Skill\` tool → OpenCode's native \`skill\` tool
+- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
 
 Use OpenCode's native \`skill\` tool to list and load skills.`;
 

.pi/extensions/superpowers.ts

@@ -1,121 +0,0 @@
-import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-const EXTREMELY_IMPORTANT_MARKER = "<EXTREMELY_IMPORTANT>";
-const BOOTSTRAP_MARKER = "superpowers:using-superpowers bootstrap for pi";
-
-const extensionDir = dirname(fileURLToPath(import.meta.url));
-const packageRoot = resolve(extensionDir, "../..");
-const skillsDir = resolve(packageRoot, "skills");
-const bootstrapSkillPath = resolve(skillsDir, "using-superpowers", "SKILL.md");
-
-let cachedBootstrap: string | null | undefined;
-
-export default function superpowersPiExtension(pi: ExtensionAPI) {
-	let injectBootstrap = true;
-
-	pi.on("resources_discover", async () => ({
-		skillPaths: [skillsDir],
-	}));
-
-	pi.on("session_start", async () => {
-		injectBootstrap = true;
-	});
-
-	pi.on("session_compact", async () => {
-		injectBootstrap = true;
-	});
-
-	pi.on("agent_end", async () => {
-		injectBootstrap = false;
-	});
-
-	pi.on("context", async (event) => {
-		if (!injectBootstrap) return;
-		if (event.messages.some(messageContainsBootstrap)) return;
-
-		const bootstrap = getBootstrapContent();
-		if (!bootstrap) return;
-
-		const bootstrapMessage = {
-			role: "user" as const,
-			content: [{ type: "text" as const, text: bootstrap }],
-			timestamp: Date.now(),
-		};
-
-		const insertAt = firstNonCompactionSummaryIndex(event.messages);
-		return {
-			messages: [
-				...event.messages.slice(0, insertAt),
-				bootstrapMessage,
-				...event.messages.slice(insertAt),
-			],
-		};
-	});
-}
-
-function getBootstrapContent(): string | null {
-	if (cachedBootstrap !== undefined) return cachedBootstrap;
-
-	try {
-		const skillContent = readFileSync(bootstrapSkillPath, "utf8");
-		const body = stripFrontmatter(skillContent);
-		cachedBootstrap = `${EXTREMELY_IMPORTANT_MARKER}
-${BOOTSTRAP_MARKER}
-
-You have superpowers.
-
-The using-superpowers skill content is included below and is already loaded for this Pi session. Follow it now. Do not try to load using-superpowers again.
-
-${body}
-
-${piToolMapping()}
-</EXTREMELY_IMPORTANT>`;
-		return cachedBootstrap;
-	} catch {
-		cachedBootstrap = null;
-		return null;
-	}
-}
-
-function stripFrontmatter(content: string): string {
-	const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
-	return (match ? match[1] : content).trim();
-}
-
-function piToolMapping(): string {
-	return `## Pi tool mapping
-
-Pi has native skills but does not expose Claude Code's \`Skill\` tool. When a Superpowers instruction says to invoke a skill, use Pi's native skill system instead: load the relevant \`SKILL.md\` with \`read\` when the skill applies, or let a human invoke \`/skill:name\` explicitly.
-
-Pi's built-in coding tools are lowercase: \`read\`, \`write\`, \`edit\`, \`bash\`, plus optional \`grep\`, \`find\`, and \`ls\`. Use those for the corresponding actions: read a file, create or edit files, run shell commands, search file contents, find files by name, and list directories.
-
-Pi does not ship a standard subagent tool. If a subagent tool such as \`subagent\` from \`pi-subagents\` is available, use it for Superpowers subagent workflows. If no subagent tool is available, do the work in this session or explain the missing capability instead of inventing \`Task\` calls.
-
-Pi does not ship a standard task-list tool. If an installed todo/task tool is available, use it. Otherwise track work in plan files or a repo-local \`TODO.md\` when task tracking is needed. Treat older \`TodoWrite\` references as this task-tracking action.`;
-}
-
-function messageContainsBootstrap(message: unknown): boolean {
-	const content = (message as { content?: unknown }).content;
-	if (typeof content === "string") return content.includes(BOOTSTRAP_MARKER);
-	if (!Array.isArray(content)) return false;
-	return content.some((part) => {
-		return (
-			part &&
-			typeof part === "object" &&
-			(part as { type?: unknown }).type === "text" &&
-			typeof (part as { text?: unknown }).text === "string" &&
-			(part as { text: string }).text.includes(BOOTSTRAP_MARKER)
-		);
-	});
-}
-
-function firstNonCompactionSummaryIndex(messages: unknown[]): number {
-	let index = 0;
-	while ((messages[index] as { role?: unknown } | undefined)?.role === "compactionSummary") {
-		index += 1;
-	}
-	return index;
-}

.version-bump.json

@@ -4,7 +4,6 @@
     { "path": ".claude-plugin/plugin.json", "field": "version" },
     { "path": ".cursor-plugin/plugin.json", "field": "version" },
     { "path": ".codex-plugin/plugin.json", "field": "version" },
-    { "path": ".kimi-plugin/plugin.json", "field": "version" },
     { "path": ".claude-plugin/marketplace.json", "field": "plugins.0.version" },
     { "path": "gemini-extension.json", "field": "version" }
   ],

CLAUDE.md

@@ -14,8 +14,7 @@ Before you open a PR against this repo, you MUST:
 2. **Search for existing PRs** — open AND closed — that address the same problem. If duplicates exist, STOP and tell your human partner. Do not open another duplicate.
 3. **Verify this is a real problem.** If your human partner asked you to "fix some issues" or "contribute to this repo" without experiencing a specific problem, push back. Ask them what broke, what failed, what the user experience was.
 4. **Confirm the change belongs in core.** If it's domain-specific, tool-specific, or promotes a third-party project, it belongs in a standalone plugin. Tell your human partner.
-5. **Identify yourself.** Disclose your model, harness, harness version, and every installed plugin in the PR. Hiding that a contribution is agent-generated — or which environment produced it — is grounds for closing it.
-6. **Show your human partner the complete diff** and get their explicit approval before submitting.
+5. **Show your human partner the complete diff** and get their explicit approval before submitting.
 
 If any of these checks fail, do not open the PR. Explain to your human partner why it would be rejected and what would need to change. They will thank you for saving them the embarrassment.
 
@@ -27,10 +26,6 @@ If any of these checks fail, do not open the PR. Explain to your human partner w
 
 **PRs that show no evidence of human involvement will be closed.** A human must review the complete proposed diff before submission.
 
-**Submitters MUST identify themselves.** Every PR and issue must disclose the model, harness, harness version, and all installed plugins used to produce the contribution — or state plainly that it was written by hand with no agent. This is not optional. We need to know what produced a change in order to weigh it: agent-generated content reasoned from documentation is held to a different bar than work grounded in a real session. Contributions that hide their authoring environment will be closed.
-
-**All PRs MUST target the `dev` branch, not `main`.** `main` is the released branch; active work lands on `dev` first. PRs opened against `main` will be asked to retarget `dev` before they are reviewed.
-
 ## What We Will Not Accept
 
 ### Third-party dependencies

README.md

@@ -4,7 +4,7 @@ Superpowers is a complete software development methodology for your coding agent
 
 ## Quickstart
 
-Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi).
+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
 
@@ -14,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 your agent 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.
 
@@ -60,25 +60,6 @@ The Superpowers marketplace provides Superpowers and some other related plugins
   /plugin install superpowers@superpowers-marketplace
   ```
 
-### Antigravity
-
-Install Superpowers as a plugin from this repository:
-
-```bash
-agy plugin install https://github.com/obra/superpowers
-```
-
-Antigravity runs the plugin's session-start hook, so Superpowers is active from
-the first message. Reinstall with the same command to update.
-
-### 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.
-
 ### Codex CLI
 
 Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
@@ -97,15 +78,13 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
 
 - Select `Install Plugin`.
 
-### Cursor
+### Codex App
 
-- In Cursor Agent chat, install from marketplace:
+Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
 
-  ```text
-  /add-plugin superpowers
-  ```
-
-- Or search for "superpowers" in the plugin marketplace.
+- 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
 
@@ -135,40 +114,6 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
   gemini extensions update superpowers
   ```
 
-### GitHub Copilot CLI
-
-- Register the marketplace:
-
-  ```bash
-  copilot plugin marketplace add obra/superpowers-marketplace
-  ```
-
-- Install the plugin:
-
-  ```bash
-  copilot plugin install superpowers@superpowers-marketplace
-  ```
-
-### Kimi Code
-
-Superpowers is available in Kimi Code's plugin marketplace.
-
-- Open Kimi Code's plugin manager:
-
-  ```text
-  /plugins
-  ```
-
-- Go to `Marketplace` > `Superpowers` and install it.
-
-- Or install directly from this repository:
-
-  ```text
-  /plugins install https://github.com/obra/superpowers
-  ```
-
-- Detailed docs: [docs/README.kimi.md](docs/README.kimi.md)
-
 ### OpenCode
 
 OpenCode uses its own plugin install; install Superpowers separately even if you
@@ -182,21 +127,29 @@ already use it in another harness.
 
 - Detailed docs: [docs/README.opencode.md](docs/README.opencode.md)
 
-### Pi
+### Cursor
 
-Install Superpowers as a Pi package from this repository:
+- In Cursor Agent chat, install from marketplace:
 
-```bash
-pi install git:github.com/obra/superpowers
-```
+  ```text
+  /add-plugin superpowers
+  ```
 
-For local development, run Pi with this checkout loaded as a temporary package:
+- Or search for "superpowers" in the plugin marketplace.
 
-```bash
-pi -e /path/to/superpowers
-```
+### GitHub Copilot CLI
 
-The Pi package loads the Superpowers skills and a small extension that injects the `using-superpowers` bootstrap at session startup and again after compaction. Pi has native skills, so no compatibility `Skill` tool is required. Subagent and task-list tools remain optional Pi companion packages.
+- Register the marketplace:
+
+  ```bash
+  copilot plugin marketplace add obra/superpowers-marketplace
+  ```
+
+- Install the plugin:
+
+  ```bash
+  copilot plugin install superpowers@superpowers-marketplace
+  ```
 
 ## The Basic Workflow
 

docs/README.kimi.md

@@ -1,88 +0,0 @@
-# Superpowers for Kimi Code
-
-Complete guide for using Superpowers with [Kimi Code](https://github.com/MoonshotAI/kimi-code).
-
-## Installation
-
-Superpowers is available in Kimi Code's plugin marketplace.
-
-Open the plugin manager:
-
-```text
-/plugins
-```
-
-Go to `Marketplace` > `Superpowers` and install it.
-
-You can also install from this repository:
-
-```text
-/plugins install https://github.com/obra/superpowers
-```
-
-For unreleased validation against `dev`, pin the branch explicitly:
-
-```text
-/plugins install https://github.com/obra/superpowers/tree/dev
-```
-
-Kimi Code applies plugin changes to new sessions. After installing, updating, enabling, disabling, or reloading a plugin, start a fresh session with `/new`.
-
-## How It Works
-
-The Kimi plugin manifest lives at `.kimi-plugin/plugin.json`.
-
-The manifest does three things:
-
-1. Points Kimi Code at the existing `skills/` directory.
-2. Loads `using-superpowers` at session start through `sessionStart.skill`.
-3. Provides Kimi-specific tool mapping through `skillInstructions`.
-
-Kimi Code reads Superpowers skills from this repository. There are no copied skills, symlinks, hooks, or extra runtime dependencies.
-
-## Tool Mapping
-
-Skills describe actions instead of hard-coding one runtime's tool names. On Kimi Code these resolve to:
-
-- "Ask the user" / "ask clarifying questions" -> `AskUserQuestion`
-- "Create a todo" / "mark complete in todo list" -> `TodoList`
-- "Dispatch a subagent" -> `Agent`
-- "Invoke a skill" -> Kimi Code's native `Skill` tool
-- "Read a file" / "write a file" / "edit a file" -> `Read`, `Write`, `Edit`
-- "Run a shell command" -> `Bash`
-- "Search file contents" -> `Grep`
-- "Find files by path or pattern" -> `Glob`
-- "Fetch a URL" -> `FetchURL`
-- "Search the web" -> `WebSearch`
-
-## Updating
-
-Use Kimi Code's plugin manager:
-
-```text
-/plugins
-```
-
-Select Superpowers and update it from there. Start a fresh session with `/new` after updating.
-
-## Troubleshooting
-
-### Plugin not loading
-
-1. Run `/plugins info superpowers` and check diagnostics.
-2. Make sure the plugin is enabled.
-3. Start a fresh session with `/new` after install or update.
-
-### Direct GitHub install used an old release
-
-Kimi Code installs the latest GitHub release for a bare repository URL when one exists. To test unreleased changes before the next Superpowers release, install the branch explicitly:
-
-```text
-/plugins install https://github.com/obra/superpowers/tree/dev
-```
-
-### Skills not triggering
-
-1. Confirm `/plugins info superpowers` shows the plugin enabled.
-2. Start a fresh session with `/new`.
-3. Try the acceptance prompt: `Let's make a react todo list`. A working install should load `brainstorming` before writing code.

docs/README.opencode.md

@@ -50,7 +50,7 @@ use skill tool to list skills
 ### Loading a Skill
 
 ```
-use skill tool to load brainstorming
+use skill tool to load superpowers/brainstorming
 ```
 
 ### Personal Skills
@@ -99,23 +99,17 @@ To pin a specific version, use a branch or tag:
 
 The plugin does two things:
 
-1. **Injects bootstrap context** via the `experimental.chat.messages.transform` hook, adding superpowers awareness to every conversation.
+1. **Injects bootstrap context** via the `experimental.chat.system.transform` hook, adding superpowers awareness to every conversation.
 2. **Registers the skills directory** via the `config` hook, so OpenCode discovers all superpowers skills without symlinks or manual config.
 
 ### Tool Mapping
 
-Skills speak in actions rather than naming any one runtime's tools. On OpenCode these resolve to:
+Skills written for Claude Code are automatically adapted for OpenCode:
 
-- "Create a todo" / "mark complete in todo list" → `todowrite`
-- `Subagent (general-purpose):` template → OpenCode's `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
-- "Invoke a skill" → OpenCode's native `skill` tool
-- "Read a file" → `read`
-- "Create a file" / "edit a file" / "delete a file" → `apply_patch`
-- "Run a shell command" → `bash`
-- "Search file contents" / "find files by name" → `grep`, `glob`
-- "Fetch a URL" → `webfetch`
-
-(Verified against the installed OpenCode CLI's tool inventory.)
+- `TodoWrite` → `todowrite`
+- `Task` with subagents → OpenCode's `@mention` system
+- `Skill` tool → OpenCode's native `skill` tool
+- File operations → Native OpenCode tools
 
 ## Troubleshooting
 
@@ -153,7 +147,7 @@ Then use the installed package path in `opencode.json`:
 
 ### Bootstrap not appearing
 
-1. Check OpenCode version supports `experimental.chat.messages.transform` hook
+1. Check OpenCode version supports `experimental.chat.system.transform` hook
 2. Restart OpenCode after config changes
 
 ## Getting Help

docs/porting-to-a-new-harness.md

@@ -1,826 +0,0 @@
-# Porting Superpowers to a New Harness
-
-This guide explains how to add support for a new harness — an IDE, CLI, or
-agent runner that isn't Claude Code — so that Superpowers skills auto-trigger
-there the same way they do natively.
-
-It is written in two layers. **Part 1–3** explain how the system works and how
-to tell whether a harness can be supported at all; read these before you touch
-anything. **Part 4–8** are a prescriptive procedure for an agent (supervised by
-a human partner) to execute the port end to end, through distribution. An
-appendix indexes the current reference integrations so you can copy the closest
-one.
-
-The integration mechanism differs across harnesses, and it will keep changing.
-This guide deliberately teaches the **invariants** — the things that must be
-true no matter the mechanism — and points you at a live reference implementation
-to copy. When this guide and the code disagree, the code wins; fix the guide.
-
-## Before you start
-
-Adding a harness is the highest-stakes contribution type in this repo. Before
-writing anything:
-
-- Read `CLAUDE.md` and `.github/PULL_REQUEST_TEMPLATE.md` in full — the
-  contributor rules and the new-harness PR requirements are not optional.
-- Search open **and closed** PRs for a prior attempt at this harness. If one
-  exists, understand why it stalled before starting your own.
-
----
-
-## Part 1 — How Superpowers works across harnesses
-
-Superpowers is the same content everywhere. What changes per harness is the thin
-layer that delivers that content to the model and translates its instructions
-into the harness's native tools. Three components:
-
-1. **Skills (harness-agnostic).** Everything in `skills/` is the source of
-   truth, shared verbatim by every harness. Skills are written to describe
-   *actions* — "invoke a skill", "read a file", "dispatch a subagent", "create a
-   todo" — and never name a specific tool. This is what lets one skill body run
-   on Claude Code, Codex, Gemini, pi, and the rest without edits.
-
-2. **Tool mapping (per-harness).** Each harness needs the action vocabulary
-   translated into its real tool names. That translation lives in
-   `skills/using-superpowers/references/<harness>-tools.md` and/or inline in the
-   harness's bootstrap injector (see Part 5). It says, e.g., "*dispatch a
-   subagent* → call `task` with `subagent_type`."
-
-3. **Bootstrap (per-harness).** At the start of every session, the full
-   `skills/using-superpowers/SKILL.md` is injected into the model's context,
-   wrapped in `<EXTREMELY_IMPORTANT>` tags, with the tool mapping appended. That
-   injected skill is what teaches the model that skills exist and that it must
-   check for a relevant skill before acting. **The bootstrap is the entire
-   integration.** Without it, the skill files are inert — present on disk, never
-   invoked.
-
-### Two rules that make this work
-
-**1. Skills name actions, not tools.** Do **not** edit skill bodies to fit your
-harness. Porting adds a tool-mapping reference and a bootstrap injector; it
-never reaches into `skills/*/SKILL.md` to swap tool names. (The project's
-contributor guidelines treat skill content as carefully-tuned behavior-shaping
-code; rewording it for "compliance" is rejected on sight.)
-
-**2. Everything ships through the harness's own install mechanism. Never edit the
-user's files.** The bootstrap, the skills, and the tool mapping all get delivered
-*as part of what the harness installs* — a plugin, an extension, a marketplace
-entry, an extension-bundled context file. A port **must not** reach into a user's
-global or personal config (`~/.gemini/config/AGENTS.md`, `settings.json`,
-`trustedFolders.json`, a hand-edited `~/.bashrc`, etc.) to inject anything. The
-harness owns what it loads; your install artifact is the only thing you get to
-write. If the install mechanism genuinely can't carry the bootstrap, that is a
-limitation to surface (Part 6) — never a license to hand-edit the user's config.
-(Shape C is *not* an exception: Gemini's context file is fine because it ships
-*inside the installed extension* and is declared by the manifest's
-`contextFileName` — the harness loads the extension's own file, not a file you
-edited in the user's home.)
-
----
-
-## Part 2 — Can this harness be supported?
-
-A harness can support Superpowers only if it can do all of the following. Check
-these before writing code — if the first one fails, stop.
-
-### Hard requirement: automatic session-start injection
-
-The harness must let you inject text into the model's context **at the start of
-every session, with no per-session opt-in by your human partner.** This is the
-one non-negotiable capability. It can take any form:
-
-- a **hook/event system** that runs a shell command at session start and reads
-  its stdout (Claude Code, Codex, Cursor, Copilot CLI), or
-- an **in-process plugin/extension** with a session-start or message lifecycle
-  callback that can mutate the message array (OpenCode, pi), or
-- an **instructions-file** convention where the harness loads a context file that
-  *your installed extension ships and declares* (e.g. Gemini's `contextFileName`
-  pointing at the extension's own `GEMINI.md`) — not a file you edit in the user's
-  home.
-
-If the only way to get Superpowers in front of the model is for your human
-partner to opt in each session (paste a prompt, run a command, enable a mode),
-the harness
-**cannot** be properly supported. The acceptance test in Part 3 will fail, and
-the PR will be closed. This is the single most common reason a "port" isn't a
-real port.
-
-### The rest of the capability checklist
-
-| Capability | Why it's needed | If absent |
-|---|---|---|
-| **Skill discovery + invocation** | The model must be able to load a skill's full content on demand | If there's no native skill tool, the sanctioned fallback is to `read` the relevant `SKILL.md` directly — see Part 5. A harness with neither a skill tool nor file-read cannot work. |
-| **File read / write / edit** | Nearly every skill manipulates files | Essential. No workaround. |
-| **Run shell commands** | TDD, verification, git workflows | Essential. |
-| **Subagent / task dispatch** | `dispatching-parallel-agents`, `subagent-driven-development` | Degradable: if unavailable, those specific skills tell the model to do the work inline or report the missing capability — *never* to invent a `Task` call. Some harnesses gate this behind a config flag (e.g. Codex needs multi-agent enabled). |
-| **Todo / task tracking** | Progress tracking in several skills | Degradable: fall back to a plan file or `TODO.md`. |
-| **Web fetch / search** | A few skills | Degradable. |
-| **Shell or polyglot script execution (Windows)** | Only for the shell-hook shape, only if you want Windows support | See Part 7. In-process-plugin harnesses sidestep this entirely. |
-
-"Degradable" means: the skill already has fallback wording for the missing
-tool. Your job in the tool mapping is to point at the real tool when it exists
-and reuse that fallback wording when it doesn't.
-
-### You may not need a new directory at all
-
-Some "new harnesses" are really existing integrations under a different
-installer. Factory's Droid, for example, consumes the Claude Code plugin via its
-own `plugin install` command and needs no new files here. Before building,
-check whether the harness can simply load an existing manifest. A port that adds
-nothing to this repo but a paragraph in the README is a perfectly good outcome.
-
----
-
-## Part 3 — Definition of done
-
-A port is finished when **all** of these are true:
-
-1. The `using-superpowers` bootstrap loads at session start, every session, with
-   no per-session opt-in.
-2. A tool mapping exists for the harness (in
-   `references/<harness>-tools.md`, inline in the bootstrap, or both — per Part 5).
-3. Skills can actually be invoked — natively, or via the documented
-   read-`SKILL.md` fallback — and the model follows them.
-4. **The acceptance test passes.** In a clean session, the user message:
-
-   > Let's make a react todo list
-
-   auto-triggers the `brainstorming` skill *before any code is written*. Capture
-   the full transcript — the PR requires it.
-5. Tests cover the integration (Part 5) and pass.
-6. A real user can install it through the harness's own mechanism (not by
-   hand-copying files), and the version is tracked in `.version-bump.json` where
-   applicable (Part 6). Note that some installers rewrite or strip the manifest on
-   install (one drops it to just `{"name": …}`), so "the *installed* files report
-   the repo version" is not always achievable — track the version at the source
-   manifest and don't treat a rewritten installed manifest as a failure.
-
-A quick smoke check before the full acceptance test: start a session and ask the
-model to describe its superpowers. If the bootstrap injected, it knows it has
-them. (OpenCode's install doc uses `opencode run --print-logs "hello" 2>&1 |
-grep -i superpowers` for the same goal via a different mechanism — log-grep
-rather than asking the model; the `2>&1` matters because logs go to stderr. Find
-your harness's equivalent.)
-
----
-
-## Part 4 — Choose your integration shape
-
-There are three structural shapes, distinguished by *how you get the bootstrap
-in front of the model*. Pick the one that matches what your harness exposes,
-then copy that reference implementation. The shape determines almost everything
-in Part 5 — the steps below branch on it.
-
-### How to tell which shape you have
-
-Before routing, learn the harness's *actual* mechanism — and don't assume it's
-well documented or that it behaves like whatever harness it forked from.
-
-**Find the surface:**
-
-- **Search the web for the harness's docs** (extension / plugin / hook / skill /
-  MCP / "context file" / "rules file"). Vendor tools change fast; search rather
-  than trust training knowledge.
-- **Find and read an existing third-party extension/plugin for the harness.** A
-  real working example beats docs — it shows the manifest shape, the install
-  command, and which components the harness actually loads.
-- Check what the harness loads at startup: a settings file? an extensions
-  directory? a per-project or global instructions file (`AGENTS.md`, `<NAME>.md`)?
-
-**If it's underdocumented, reverse-engineer it empirically** (a real porter has
-had to do every one of these):
-
-- `strings` the binary / grep the install tree for hook event names, config
-  paths, and the instructions file it reads.
-- **Ask the running model to enumerate its own tool names** — e.g. "list the
-  exact machine names of every tool you can call." This is the authoritative way
-  to get tool names without inventing them (see Step 4).
-- Prove every assumption with a **unique-marker test**: inject a nonsense token
-  through the mechanism you think works, start a fresh session, and confirm the
-  token actually reached the model.
-
-**A fork does not inherit its parent's behavior.** A harness derived from another
-(e.g. a Gemini-derived CLI) may expose the parent's manifest fields and
-`@`-include syntax and *still not honor them the same way*. Verify with a marker;
-never assume the parent's recipe transfers.
-
-Then route to a shape:
-
-- Shell command at session start whose stdout is read → **Shape A**.
-- Plugin/extension module with lifecycle callbacks you run code in → **Shape B**.
-- Only ever an always-on instructions file, no hook and no code plugin →
-  **Shape C**.
-
-**Shapes compose — they are not mutually exclusive.** The *skill-discovery*
-mechanism and the *bootstrap* mechanism need not be the same shape — but **both
-must still ride the install mechanism** (rule 2). Decide the two questions
-separately: *where do skills get discovered?* and *how does the bootstrap reach
-the model every session?* A harness might install skills via a plugin yet need
-the bootstrap delivered another install-shipped way (an extension-declared
-context file, or — see below — by the harness surfacing the installed
-`using-superpowers` skill's own description at session start). If more than one
-install-mechanism surface injects automatically, prefer the most reliable. What
-you may **not** do is bridge a gap by editing the user's global config.
-
-### Shape A — Shell-hook
-
-The harness has a hook system that runs a shell command at session start and
-reads JSON from its stdout. The configured command runs `run-hook.cmd`, a
-polyglot wrapper that just locates bash and dispatches the named script; the
-script (`hooks/session-start`, or a harness-specific variant like
-`hooks/session-start-codex`) is what reads `using-superpowers/SKILL.md` and
-prints a JSON object whose **field name and nesting differ per harness**.
-
-- Reference: `hooks/session-start` (and `hooks/session-start-codex`),
-  `hooks/run-hook.cmd`, and the per-harness hook config `hooks/hooks.json`
-  (Claude Code), `hooks/hooks-codex.json` (Codex), `hooks/hooks-cursor.json`
-  (Cursor).
-- Manifests: `.codex-plugin/plugin.json`, `.cursor-plugin/plugin.json` point the
-  harness at `./skills/` and the right `hooks-*.json`. (Claude Code's
-  `.claude-plugin/plugin.json` sets neither field — it auto-discovers `skills/`
-  and `hooks/hooks.json` by convention.)
-
-> **A hook *system* is not a session-start *event*.** A harness can have a
-> `hooks.json` mechanism — and even contain the literal string `SessionStart` in
-> its binary — while having no hook event that fires at session start and can
-> inject context. (One real harness only exposed pre/post-tool and stop events;
-> the `SessionStart` strings were telemetry.) Confirm the *specific event* you
-> need exists and can write to the model's context before committing to Shape A.
-> If it can't, the bootstrap belongs in an instructions file (Shape C) instead.
-
-### Shape B — In-process plugin / extension
-
-The harness loads a JS/TS module that exposes lifecycle callbacks. You register
-the skills directory through the harness's API and inject the bootstrap by
-mutating the message array in code.
-
-- Reference: `.opencode/plugins/superpowers.js` (JavaScript) and
-  `.pi/extensions/superpowers.ts` (TypeScript). pi is the closest reference for
-  any harness that has **no native skill tool**.
-
-### Shape C — Instructions-file
-
-The harness has neither a shell hook nor a code plugin — its session-start
-surface is a context file that *your installed extension ships and the manifest
-declares* (e.g. Gemini's `contextFileName` → the extension's own `GEMINI.md`).
-You can't run code or mutate messages; the extension's context file points at the
-bootstrap. There is no injector to assemble a string or strip frontmatter — the
-harness loads the referenced content as-is. **This works only because the file is
-part of the installed extension** — never substitute "edit the user's global
-`GEMINI.md`/`AGENTS.md`" for shipping your own (rule 2).
-
-- Reference: `gemini-extension.json` (manifest, with `contextFileName`),
-  `GEMINI.md` (two `@`-includes — the bootstrap skill and the tool-mapping
-  reference), `skills/using-superpowers/references/gemini-tools.md`.
-- Note: `@`-include is a Gemini feature. If your harness loads an instructions
-  file but has no include syntax, you must inline the bootstrap content into the
-  file instead.
-- **Don't trust that an `@`-include is actually expanded — prove it.** A
-  Gemini-*derived* harness can accept `@./path` syntax yet treat it as a *hint
-  the model may choose to read* (it emits a file-read tool call) rather than a
-  guaranteed inline expansion. That's the difference between the bootstrap being
-  reliably present every session and the model maybe-reading it. Run a
-  unique-marker test: if the marker isn't in context *without* a tool call,
-  **inline the content** rather than `@`-include it.
-
-### Routing table
-
-| If the harness… | Use shape | Copy from |
-|---|---|---|
-| runs a shell command at session start and reads its stdout | A (shell-hook) | Codex (`hooks/session-start-codex` + `hooks/hooks-codex.json` + `.codex-plugin/`) |
-| is a JS/TS plugin host with session/message lifecycle callbacks | B (in-process) | OpenCode (`.opencode/`) — or pi (`.pi/`) if it has no native skill tool |
-| ships an extension-declared context file it always loads | C (instructions-file) | Gemini (`gemini-extension.json` + `GEMINI.md` + `references/gemini-tools.md`) |
-| has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |
-
-Most real harnesses fit one row cleanly; the last is the hybrid case (rule 2 still
-holds — the bootstrap rides the install mechanism, never a user-config edit).
-
----
-
-## Part 5 — The porting procedure
-
-### Step 1 — Study the closest reference implementation
-
-Open the files named in Part 4 for your shape and read them end to end. The
-patterns below are summaries; the code is the spec.
-
-### Step 2 — Create the manifest / entry point
-
-Create whatever the harness uses to recognize the plugin. Match the existing
-ones in spirit:
-
-- **Shape A:** a `*-plugin/plugin.json` (see `.codex-plugin/plugin.json`) with
-  `name`, `version`, `description`, author/license/keywords, `"skills":
-  "./skills/"`, and `"hooks": "./hooks/hooks-<harness>.json"`. Plus the
-  `hooks-<harness>.json` itself, registering a session-start hook whose command
-  invokes `run-hook.cmd`.
-- **Shape B:** the module the harness loads (e.g. `.<harness>/plugins/*.js`) plus
-  whatever package metadata it needs to be discovered. The committed package
-  metadata is the **repo-root `package.json`**: `main` points at the OpenCode
-  plugin, the `pi` field (`pi.extensions`, `pi.skills`) plus the `pi-package`
-  keyword declare the pi extension. Per-harness local manifests and lockfiles are
-  kept out of git — `.opencode/.gitignore` excludes `node_modules`,
-  `package.json`, and lockfiles. Do the same for your harness's *local* install
-  artifacts so they don't pollute the repo — but never gitignore the repo-root
-  `package.json`, which is the tracked source of truth.
-  - **Build/dependency check.** Decide how the harness loads your module:
-    does it run the source directly (pi's `.ts` is referenced as-is from
-    `package.json`; OpenCode ships plain `.js`), or does it need a transpile/build
-    step? Superpowers is zero-runtime-dependency. pi's `import type
-    { ExtensionAPI }` works specifically because the harness runs the `.ts`
-    directly, supplies that type at load, and the repo never type-checks the file
-    in CI — the import isn't even declared as a dependency. If *your* harness
-    actually type-checks or bundles the plugin, that breaks: an undeclared type
-    import fails, and the PR rules only carve out *runtime* deps for new
-    harnesses, not dev/type packages. If you hit this, confirm the approach with
-    the maintainer rather than quietly adding a dependency. Keep any build output
-    out of git and document the command.
-- **Shape C (instructions-file):** a small manifest (see `gemini-extension.json`:
-  `name`, `description`, `version`, `contextFileName`) plus the context file
-  itself (`GEMINI.md` is just two `@`-includes: the bootstrap skill and the
-  tool-mapping reference). The Gemini manifest has no `skills` field — Gemini
-  auto-discovers the `skills/` directory bundled in the installed extension. If
-  your harness has a native skill tool but no manifest field to register the
-  directory, you must find its discovery convention (read its extension docs),
-  then verify empirically: after wiring, ask the model to list its available
-  skills — if the bundled skills don't appear, discovery isn't working yet.
-
-### Step 3 — Wire the bootstrap injection
-
-This is the heart of the port. The shared goal: at session start, get the
-`using-superpowers` skill content (wrapped in `<EXTREMELY_IMPORTANT>` tags) plus
-the harness's tool mapping in front of the model, with a note that the skill is
-already active so the model doesn't try to load it again. *How* you do that —
-and what you assemble vs. what the harness loads raw — depends entirely on your
-shape. Do **not** apply one shape's recipe to another.
-
-**Shape A — a script reads `SKILL.md` and prints the harness's JSON.** The
-dispatched script (`hooks/session-start`) `cat`s the whole `SKILL.md` (frontmatter
-included — that's fine; it's emitted verbatim), wraps it with the "You have
-superpowers… for all other skills use the Skill tool" preamble, escapes it, and
-prints the harness's JSON shape. The tool mapping for Shape A does **not** go
-inline here — it lives in `references/<harness>-tools.md` (Step 4). Get the JSON
-output shape exactly right. `hooks/session-start`
-detects the harness from environment variables and prints *one of three* shapes:
-
-- Cursor (`CURSOR_PLUGIN_ROOT` set): `{ "additional_context": "…" }`
-- Claude Code (`CLAUDE_PLUGIN_ROOT` set, `COPILOT_CLI` unset):
-  `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "…" } }`
-- Copilot CLI / SDK standard (else): `{ "additionalContext": "…" }`
-
-This is a trap. Emitting the wrong field, or an extra one, means the bootstrap
-either never injects or injects twice (Claude Code reads both
-`additional_context` and `hookSpecificOutput` without de-duplicating, so emitting
-both double-injects). Find the
-exact field, nesting, and event-matcher values your harness expects. Then
-decide: add a fourth branch to `hooks/session-start`, or — if the harness needs
-a different bootstrap message or env contract — add a dedicated
-`hooks/session-start-<harness>` script, the way Codex did. If you add a branch
-and your harness *also* sets an env var an earlier branch keys on (some harnesses
-set `CLAUDE_PLUGIN_ROOT` too), order your branch before the one that would
-otherwise shadow it. Match the harness's
-own event-matcher strings (Claude Code uses `startup|clear|compact`, Codex
-`startup|resume|clear`, Cursor `sessionStart`); wrong matchers mean the hook
-silently never fires.
-
-The **hook-config schema itself varies per harness** — don't assume the
-Claude/Codex shape is universal. Compare `hooks/hooks.json`,
-`hooks/hooks-codex.json`, and `hooks/hooks-cursor.json`: Cursor's uses
-`"version": 1`, a lowercase `sessionStart` key, a relative
-`./hooks/run-hook.cmd` command, and omits the `matcher`/`type`/`async` fields the
-others use. Match your `hooks-<harness>.json` to whichever existing file is
-closest, not to a single canonical template.
-
-The hook **command string references a harness-provided plugin-root variable**,
-and its name differs per harness: `hooks.json` uses `${CLAUDE_PLUGIN_ROOT}`,
-`hooks-codex.json` uses `${PLUGIN_ROOT}`, Cursor uses a relative path. Use
-whatever your harness exports. (The `session-start` script re-derives the root
-itself via `dirname`, so the script body doesn't depend on this — but the
-command in the manifest does.)
-
-**Discovering the harness's contract.** The three facts above — env var, JSON
-field/nesting, matcher strings — are the harness's contract, not Superpowers',
-so you have to source them. Read the harness's hook docs, or find out
-empirically: register a throwaway session-start hook that dumps its environment
-and emits a marker, then observe which env var identifies the harness and
-whether/how the harness ingests your stdout. Pin these down before writing the
-real branch.
-
-**Shape B — assemble the string in code, then inject as a user message.** Here
-you build the bootstrap yourself: read `SKILL.md`, strip its YAML frontmatter,
-and assemble `<EXTREMELY_IMPORTANT>` + a short preamble that the skill is already
-loaded and must not be re-invoked + the stripped body + the inline tool mapping +
-`</EXTREMELY_IMPORTANT>`. One subtlety the references disagree on: OpenCode's
-preamble says "do NOT use the skill tool…" (assumes a `skill` tool exists), while
-pi's just says "do not try to load using-superpowers again." If your harness has
-no skill tool, use pi's wording, not OpenCode's.
-
-Inject the result as a **user-role message, not a system message** — system
-messages bloat tokens when repeated every turn (#750) and multiple system
-messages break some models (#894). Three things you must replicate:
-
-- **Dedup guard.** The lifecycle callback can fire repeatedly (OpenCode's
-  transform runs on *every* agent step; pi's `context` fires per turn). Before
-  injecting, check whether a bootstrap marker is already present and skip if so.
-  (The references pick different markers — pi a custom string, OpenCode the
-  `EXTREMELY_IMPORTANT` tag; matching the tag is more robust since it needs no
-  harness-specific constant.) Cache the bootstrap content at module level so
-  you're not re-reading and re-parsing `SKILL.md` on every call (#1202).
-- **Compaction.** If the harness compacts/summarizes history, re-inject
-  afterward. pi sets an `injectBootstrap` flag on `session_start` and
-  `session_compact`, clears it on `agent_end`, and inserts the message *after*
-  any leading compaction-summary messages. OpenCode relies on its per-step
-  re-injection plus the dedup guard.
-- **Message-object shape is per-harness — discover yours, don't copy a literal.**
-  The two references use *incompatible* shapes: pi builds
-  `{ role, content: [{ type, text }], timestamp }`; OpenCode manipulates
-  `message.info.role` and `message.parts[]`. Find your harness's message shape
-  from its API; copying a reference's object literal verbatim will fail silently.
-
-**Shape C — point your extension's context file at the bootstrap; assemble
-nothing.** There is no injector, so you do *not* strip frontmatter or build a
-wrapped string. The context file your extension ships (declared by the manifest —
-*not* the user's own global file) pulls in two things: the `using-superpowers`
-skill and the harness's tool-mapping reference. `GEMINI.md`
-does this with two `@`-includes (`@./skills/using-superpowers/SKILL.md` and
-`@./skills/using-superpowers/references/<harness>-tools.md`); the harness loads
-them raw, frontmatter and all, and `SKILL.md` already carries its own
-`<EXTREMELY-IMPORTANT>` block internally. If your harness has no include syntax,
-inline the content into the instructions file instead. Gemini ships **no**
-"already loaded, don't re-invoke" preamble — for an `@`-include harness the
-content is the active instruction set, not a skill the model would re-load. If
-you find your harness does try to re-invoke, add that note as a literal line in
-the instructions file (you have no code to add it any other way).
-
-### Step 4 — Write the tool mapping
-
-Translate the action vocabulary into the harness's real tools. Cover every one
-of these actions (omit only what genuinely doesn't apply):
-
-- read a file
-- create / edit / delete a file (one `apply_patch`-style tool, or separate
-  write/edit?)
-- run a shell command
-- search file contents / find files by name (grep, glob)
-- fetch a URL / web search
-- **dispatch a subagent**, including how to pass the agent type — and any config
-  flag needed to enable it
-- **create / update todos** (treat older `TodoWrite` references as this action)
-- **invoke a skill** — see Step 5
-
-**Get the real tool names from the harness; never invent them.** If the docs
-don't list them, the authoritative source is the harness itself: in a live
-session, ask the model to "list the exact machine names of every tool you can
-call, one per line" and use what it reports.
-
-**How the harness finds the `skills/` directory is itself per-harness** — confirm
-it, don't assume. Possibilities: a manifest `skills` path field (Codex's
-`"skills": "./skills/"`); a *co-located* `skills/` the harness auto-scans (where a
-path field is **ignored** — one real harness only scanned a `skills/` sitting next
-to `plugin.json`); an API/registration call (OpenCode, pi); or you stage an
-install dir that pairs the manifest with a **symlink to the repo's `skills/`** and
-point the installer at the staging dir (verify the installer *dereferences* the
-symlink and copies the real files — confirm with `agy plugin validate`/`install`
-or the equivalent before relying on it). A `skills` path field is *not* portable.
-
-Where the mapping lives depends on shape:
-
-- **Shape A:** put it in `skills/using-superpowers/references/<harness>-tools.md`.
-  The agent reaches it from the bootstrap — `SKILL.md`'s "Platform Adaptation"
-  section links the per-harness references files. (Shape A harnesses have no
-  instructions file; the mapping is *not* inlined into the hook output.)
-- **Shape B:** the mapping is typically inlined into the bootstrap string you
-  inject (see the `toolMapping` constant in `superpowers.js`). pi keeps it in
-  *both* places — `piToolMapping()` inline **and** `references/pi-tools.md`. If
-  you maintain it in two places, update both, or the port is half-done.
-- **Shape C:** put it in `references/<harness>-tools.md` and pull it into the
-  always-loaded instructions file (e.g. `GEMINI.md` `@`-includes
-  `gemini-tools.md`).
-
-You may also add a one-line pointer to your harness in `SKILL.md`'s "Platform
-Adaptation" section so an agent reading the bootstrap knows where its mapping
-lives. This is the one edit to a `SKILL.md` a port may make — and only because
-that section is a pointer list, not behavior-shaping content. It does not violate
-the "don't edit skill bodies" rule (Part 1); do not touch anything else in any
-skill. (The list is a convenience pointer, not an exhaustive registry — not every
-harness is listed.)
-
-### Step 5 — Handle a harness with no native skill tool
-
-`using-superpowers/SKILL.md` tells the model to *never read skill files manually
-with file tools — always use your platform's skill-loading mechanism.* The point
-is "don't bypass the mechanism," not "never use file-read." What counts as "your
-platform's mechanism" depends on the harness — and for a harness with no skill
-tool, the documented mechanism *is* reading `SKILL.md`. So reading it there
-honors the rule rather than breaking it. Distinguish three cases:
-
-1. **Native `Skill`-style tool** (Claude Code, Copilot CLI, Gemini's
-   `activate_skill`): point the mapping at that tool.
-2. **Native skill *discovery* but no `Skill` tool** (pi, Antigravity): the harness
-   can find and list skills, but the model can't call a tool to load one. Get the
-   skills installed where the harness scans (pi registers via `resources_discover`
-   → `skillPaths`; OpenCode via its `config` hook; `agy plugin install` copies
-   them in), and tell the model to load a skill by **reading its `SKILL.md` with
-   the file-read tool when the skill applies** — the sanctioned mechanism here,
-   the way `references/pi-tools.md` states it.
-
-   **For the bootstrap itself, prefer a declared context file (Part 6).** If the
-   harness has a `contextFileName`-style manifest field — as Antigravity does —
-   ship a generated context file through the installer: it's guaranteed-loaded and
-   carries both the `using-superpowers` content and the tool mapping. That is the
-   strong, preferred path.
-
-   **Fallback — the surfaced skill index.** If there's no context-file field but
-   the harness surfaces each installed skill's name + description at session start,
-   you need *neither* a built index nor a runtime-list instruction — the harness
-   is the index, and `using-superpowers`'s own surfaced description can be what
-   triggers the model to load it. This is softer than a declared context file;
-   two things it does **not** give you, versus a context file / hook / in-process
-   injector — account for both:
-   - **It bootstraps *triggering*, not the *tool mapping*.** An injector prepends
-     `<harness>-tools.md` alongside `using-superpowers` every session. Here nothing
-     injects the mapping — the model only sees skill *descriptions* and must *read*
-     your `references/<harness>-tools.md` when it needs tool names. It works
-     because skills name actions (the model reads the mapping when it acts), but
-     it's softer than injection. Make sure the mapping is reachable from what the
-     model loads — e.g. linked from `SKILL.md`'s Platform Adaptation section and
-     installed alongside the skills — not just sitting in the repo.
-   - **There's no structural guarantee the trigger fires.** No `<EXTREMELY_IMPORTANT>`
-     wrapper, no dedup, no re-injection after compaction — firing depends on the
-     model choosing to act on a description it sees in the index. This is exactly
-     why the acceptance test is mandatory here: it is the *only* guarantee, so run
-     it on the model(s) your users will actually use, not just the strongest one.
-3. **No skill system at all:** there is nothing to register, and the *only*
-   mechanism is the model reading `SKILL.md` on demand. But the model can't read
-   what it can't find: `using-superpowers/SKILL.md` does **not** enumerate the
-   available skills, so on its own the model won't know which skills exist or
-   their triggers. You must supply a discovery path. Two options, and they differ
-   in durability: (a) generate a skill index (each `skills/*/SKILL.md`'s `name` +
-   `description` frontmatter) and place it *inside* the `<EXTREMELY_IMPORTANT>`
-   wrapper alongside the tool mapping (Shape B recipe above) so it's covered by
-   the dedup guard — but a build-time index goes stale as skills are added; or
-   (b) instruct the model to list `skills/*/SKILL.md` at runtime and read their
-   frontmatter to find a match — slower but never stale. Prefer (b) unless you
-   have a reason not to. Without either, a no-skill-system port loads the
-   bootstrap but silently never triggers any other skill.
-
-In cases 2 and 3, say plainly in your tool mapping that reading `SKILL.md` is the
-blessed path, so the model doesn't think it's violating the "never read skill
-files" rule. Don't go hunting for a `skillPaths`-style registration API in a
-harness that has no skill system — case 3 has none.
-
-### Step 6 — Add tests
-
-Match the existing per-harness test style:
-
-- **Shape A:** assert the hook's stdout has the exact JSON shape your harness
-  consumes, and that it contains the bootstrap. See `tests/hooks/test-session-start.sh`,
-  which validates each harness's output shape.
-- **Shape B:** a unit test that fakes the harness's plugin API and asserts the
-  lifecycle handlers register, the bootstrap injects once, the dedup guard
-  works, and (if relevant) compaction re-injection works. See
-  `tests/pi/test-pi-extension.mjs`. Add an isolated-install integration check in
-  the style of `tests/opencode/`.
-- If the bootstrap is cached, test that the cache behaves when the file is
-  missing (see the OpenCode caching tests).
-
-These automated tests cover the wiring; the live tmux run in Step 7 is what
-proves the integration actually triggers skills.
-
-### Step 7 — Install locally, then drive a live instance to verify
-
-You cannot confirm a port works by reading code. You have to run the harness with
-your in-progress port loaded and watch a real session — which is also how you
-produce the transcript the PR requires.
-
-**Install locally.** Point a *local* instance of the harness at your working
-tree, not a published build:
-
-- **Shape A / C:** install the plugin/extension from this repo's local path (or
-  symlink its directory into wherever the harness looks). Find the harness's
-  "install from a local directory / git checkout" path in its docs.
-- **Shape B:** register the local module — e.g. an `opencode.json` `plugin`
-  entry pointing at the local path, or pi resolving the `package.json` fields
-  from the repo.
-
-Reinstall after each change and restart the harness, since the bootstrap loads at
-startup.
-
-**Drive it with tmux.** Most harnesses are interactive REPLs/TUIs that can't be
-driven by piping stdin, so run the harness inside a detached tmux session and
-control it with `send-keys` / `capture-pane`. A harness may advertise a
-non-interactive "run one prompt" mode (e.g. `opencode run "..."`) — try it for the
-quick smoke check, but **don't depend on it**: these modes are frequently flaky,
-auth-gated, or trust-gated (one real harness's `--print` mode hung and timed out
-with no output every time). Be ready to do *everything*, including the smoke
-check, through tmux.
-
-**Clear the gates first, or tmux stalls silently.** Many harnesses block on
-first-run onboarding, a "do you trust this folder?" prompt, a sandbox mode, or a
-permission gate — and a detached tmux session will just sit there with no error
-while it waits. Before the run, pre-trust your scratch directory (in the harness's
-settings/config) or be prepared to answer those prompts via `send-keys`, and
-account for the harness's startup time in your first `sleep`.
-
-```bash
-# 1. Launch the harness detached, in a throwaway project dir
-mkdir -p /tmp/port-smoke
-tmux new-session -d -s port-test -c /tmp/port-smoke '<harness-launch-command>'
-
-# 2. Let it initialize — real TUIs take longer than you think (10s+ with a model
-#    handshake); tune this. THEN capture and clear any blocking modal before you
-#    type a prompt: first-run onboarding and "trust this folder?" are modal, so
-#    keystrokes sent during them select menu items instead of typing your prompt.
-sleep 12
-tmux capture-pane -t port-test -p          # onboarding / trust prompt? answer it via send-keys first
-# (e.g. tmux send-keys -t port-test Enter   # to accept a trust prompt — inspect before assuming)
-
-# 3. Smoke check: does the model know it has superpowers?
-#    Send the text and Enter as SEPARATE send-keys with a beat between them —
-#    sending them together races on some TUIs (Enter arrives before the text lands).
-tmux send-keys -t port-test 'What are your superpowers?'; sleep 0.4; tmux send-keys -t port-test Enter
-sleep 5
-tmux capture-pane -t port-test -p          # reply should show it knows its skills
-
-# 4. Acceptance test: exact prompt (note the escaped apostrophe), fresh session
-tmux send-keys -t port-test 'Let'\''s make a react todo list'; sleep 0.4; tmux send-keys -t port-test Enter
-# poll until the turn finishes — re-capture every few seconds, don't capture once
-sleep 8
-tmux capture-pane -t port-test -p          # PASS = brainstorming triggers BEFORE any code
-
-# 5. Save the transcript for the PR, then clean up
-tmux capture-pane -t port-test -p > /tmp/port-smoke/transcript.txt
-tmux kill-session -t port-test
-```
-
-tmux gotchas that bite here: wait after launch before the first capture; send the
-prompt text and `Enter` as *separate* `send-keys` calls with a short `sleep`
-between them (sending them together races on some TUIs), and `Enter` is a key name
-not `\n`; the agent's turn takes time, so **poll `capture-pane` in a loop** rather
-than capturing once; `capture-pane` shows only the visible pane, so for a long
-conversation use the harness's own transcript/log file as the record of truth;
-always `kill-session` when done.
-
-If the smoke check shows the model *doesn't* know it has superpowers, the
-bootstrap isn't loading — fix that before bothering with the acceptance test.
-
----
-
-## Part 6 — Distribution and release
-
-A working integration in this repo isn't usable until a real user can install
-it. Distribution differs per harness ecosystem — find yours:
-
-| Channel | Example | What you do |
-|---|---|---|
-| Native plugin marketplace | Claude Code | Register in `.claude-plugin/marketplace.json`; users `/plugin install`. The external `superpowers-marketplace` repo is the source of truth users install from — see the release steps in `CLAUDE.md`. |
-| External marketplace fork, synced by script | Codex | `scripts/sync-to-codex-plugin.sh` rsyncs the tracked plugin files into a separate fork repo and opens a PR. Read its include/exclude list so you ship the right tree (it deliberately drops repo-internal dirs and other harnesses' dotdirs). |
-| Git-URL extension install | Gemini, Kimi Code, OpenCode | Users install from a git URL (`gemini extensions install …`; Kimi Code `/plugins install …`; an `opencode.json` `plugin` array entry). Document the exact command. |
-| Package-manifest fields | pi | Declared through fields in the repo-root `package.json`; users install via the harness's package command. |
-| Local installer (plugin install) | Antigravity (`agy`) | A small `install.sh` that runs the harness's own `agy plugin install` against a staging dir holding the manifest, the skills, and a generated `contextFileName` context file (the bootstrap). Everything arrives through the install mechanism — *not* by editing the user's config (see below). |
-
-Then:
-
-- **A plugin installer may silently strip *undeclared* files — so make the
-  bootstrap a file the installer *recognizes*, never a user-config edit.** A
-  `plugin install` typically copies only the components it knows about
-  (skills/agents/commands/mcp/hooks/context) and discards anything else, so a
-  context file the manifest doesn't declare just vanishes from the install. The
-  fix is **not** to give up and write into the user's config (**rule 2**) — it's
-  to declare the bootstrap as a recognized component. In escalation order:
-  - **Ship a context file the manifest declares.** If the harness has a
-    `contextFileName`-style field (an extension-declared file it loads every
-    session), that is the strongest clean bootstrap: declare it, and the installer
-    preserves it *and* the harness loads it. Generate it at install time from the
-    live `using-superpowers/SKILL.md` + the tool mapping (wrapped in
-    `<EXTREMELY_IMPORTANT>`) so the installed bootstrap never drifts. This is what
-    `.antigravity-plugin/install.sh` does — `agy plugin install` reports
-    `✔ context : ANTIGRAVITY.md`, and a clean session reads `using-superpowers`'s
-    SKILL.md, loads `brainstorming`, and enters the brainstorming flow before any
-    code. **Verify with a marker** that the installer keeps the file and the
-    harness loads it: one porter wrongly concluded it couldn't, because they
-    shipped the file *without* declaring `contextFileName` and it was stripped as
-    unrecognized.
-  - **Otherwise lean on the installed `using-superpowers` skill itself.** If the
-    harness surfaces each installed skill's name + description at session start,
-    the `using-superpowers` description ("Use when starting any conversation…")
-    can prompt the model to load it — installing the skill *is* the bootstrap.
-    Softer (no guaranteed wrapper; it carries triggering but not the tool mapping
-    — see Step 5), so prefer the declared context file when available.
-  - If neither works, the harness cannot be cleanly supported yet — **say so**
-    and raise it, rather than hand-editing the user's config.
-
-- **Write install docs.** A `docs/README.<harness>.md` and/or a
-  `.<harness>/INSTALL.md` (see `docs/README.opencode.md` and
-  `.opencode/INSTALL.md`), plus an install section in the top-level `README.md`.
-  The only supported install action is **running the harness's own install
-  command** (`agy plugin install`, `gemini extensions install`, `/plugin
-  install`, etc.). Hand-copying skill files and editing the user's global/personal
-  config are *both* off-limits (rule 2 / the PR rules). If the harness has no
-  install command at all — its only surface is a user-owned config file — then it
-  fails the "deliver via install mechanism" rule, and you should raise that rather
-  than ship an installer that edits the user's files.
-- **Register the version.** If your harness introduces a *new* versioned
-  manifest, add its path and version field to `.version-bump.json` so
-  `scripts/bump-version.sh` keeps it in lockstep (read that file to see what's
-  currently tracked). A new manifest that isn't registered there will ship a
-  stale version. If your harness instead rides an already-tracked file — pi
-  declares itself in the repo-root `package.json`, which is already listed —
-  there's nothing new to add.
-- **If no existing channel fits, you're standing up a new one.** None of the four
-  rows may match your harness. If it needs a Codex-style external fork sync,
-  `scripts/sync-to-codex-plugin.sh` is the template to clone (note its anchored
-  include/exclude list and its PR automation). And whenever you add a new
-  per-harness directory, add it to the *other* harnesses' sync excludes (e.g. the
-  EXCLUDES list in `sync-to-codex-plugin.sh`) so your dotdir doesn't leak into
-  their distributions.
-
----
-
-## Part 7 — Cross-platform / Windows
-
-Only relevant to the shell-hook shape. `hooks/run-hook.cmd` is a polyglot: a
-single file that's valid as both a Windows batch script and a Unix shell script.
-On Windows, `cmd.exe` runs the batch portion, which locates `bash` (Git for
-Windows, then `bash` on PATH) and runs the named hook script; if no bash is
-found it exits cleanly so the harness still works, just without injection. On
-Unix, the leading `:` makes the batch block a no-op and the shell runs the
-script directly.
-
-Two rules this enforces, which you must respect:
-
-- **Hook scripts are extensionless** (`session-start`, not `session-start.sh`).
-  Claude Code's Windows handling prepends `bash` to any command containing
-  `.sh`, which would double-invoke. Name your hook script without an extension.
-- Don't write per-OS variants of the hook script. One extensionless bash script
-  plus the polyglot wrapper covers all three platforms.
-
-`hooks/run-hook.cmd` itself is the authoritative implementation — read it. See
-`docs/windows/polyglot-hooks.md` for the background and rationale behind the
-dispatcher pattern.
-
----
-
-## Part 8 — Submitting the PR
-
-- Target the **`dev`** branch. One harness per PR.
-- Fill in the PR template's **"New harness support"** section and paste the
-  complete acceptance-test transcript (the "Let's make a react todo list"
-  session showing `brainstorming` auto-triggering). A PR without this proof will
-  be closed.
-- Superpowers is a zero-dependency plugin. Don't add a third-party runtime
-  dependency. Adding a new harness is the one carve-out the contributor rules
-  allow, and even then keep it to what the integration strictly requires —
-  type-only imports that compile away are fine; runtime packages are not.
-- Don't touch skill bodies (Part 1). If you found yourself editing a `SKILL.md`
-  to make the port work, the fix belongs in your tool mapping instead.
-
----
-
-## Appendix A — Reference integrations (current)
-
-Use this as the live index; when in doubt, read the files, not this table.
-
-| Harness | Entry point | Bootstrap mechanism | Tool mapping | Tests | Distribution |
-|---|---|---|---|---|---|
-| Claude Code | `.claude-plugin/plugin.json` + `hooks/hooks.json` | shell hook → `hooks/session-start` (`hookSpecificOutput.additionalContext`) | native `Skill` tool; `references/claude-code-tools.md` | `tests/hooks/` | marketplace |
-| Codex | `.codex-plugin/plugin.json` + `hooks/hooks-codex.json` | shell hook → `hooks/session-start-codex` | `references/codex-tools.md` | `tests/codex-plugin-sync/`, `tests/hooks/` | fork sync (`scripts/sync-to-codex-plugin.sh`) |
-| Cursor | `.cursor-plugin/plugin.json` + `hooks/hooks-cursor.json` | shell hook → `hooks/session-start` (`additional_context`) | `references/claude-code-tools.md` | `tests/hooks/` | hand-authored |
-| Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | `references/copilot-tools.md` | `tests/hooks/` | — |
-| Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |
-| Kimi Code | `.kimi-plugin/plugin.json` | manifest `sessionStart.skill` loads `using-superpowers` | inline `skillInstructions` in manifest | `tests/kimi/` | marketplace or `/plugins install` GitHub URL |
-| OpenCode | `.opencode/plugins/superpowers.js` (declared via root `package.json` `main`) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` plugin git URL |
-| pi | `.pi/extensions/superpowers.ts` | in-process: `resources_discover` registers skills; `context` event injects user message; lifecycle-flag + compaction-aware | `piToolMapping()` inline **and** `references/pi-tools.md` | `tests/pi/` | repo-root `package.json` fields |
-
-## Appendix B — Gotchas that have bitten porters
-
-- **Opt-in isn't a port.** If your human partner has to do anything per session
-  to get Superpowers, the acceptance test fails. Re-read Part 2.
-- **Wrong JSON field → silent failure or double injection.** Shape A only.
-  Confirm the exact field/nesting; Claude Code reads two fields without dedup.
-- **Hook-config schema varies per harness.** Shape A. Cursor's `hooks-cursor.json`
-  looks nothing like the Claude/Codex one (`version`, lowercase `sessionStart`,
-  relative command, no `matcher`/`type`/`async`). Match the closest existing file.
-- **Plugin-root env var differs per harness.** Shape A. The hook command uses
-  `${CLAUDE_PLUGIN_ROOT}` (Claude), `${PLUGIN_ROOT}` (Codex), or a relative path
-  (Cursor). Use what your harness exports; the script re-derives the root itself.
-- **System-message injection.** Shape B injects a *user* message on purpose
-  (#750, #894). Don't "fix" it to a system message.
-- **Per-step vs per-turn callbacks.** OpenCode fires every step (per-call dedup
-  guard); pi fires per turn (lifecycle flag + `agent_end` reset). Copying one
-  harness's dedup strategy onto the other's callback frequency breaks injection.
-- **Message-object shape is per-harness.** Shape B. pi and OpenCode use
-  incompatible shapes; discover yours, don't copy a reference's object literal.
-- **Hunting for a skill-registration API that doesn't exist.** A harness with no
-  skill system (not just no `Skill` tool) has nothing to register — the model
-  reads `SKILL.md` on demand. Don't assume a `skillPaths` equivalent exists.
-- **Mapping in two places.** For in-process plugins the mapping may live both
-  inline and in a `references/` file (pi). Update both.
-- **The "never read skill files" line.** It means "don't bypass your platform's
-  skill-loading mechanism," not "never use file-read." On a no-skill-tool harness
-  that mechanism *is* reading `SKILL.md` — say so explicitly in the mapping
-  (Part 5).
-- **`.sh` on Windows.** Keep hook scripts extensionless (Part 7).
-- **Unregistered version.** A new manifest not added to `.version-bump.json`
-  ships stale (Part 6).
-- **Editing skills to fit the harness.** Never. The fix goes in the tool mapping.

docs/superpowers/plans/2026-05-07-pi-extension-and-evals.md

@@ -1,143 +0,0 @@
-# Pi Extension and Evals Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add first-class Pi package support for Superpowers and add Pi as a Drill eval backend.
-
-**Architecture:** The Pi package is declared in the root `package.json` and loads existing `skills/` plus a small Pi extension. The extension injects the `using-superpowers` bootstrap into provider context as a user-role message on session startup and after compaction, with Pi-specific tool mapping. Drill gains a `pi` backend, Pi session-log normalization, and tests.
-
-**Tech Stack:** Pi TypeScript extension API, Node built-in test runner, Drill Python eval harness, pytest.
-
----
-
-### Task 1: Pi package manifest and extension tests
-
-**Files:**
-- Modify: `package.json`
-- Create: `tests/pi/test-pi-extension.mjs`
-
-- [ ] **Step 1: Write failing package/extension tests**
-
-Create `tests/pi/test-pi-extension.mjs` with tests that import `extensions/superpowers.ts`, register fake Pi handlers, and assert:
-- root `package.json` has `keywords` containing `pi-package`
-- root `package.json` has `pi.skills: ["./skills"]`
-- root `package.json` has `pi.extensions: ["./extensions/superpowers.ts"]`
-- the extension registers `resources_discover`, `session_start`, `session_compact`, `context`, and `agent_end`
-- startup `context` injects exactly one user-role bootstrap message
-- `agent_end` clears startup injection
-- `session_compact` re-enables injection
-- the extension does not register `session_before_compact`
-
-- [ ] **Step 2: Run tests and verify RED**
-
-Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
-
-Expected: FAIL because `extensions/superpowers.ts` does not exist and `package.json` lacks the `pi` manifest.
-
-- [ ] **Step 3: Implement manifest fields**
-
-Update `package.json` with `description`, `keywords`, `pi.extensions`, and `pi.skills` while preserving existing `name`, `version`, `type`, and `main`.
-
-- [ ] **Step 4: Implement `extensions/superpowers.ts`**
-
-Create a zero-runtime-dependency extension that:
-- locates the package root from `import.meta.url`
-- reads `skills/using-superpowers/SKILL.md`
-- strips YAML frontmatter
-- appends Pi-specific tool mapping
-- exposes `resources_discover` with the skills path
-- marks bootstrap pending on `session_start` and `session_compact`
-- injects a user-role bootstrap message in `context`
-- inserts post-compact bootstrap after leading `compactionSummary` messages
-- clears pending bootstrap on `agent_end`
-
-- [ ] **Step 5: Run tests and verify GREEN**
-
-Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
-
-Expected: PASS.
-
-### Task 2: Pi tool mapping reference
-
-**Files:**
-- Create: `skills/using-superpowers/references/pi-tools.md`
-- Modify: `tests/pi/test-pi-extension.mjs`
-
-- [ ] **Step 1: Write failing test for Pi reference doc**
-
-Add assertions that `skills/using-superpowers/references/pi-tools.md` exists and documents mappings for `Skill`, `Task`, `TodoWrite`, and built-in tool names.
-
-- [ ] **Step 2: Run tests and verify RED**
-
-Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
-
-Expected: FAIL because `pi-tools.md` does not exist.
-
-- [ ] **Step 3: Add Pi reference doc**
-
-Create `skills/using-superpowers/references/pi-tools.md` explaining Pi-native skills, optional `pi-subagents`, no canonical todo/tasklist plugin, and built-in lowercase tools.
-
-- [ ] **Step 4: Run tests and verify GREEN**
-
-Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
-
-Expected: PASS.
-
-### Task 3: Drill Pi backend and session log normalization
-
-**Files:**
-- Create: `evals/backends/pi.yaml`
-- Modify: `evals/drill/backend.py`
-- Modify: `evals/drill/engine.py`
-- Modify: `evals/drill/normalizer.py`
-- Modify: `evals/tests/test_backend.py`
-- Modify: `evals/tests/test_normalizer.py`
-
-- [ ] **Step 1: Write failing backend/normalizer tests**
-
-Add pytest coverage for:
-- `load_backend("pi")` returns `family == "pi"`
-- Pi backend command starts with `pi` and includes `-e ${SUPERPOWERS_ROOT}`
-- `_resolve_log_dir()` for Pi points under `~/.pi/agent/sessions`
-- `filter_pi_logs_by_cwd()` keeps only session files whose header `cwd` matches the scenario workdir
-- `normalize_pi_logs()` extracts `toolCall` blocks from Pi assistant session entries and maps built-in lowercase tools to canonical names
-
-- [ ] **Step 2: Run tests and verify RED**
-
-Run: `uv run pytest evals/tests/test_backend.py evals/tests/test_normalizer.py -q`
-
-Expected: FAIL because the Pi backend and normalizer do not exist.
-
-- [ ] **Step 3: Add `evals/backends/pi.yaml`**
-
-Configure the backend to run `pi -e ${SUPERPOWERS_ROOT}`, use permissive TUI readiness, `/quit` shutdown, and Pi session log location.
-
-- [ ] **Step 4: Implement Pi family support**
-
-Update `Backend.family`, `Engine._resolve_log_dir`, `Engine._collect_tool_calls`, and `normalizer.py` with Pi log filtering and normalizing.
-
-- [ ] **Step 5: Run tests and verify GREEN**
-
-Run: `uv run pytest evals/tests/test_backend.py evals/tests/test_normalizer.py -q`
-
-Expected: PASS.
-
-### Task 4: Documentation and full verification
-
-**Files:**
-- Modify: `README.md`
-- Modify: `evals/README.md`
-
-- [ ] **Step 1: Document Pi install and eval backend**
-
-Add Pi to README quickstart/install list and add backend entry/usage to `evals/README.md`.
-
-- [ ] **Step 2: Run verification**
-
-Run:
-```bash
-node --experimental-strip-types --test tests/pi/test-pi-extension.mjs
-uv run pytest evals/tests/test_backend.py evals/tests/test_setup.py evals/tests/test_normalizer.py -q
-```
-
-Expected: all tests pass.

docs/superpowers/specs/2026-05-05-platform-neutral-config-refs-design.md

@@ -1,77 +0,0 @@
-# Platform-neutral config-file references — Phase B design
-
-## Background
-
-Phase A (see `2026-05-05-platform-neutral-prose-design.md`) replaced generic third-person "Claude" prose with agent-neutral forms. This phase tackles the next category: references to the per-platform instruction file (CLAUDE.md, AGENTS.md, GEMINI.md) inside skills.
-
-The plugin runs on multiple harnesses, and each one reads its own instruction file. Where a skill names CLAUDE.md as if it were the only file, that's a Claude-Code-centric assumption that doesn't hold on Codex / Gemini CLI / OpenCode.
-
-## In scope
-
-Two specific lines in active skills:
-
-1. **`skills/writing-skills/SKILL.md:58`** — `Project-specific conventions (put in CLAUDE.md)`
-2. **`skills/receiving-code-review/SKILL.md:30`** — `"You're absolutely right!" (explicit CLAUDE.md violation)`
-
-## Out of scope
-
-- **`skills/using-superpowers/SKILL.md:22, 26`** — instruction-priority list. The list already names all three (CLAUDE.md, GEMINI.md, AGENTS.md) inclusively, which is correct: the section is making a real claim about *what counts as user instruction* on a multi-platform plugin. No change needed.
-- **Historical / example artifacts**:
-  - `skills/systematic-debugging/CREATION-LOG.md` — attribution path (`~/.claude/CLAUDE.md`) is a historical fact.
-  - `skills/writing-skills/examples/CLAUDE_MD_TESTING.md` — the entire file is a worked example testing CLAUDE.md content variants. The filename, body, and the reference from `testing-skills-with-subagents.md` all stay; normalizing them defeats the example.
-- **Platform-tooling references** — Phase D candidates:
-  - `skills/using-superpowers/SKILL.md:40` (Gemini CLI tool mapping note about GEMINI.md)
-  - `skills/using-superpowers/references/gemini-tools.md` (`save_memory` persists to GEMINI.md)
-
-## Substitution rules
-
-Two distinct calls, one per in-scope line.
-
-### Rule 1: "where to put project-specific conventions"
-
-`writing-skills/SKILL.md:58`:
-
-- **Before:** `Project-specific conventions (put in CLAUDE.md)`
-- **After:** `Project-specific conventions (put in your instructions file)`
-
-Use a generic phrase rather than picking one filename. Different harnesses read different files (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) and the skill should not assume one. The platform-tools reference docs (`references/{codex,copilot,gemini}-tools.md`) are the right place to name each platform's preferred file.
-
-### Rule 2: the "(explicit CLAUDE.md violation)" parenthetical
-
-`receiving-code-review/SKILL.md:30`:
-
-- **Before:** `"You're absolutely right!" (explicit CLAUDE.md violation)`
-- **After:** `"You're absolutely right!" (explicit instruction-file violation)`
-
-The parenthetical is doing real work — it signals this phrase isn't just stylistically bad, it actively violates rules many users put in their instruction files. "Instruction file" is the natural cross-platform term covering AGENTS.md / CLAUDE.md / GEMINI.md collectively, and keeps the original signal without picking one filename or softening to "common".
-
-## Commit plan
-
-Atomic commits, in order:
-
-1. **`writing-skills/SKILL.md`** — CLAUDE.md → "your instructions file" in the "where to put project conventions" line
-2. **`receiving-code-review/SKILL.md`** — CLAUDE.md → instruction-file in the violation parenthetical
-3. **Platform-tools reference docs** — add the preferred per-platform instructions filename (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) to each `references/{codex,copilot,gemini}-tools.md` so readers can resolve "your instructions file" to a real filename.
-
-Each commit message names "Phase B" and the slice.
-
-## Verification
-
-After each commit:
-
-- Read the surrounding paragraph to confirm grammar and meaning still parse.
-- `grep -n "CLAUDE\.md" <touched-file>` — no remaining hits in active prose (carve-outs already documented).
-
-After both commits:
-
-- `grep -rn "CLAUDE\.md" skills/` should return only the documented carve-outs (CREATION-LOG, CLAUDE_MD_TESTING and its inbound reference, the priority list in using-superpowers).
-
-## Non-goals
-
-- Do not touch the priority list ordering in `using-superpowers/SKILL.md`. Reordering CLAUDE.md / GEMINI.md / AGENTS.md is an aesthetic change, not a substitution, and out of scope here.
-- Do not rename `examples/CLAUDE_MD_TESTING.md` or change its content.
-- Do not modify Gemini-CLI-specific tooling references (Phase D candidates).
-
-## Implementation note
-
-Phase B as written here covered three commits and the three non-Claude-Code platform-tools refs. Implementation went one step further: a fourth ref, `references/claude-code-tools.md`, was added in commit `8505703` for symmetry, so Claude Code's instructions-file conventions and tool-name list live alongside the others rather than implicitly in the surrounding skill prose. That addition wasn't anticipated in this spec but is consistent with its intent.

docs/superpowers/specs/2026-05-05-platform-neutral-prose-design.md

@@ -1,94 +0,0 @@
-# Platform-neutral prose — Phase A design
-
-## Background
-
-Superpowers ships to multiple agent runtimes (Claude Code, Codex, Cursor, OpenCode, Copilot CLI, Gemini CLI). Skill content and supporting docs were written first for Claude Code and use "Claude" in places where any runtime's agent applies. OpenAI's vendored fork (openai/plugins#217) attempted a wholesale rewrite that was actively wrong in places — rewriting historical attribution paths, model names, and platform-specific install instructions — and we want to avoid that mistake while still removing platform-centric prose where it is genuinely incidental.
-
-The full effort is broken into phases by reference category. **This spec covers Phase A only:** generic third-person prose mentioning "Claude" in non-platform-specific contexts. Later phases (config-file references, marketing copy, tool-name references) are out of scope here and will get their own specs.
-
-## In scope
-
-Generic prose mentions of "Claude" in:
-
-- `skills/*/SKILL.md` and supporting `.md` files in active skill directories
-- `skills/writing-skills/anthropic-best-practices.md`
-- `README.md` (only where the mention is generic prose, not platform marketing)
-
-Plus one coined-term rename: **Claude Search Optimization (CSO) → Skill Discovery Optimization (SDO)** in `skills/writing-skills/SKILL.md`.
-
-## Out of scope
-
-- **Platform/runtime statements** — "In Claude Code:", install instructions, tool-mapping references. (Phase D candidate.)
-- **Config-file references** — CLAUDE.md, AGENTS.md, GEMINI.md priority lists and "where to put project conventions" callouts. (Phase B.)
-- **Tool-name references** — `Skill`, `Bash`, `Read`, `Task`, `TodoWrite`. Skills are written in Claude Code's tool vocabulary; the existing `references/{codex,copilot,gemini}-tools.md` files map them. (At the time this spec was written, the plan was to defer or skip these. Phase E ended up doing them — replacing tool names with action language across active skills and unifying the platform-tools refs around the same vocabulary.)
-- **Marketing copy** in README — "Superpowers for Claude Code", platform-named install sections. (Phase C.)
-- **Historical artifacts** — `docs/plans/*.md`, `docs/superpowers/specs/*.md`, `CREATION-LOG.md`. These are dated, point-in-time documents; rewriting them rewrites history.
-- **Model identifiers** — Claude Haiku / Sonnet / Opus. These are real product names.
-- **Filename / URL references** — `CLAUDE.md`, `claude.com`, `claude-plugin/`, paths under `~/.claude/`.
-- **`anthropic-best-practices.md` filename** — the file remains named after its source even though we rewrite the prose inside it.
-
-## Replacement style
-
-Use a mix that reads naturally in English:
-
-- **Second person — "your agent"** when addressing the skill author about *their* runtime
-  - "your agent reads the description"
-- **Third person — "the agent" / "agents" / "an agent"** when describing system behavior generically
-  - "Future agents find your skills"
-  - "Use words an agent would search for"
-  - "Agents read SKILL.md only when the skill becomes relevant"
-
-Pick whichever fits the surrounding sentence; do not force consistency at the cost of awkward phrasing. Pluralize when natural ("future agents", "agents read") rather than always saying "the agent".
-
-### Carve-outs that stay as "Claude"
-
-- Model names: Claude Haiku, Claude Sonnet, Claude Opus
-- Filenames and URLs: `CLAUDE.md`, `claude.com`, `~/.claude/`
-- Branded platform name "Claude Code" wherever it refers to the runtime as such (handled in later phases)
-
-### Coined-term rename
-
-- **Claude Search Optimization (CSO) → Skill Discovery Optimization (SDO)**
-  - Appears in `skills/writing-skills/SKILL.md` as a section heading and in nearby prose. Rename the heading, the acronym, and any in-file cross-references.
-
-## Files affected
-
-Approximate counts based on a `grep` filtered to exclude carve-outs:
-
-| File | Generic-prose mentions |
-|------|------------------------|
-| `skills/writing-skills/SKILL.md` | ~12 (includes CSO heading + body) |
-| `skills/writing-skills/anthropic-best-practices.md` | ~30 |
-| `skills/writing-skills/examples/CLAUDE_MD_TESTING.md` | ~1 — filename stays (it's a CLAUDE.md test artifact); the "Variant C: Claude.AI Emphatic Style" heading also stays (it's a label naming a specific style) |
-| `README.md` | ~1 |
-
-Final list confirmed during implementation by re-running the filtered grep.
-
-## Commit plan
-
-Four atomic commits, in order:
-
-1. **Rename CSO → SDO** in `skills/writing-skills/SKILL.md`. Mechanical, isolated, easy to revert if we change our minds about the term.
-2. **Active skills prose** — generic "Claude" → "agent" forms across `skills/*/SKILL.md` and supporting `.md`, excluding `anthropic-best-practices.md`.
-3. **`anthropic-best-practices.md` prose** — same substitution rules. Separate commit because this file is a vendored adaptation of an external doc; isolating the change makes future reconciliation with upstream easier to read.
-4. **README.md prose** *(only if any generic-prose mentions remain after filtering)*. Skipped if empty.
-
-Each commit message names the phase ("Phase A") and the slice ("rename CSO to SDO", "agent prose in active skills", etc.) so the series is self-documenting.
-
-## Verification
-
-After each commit:
-
-- `grep -rn "Claude" <touched-paths>` — every remaining hit must fall into a documented carve-out (model name, filename, URL, "Claude Code" platform name, historical artifact).
-- Read the touched file end-to-end — substitutions should not have broken sentence flow, pronoun agreement, or list parallelism.
-- No tests to run; this is prose-only.
-
-After the final commit:
-
-- Skim each modified skill in a live session to confirm nothing reads awkwardly.
-
-## Non-goals
-
-- Do not change behavior, structure, headings (other than CSO→SDO), examples, code blocks, or YAML frontmatter.
-- Do not introduce new sections, callouts, or compatibility notes.
-- Do not "improve" prose beyond the substitution while editing.

docs/superpowers/specs/2026-05-05-platform-neutral-readme-design.md

@@ -1,47 +0,0 @@
-# Platform-neutral README ordering — Phase C design
-
-## Background
-
-Phases A and B (see `2026-05-05-platform-neutral-prose-design.md` and `2026-05-05-platform-neutral-config-refs-design.md`) already neutralized generic Claude prose and config-file references in the README. The remaining platform-leaning signal is layout: the README's two platform listings put Claude Code first and aren't strictly alphabetical elsewhere.
-
-This phase fixes the ordering. No prose changes.
-
-## In scope
-
-1. **Quickstart platform list** (`README.md:7`) — the inline link list of supported harnesses
-2. **Installation section ordering** (`README.md:35–152`) — the per-harness install sub-sections
-
-## Out of scope
-
-- Prose, marketplace names, plugin IDs, URLs — all factually correct as-is.
-- Visual weight of the Claude Code section (which has two sub-sections — official Anthropic marketplace and Superpowers marketplace). Both are real install paths; collapsing them would hide accurate info.
-- Section headings and content within each install block — only the ordering of the blocks changes.
-
-## Substitution
-
-Both listings reorder to strict alphabetical:
-
-| Old order | New order |
-|-----------|-----------|
-| Claude Code | Claude Code |
-| Codex CLI | Codex App |
-| Codex App | Codex CLI |
-| Factory Droid | Cursor |
-| Gemini CLI | Factory Droid |
-| OpenCode | Gemini CLI |
-| Cursor | GitHub Copilot CLI |
-| GitHub Copilot CLI | OpenCode |
-
-Three moves: Codex App swaps with Codex CLI; Cursor moves up two slots; GitHub Copilot CLI moves up one.
-
-Claude Code remains first by alphabetical chance (`Cl…` precedes `Co…`).
-
-## Commit plan
-
-One atomic commit covering both listings, since changing one without the other would create inconsistency between the quickstart and the installation section.
-
-## Verification
-
-- Quickstart anchors (`#claude-code`, `#codex-app`, etc.) still resolve to existing `### …` headings — no headings renamed.
-- Each install sub-section's body is byte-identical pre/post; only positions changed.
-- `git diff README.md` shows section moves only, no content edits.

docs/testing.md

@@ -12,10 +12,9 @@ Live in `tests/`. Currently:
 - `tests/brainstorm-server/` — node test suite for the brainstorm server JS code.
 - `tests/opencode/` — bash tests for OpenCode plugin loading, bootstrap caching, and tool registration.
 - `tests/codex-plugin-sync/` — bash sync verification.
-- `tests/kimi/` — bash/Python checks for Kimi plugin manifest wiring.
 - `tests/claude-code/test-helpers.sh`, `analyze-token-usage.py` — utilities used by remaining bash tests.
 - `tests/claude-code/test-subagent-driven-development.sh` — agent-can-describe-SDD test (no drill counterpart; tests description-recall, not behavior).
-- `tests/claude-code/test-subagent-driven-development-integration.sh` — extended SDD integration with token analysis (drill covers the YAGNI subset; bash adds commit-count, Claude Code task-tracking, and token telemetry assertions).
+- `tests/claude-code/test-subagent-driven-development-integration.sh` — extended SDD integration with token analysis (drill covers the YAGNI subset; bash adds commit-count, TodoWrite, and token telemetry assertions).
 - `tests/claude-code/test-worktree-native-preference.sh` — RED-GREEN-REFACTOR validation for worktree skill (drill covers the PRESSURE phase; bash also covers RED/GREEN baselines).
 - `tests/explicit-skill-requests/` — Haiku-specific, multi-turn, and skill-name-prompted tests not covered by drill.
 

docs/windows/polyglot-hooks.md

@@ -1,8 +1,6 @@
 # Cross-Platform Polyglot Hooks for Claude Code
 
-Claude Code plugins need hooks that work on Windows, macOS, and Linux. This document describes the single generic dispatcher pattern used in `hooks/run-hook.cmd`.
-
-> **Authoritative source:** `hooks/run-hook.cmd` is the canonical implementation. When this document and the code diverge, trust the code.
+Claude Code plugins need hooks that work on Windows, macOS, and Linux. This document explains the polyglot wrapper technique that makes this possible.
 
 ## The Problem
 
@@ -12,22 +10,52 @@ Claude Code runs hook commands through the system's default shell:
 
 This creates several challenges:
 
-1. **Script execution**: Windows CMD can't execute `.sh` files directly
+1. **Script execution**: Windows CMD can't execute `.sh` files directly - it tries to open them in a text editor
 2. **Path format**: Windows uses backslashes (`C:\path`), Unix uses forward slashes (`/path`)
 3. **Environment variables**: `$VAR` syntax doesn't work in CMD
-4. **`.sh` auto-prepend**: Claude Code on Windows automatically prepends `bash` to any command that contains `.sh` in its path — this interferes with the dispatcher if scripts have extensions
+4. **No `bash` in PATH**: Even with Git Bash installed, `bash` isn't in the PATH when CMD runs
 
-## The Solution: Extensionless Scripts + Single Generic Dispatcher
+## The Solution: Polyglot `.cmd` Wrapper
 
-The repo uses one generic `run-hook.cmd` dispatcher for all hooks. Hook scripts are **extensionless** (`session-start`, not `session-start.sh`). This is deliberate: it prevents Claude Code's Windows auto-detection from prepending `bash` to the dispatcher command and breaking it.
+A polyglot script is valid syntax in multiple languages simultaneously. Our wrapper is valid in both CMD and bash:
 
-### File Structure
+```cmd
+: << 'CMDBLOCK'
+@echo off
+"C:\Program Files\Git\bin\bash.exe" -l -c "\"$(cygpath -u \"$CLAUDE_PLUGIN_ROOT\")/hooks/session-start.sh\""
+exit /b
+CMDBLOCK
+
+# Unix shell runs from here
+"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+```
+
+### How It Works
+
+#### On Windows (CMD.exe)
+
+1. `: << 'CMDBLOCK'` - CMD sees `:` as a label (like `:label`) and ignores `<< 'CMDBLOCK'`
+2. `@echo off` - Suppresses command echoing
+3. The bash.exe command runs with:
+   - `-l` (login shell) to get proper PATH with Unix utilities
+   - `cygpath -u` converts Windows path to Unix format (`C:\foo` → `/c/foo`)
+4. `exit /b` - Exits the batch script, stopping CMD here
+5. Everything after `CMDBLOCK` is never reached by CMD
+
+#### On Unix (bash/sh)
+
+1. `: << 'CMDBLOCK'` - `:` is a no-op, `<< 'CMDBLOCK'` starts a heredoc
+2. Everything until `CMDBLOCK` is consumed by the heredoc (ignored)
+3. `# Unix shell runs from here` - Comment
+4. The script runs directly with the Unix path
+
+## File Structure
 
 ```
 hooks/
-├── hooks.json          # Points to run-hook.cmd with extensionless script name
-├── run-hook.cmd        # Cross-platform dispatcher (the polyglot wrapper)
-└── session-start       # Actual hook logic — extensionless bash script
+├── hooks.json           # Points to the .cmd wrapper
+├── session-start.cmd    # Polyglot wrapper (cross-platform entry point)
+└── session-start.sh     # Actual hook logic (bash script)
 ```
 
 ### hooks.json
@@ -37,12 +65,11 @@ hooks/
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|clear|compact",
+        "matcher": "startup|resume|clear|compact",
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
-            "async": false
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.cmd\""
           }
         ]
       }
@@ -51,63 +78,41 @@ hooks/
 }
 ```
 
-The path is quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces.
+Note: The path must be quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces on Windows (e.g., `C:\Program Files\...`).
 
-## How `run-hook.cmd` Works at a High Level
+## Requirements
 
-`run-hook.cmd` is a polyglot script: Windows treats the first block as batch
-commands, while Unix shells treat that block as a no-op heredoc and continue
-after it.
+### Windows
+- **Git for Windows** must be installed (provides `bash.exe` and `cygpath`)
+- Default installation path: `C:\Program Files\Git\bin\bash.exe`
+- If Git is installed elsewhere, the wrapper needs modification
 
-Do not copy an implementation from this document. Read `hooks/run-hook.cmd`
-directly when changing the dispatcher, and run `tests/hooks/test-session-start.sh`
-afterward.
-
-### How it works on Windows (CMD.exe)
-
-1. The batch section validates the script name and resolves the hook directory
-   from the dispatcher's own location.
-2. It tries bash in three places:
-   - `C:\Program Files\Git\bin\bash.exe`
-   - `C:\Program Files (x86)\Git\bin\bash.exe`
-   - `bash` on `PATH` (MSYS2, Cygwin, or a non-default Git install)
-3. If bash is found, it runs the named extensionless hook script from the hooks
-   directory.
-4. If no bash is found, the dispatcher exits `0` silently — the plugin
-   continues working, it just skips the hook.
-5. `exit /b` stops CMD before it reaches the Unix section.
-
-### How it works on Unix (bash/sh)
-
-1. `: << 'CMDBLOCK'` opens a heredoc on a no-op command.
-2. The entire CMD batch block is consumed by the heredoc and ignored.
-3. After `CMDBLOCK`, bash resolves the script directory and `exec`s the named
-   extensionless script directly.
-
-### Key design decisions
-
-| Decision | Why |
-|----------|-----|
-| Extensionless scripts | Prevents Claude Code's Windows `.sh`-auto-prepend from interfering with the dispatcher command |
-| No `-l` (login shell) | Not needed; hook scripts should be self-contained and not depend on login-shell PATH setup |
-| No `cygpath` | Bash receives the Windows path directly and handles it correctly; `cygpath` was needed by the old `-c "..."` invocation pattern, not by direct exec |
-| Silent exit on no-bash | Avoids breaking the plugin for users who don't have Git for Windows; hook context injection is skipped gracefully |
+### Unix (macOS/Linux)
+- Standard bash or sh shell
+- The `.cmd` file must have execute permission (`chmod +x`)
 
 ## Writing Cross-Platform Hook Scripts
 
-Your hook logic goes in the extensionless script file. A few portable patterns:
+Your actual hook logic goes in the `.sh` file. To ensure it works on Windows (via Git Bash):
 
-### Do
+### Do:
 - Use pure bash builtins when possible
 - Use `$(command)` instead of backticks
 - Quote all variable expansions: `"$VAR"`
+- Use `printf` or here-docs for output
 
-### Avoid
-- Relying on PATH-dependent tools without fallbacks (the hook runs without `-l`, so login-shell PATH is not set)
-- Giving scripts a `.sh` extension — this triggers Claude Code's Windows auto-prepend
+### Avoid:
+- External commands that may not be in PATH (sed, awk, grep)
+- If you must use them, they're available in Git Bash but ensure PATH is set up (use `bash -l`)
 
-### Example: JSON escaping without external tools
+### Example: JSON Escaping Without sed/awk
 
+Instead of:
+```bash
+escaped=$(echo "$content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
+```
+
+Use pure bash:
 ```bash
 escape_for_json() {
     local input="$1"
@@ -128,21 +133,80 @@ escape_for_json() {
 }
 ```
 
+## Reusable Wrapper Pattern
+
+For plugins with multiple hooks, you can create a generic wrapper that takes the script name as an argument:
+
+### run-hook.cmd
+```cmd
+: << 'CMDBLOCK'
+@echo off
+set "SCRIPT_DIR=%~dp0"
+set "SCRIPT_NAME=%~1"
+"C:\Program Files\Git\bin\bash.exe" -l -c "cd \"$(cygpath -u \"%SCRIPT_DIR%\")\" && \"./%SCRIPT_NAME%\""
+exit /b
+CMDBLOCK
+
+# Unix shell runs from here
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
+```
+
+### hooks.json using the reusable wrapper
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" validate-bash.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## Troubleshooting
 
 ### "bash is not recognized"
+CMD can't find bash. The wrapper uses the full path `C:\Program Files\Git\bin\bash.exe`. If Git is installed elsewhere, update the path.
 
-CMD couldn't find bash in any of the three locations the dispatcher tries. The dispatcher exits silently (0) rather than erroring, so the hook is skipped. Install Git for Windows at the standard path or ensure `bash` is on `PATH`.
+### "cygpath: command not found" or "dirname: command not found"
+Bash isn't running as a login shell. Ensure `-l` flag is used.
 
-### Hook runs on Unix but does nothing on Windows
+### Path has weird `\/` in it
+`${CLAUDE_PLUGIN_ROOT}` expanded to a Windows path ending with backslash, then `/hooks/...` was appended. Use `cygpath` to convert the entire path.
 
-Check that the script filename is **extensionless** in `hooks.json`. A command like `run-hook.cmd session-start.sh` can trigger Claude Code's `.sh` auto-detection and bypass the intended CMD dispatcher path, or just try to run a non-existent `session-start.sh` script.
+### Script opens in text editor instead of running
+The hooks.json is pointing directly to the `.sh` file. Point to the `.cmd` wrapper instead.
 
-### Hook doesn't fire at all
-
-Verify the `matcher` in `hooks.json` matches the event type your harness emits. Claude Code uses `startup|clear|compact`; Codex uses `startup|resume|clear`. Check `hooks-codex.json` for the Codex variant.
+### Works in terminal but not as hook
+Claude Code may run hooks differently. Test by simulating the hook environment:
+```powershell
+$env:CLAUDE_PLUGIN_ROOT = "C:\path\to\plugin"
+cmd /c "C:\path\to\plugin\hooks\session-start.cmd"
+```
 
 ## Related Issues
 
-- [anthropics/claude-code#9758](https://github.com/anthropics/claude-code/issues/9758) — `.sh` scripts open in editor on Windows
-- [anthropics/claude-code#3417](https://github.com/anthropics/claude-code/issues/3417) — Hooks don't work on Windows
+- [anthropics/claude-code#9758](https://github.com/anthropics/claude-code/issues/9758) - .sh scripts open in editor on Windows
+- [anthropics/claude-code#3417](https://github.com/anthropics/claude-code/issues/3417) - Hooks don't work on Windows
+- [anthropics/claude-code#6023](https://github.com/anthropics/claude-code/issues/6023) - CLAUDE_PROJECT_DIR not found

hooks/hooks-codex.json

@@ -1,16 +0,0 @@
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup|resume|clear",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start-codex",
-            "async": false
-          }
-        ]
-      }
-    ]
-  }
-}

hooks/session-start

@@ -7,6 +7,13 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 
+# Check if legacy skills directory exists and build warning
+warning_message=""
+legacy_skills_dir="${HOME}/.config/superpowers/skills"
+if [ -d "$legacy_skills_dir" ]; then
+    warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.claude/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
+fi
+
 # Read using-superpowers content
 using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
 
@@ -24,7 +31,8 @@ escape_for_json() {
 }
 
 using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
-session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n</EXTREMELY_IMPORTANT>"
+warning_escaped=$(escape_for_json "$warning_message")
+session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
 
 # Output context injection as JSON.
 # Cursor hooks expect additional_context (snake_case).
@@ -37,13 +45,13 @@ session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the
 # See: https://github.com/obra/superpowers/issues/571
 if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
   # Cursor sets CURSOR_PLUGIN_ROOT (may also set CLAUDE_PLUGIN_ROOT)
-  printf '{\n  "additional_context": "%s"\n}\n' "$session_context" | cat
+  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
 elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
   # Claude Code sets CLAUDE_PLUGIN_ROOT without COPILOT_CLI
-  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context" | cat
+  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
 else
   # Copilot CLI (sets COPILOT_CLI=1) or unknown platform — SDK standard format
-  printf '{\n  "additionalContext": "%s"\n}\n' "$session_context" | cat
+  printf '{\n  "additionalContext": "%s"\n}\n' "$session_context"
 fi
 
 exit 0

hooks/session-start-codex

@@ -1,26 +0,0 @@
-#!/usr/bin/env bash
-# Codex SessionStart hook for superpowers plugin
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-
-using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
-
-escape_for_json() {
-    local s="$1"
-    s="${s//\\/\\\\}"
-    s="${s//\"/\\\"}"
-    s="${s//$'\n'/\\n}"
-    s="${s//$'\r'/\\r}"
-    s="${s//$'\t'/\\t}"
-    printf '%s' "$s"
-}
-
-using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
-session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, follow the Codex skill-loading instructions in that skill:**\n\n${using_superpowers_escaped}\n</EXTREMELY_IMPORTANT>"
-
-printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context" | cat
-
-exit 0

package.json

@@ -1,23 +1,6 @@
 {
   "name": "superpowers",
   "version": "5.1.0",
-  "description": "Superpowers skills and runtime bootstrap for coding agents",
   "type": "module",
-  "main": ".opencode/plugins/superpowers.js",
-  "keywords": [
-    "pi-package",
-    "skills",
-    "tdd",
-    "debugging",
-    "collaboration",
-    "workflow"
-  ],
-  "pi": {
-    "extensions": [
-      "./.pi/extensions/superpowers.ts"
-    ],
-    "skills": [
-      "./skills"
-    ]
-  }
+  "main": ".opencode/plugins/superpowers.js"
 }

scripts/lint-shell.sh

@@ -1,211 +0,0 @@
-#!/usr/bin/env bash
-#
-# Lint shell scripts in this repository.
-#
-# Usage:
-#   scripts/lint-shell.sh [--all] [--format] [--strict] [file ...]
-#
-# By default, runs ShellCheck and shell syntax checks on changed shell scripts.
-# Use --format to format with shfmt before linting. Use --all for the full tracked
-# baseline, or pass files explicitly to lint a smaller set.
-set -euo pipefail
-
-usage() {
-  sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'
-}
-
-die() {
-  echo "error: $*" >&2
-  exit 1
-}
-
-require_tool() {
-  command -v "$1" >/dev/null 2>&1 || die "required tool '$1' is not on PATH"
-}
-
-is_shell_file() {
-  local path="$1"
-  local first_line=""
-
-  [[ -f "$path" ]] || return 1
-
-  case "$path" in
-    *.sh)
-      return 0
-      ;;
-  esac
-
-  IFS= read -r first_line <"$path" || true
-  [[ "$first_line" =~ ^#!.*[/[:space:]](bash|dash|ksh|sh)([[:space:]]|$) ]]
-}
-
-ensure_git_work_tree() {
-  git rev-parse --is-inside-work-tree >/dev/null 2>&1 \
-    || die "run this from inside a git work tree, or pass files explicitly"
-}
-
-add_shell_file() {
-  local path
-  local existing
-
-  path="$1"
-  if ! is_shell_file "$path"; then
-    return 0
-  fi
-
-  if [[ "${#files[@]}" -gt 0 ]]; then
-    for existing in "${files[@]}"; do
-      if [[ "$existing" == "$path" ]]; then
-        return 0
-      fi
-    done
-  fi
-
-  files+=("$path")
-}
-
-collect_all_shell_files() {
-  local path
-
-  ensure_git_work_tree
-
-  while IFS= read -r -d '' path; do
-    add_shell_file "$path"
-  done < <(git ls-files -z)
-}
-
-collect_changed_shell_files() {
-  local path
-
-  ensure_git_work_tree
-
-  if git rev-parse --verify HEAD >/dev/null 2>&1; then
-    while IFS= read -r -d '' path; do
-      add_shell_file "$path"
-    done < <(git diff --name-only -z --diff-filter=ACMR HEAD)
-
-    while IFS= read -r -d '' path; do
-      add_shell_file "$path"
-    done < <(git diff --cached --name-only -z --diff-filter=ACMR)
-  else
-    collect_all_shell_files
-  fi
-
-  while IFS= read -r -d '' path; do
-    add_shell_file "$path"
-  done < <(git ls-files --others --exclude-standard -z)
-}
-
-collect_requested_shell_files() {
-  local path
-
-  for path in "$@"; do
-    add_shell_file "$path"
-  done
-}
-
-syntax_shell_for() {
-  local path="$1"
-  local first_line=""
-
-  IFS= read -r first_line <"$path" || true
-
-  case "$first_line" in
-    *"/sh"* | *" env sh"* | *"/dash"* | *" env dash"*)
-      printf 'sh'
-      ;;
-    *)
-      printf 'bash'
-      ;;
-  esac
-}
-
-run_syntax_checks() {
-  local file
-  local shell_name
-
-  for file in "$@"; do
-    shell_name="$(syntax_shell_for "$file")"
-    case "$shell_name" in
-      sh)
-        sh -n "$file"
-        ;;
-      bash)
-        bash -n "$file"
-        ;;
-      *)
-        die "unsupported shell for syntax check: $shell_name"
-        ;;
-    esac
-  done
-}
-
-format=false
-strict=false
-all=false
-requested_files=()
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --all)
-      all=true
-      ;;
-    --format)
-      format=true
-      ;;
-    --strict)
-      strict=true
-      ;;
-    -h | --help)
-      usage
-      exit 0
-      ;;
-    --)
-      shift
-      requested_files+=("$@")
-      break
-      ;;
-    -*)
-      die "unknown option: $1"
-      ;;
-    *)
-      requested_files+=("$1")
-      ;;
-  esac
-  shift
-done
-
-require_tool shellcheck
-if [[ "$format" == true ]]; then
-  require_tool shfmt
-fi
-
-files=()
-if [[ "${#requested_files[@]}" -gt 0 ]]; then
-  collect_requested_shell_files "${requested_files[@]}"
-elif [[ "$all" == true ]]; then
-  collect_all_shell_files
-else
-  collect_changed_shell_files
-fi
-
-if [[ "${#files[@]}" -eq 0 ]]; then
-  echo "No shell files found."
-  exit 0
-fi
-
-if [[ "$format" == true ]]; then
-  echo "Formatting ${#files[@]} shell files"
-  shfmt_args=(-i 2 -ci -bn)
-  shfmt "${shfmt_args[@]}" -w "${files[@]}"
-fi
-
-echo "Linting ${#files[@]} shell files"
-
-shellcheck_args=(--severity=warning --external-sources --source-path=SCRIPTDIR)
-if [[ "$strict" == true ]]; then
-  shellcheck_args+=("--enable=check-extra-masked-returns,check-set-e-suppressed,quote-safe-variables,deprecate-which,avoid-nullary-conditions")
-fi
-
-shellcheck "${shellcheck_args[@]}" "${files[@]}"
-run_syntax_checks "${files[@]}"

scripts/sync-to-codex-plugin.sh

@@ -52,9 +52,7 @@ EXCLUDES=(
   "/.gitattributes"
   "/.github/"
   "/.gitignore"
-  "/.kimi-plugin/"
   "/.opencode/"
-  "/.pi/"
   "/.version-bump.json"
   "/.worktrees/"
   ".DS_Store"
@@ -72,6 +70,7 @@ EXCLUDES=(
   "/commands/"
   "/docs/"
   "/evals/"
+  "/hooks/"
   "/lib/"
   "/scripts/"
   "/tests/"
@@ -421,7 +420,7 @@ if [[ $BOOTSTRAP -eq 1 ]]; then
   COMMIT_TITLE="bootstrap superpowers v$UPSTREAM_VERSION from upstream main @ $UPSTREAM_SHORT"
   PR_BODY="Initial bootstrap of the superpowers plugin from upstream \`main\` @ \`$UPSTREAM_SHORT\` (v$UPSTREAM_VERSION).
 
-Creates \`plugins/superpowers/\` by copying the tracked plugin files from upstream, including \`.codex-plugin/plugin.json\`, \`assets/\`, and \`hooks/\`.
+Creates \`plugins/superpowers/\` by copying the tracked plugin files from upstream, including \`.codex-plugin/plugin.json\` and \`assets/\`.
 
 Run via: \`scripts/sync-to-codex-plugin.sh --bootstrap\`
 Upstream commit: https://github.com/obra/superpowers/commit/$UPSTREAM_SHA
@@ -431,7 +430,7 @@ else
   COMMIT_TITLE="sync superpowers v$UPSTREAM_VERSION from upstream main @ $UPSTREAM_SHORT"
   PR_BODY="Automated sync from superpowers upstream \`main\` @ \`$UPSTREAM_SHORT\` (v$UPSTREAM_VERSION).
 
-Copies the tracked plugin files from upstream, including the committed Codex manifest, assets, and hooks.
+Copies the tracked plugin files from upstream, including the committed Codex manifest and assets.
 
 Run via: \`scripts/sync-to-codex-plugin.sh\`
 Upstream commit: https://github.com/obra/superpowers/commit/$UPSTREAM_SHA

skills/brainstorming/SKILL.md

@@ -26,7 +26,7 @@ You MUST create a task for each of these items and complete them in order:
 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 (exactly this path — not `docs/specs/`)
+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
@@ -109,7 +109,6 @@ digraph brainstorming {
 **Documentation:**
 
 - Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
-  - The `docs/superpowers/` prefix is the convention; do not shorten it to `docs/specs/`
   - (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

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 #frame-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; }
-    #frame-content { padding: 2rem; min-height: 100%; }
+    #claude-content { padding: 2rem; min-height: 100%; }
 
     .indicator-bar {
       background: var(--bg-secondary);
@@ -201,7 +201,7 @@
   </div>
 
   <div class="main">
-    <div id="frame-content">
+    <div id="claude-content">
       <!-- CONTENT -->
     </div>
   </div>

skills/brainstorming/scripts/server.cjs

@@ -7,7 +7,6 @@ const path = require('path');
 
 const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
 const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
-const MAX_FRAME_PAYLOAD_BYTES = 10 * 1024 * 1024;
 
 function computeAcceptKey(clientKey) {
   return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
@@ -54,18 +53,10 @@ function decodeFrame(buffer) {
     offset = 4;
   } else if (payloadLen === 127) {
     if (buffer.length < 10) return null;
-    const extendedLen = buffer.readBigUInt64BE(2);
-    if (extendedLen > BigInt(MAX_FRAME_PAYLOAD_BYTES)) {
-      throw new Error('WebSocket frame payload exceeds maximum allowed size');
-    }
-    payloadLen = Number(extendedLen);
+    payloadLen = Number(buffer.readBigUInt64BE(2));
     offset = 10;
   }
 
-  if (payloadLen > MAX_FRAME_PAYLOAD_BYTES) {
-    throw new Error('WebSocket frame payload exceeds maximum allowed size');
-  }
-
   const maskOffset = offset;
   const dataOffset = offset + 4;
   const totalLen = dataOffset + payloadLen;
@@ -360,4 +351,4 @@ if (require.main === module) {
   startServer();
 }
 
-module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES, MAX_FRAME_PAYLOAD_BYTES };
+module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };

skills/brainstorming/scripts/start-server.sh

@@ -107,23 +107,10 @@ if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then
   OWNER_PID="$PPID"
 fi
 
-# Windows/MSYS2: Node.js cannot see POSIX PIDs from the MSYS2 namespace.
-# Passing a PID node cannot verify causes server to log owner-pid-invalid
-# and self-terminate at the 60-second lifecycle check. Clear it so the
-# watchdog is disabled and the idle timeout becomes the only shutdown trigger.
-case "${OSTYPE:-}" in
-  msys*|cygwin*|mingw*) OWNER_PID="" ;;
-esac
-if [[ -n "${MSYSTEM:-}" ]]; then
-  OWNER_PID=""
-fi
-
 # Foreground mode for environments that reap detached/background processes.
 if [[ "$FOREGROUND" == "true" ]]; then
-  env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs &
-  SERVER_PID=$!
-  echo "$SERVER_PID" > "$PID_FILE"
-  wait "$SERVER_PID"
+  echo "$$" > "$PID_FILE"
+  env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs
   exit $?
 fi
 

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

@@ -7,7 +7,7 @@ Use this template when dispatching a spec document reviewer subagent.
 **Dispatch after:** Spec document is written to docs/superpowers/specs/
 
 ```
-Subagent (general-purpose):
+Task tool (general-purpose):
   description: "Review spec document"
   prompt: |
     You are a spec document reviewer. Verify this spec is complete and ready for planning.

skills/brainstorming/visual-companion.md

@@ -49,13 +49,20 @@ Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.
 
 **Launching the server by platform:**
 
-**Claude Code:**
+**Claude Code (macOS / Linux):**
 ```bash
-# Default mode works — the script backgrounds the server itself.
+# Default mode works — the script backgrounds the server itself
 scripts/start-server.sh --project-dir /path/to/project
 ```
 
-On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
+**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
+# across conversation turns.
+scripts/start-server.sh --project-dir /path/to/project
+```
+When calling this via the Bash tool, set `run_in_background: true`. Then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
 
 **Codex:**
 ```bash
@@ -71,14 +78,6 @@ scripts/start-server.sh --project-dir /path/to/project
 scripts/start-server.sh --project-dir /path/to/project --foreground
 ```
 
-**Copilot CLI:**
-```bash
-# Use --foreground and start the server via the bash tool with mode: "async"
-# so the process survives across turns. Capture the returned shellId for
-# read_bash / stop_bash if you need to interact with it later.
-scripts/start-server.sh --project-dir /path/to/project --foreground
-```
-
 **Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
 
 If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
@@ -98,7 +97,7 @@ Use `--url-host` to control what hostname is printed in the returned URL JSON.
    - Before each write, check that `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
    - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
    - **Never reuse filenames** — each screen gets a fresh file
-   - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
    - Server automatically serves the newest file
 
 2. **Tell user what to expect and end your turn:**

skills/dispatching-parallel-agents/SKILL.md

@@ -65,17 +65,14 @@ Each agent gets:
 
 ### 3. Dispatch in Parallel
 
-Issue all three subagent dispatches in the same response — they run in parallel:
-
-```text
-Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
-Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
-Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
-# All three run concurrently.
+```typescript
+// 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")
+// All three run concurrently
 ```
 
-Multiple dispatch calls in one response = parallel execution. One per response = sequential.
-
 ### 4. Review and Integrate
 
 When agents return:

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 (Claude Code, Codex CLI, Codex App, Copilot CLI, and Gemini CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). 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
 
@@ -19,7 +19,7 @@ Load plan, review critically, execute all tasks, report when complete.
 1. Read plan file
 2. Review critically - identify any questions or concerns about the plan
 3. If concerns: Raise them with your human partner before starting
-4. If no concerns: Create todos for the plan items and proceed
+4. If no concerns: Create TodoWrite and proceed
 
 ### Step 2: Execute Tasks
 

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

@@ -123,6 +123,16 @@ git branch -d <feature-branch>
 ```bash
 # Push branch
 git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
 ```
 
 **Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.

skills/receiving-code-review/SKILL.md

@@ -27,7 +27,7 @@ WHEN receiving code review feedback:
 ## Forbidden Responses
 
 **NEVER:**
-- "You're absolutely right!" (explicit instruction-file violation)
+- "You're absolutely right!" (explicit CLAUDE.md violation)
 - "Great point!" / "Excellent feedback!" (performative)
 - "Let me implement that now" (before verification)
 

skills/requesting-code-review/SKILL.md

@@ -31,7 +31,7 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 **2. Dispatch code reviewer subagent:**
 
-Dispatch a `general-purpose` subagent, filling the template at [code-reviewer.md](code-reviewer.md)
+Use Task tool with `general-purpose` type, fill template at `code-reviewer.md`
 
 **Placeholders:**
 - `{DESCRIPTION}` - Brief summary of what you built
@@ -100,4 +100,4 @@ You: [Fix progress indicators]
 - Show code/tests that prove it works
 - Request clarification
 
-See template at: [code-reviewer.md](code-reviewer.md)
+See template at: requesting-code-review/code-reviewer.md

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

@@ -5,7 +5,7 @@ Use this template when dispatching a code reviewer subagent.
 **Purpose:** Review completed work against requirements and code quality standards before it cascades into more work.
 
 ```
-Subagent (general-purpose):
+Task tool (general-purpose):
   description: "Review code changes"
   prompt: |
     You are a Senior Code Reviewer with expertise in software architecture,
@@ -14,26 +14,22 @@ Subagent (general-purpose):
 
     ## What Was Implemented
 
-    [DESCRIPTION]
+    {DESCRIPTION}
 
     ## Requirements / Plan
 
-    [PLAN_OR_REQUIREMENTS]
+    {PLAN_OR_REQUIREMENTS}
 
     ## Git Range to Review
 
-    **Base:** [BASE_SHA]
-    **Head:** [HEAD_SHA]
+    **Base:** {BASE_SHA}
+    **Head:** {HEAD_SHA}
 
     ```bash
-    git diff --stat [BASE_SHA]..[HEAD_SHA]
-    git diff [BASE_SHA]..[HEAD_SHA]
+    git diff --stat {BASE_SHA}..{HEAD_SHA}
+    git diff {BASE_SHA}..{HEAD_SHA}
     ```
 
-    ## Read-Only Review
-
-    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
-
     ## What to Check
 
     **Plan alignment:**
@@ -126,10 +122,10 @@ Subagent (general-purpose):
 ```
 
 **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
+- `{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
 

skills/subagent-driven-development/SKILL.md

@@ -57,15 +57,15 @@ digraph process {
         "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
         "Code quality reviewer subagent approves?" [shape=diamond];
         "Implementer subagent fixes quality issues" [shape=box];
-        "Mark task complete in todo list" [shape=box];
+        "Mark task complete in TodoWrite" [shape=box];
     }
 
-    "Read plan, extract all tasks with full text, note context, create todos" [shape=box];
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
     "More tasks remain?" [shape=diamond];
     "Dispatch final code reviewer subagent for entire implementation" [shape=box];
     "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
 
-    "Read plan, extract all tasks with full text, note context, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
     "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
     "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
     "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
@@ -78,8 +78,8 @@ digraph process {
     "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
     "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
     "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
-    "Code quality reviewer subagent approves?" -> "Mark task complete in todo list" [label="yes"];
-    "Mark task complete in todo list" -> "More tasks remain?";
+    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
+    "Mark task complete in TodoWrite" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
     "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
     "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
@@ -121,9 +121,9 @@ Implementer subagents report one of four statuses. Handle each appropriately:
 
 ## Prompt Templates
 
-- [implementer-prompt.md](implementer-prompt.md) - Dispatch implementer subagent
-- [spec-reviewer-prompt.md](spec-reviewer-prompt.md) - Dispatch spec compliance reviewer subagent
-- [code-quality-reviewer-prompt.md](code-quality-reviewer-prompt.md) - Dispatch code quality reviewer subagent
+- `./implementer-prompt.md` - Dispatch implementer subagent
+- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
+- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
 
 ## Example Workflow
 
@@ -132,7 +132,7 @@ You: I'm using Subagent-Driven Development to execute this plan.
 
 [Read plan file once: docs/superpowers/plans/feature-plan.md]
 [Extract all 5 tasks with full text and context]
-[Create todos for all tasks]
+[Create TodoWrite with all tasks]
 
 Task 1: Hook installation script
 

skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -7,8 +7,8 @@ Use this template when dispatching a code quality reviewer subagent.
 **Only dispatch after spec compliance review passes.**
 
 ```
-Subagent (general-purpose):
-  Use template at ../requesting-code-review/code-reviewer.md
+Task tool (general-purpose):
+  Use template at requesting-code-review/code-reviewer.md
 
   DESCRIPTION: [task summary, from implementer's report]
   PLAN_OR_REQUIREMENTS: Task N from [plan-file]

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

@@ -3,7 +3,7 @@
 Use this template when dispatching an implementer subagent.
 
 ```
-Subagent (general-purpose):
+Task tool (general-purpose):
   description: "Implement Task N: [task name]"
   prompt: |
     You are implementing Task N: [task name]
@@ -103,9 +103,6 @@ Subagent (general-purpose):
     - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
     - What you implemented (or what you attempted, if blocked)
     - What you tested and test results
-    - **TDD Evidence** (if TDD was required for this task):
-      - RED: command run, relevant failing output before implementation, and why the failure was expected
-      - GREEN: command run and relevant passing output after implementation
     - Files changed
     - Self-review findings (if any)
     - Any issues or concerns

skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -5,7 +5,7 @@ Use this template when dispatching a spec compliance reviewer subagent.
 **Purpose:** Verify implementer built what was requested (nothing more, nothing less)
 
 ```
-Subagent (general-purpose):
+Task tool (general-purpose):
   description: "Review spec compliance for Task N"
   prompt: |
     You are reviewing whether an implementation matches its specification.
@@ -18,22 +18,6 @@ Subagent (general-purpose):
 
     [From implementer's report]
 
-    ## Git Range to Review
-
-    **Base:** [BASE_SHA — commit before this task]
-    **Head:** [HEAD_SHA — current commit]
-
-    ```bash
-    git diff --stat [BASE_SHA]..[HEAD_SHA]
-    git diff [BASE_SHA]..[HEAD_SHA]
-    ```
-
-    Only read files in this diff. Do not crawl the broader codebase.
-
-    ## Read-Only Review
-
-    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
-
     ## CRITICAL: Do Not Trust the Report
 
     The implementer finished suspiciously quickly. Their report may be incomplete,

skills/systematic-debugging/SKILL.md

@@ -237,7 +237,7 @@ If you catch yourself thinking:
 - "Is that not happening?" - You assumed without verifying
 - "Will it show us...?" - You should have added evidence gathering
 - "Stop guessing" - You're proposing fixes without understanding
-- "Ultra-think this" - Question fundamentals, not just symptoms
+- "Ultrathink this" - Question fundamentals, not just symptoms
 - "We're stuck?" (frustrated) - Your approach isn't working
 
 **When you see these:** STOP. Return to Phase 1.

skills/using-superpowers/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-superpowers
-description: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
+description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
 ---
 
 <SUBAGENT-STOP>
@@ -27,13 +27,9 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw
 
 ## How to Access Skills
 
-**Never read skill files manually with file tools** — always use your platform's skill-loading mechanism so the skill is properly activated.
+**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 Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you — follow it directly.
-
-**In Codex:** Skills load natively. Follow the instructions presented when a skill activates.
-
-**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins.
+**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.
 
@@ -41,7 +37,7 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw
 
 ## Platform Adaptation
 
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), [pi-tools.md](references/pi-tools.md), and [antigravity-tools.md](references/antigravity-tools.md). 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
 
@@ -52,30 +48,30 @@ Skills speak in actions ("dispatch a subagent", "create a todo", "read a file")
 ```dot
 digraph skill_flow {
     "User message received" [shape=doublecircle];
-    "About to enter plan mode?" [shape=doublecircle];
+    "About to EnterPlanMode?" [shape=doublecircle];
     "Already brainstormed?" [shape=diamond];
     "Invoke brainstorming skill" [shape=box];
     "Might any skill apply?" [shape=diamond];
-    "Invoke the skill" [shape=box];
+    "Invoke Skill tool" [shape=box];
     "Announce: 'Using [skill] to [purpose]'" [shape=box];
     "Has checklist?" [shape=diamond];
-    "Create a todo per item" [shape=box];
+    "Create TodoWrite todo per item" [shape=box];
     "Follow skill exactly" [shape=box];
     "Respond (including clarifications)" [shape=doublecircle];
 
-    "About to enter plan mode?" -> "Already brainstormed?";
+    "About to EnterPlanMode?" -> "Already brainstormed?";
     "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
     "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
     "Invoke brainstorming skill" -> "Might any skill apply?";
 
     "User message received" -> "Might any skill apply?";
-    "Might any skill apply?" -> "Invoke the skill" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
     "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
-    "Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
+    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
     "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
-    "Has checklist?" -> "Create a todo per item" [label="yes"];
+    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
     "Has checklist?" -> "Follow skill exactly" [label="no"];
-    "Create a todo per item" -> "Follow skill exactly";
+    "Create TodoWrite todo per item" -> "Follow skill exactly";
 }
 ```
 
@@ -102,15 +98,15 @@ These thoughts mean STOP—you're rationalizing:
 
 When multiple skills could apply, use this order:
 
-1. **Process skills first** (brainstorming, systematic-debugging) - these determine HOW to approach the task
+1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
 2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
 
 "Let's build X" → brainstorming first, then implementation skills.
-"Fix this bug" → systematic-debugging first, then domain-specific skills.
+"Fix this bug" → debugging first, then domain-specific skills.
 
 ## Skill Types
 
-**Rigid** (TDD, systematic-debugging): Follow exactly. Don't adapt away discipline.
+**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.
 
 **Flexible** (patterns): Adapt principles to context.
 

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

@@ -1,96 +0,0 @@
-# Antigravity CLI (`agy`) Tool Mapping
-
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On the Antigravity CLI (`agy`) these resolve to the tools below.
-
-| Action skills request | Antigravity CLI equivalent |
-|----------------------|----------------------|
-| Read a file | `view_file` |
-| Create a new file | `write_to_file` |
-| Edit a file | `replace_file_content` |
-| Edit a file in several places at once | `multi_replace_file_content` |
-| Run a shell command | `run_command` |
-| Search file contents | `grep_search` |
-| Find files by name / list a directory | `list_dir` (no dedicated glob tool — combine `list_dir` with `grep_search`) |
-| Fetch a URL | `read_url_content` |
-| Search the web | `search_web` |
-| Pose a structured question to your human partner | `ask_question` |
-| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName` — `self` for full-capability work, `research` for read-only (see [Subagent support](#subagent-support)) |
-| Multiple parallel dispatches | Multiple entries in one `invoke_subagent` call's `Subagents` array |
-| Task tracking ("create a todo", "mark complete") | a **task artifact** — `write_to_file` with `IsArtifact: true` and `ArtifactType: "task"` (see [Task tracking](#task-tracking)). **Not** `manage_task`, which manages background processes. |
-
-## Invoking a skill — read its `SKILL.md`
-
-Antigravity surfaces every installed skill's `name` + `description` to you at the
-start of each session, but it has **no `Skill`/`activate_skill` tool**. To load a
-skill, **read its `SKILL.md` with `view_file`, setting `IsSkillFile: true`** when
-the skill applies — e.g. `view_file` on
-`.../plugins/superpowers/skills/<skill-name>/SKILL.md` with `IsSkillFile: true`.
-(`IsSkillFile` is agy's own signal that you're reading a file to *execute its
-instructions*, not to edit or preview it — set it whenever you load a skill.)
-
-This is the blessed skill-loading mechanism on this harness. The general rule
-"never read skill files manually" means "don't bypass your platform's
-skill-loading mechanism" — and on Antigravity, reading `SKILL.md` *is* that
-mechanism. Reading it honors the rule rather than breaking it.
-
-You already know which skills exist and what they're for: their names and
-descriptions are in front of you at session start. When a description matches
-what you're about to do, read that skill's `SKILL.md` before acting.
-
-## Subagent support
-
-Antigravity dispatches subagents with `invoke_subagent`, passing each one a
-`TypeName` in the `Subagents` array. Two `TypeName`s are **built in** — use them
-directly, no `define_subagent` needed:
-
-- **`self`** — a full clone of you, with every tool you have (including
-  `write_to_file`/`replace_file_content`/`run_command`). The safe default for
-  general-purpose work: implementing, fixing, anything that edits files or runs
-  commands.
-- **`research`** — read-only (file reading, `grep_search`, web/URL fetch; no write
-  or command access). Use it when you specifically want a subagent that can't make
-  changes — investigation and read-only review.
-
-Call `define_subagent` only for a custom system prompt or capability mix: set
-`enable_write_tools: true` to grant file edits **and** `run_command`,
-`enable_subagent_tools` for nested dispatch, `enable_mcp_tools` for MCP. Then
-invoke it by the name you gave it. (`manage_subagents` lists/kills running
-subagents.)
-
-Skills dispatch with `Subagent (general-purpose):` and either reference a
-prompt-template file (e.g. `superpowers:subagent-driven-development`'s
-`./implementer-prompt.md`) or supply an inline prompt. On Antigravity:
-
-| Skill dispatch form | Antigravity equivalent |
-|---------------------|----------------------|
-| An implementer-style `*-prompt.md` template (writes code, runs tests) | Fill the template, then `invoke_subagent` with `TypeName: "self"` and the filled prompt |
-| A read-only reviewer template (`spec-reviewer`, `code-quality-reviewer`, `code-reviewer`, `requesting-code-review`'s `./code-reviewer.md`) | `invoke_subagent` with `TypeName: "research"` and the filled review template |
-| Inline prompt (no template referenced) | `invoke_subagent` with `TypeName: "self"` (or `"research"` if the task only reads) and your inline prompt |
-
-### Prompt filling
-
-Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or
-`[FULL TEXT of task]`. Fill all placeholders before passing the complete prompt to
-`invoke_subagent`. The prompt template itself contains the agent's role, review
-criteria, and expected output format — the subagent will follow it.
-
-### Parallel dispatch
-
-Put multiple entries in a single `invoke_subagent` call's `Subagents` array to run
-independent subagent work in parallel. Keep dependent tasks sequential, but do not
-serialize independent subagent tasks just to preserve a simpler history.
-
-## Task tracking
-
-Antigravity has **no todo / `TodoWrite` tool** (`manage_task` manages background
-processes — `list`/`kill`/`status`/`send_input` — it is *not* a checklist). When a
-skill says to create a todo list or track tasks, maintain a **task artifact**: a
-markdown checklist saved with `write_to_file` (`IsArtifact: true`,
-`ArtifactMetadata.ArtifactType: "task"`), edited with `replace_file_content` /
-`multi_replace_file_content` as you go.
-
-At the start of any multi-step task, create the task artifact listing every step of
-your plan. As you complete each step, edit the artifact to mark it done (`- [x]`).
-If the plan changes, update the checklist. Keep it current — it is your source of
-truth for what remains; once the conversation gets long, re-read it before starting
-each step.

skills/using-superpowers/references/claude-code-tools.md

@@ -1,50 +0,0 @@
-# Claude Code Tool Mapping
-
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Claude Code these resolve to the tools below.
-
-## Tools
-
-| Action skills request | Claude Code tool |
-|----------------------|------------------|
-| Read a file | `Read` |
-| Create a new file | `Write` |
-| Edit a file | `Edit` |
-| Run a shell command | `Bash` |
-| Search file contents | `Grep` |
-| Find files by name | `Glob` |
-| Fetch a URL | `WebFetch` |
-| Search the web | `WebSearch` |
-| Invoke a skill | `Skill` |
-| Dispatch a subagent (`Subagent (general-purpose):` template) | `Agent` (older releases named this `Task`) |
-| Multiple parallel dispatches | Multiple `Agent` calls in one response |
-| Task tracking ("create a todo", "mark complete") | `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`; `TodoWrite` in `claude -p` / Agent SDK unless `CLAUDE_CODE_ENABLE_TASKS=1` is set |
-| Background-process / subagent lifecycle (read output, cancel) | `TaskOutput`, `TaskStop` — these are distinct from the todo tools above and apply to running shells, agents, and remote sessions |
-
-## Instructions file
-
-When a skill mentions "your instructions file", on Claude Code this is **`CLAUDE.md`**. Claude Code walks up the directory tree from the current working directory and concatenates every `CLAUDE.md` and `CLAUDE.local.md` it finds along the way. Standard locations:
-
-| Scope | Location |
-|-------|----------|
-| Project (team-shared) | `./CLAUDE.md` or `./.claude/CLAUDE.md` |
-| User global | `~/.claude/CLAUDE.md` |
-| Local-private (gitignored) | `./CLAUDE.local.md` |
-| Managed policy (org-wide) | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux/WSL), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) |
-
-CLAUDE.md files can pull in additional content with `@path/to/file` imports (relative or absolute, max five hops deep). Subdirectory `CLAUDE.md` files are also discovered automatically and loaded on-demand when Claude Code reads files in those subdirectories.
-
-Claude Code does **not** read `AGENTS.md` directly. If a project already maintains `AGENTS.md` for other agents, import it from `CLAUDE.md` so both runtimes share the same instructions:
-
-```markdown
-@AGENTS.md
-
-## Claude Code
-
-(Claude-Code-specific instructions go here.)
-```
-
-For path-scoped rules and larger-project organization, see `.claude/rules/` (rules can be scoped to specific files via `paths` frontmatter and load on demand).
-
-## Personal skills directory
-
-User-level skills live at **`~/.claude/skills/`**. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter) plus any supporting files. Claude Code does not currently recognize the cross-runtime `~/.agents/skills/` path that Codex, Copilot CLI, and Gemini CLI read; if you're relying on cross-runtime support in the future, verify against the [official skills docs](https://code.claude.com/docs/en/skills).

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

@@ -1,30 +1,17 @@
 # Codex Tool Mapping
 
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Codex these resolve to the tools below.
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
 
-| Action skills request | Codex equivalent |
-|----------------------|------------------|
-| Read a file | `shell` (e.g., `cat`, `head`, `tail`) — Codex reads files via shell |
-| Create / edit / delete a file | `apply_patch` (structured diff for create, update, delete) |
-| Run a shell command | `shell` |
-| Search file contents | `shell` (e.g., `grep`, `rg`) |
-| Find files by name | `shell` (e.g., `find`, `ls`) |
-| Fetch a URL | `shell` with `curl` / `wget` — Codex has no native fetch tool |
-| Search the web | `web_search` (enabled by default; configurable in `config.toml` via the top-level `web_search` setting — `live`, `cached`, or `disabled`) |
-| Invoke a skill | Skills load natively — just follow the instructions |
-| Dispatch a subagent (`Subagent (general-purpose):` template) | `spawn_agent` (see [Subagent dispatch requires multi-agent support](#subagent-dispatch-requires-multi-agent-support)) |
-| Multiple parallel dispatches | Multiple `spawn_agent` calls in one response |
-| Wait for subagent result | `wait_agent` |
-| Free up subagent slot when done | `close_agent` |
-| Task tracking ("create a todo", "mark complete") | `update_plan` |
-
-## Instructions file
-
-When a skill mentions "your instructions file", on Codex this is **`AGENTS.md`** at the project root. Codex also reads `~/.codex/AGENTS.md` for global context, and an `AGENTS.override.md` (in the project tree or `~/.codex/`) takes precedence when present. Codex walks from the project root down to the current working directory, concatenating `AGENTS.md` files it finds along the way, up to `project_doc_max_bytes` (32 KiB by default).
-
-## Personal skills directory
-
-User-level skills live at **`$CODEX_HOME/skills/`** (default `~/.codex/skills/`). Codex also reads the cross-runtime path **`~/.agents/skills/`** (shared with Copilot CLI and Gemini CLI). When both directories exist at the same scope, Codex loads them both as separate skill catalogs — Codex's docs don't currently document a precedence between them. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
+| 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
 

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

@@ -1,38 +1,31 @@
 # Copilot CLI Tool Mapping
 
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Copilot CLI these resolve to the tools below.
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
 
-| Action skills request | Copilot CLI equivalent |
-|----------------------|----------------------|
-| Read a file | `view` |
-| Create / edit / delete a file | `apply_patch` (Copilot CLI has no separate create/edit/write tools) |
-| Run a shell command | `bash` |
-| Search file contents | `rg` (ripgrep; Copilot CLI does not expose a `grep` tool) |
-| Find files by name | `glob` |
-| Fetch a URL | `web_fetch` |
-| Search the web | `web_search` |
-| Invoke a skill | `skill` |
-| Dispatch a subagent (`Subagent (general-purpose):` template) | `task` with `agent_type: "general-purpose"` (other accepted types: `explore`, `task`, `code-review`, `research`, `configure-copilot`) |
-| Multiple parallel dispatches | Multiple `task` calls in one response |
-| Subagent status/output/control | `read_agent`, `list_agents`, `write_agent` |
-| Task tracking ("create a todo", "mark complete") | `update_todo` |
-| Enter / exit plan mode | No equivalent — stay in the main session |
-
-## Instructions file
-
-When a skill mentions "your instructions file", on Copilot CLI this is **`AGENTS.md`** at the repository root. If both `AGENTS.md` and `.github/copilot-instructions.md` are present, Copilot reads both.
-
-## Personal skills directory
-
-User-level skills live at **`~/.copilot/skills/`**. Copilot CLI also recognizes the cross-runtime alias **`~/.agents/skills/`**, which is shared with Codex and Gemini CLI. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
+| 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:
+Copilot CLI supports persistent async shell sessions, which have no direct Claude Code equivalent:
 
 | Tool | Purpose |
 |------|---------|
-| `bash` with `mode: "async"` (and optionally `detach: true`) | Start a long-running command in the background; returns a `shellId` |
+| `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 |

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

@@ -1,63 +1,51 @@
 # Gemini CLI Tool Mapping
 
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Gemini CLI these resolve to the tools below.
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
 
-| Action skills request | Gemini CLI equivalent |
-|----------------------|----------------------|
-| Read a file | `read_file` |
-| Read multiple files at once | `read_many_files` |
-| Create a new file | `write_file` |
-| Edit a file | `replace` |
-| Run a shell command | `run_shell_command` |
-| Search file contents | `grep_search` |
-| Find files by name | `glob` |
-| List files and subdirectories | `list_directory` |
-| Fetch a URL | `web_fetch` |
-| Search the web | `google_web_search` |
-| Invoke a skill | `activate_skill` |
-| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_agent` with `agent_name: "generalist"` (invocable via `@generalist` chat syntax — see [Subagent support](#subagent-support)) |
-| Multiple parallel dispatches | Multiple `invoke_agent` calls in the same response |
-| Task tracking ("create a todo", "mark complete") | `write_todos` (statuses: pending, in_progress, completed, cancelled, blocked) |
-
-## Instructions file
-
-When a skill mentions "your instructions file", on Gemini CLI this is **`GEMINI.md`**. Gemini CLI loads `GEMINI.md` hierarchically: global at `~/.gemini/GEMINI.md`, project-level files in workspace directories and their ancestors, and sub-directory `GEMINI.md` files when a tool accesses files in those directories.
-
-## Personal skills directory
-
-User-level skills live at **`~/.gemini/skills/`**, with **`~/.agents/skills/`** as a cross-runtime alias (shared with Codex and Copilot CLI). When both directories exist at the same scope, `.agents/skills/` takes precedence. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
+| 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 dispatches subagents through the `invoke_agent` tool, which takes `agent_name` and `prompt` parameters. The same dispatch is also surfaced as a chat-syntax shortcut: typing `@generalist <prompt>` is equivalent to calling `invoke_agent` with `agent_name: "generalist"`. Built-in agent names include `generalist`, `cli_help`, `codebase_investigator`, and (with browser tooling enabled) `browser_agent`.
+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.
 
-Skills dispatch with `Subagent (general-purpose):` and either reference a prompt-template file (e.g., `superpowers:subagent-driven-development`'s `./implementer-prompt.md`) or supply an inline prompt. On Gemini CLI:
+When a skill says to dispatch a named agent type, use `@generalist` with the full prompt from the skill's prompt template:
 
-| Skill dispatch form | Gemini CLI equivalent |
-|---------------------|----------------------|
-| References a `*-prompt.md` template (implementer, spec-reviewer, code-quality-reviewer, code-reviewer, etc.) | Fill the template, then `invoke_agent` with `agent_name: "generalist"` and the filled prompt |
-| References `superpowers:requesting-code-review`'s `./code-reviewer.md` | `invoke_agent` with `agent_name: "generalist"` and the filled review template |
-| Inline prompt (no template referenced) | `invoke_agent` with `agent_name: "generalist"` and your inline prompt |
+| 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 before passing the complete prompt to `invoke_agent`. The prompt template itself contains the agent's role, review criteria, and expected output format — the subagent will follow it.
+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. Issue multiple `invoke_agent` calls in the same response (or multiple `@generalist` invocations in one prompt) to run independent subagent work in parallel. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.
+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 unique to Gemini CLI:
+These tools are available in Gemini CLI but have no Claude Code equivalent:
 
 | Tool | Purpose |
 |------|---------|
-| `save_memory` (legacy) | Persist facts across sessions when `experimental.memoryV2 = false` |
-| `get_internal_docs` | Look up Gemini CLI's bundled documentation |
-| `ask_user` | Pose structured questions to the user (text / single-select / multi-select) |
-| `enter_plan_mode` / `exit_plan_mode` | Switch into and out of read-only plan mode |
-| `update_topic` | Update the current conversation's topic / strategic-intent metadata |
-| `complete_task` | Signal that a Gemini subagent has completed and return its result to the parent agent |
-| `tracker_create_task`, `tracker_update_task`, `tracker_get_task`, `tracker_list_tasks`, `tracker_add_dependency`, `tracker_visualize` | Rich task tracker with dependency and visualization support |
-| `read_mcp_resource`, `list_mcp_resources` | MCP resource access |
+| `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 |

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

@@ -1,28 +0,0 @@
-# Pi Tool Mapping
-
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Pi these resolve to the tools below.
-
-| Action skills request | Pi equivalent |
-| --- | --- |
-| Invoke a skill | Pi native skills: load the relevant `SKILL.md` with `read`, or let the human use `/skill:name` |
-| Read a file | `read` |
-| Create a file | `write` |
-| Edit a file | `edit` |
-| Run a shell command | `bash` |
-| Search file contents | `grep` when active; otherwise `bash` with `rg`/`grep` |
-| Find files by name | `find` or `bash` with shell globs |
-| List files and subdirectories | `ls` when active; otherwise `bash` with `ls` |
-| Dispatch a subagent (`Subagent (general-purpose):` template) | Use an installed subagent tool such as `subagent` from `pi-subagents` if available |
-| Task tracking ("create a todo", "mark complete") | Use an installed todo/task tool if available, otherwise track tasks in the plan or `TODO.md` |
-
-## Skills
-
-Pi discovers skills from configured skill directories and installed Pi packages. A Superpowers Pi package should expose `skills/` through its `pi.skills` manifest entry. Pi does not expose Claude Code's `Skill` tool, but the agent should still follow the Superpowers rule: when a skill applies, load and follow it before responding.
-
-## Subagents
-
-Pi core does not ship a standard subagent tool. The `pi-subagents` package is a strong optional companion and provides a `subagent` tool with single-agent, chain, parallel, async, forked-context, and resume/status workflows. If no subagent tool is available, do not fabricate `Task` calls; execute sequentially in the current session or explain that the optional subagent capability is not installed.
-
-## Task lists
-
-Pi core does not ship a standard task-list tool. If a todo/task extension is installed, use its documented tool. Otherwise use Superpowers plan files, checklists in Markdown, or a repo-local `TODO.md` for task tracking. Older Superpowers docs may refer to `TodoWrite`; treat that as the task-tracking action above.

skills/writing-plans/SKILL.md

@@ -7,12 +7,10 @@ description: Use when you have a spec or requirements for a multi-step task, bef
 
 ## Overview
 
-Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to execute: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
 
 Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
 
-**Plans reference the spec; they never restate it.** The spec owns the WHAT and WHY — requirements, acceptance criteria, design decisions. The plan owns the HOW — tasks, files, code, commands. Cite the spec by path in the header and by section where a task needs context. Re-deriving spec content inline doubles the documents and lets them drift apart. "Zero context" means the engineer can execute each step mechanically; it does not mean the plan repeats what the spec already says — they can read the spec at the cited path.
-
 **Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
 
 **Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time.
@@ -55,8 +53,6 @@ This structure informs the task decomposition. Each task should produce self-con
 
 **Goal:** [One sentence describing what this builds]
 
-**Spec:** [Path to the spec doc, e.g. `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — requirements and design decisions live there; do not restate them here]
-
 **Architecture:** [2-3 sentences about approach]
 
 **Tech Stack:** [Key technologies/libraries]

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

@@ -7,7 +7,7 @@ Use this template when dispatching a plan document reviewer subagent.
 **Dispatch after:** The complete plan is written.
 
 ```
-Subagent (general-purpose):
+Task tool (general-purpose):
   description: "Review plan document"
   prompt: |
     You are a plan document reviewer. Verify this plan is complete and ready for implementation.

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 live in your runtime's skills directory** — see [claude-code-tools.md](../using-superpowers/references/claude-code-tools.md), [codex-tools.md](../using-superpowers/references/codex-tools.md), [copilot-tools.md](../using-superpowers/references/copilot-tools.md), or [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on your runtime. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias.
+**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 agents 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 your instructions file)
+- 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
@@ -99,7 +99,7 @@ skills/
 - `description`: Third-person, describes ONLY when to use (NOT what it does)
   - Start with "Use when..." to focus on triggering conditions
   - Include specific symptoms, situations, and contexts
-  - **NEVER summarize the skill's process or workflow** (see SDO section for why)
+  - **NEVER summarize the skill's process or workflow** (see CSO section for why)
   - Keep under 500 characters if possible
 
 ```markdown
@@ -137,13 +137,13 @@ Concrete results
 ```
 
 
-## Skill Discovery Optimization (SDO)
+## Claude Search Optimization (CSO)
 
-**Critical for discovery:** Future agents need to FIND your skill
+**Critical for discovery:** Future Claude needs to FIND your skill
 
 ### 1. Rich Description Field
 
-**Purpose:** Your agent reads the 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, an agent may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused an agent 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), the agent 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 agents will take. The skill body becomes documentation agents skip.
+**The trap:** Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips.
 
 ```yaml
-# ❌ BAD: Summarizes workflow - agents 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 an agent 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"
@@ -275,7 +275,7 @@ wc -w skills/path/SKILL.md
 - `creating-skills`, `testing-skills`, `debugging-with-logs`
 - Active, describes the action you're taking
 
-### 5. Cross-Referencing Other Skills
+### 4. Cross-Referencing Other Skills
 
 **When writing documentation that references other skills:**
 
@@ -313,7 +313,7 @@ digraph when_flowchart {
 - Linear instructions → Numbered lists
 - Labels without semantic meaning (step1, helper2)
 
-See `graphviz-conventions.dot` in this directory for graphviz style rules.
+See @graphviz-conventions.dot for graphviz style rules.
 
 **Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG:
 ```bash
@@ -522,7 +522,7 @@ Make it easy for agents to self-check when rationalizing:
 **All of these mean: Delete code. Start over with TDD.**
 ```
 
-### Update SDO for Violation Symptoms
+### Update CSO for Violation Symptoms
 
 Add to description: symptoms of when you're ABOUT to violate the rule:
 
@@ -595,7 +595,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 
 ## Skill Creation Checklist (TDD Adapted)
 
-**IMPORTANT: Create a todo for EACH checklist item below.**
+**IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.**
 
 **RED Phase - Write Failing Test:**
 - [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
@@ -634,10 +634,9 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 
 ## Discovery Workflow
 
-How future agents find your skill:
+How future Claude finds your skill:
 
 1. **Encounters problem** ("tests are flaky")
-2. **Searches skills** (greps descriptions, browses categories)
 3. **Finds SKILL** (description matches)
 4. **Scans overview** (is this relevant?)
 5. **Reads patterns** (quick reference table)

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

@@ -1,30 +1,30 @@
 # Skill authoring best practices
 
-> Learn how to write effective Skills that agents 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 agents 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
+For conceptual background on how Skills work, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview).
 
 ## Core principles
 
 ### Concise is key
 
-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 your agent 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. Agents read SKILL.md only when the Skill becomes relevant, and read additional files only as needed. However, being concise in SKILL.md still matters: once an agent 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**: Agents are already very smart
+**Default assumption**: Claude is already very smart
 
-Only add context agents don't already have. Challenge each piece of information:
+Only add context Claude doesn't already have. Challenge each piece of information:
 
-* "Does the agent really need this explanation?"
-* "Can I assume the agent 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 the agent 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 the agent 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 the agent 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
 
@@ -149,7 +149,7 @@ What works perfectly for Opus might need more detail for Haiku. If you plan to u
   * `name` - Human-readable name of the Skill (64 characters maximum)
   * `description` - One-line description of what the Skill does and when to use it (1024 characters maximum)
 
-  For complete Skill structure details, see the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#skill-structure).
+  For complete Skill structure details, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure).
 </Note>
 
 ### Naming conventions
@@ -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: agents use it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for an agent 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 agents 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](https://platform.claude.com/docs/en/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
 
 <img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=87782ff239b297d9a9e8e1b72ed72db9" alt="Simple SKILL.md file showing YAML frontmatter and markdown body" data-og-width="2048" width="2048" data-og-height="1153" height="1153" data-path="images/agent-skills-simple-file.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=c61cc33b6f5855809907f7fda94cd80e 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=90d2c0c1c76b36e8d485f49e0810dbfd 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=ad17d231ac7b0bea7e5b4d58fb4aeabb 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f5d0a7a3c668435bb0aee9a3a8f8c329 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0e927c1af9de5799cfe557d12249f6e6 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=46bbb1a51dd4c8202a470ac8c80a893d 2500w" />
 
-As your Skill grows, you can bundle additional content that agents load only when needed:
+As your Skill grows, you can bundle additional content that Claude loads only when needed:
 
 <img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=a5e0aa41e3d53985a7e3e43668a33ea3" alt="Bundling additional reference files like reference.md and forms.md." data-og-width="2048" width="2048" data-og-height="1327" height="1327" data-path="images/agent-skills-bundling-content.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f8a0e73783e99b4a643d79eac86b70a2 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=dc510a2a9d3f14359416b706f067904a 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=82cd6286c966303f7dd914c28170e385 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=56f3be36c77e4fe4b523df209a6824c6 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=d22b5161b2075656417d56f41a74f3dd 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=3dd4bdd6850ffcc96c6c45fcb0acd6eb 2500w" />
 
@@ -292,11 +292,11 @@ with pdfplumber.open("file.pdf") as pdf:
 **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
 ````
 
-Agents load 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, the agent 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)
 ```
 
-Agents read 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
 
-Agents may partially read files when they're referenced from other referenced files. When encountering nested references, an agent 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 agents read 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 agents 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
 ...
 ```
 
-Agents 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 the agent 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 agents from skipping critical validation. The checklist helps both you and the agent 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 the agent 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 agents 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 agents 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 agents through decision points:
+Guide Claude through decision points:
 
 ```markdown  theme={null}
 ## Document modification workflow
@@ -715,7 +715,7 @@ Guide agents through decision points:
 ```
 
 <Tip>
-  If workflows become large or complicated with many steps, consider pushing them into separate files and tell the agent 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.
 </Tip>
 
 ## Evaluation and iteration
@@ -726,9 +726,9 @@ Guide agents through decision points:
 
 **Evaluation-driven development:**
 
-1. **Identify gaps**: Run your agent 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 the agent'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.
 </Note>
 
-### Develop Skills iteratively with the agent
+### Develop Skills iteratively with Claude
 
-The most effective Skill development process involves the agent itself. Work with one instance ("Agent A") to create a Skill that will be used by other instances ("Agent B"). Agent A helps you design and refine instructions, while Agent B tests them in real tasks. This works because the underlying 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 Agent 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 Agent 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."
 
    <Tip>
-     Modern agents understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get help creating Skills. Simply ask the agent 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.
    </Tip>
 
-4. **Review for conciseness**: Check that Agent A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - the agent 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 Agent 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 Agent B (a fresh instance with the Skill loaded) on related use cases. Observe whether Agent 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 Agent B struggles or misses something, return to Agent A with specifics: "When the agent 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 Agent A** (the expert who helps refine the Skill)
-* **Testing with Agent B** (the agent using the Skill to perform real work)
-* **Observing Agent B's behavior** and bringing insights back to Agent 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 Agent 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 Agent 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 Agent 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 Agent A for improvements**: Share the current SKILL.md and describe what you observed. Ask: "I noticed Agent 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 Agent A's suggestions**: Agent 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 Agent A's refinements, then test again with Agent 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**: Agent A understands agent needs, you provide domain expertise, Agent 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 agents navigate Skills
+### Observe how Claude navigates Skills
 
-As you iterate on Skills, pay attention to how agents actually use 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 the agent read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
-* **Missed connections**: Does the agent fail to follow references to important files? Your links might need to be more explicit or prominent
-* **Overreliance on certain sections**: If the agent repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
-* **Ignored content**: If the agent 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. Agents use 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 the agent.
+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 the agent**:
+**Bad example: Punt to Claude**:
 
 ```python  theme={null}
 def process_file(path):
-    # Just fail and let the agent 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 the agent 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 your agent 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 your agent could write a script, pre-made scripts offer advantages:
 
 <img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=4bbc45f2c2e0bee9f2f0d5da669bad00" alt="Bundling executable scripts alongside instruction files" data-og-width="2048" width="2048" data-og-height="1154" height="1154" data-path="images/agent-skills-executable-scripts.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=9a04e6535a8467bfeea492e517de389f 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=e49333ad90141af17c0d7651cca7216b 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=954265a5df52223d6572b6214168c428 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=2ff7a2d8f2a83ee8af132b29f10150fd 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=48ab96245e04077f4d15e9170e081cfb 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0301a6c8b3ee879497cc5b5483177c90 2500w" />
 
-The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and the agent 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 the agent 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 the agent 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 the agent analyze them:
    ```
 
 2. Analyze each page image to identify form fields
-3. The agent can see field locations and types visually
+3. Claude can see field locations and types visually
 ````
 
 <Note>
   In this example, you'd need to write the `pdf_to_images.py` script.
 </Note>
 
-Agent vision capabilities help understand layouts and structures.
+Claude's vision capabilities help understand layouts and structures.
 
 ### Create verifiable intermediate outputs
 
-When agents perform complex, open-ended tasks, they can make mistakes. The "plan-validate-execute" pattern catches errors early by having the agent 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 the agent to update 50 form fields in a PDF based on a spreadsheet. Without validation, it 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,12 +994,12 @@ When agents perform complex, open-ended tasks, they can make mistakes. The "plan
 
 * **Catches errors early**: Validation finds problems before changes are applied
 * **Machine-verifiable**: Scripts provide objective verification
-* **Reversible planning**: The agent 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 the agent 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
 
@@ -1008,32 +1008,32 @@ Skills run in the code execution environment with platform-specific limitations:
 * **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](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool).
+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).
 
 ### Runtime environment
 
-Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see [The Skills architecture](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#the-skills-architecture) in the overview.
+Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see [The Skills architecture](/en/docs/agents-and-tools/agent-skills/overview#the-skills-architecture) in the overview.
 
 **How this affects your authoring:**
 
-**How agents access 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**: Agents use their file-reading 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**: Agents navigate 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 the agent 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 the agent 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,9 +1046,9 @@ bigquery-skill/
     └── product.md (usage analytics)
 ```
 
-When the user asks about revenue, the agent 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. Agents 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the Skills overview.
+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.
 
 ### MCP tool references
 
@@ -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, agents 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
 
@@ -1092,11 +1092,11 @@ reader = PdfReader("file.pdf")
 
 ### YAML frontmatter requirements
 
-The SKILL.md frontmatter requires `name` (64 characters max) and `description` (1024 characters max) fields. See the [Skills overview](https://platform.claude.com/docs/en/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.
 
 ### Token budgets
 
-Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work).
+Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work).
 
 ## Checklist for effective Skills
 
@@ -1117,7 +1117,7 @@ Before sharing a Skill, verify:
 
 ### Code and scripts
 
-* [ ] Scripts solve problems rather than punt to the agent
+* [ ] 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
@@ -1136,15 +1136,15 @@ Before sharing a Skill, verify:
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Get started with Agent Skills" icon="rocket" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart">
+  <Card title="Get started with Agent Skills" icon="rocket" href="/en/docs/agents-and-tools/agent-skills/quickstart">
     Create your first Skill
   </Card>
 
-  <Card title="Use Skills in Claude Code" icon="terminal" href="https://code.claude.com/docs/en/skills">
+  <Card title="Use Skills in Claude Code" icon="terminal" href="/en/docs/claude-code/skills">
     Create and manage Skills in Claude Code
   </Card>
 
-  <Card title="Use Skills with the API" icon="code" href="https://platform.claude.com/docs/en/build-with-claude/skills-guide">
+  <Card title="Use Skills with the API" icon="code" href="/en/api/skills-guide">
     Upload and use Skills programmatically
   </Card>
 </CardGroup>

skills/writing-skills/persuasion-principles.md

@@ -33,7 +33,7 @@ LLMs respond to the same persuasion principles as humans. Understanding this psy
 **How it works in skills:**
 - Require announcements: "Announce skill usage"
 - Force explicit choices: "Choose A, B, or C"
-- Use tracking: todos for checklists
+- Use tracking: TodoWrite for checklists
 
 **When to use:**
 - Ensuring skills are actually followed
@@ -80,8 +80,8 @@ LLMs respond to the same persuasion principles as humans. Understanding this psy
 
 **Example:**
 ```markdown
-✅ Checklists without todo tracking = steps get skipped. Every time.
-❌ Some people find a todo list helpful for checklists.
+✅ Checklists without TodoWrite tracking = steps get skipped. Every time.
+❌ Some people find TodoWrite helpful for checklists.
 ```
 
 ### 5. Unity

tests/antigravity/run-tests.sh

@@ -1,16 +0,0 @@
-#!/usr/bin/env bash
-# Run all Antigravity (agy) integration tests.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-echo "=== Antigravity integration tests ==="
-
-for t in "$SCRIPT_DIR"/test-*.sh; do
-  echo
-  echo ">>> $t"
-  bash "$t"
-done
-
-echo
-echo "=== All Antigravity tests passed ==="

tests/antigravity/test-antigravity-tools.sh

@@ -1,53 +0,0 @@
-#!/usr/bin/env bash
-# Validate the Antigravity (agy) integration. agy installs the existing plugin
-# directly (`agy plugin install <repo-url>`): it loads the bundled skills and
-# runs the SessionStart hook for bootstrap, so there is no agy-specific scaffold
-# to test. What IS agy-specific is the tool mapping — agy has no `Skill` tool and
-# loads skills by reading SKILL.md with view_file — and SKILL.md pointing at it.
-#
-# Mirrors tests/pi/test-pi-extension.mjs's "tools reference documents
-# harness-specific mappings" check. CI-safe: does not require `agy` installed.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-
-MAPPING="$REPO_ROOT/skills/using-superpowers/references/antigravity-tools.md"
-SKILL="$REPO_ROOT/skills/using-superpowers/SKILL.md"
-
-fail() { echo "FAIL: $*" >&2; exit 1; }
-
-echo "test-antigravity-tools: checking Antigravity tool mapping"
-
-# --- Mapping exists ---------------------------------------------------------
-[ -f "$MAPPING" ] || fail "tool mapping missing at $MAPPING"
-
-# --- Skill-load mechanism: view_file on SKILL.md (IsSkillFile), no Skill tool -
-grep -qiE "view_file" "$MAPPING" \
-  || fail "mapping does not document view_file as the file/skill-read tool"
-grep -qiE "SKILL\.md" "$MAPPING" \
-  || fail "mapping does not document reading SKILL.md as the skill-load path"
-grep -q "IsSkillFile" "$MAPPING" \
-  || fail "mapping does not document setting IsSkillFile when loading a skill"
-
-# --- Core action→tool mappings are documented -------------------------------
-for tool in write_to_file replace_file_content run_command grep_search invoke_subagent; do
-  grep -q "$tool" "$MAPPING" \
-    || fail "mapping does not document the '$tool' tool"
-done
-
-# --- Subagents use the built-in self/research types -------------------------
-grep -q '`self`' "$MAPPING" \
-  || fail "mapping does not document the built-in 'self' subagent type"
-grep -q '`research`' "$MAPPING" \
-  || fail "mapping does not document the built-in 'research' subagent type"
-
-# --- Task tracking documents the 'task' artifact mechanism ------------------
-grep -qE 'ArtifactType.*task|task. artifact' "$MAPPING" \
-  || fail "mapping does not document task tracking as a 'task' artifact"
-
-# --- SKILL.md Platform Adaptation links the mapping -------------------------
-grep -q "antigravity-tools.md" "$SKILL" \
-  || fail "SKILL.md Platform Adaptation does not reference antigravity-tools.md"
-
-echo "PASS: Antigravity tool mapping valid (view_file skill-load, agy tools, SKILL.md link)"

tests/brainstorm-server/server.test.js

@@ -406,7 +406,7 @@ async function runTests() {
       assert(template.includes('indicator-bar'), 'Should have indicator bar');
       assert(template.includes('indicator-text'), 'Should have indicator text');
       assert(template.includes('<!-- CONTENT -->'), 'Should have content placeholder');
-      assert(template.includes('frame-content'), 'Should have content container');
+      assert(template.includes('claude-content'), 'Should have content container');
       return Promise.resolve();
     });
 

tests/brainstorm-server/windows-lifecycle.test.sh

@@ -1,11 +1,9 @@
 #!/usr/bin/env bash
 # Windows lifecycle tests for the brainstorm server.
 #
-# Verifies brainstorm server lifecycle behavior, including:
-#  - Windows/MSYS2 foreground mode and empty OWNER_PID handling
-#  - Server survival past the 60-second lifecycle check window
-#  - Dead-at-startup OWNER_PID validation (logged, monitoring disabled)
-#  - Clean stop-server.sh shutdown
+# Verifies that the brainstorm server survives the 60-second lifecycle
+# check on Windows, where OWNER_PID monitoring is disabled because the
+# MSYS2 PID namespace is invisible to Node.js.
 #
 # Requirements:
 #   - Node.js in PATH
@@ -22,7 +20,7 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="${SUPERPOWERS_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 START_SCRIPT="$REPO_ROOT/skills/brainstorming/scripts/start-server.sh"
 STOP_SCRIPT="$REPO_ROOT/skills/brainstorming/scripts/stop-server.sh"
-SERVER_SCRIPT="$REPO_ROOT/skills/brainstorming/scripts/server.cjs"
+SERVER_JS="$REPO_ROOT/skills/brainstorming/scripts/server.js"
 
 TEST_DIR="${TMPDIR:-/tmp}/brainstorm-win-test-$$"
 
@@ -66,7 +64,7 @@ skip() {
 wait_for_server_info() {
   local dir="$1"
   for _ in $(seq 1 50); do
-    if [[ -f "$dir/state/server-info" ]]; then
+    if [[ -f "$dir/.server-info" ]]; then
       return 0
     fi
     sleep 0.1
@@ -75,9 +73,9 @@ wait_for_server_info() {
 }
 
 get_port_from_info() {
-  # Read the port from state/server-info. Use grep/sed instead of Node.js
+  # Read the port from .server-info. Use grep/sed instead of Node.js
   # to avoid MSYS2-to-Windows path translation issues.
-  grep -o '"port":[0-9]*' "$1/state/server-info" | head -1 | sed 's/"port"://'
+  grep -o '"port":[0-9]*' "$1/.server-info" | head -1 | sed 's/"port"://'
 }
 
 http_check() {
@@ -216,11 +214,11 @@ BRAINSTORM_HOST="127.0.0.1" \
 BRAINSTORM_URL_HOST="localhost" \
 BRAINSTORM_OWNER_PID="" \
 BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
-  node "$SERVER_SCRIPT" > "$TEST_DIR/survival/.server.log" 2>&1 &
+  node "$SERVER_JS" > "$TEST_DIR/survival/.server.log" 2>&1 &
 SERVER_PID=$!
 
 if ! wait_for_server_info "$TEST_DIR/survival"; then
-  fail "Server starts successfully" "Server did not write state/server-info within 5 seconds"
+  fail "Server starts successfully" "Server did not write .server-info within 5 seconds"
   kill "$SERVER_PID" 2>/dev/null || true
   SERVER_PID=""
 else
@@ -256,15 +254,10 @@ else
   SERVER_PID=""
 fi
 
-# ========== Test 5: Dead-at-startup OWNER_PID is logged but does not kill the server ==========
-#
-# The server validates BRAINSTORM_OWNER_PID at startup. If it's already dead,
-# the PID resolution was wrong (common on WSL, Tailscale SSH, cross-user
-# scenarios). The server logs 'owner-pid-invalid', disables owner monitoring,
-# and continues running. The idle timeout becomes the only shutdown trigger.
+# ========== Test 5: Bad OWNER_PID causes shutdown (control) ==========
 
 echo ""
-echo "--- Dead-at-startup OWNER_PID: server survives, logs owner-pid-invalid ---"
+echo "--- Control: Bad OWNER_PID causes shutdown ---"
 
 mkdir -p "$TEST_DIR/control"
 
@@ -279,41 +272,33 @@ BRAINSTORM_HOST="127.0.0.1" \
 BRAINSTORM_URL_HOST="localhost" \
 BRAINSTORM_OWNER_PID="$BAD_PID" \
 BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
-  node "$SERVER_SCRIPT" > "$TEST_DIR/control/.server.log" 2>&1 &
+  node "$SERVER_JS" > "$TEST_DIR/control/.server.log" 2>&1 &
 CONTROL_PID=$!
 
 if ! wait_for_server_info "$TEST_DIR/control"; then
-  fail "Control server starts" "Server did not write state/server-info within 5 seconds"
+  fail "Control server starts" "Server did not write .server-info within 5 seconds"
   kill "$CONTROL_PID" 2>/dev/null || true
   CONTROL_PID=""
 else
-  pass "Control server starts with dead-at-startup OWNER_PID=$BAD_PID"
+  pass "Control server starts with bad OWNER_PID=$BAD_PID"
 
-  echo "  Waiting ~75s to verify server survives past lifecycle check..."
+  echo "  Waiting ~75s for lifecycle check to kill server..."
   sleep 75
 
   if kill -0 "$CONTROL_PID" 2>/dev/null; then
-    pass "Server survives with dead-at-startup OWNER_PID (owner monitoring disabled)"
+    fail "Control server self-terminates with bad OWNER_PID" \
+         "Server is still alive (expected it to die)"
+    kill "$CONTROL_PID" 2>/dev/null || true
   else
-    fail "Server survives with dead-at-startup OWNER_PID" \
-         "Server died unexpectedly. Log tail: $(tail -5 "$TEST_DIR/control/.server.log" 2>/dev/null)"
-  fi
-
-  if grep -q "owner-pid-invalid" "$TEST_DIR/control/.server.log" 2>/dev/null; then
-    pass "Server logs 'owner-pid-invalid' for dead-at-startup PID"
-  else
-    fail "Server logs 'owner-pid-invalid' for dead-at-startup PID" \
-         "Log tail: $(tail -5 "$TEST_DIR/control/.server.log" 2>/dev/null)"
+    pass "Control server self-terminates with bad OWNER_PID"
   fi
 
   if grep -q "owner process exited" "$TEST_DIR/control/.server.log" 2>/dev/null; then
-    fail "No spurious 'owner process exited' log" \
-         "Found 'owner process exited' but owner monitoring should be disabled"
+    pass "Control server logs 'owner process exited'"
   else
-    pass "No spurious 'owner process exited' log"
+    fail "Control server logs 'owner process exited'" \
+         "Log tail: $(tail -5 "$TEST_DIR/control/.server.log" 2>/dev/null)"
   fi
-
-  kill "$CONTROL_PID" 2>/dev/null || true
 fi
 
 wait "$CONTROL_PID" 2>/dev/null || true
@@ -324,16 +309,16 @@ CONTROL_PID=""
 echo ""
 echo "--- Clean Shutdown ---"
 
-mkdir -p "$TEST_DIR/stop-test/state"
+mkdir -p "$TEST_DIR/stop-test"
 
 BRAINSTORM_DIR="$TEST_DIR/stop-test" \
 BRAINSTORM_HOST="127.0.0.1" \
 BRAINSTORM_URL_HOST="localhost" \
 BRAINSTORM_OWNER_PID="" \
 BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
-  node "$SERVER_SCRIPT" > "$TEST_DIR/stop-test/.server.log" 2>&1 &
+  node "$SERVER_JS" > "$TEST_DIR/stop-test/.server.log" 2>&1 &
 STOP_TEST_PID=$!
-echo "$STOP_TEST_PID" > "$TEST_DIR/stop-test/state/server.pid"
+echo "$STOP_TEST_PID" > "$TEST_DIR/stop-test/.server.pid"
 
 if ! wait_for_server_info "$TEST_DIR/stop-test"; then
   fail "Stop-test server starts" "Server did not start"

tests/brainstorm-server/ws-protocol.test.js

@@ -329,21 +329,6 @@ function runTests() {
     assert.strictEqual(result.payload.length, 65536);
   });
 
-  test('rejects oversized 64-bit frames before payload allocation', () => {
-    const mask = Buffer.from([0x00, 0x00, 0x00, 0x00]);
-    const header = Buffer.alloc(14);
-    header[0] = 0x81; // FIN + TEXT
-    header[1] = 0x80 | 127; // masked, 64-bit length
-    header.writeBigUInt64BE(BigInt(ws.MAX_FRAME_PAYLOAD_BYTES) + 1n, 2);
-    mask.copy(header, 10);
-
-    assert.throws(
-      () => ws.decodeFrame(header),
-      /exceeds maximum allowed size/i,
-      'oversized advertised payload must be rejected from header alone'
-    );
-  });
-
   // ========== Close Frame with Status Code ==========
   console.log('\n--- Close Frame Details ---');
 

tests/claude-code/test-subagent-driven-development-integration.sh

@@ -7,8 +7,8 @@
 # and is stricter on that axis. This bash test additionally asserts:
 #   - >=3 git commits (initial + per-task commits, exercising SDD's
 #     commit-per-task workflow shape)
-#   - >=2 Claude Code subagent dispatches via Agent or Task (drill only asserts >=1)
-#   - Claude Code task-tracking tool usage (drill makes no assertion)
+#   - >=2 Agent/Task subagent dispatches (drill only asserts >=1)
+#   - TodoWrite usage (drill makes no assertion)
 #   - test/math.test.js exists (drill relies on `npm test` succeeding)
 #   - analyze-token-usage.py token-budget telemetry
 # Kept until those assertions are added to drill or explicitly retired.
@@ -224,13 +224,13 @@ else
 fi
 echo ""
 
-# Test 3: Claude Code task-tracking tool was used
+# Test 3: TodoWrite was used for tracking
 echo "Test 3: Task tracking..."
-todo_count=$(grep -cE '"name":"(TodoWrite|TaskCreate|TaskUpdate|TaskList|TaskGet)"' "$SESSION_FILE" || echo "0")
+todo_count=$(grep -c '"name":"TodoWrite"' "$SESSION_FILE" || echo "0")
 if [ "$todo_count" -ge 1 ]; then
-    echo "  [PASS] Task tracking used $todo_count time(s)"
+    echo "  [PASS] TodoWrite used $todo_count time(s) for task tracking"
 else
-    echo "  [FAIL] No Claude Code task-tracking tool used"
+    echo "  [FAIL] TodoWrite not used"
     FAILED=$((FAILED + 1))
 fi
 echo ""

tests/codex-plugin-sync/test-sync-to-codex-plugin.sh

@@ -175,11 +175,9 @@ write_upstream_fixture() {
 
     mkdir -p \
         "$repo/.codex-plugin" \
-        "$repo/.kimi-plugin" \
         "$repo/.private-journal" \
         "$repo/assets" \
         "$repo/evals/drill" \
-        "$repo/hooks" \
         "$repo/scripts" \
         "$repo/skills/example"
 
@@ -211,13 +209,6 @@ EOF
   "name": "superpowers",
   "version": "$MANIFEST_VERSION"
 }
-EOF
-
-    cat > "$repo/.kimi-plugin/plugin.json" <<EOF
-{
-  "name": "superpowers",
-  "version": "$MANIFEST_VERSION"
-}
 EOF
 
     cat > "$repo/assets/superpowers-small.svg" <<'EOF'
@@ -227,40 +218,6 @@ EOF
     printf 'png fixture\n' > "$repo/assets/app-icon.png"
     printf 'eval harness fixture\n' > "$repo/evals/drill/README.md"
 
-    cat > "$repo/hooks/hooks-codex.json" <<'EOF'
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup|resume|clear",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start-codex",
-            "async": false
-          }
-        ]
-      }
-    ]
-  }
-}
-EOF
-
-    cat > "$repo/hooks/session-start" <<'EOF'
-#!/usr/bin/env sh
-echo "session-start fixture"
-EOF
-    cat > "$repo/hooks/session-start-codex" <<'EOF'
-#!/usr/bin/env sh
-echo "session-start-codex fixture"
-EOF
-
-    cat > "$repo/hooks/run-hook.cmd" <<'EOF'
-@echo off
-echo run-hook fixture
-EOF
-    chmod +x "$repo/hooks/session-start" "$repo/hooks/session-start-codex" "$repo/hooks/run-hook.cmd"
-
     cat > "$repo/skills/example/SKILL.md" <<'EOF'
 # Example Skill
 
@@ -275,15 +232,10 @@ EOF
 
     git -C "$repo" add \
         .codex-plugin/plugin.json \
-        .kimi-plugin/plugin.json \
         .gitignore \
         assets/app-icon.png \
         assets/superpowers-small.svg \
         evals/drill/README.md \
-        hooks/hooks-codex.json \
-        hooks/run-hook.cmd \
-        hooks/session-start \
-        hooks/session-start-codex \
         package.json \
         scripts/sync-to-codex-plugin.sh \
         skills/example/SKILL.md
@@ -341,7 +293,6 @@ write_synced_destination_fixture() {
         "$repo/plugins/superpowers/.codex-plugin" \
         "$repo/plugins/superpowers/.private-journal" \
         "$repo/plugins/superpowers/assets" \
-        "$repo/plugins/superpowers/hooks" \
         "$repo/plugins/superpowers/skills/example/agents" \
         "$repo/plugins/superpowers/skills/example"
 
@@ -358,40 +309,6 @@ EOF
 
     printf 'png fixture\n' > "$repo/plugins/superpowers/assets/app-icon.png"
 
-    cat > "$repo/plugins/superpowers/hooks/hooks-codex.json" <<'EOF'
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup|resume|clear",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start-codex",
-            "async": false
-          }
-        ]
-      }
-    ]
-  }
-}
-EOF
-
-    cat > "$repo/plugins/superpowers/hooks/session-start" <<'EOF'
-#!/usr/bin/env sh
-echo "session-start fixture"
-EOF
-    cat > "$repo/plugins/superpowers/hooks/session-start-codex" <<'EOF'
-#!/usr/bin/env sh
-echo "session-start-codex fixture"
-EOF
-
-    cat > "$repo/plugins/superpowers/hooks/run-hook.cmd" <<'EOF'
-@echo off
-echo run-hook fixture
-EOF
-    chmod +x "$repo/plugins/superpowers/hooks/session-start" "$repo/plugins/superpowers/hooks/session-start-codex" "$repo/plugins/superpowers/hooks/run-hook.cmd"
-
     cat > "$repo/plugins/superpowers/skills/example/SKILL.md" <<'EOF'
 # Example Skill
 
@@ -410,10 +327,6 @@ EOF
         plugins/superpowers/.codex-plugin/plugin.json \
         plugins/superpowers/assets/app-icon.png \
         plugins/superpowers/assets/superpowers-small.svg \
-        plugins/superpowers/hooks/hooks-codex.json \
-        plugins/superpowers/hooks/run-hook.cmd \
-        plugins/superpowers/hooks/session-start \
-        plugins/superpowers/hooks/session-start-codex \
         plugins/superpowers/skills/example/agents/openai.yaml \
         plugins/superpowers/skills/example/SKILL.md \
         plugins/superpowers/.private-journal/keep.txt
@@ -424,15 +337,10 @@ EOF
 write_stale_ignored_destination_fixture() {
     local repo="$1"
 
-    mkdir -p \
-        "$repo/plugins/superpowers/.kimi-plugin" \
-        "$repo/plugins/superpowers/.private-journal"
+    mkdir -p "$repo/plugins/superpowers/.private-journal"
     printf 'fixture keep\n' > "$repo/plugins/superpowers/.fixture-keep"
-    printf '{"name":"stale-kimi"}\n' > "$repo/plugins/superpowers/.kimi-plugin/plugin.json"
     printf 'stale ignored leak\n' > "$repo/plugins/superpowers/.private-journal/leak.txt"
-    git -C "$repo" add \
-        plugins/superpowers/.fixture-keep \
-        plugins/superpowers/.kimi-plugin/plugin.json
+    git -C "$repo" add plugins/superpowers/.fixture-keep
 
     commit_fixture "$repo" "Initial stale ignored destination fixture"
 }
@@ -632,13 +540,8 @@ main() {
     assert_contains "$preview_output" "Version:  $MANIFEST_VERSION" "Preview uses manifest version"
     assert_not_contains "$preview_output" "Version:  $PACKAGE_VERSION" "Preview does not use package.json version"
     assert_contains "$preview_section" ".codex-plugin/plugin.json" "Preview includes manifest path"
-    assert_not_contains "$preview_section" ".kimi-plugin/plugin.json" "Preview excludes Kimi manifest from Codex sync"
     assert_contains "$preview_section" "assets/superpowers-small.svg" "Preview includes SVG asset"
     assert_contains "$preview_section" "assets/app-icon.png" "Preview includes PNG asset"
-    assert_contains "$preview_section" "hooks/hooks-codex.json" "Preview includes Codex hook manifest"
-    assert_contains "$preview_section" "hooks/session-start" "Preview includes session-start hook"
-    assert_contains "$preview_section" "hooks/session-start-codex" "Preview includes Codex session-start hook"
-    assert_contains "$preview_section" "hooks/run-hook.cmd" "Preview includes hook command wrapper"
     assert_contains "$preview_section" ".private-journal/keep.txt" "Preview includes tracked ignored file"
     assert_not_contains "$preview_section" ".private-journal/leak.txt" "Preview excludes ignored untracked file"
     assert_not_contains "$preview_section" "ignored-cache/" "Preview excludes pure ignored directories"
@@ -659,7 +562,6 @@ main() {
     echo ""
     echo "Convergence assertions..."
     assert_equals "$stale_preview_status" "0" "Stale ignored destination preview exits successfully"
-    assert_matches "$stale_preview_section" "\\*deleting +\\.kimi-plugin/plugin\\.json" "Preview deletes stale Kimi manifest from Codex plugin"
     assert_matches "$stale_preview_section" "\\*deleting +\\.private-journal/leak\\.txt" "Preview deletes stale ignored destination file"
 
     echo ""

tests/explicit-skill-requests/run-multiturn-test.sh

@@ -109,7 +109,7 @@ if [ -n "$FIRST_SKILL_LINE" ]; then
     PREMATURE_TOOLS=$(head -n "$FIRST_SKILL_LINE" "$TURN3_LOG" | \
         grep '"type":"tool_use"' | \
         grep -v '"name":"Skill"' | \
-        grep -vE '"name":"(TodoWrite|TaskCreate|TaskUpdate|TaskList|TaskGet)"' || true)
+        grep -v '"name":"TodoWrite"' || true)
     if [ -n "$PREMATURE_TOOLS" ]; then
         echo "WARNING: Tools invoked BEFORE Skill tool in Turn 3:"
         echo "$PREMATURE_TOOLS" | head -5

tests/explicit-skill-requests/run-test.sh

@@ -103,11 +103,11 @@ echo "Checking for premature action..."
 FIRST_SKILL_LINE=$(grep -n '"name":"Skill"' "$LOG_FILE" | head -1 | cut -d: -f1)
 if [ -n "$FIRST_SKILL_LINE" ]; then
     # Check if any non-Skill, non-system tools were invoked before the first Skill invocation
-    # Filter out task tracking tools (planning is ok) and other non-action tools
+    # Filter out system messages, TodoWrite (planning is ok), and other non-action tools
     PREMATURE_TOOLS=$(head -n "$FIRST_SKILL_LINE" "$LOG_FILE" | \
         grep '"type":"tool_use"' | \
         grep -v '"name":"Skill"' | \
-        grep -vE '"name":"(TodoWrite|TaskCreate|TaskUpdate|TaskList|TaskGet)"' || true)
+        grep -v '"name":"TodoWrite"' || true)
     if [ -n "$PREMATURE_TOOLS" ]; then
         echo "WARNING: Tools invoked BEFORE Skill tool:"
         echo "$PREMATURE_TOOLS" | head -5

tests/hooks/test-session-start.sh

@@ -1,240 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-HOOK_UNDER_TEST="$REPO_ROOT/hooks/session-start"
-CODEX_HOOK_UNDER_TEST="$REPO_ROOT/hooks/session-start-codex"
-WRAPPER_UNDER_TEST="$REPO_ROOT/hooks/run-hook.cmd"
-
-FAILURES=0
-TEST_ROOT="$(mktemp -d)"
-
-cleanup() {
-    rm -rf "$TEST_ROOT"
-}
-trap cleanup EXIT
-
-pass() {
-    echo "  [PASS] $1"
-}
-
-fail() {
-    echo "  [FAIL] $1"
-    FAILURES=$((FAILURES + 1))
-}
-
-make_home() {
-    local name="$1"
-    local home="$TEST_ROOT/$name/home"
-    mkdir -p "$home"
-    printf '%s\n' "$home"
-}
-
-assert_command_output() {
-    local description="$1"
-    local shape="$2"
-    local contains="$3"
-    local not_contains="$4"
-    local home="$5"
-    shift 5
-
-    local output
-    if ! output="$(env -i PATH="${PATH:-}" HOME="$home" "$@" 2>&1)"; then
-        fail "$description"
-        echo "    hook exited non-zero"
-        echo "$output" | sed 's/^/      /'
-        return
-    fi
-
-    if printf '%s' "$output" | \
-        EXPECT_SHAPE="$shape" \
-        EXPECT_CONTAINS="$contains" \
-        EXPECT_NOT_CONTAINS="$not_contains" \
-        node -e '
-const fs = require("fs");
-
-const input = fs.readFileSync(0, "utf8");
-let payload;
-try {
-  payload = JSON.parse(input);
-} catch (error) {
-  console.error(`invalid JSON: ${error.message}`);
-  process.exit(1);
-}
-
-function hasOwn(object, key) {
-  return Object.prototype.hasOwnProperty.call(object, key);
-}
-
-function fail(message) {
-  console.error(message);
-  process.exit(1);
-}
-
-const shape = process.env.EXPECT_SHAPE;
-let context;
-
-if (shape === "nested") {
-  if (!hasOwn(payload, "hookSpecificOutput")) {
-    fail("missing hookSpecificOutput");
-  }
-  if (hasOwn(payload, "additional_context") || hasOwn(payload, "additionalContext")) {
-    fail("nested output also included a top-level context field");
-  }
-  const hookOutput = payload.hookSpecificOutput;
-  if (!hookOutput || typeof hookOutput !== "object" || Array.isArray(hookOutput)) {
-    fail("hookSpecificOutput is not an object");
-  }
-  if (hookOutput.hookEventName !== "SessionStart") {
-    fail(`unexpected hookEventName: ${hookOutput.hookEventName}`);
-  }
-  context = hookOutput.additionalContext;
-} else if (shape === "cursor") {
-  if (hasOwn(payload, "hookSpecificOutput")) {
-    fail("cursor output included hookSpecificOutput");
-  }
-  if (!hasOwn(payload, "additional_context")) {
-    fail("cursor output missing additional_context");
-  }
-  if (hasOwn(payload, "additionalContext")) {
-    fail("cursor output included additionalContext");
-  }
-  context = payload.additional_context;
-} else if (shape === "sdk") {
-  if (hasOwn(payload, "hookSpecificOutput")) {
-    fail("sdk output included hookSpecificOutput");
-  }
-  if (!hasOwn(payload, "additionalContext")) {
-    fail("sdk output missing additionalContext");
-  }
-  if (hasOwn(payload, "additional_context")) {
-    fail("sdk output included additional_context");
-  }
-  context = payload.additionalContext;
-} else {
-  fail(`unknown expected shape: ${shape}`);
-}
-
-if (typeof context !== "string" || context.trim() === "") {
-  fail("injected context was empty");
-}
-
-const expectedText = process.env.EXPECT_CONTAINS || "";
-if (expectedText && !context.includes(expectedText)) {
-  fail(`context did not contain expected text: ${expectedText}`);
-}
-
-const forbiddenTexts = (process.env.EXPECT_NOT_CONTAINS || "")
-  .split("\u001f")
-  .filter(Boolean);
-for (const forbiddenText of forbiddenTexts) {
-  if (context.includes(forbiddenText)) {
-    fail(`context contained forbidden text: ${forbiddenText}`);
-  }
-}
-'; then
-        pass "$description"
-    else
-        fail "$description"
-        echo "    output:"
-        echo "$output" | sed 's/^/      /'
-    fi
-}
-
-echo "SessionStart hook output tests"
-
-claude_home="$(make_home claude-code)"
-assert_command_output \
-    "Claude Code emits nested SessionStart additionalContext" \
-    "nested" \
-    "" \
-    "" \
-    "$claude_home" \
-    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
-    bash "$HOOK_UNDER_TEST"
-
-codex_home="$(make_home codex-plugin-hooks)"
-codex_data="$TEST_ROOT/codex-plugin-hooks/data"
-mkdir -p "$codex_data"
-assert_command_output \
-    "Codex plugin hooks use dedicated script and emit nested SessionStart additionalContext" \
-    "nested" \
-    "" \
-    "" \
-    "$codex_home" \
-    PLUGIN_DATA="$codex_data" \
-    CLAUDE_PLUGIN_DATA="$codex_data" \
-    PLUGIN_ROOT="$REPO_ROOT" \
-    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
-    bash "$CODEX_HOOK_UNDER_TEST"
-
-codex_wrapper_home="$(make_home codex-wrapper)"
-codex_wrapper_data="$TEST_ROOT/codex-wrapper/data"
-mkdir -p "$codex_wrapper_data"
-assert_command_output \
-    "Codex wrapper path dispatches to dedicated script" \
-    "nested" \
-    "" \
-    "" \
-    "$codex_wrapper_home" \
-    PLUGIN_DATA="$codex_wrapper_data" \
-    CLAUDE_PLUGIN_DATA="$codex_wrapper_data" \
-    PLUGIN_ROOT="$REPO_ROOT" \
-    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
-    bash "$WRAPPER_UNDER_TEST" session-start-codex
-
-cursor_home="$(make_home cursor)"
-assert_command_output \
-    "Cursor emits top-level additional_context only" \
-    "cursor" \
-    "" \
-    "" \
-    "$cursor_home" \
-    CURSOR_PLUGIN_ROOT="$REPO_ROOT" \
-    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
-    bash "$HOOK_UNDER_TEST"
-
-copilot_home="$(make_home copilot-cli)"
-assert_command_output \
-    "Copilot CLI emits top-level additionalContext only" \
-    "sdk" \
-    "" \
-    "" \
-    "$copilot_home" \
-    COPILOT_CLI=1 \
-    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
-    bash "$HOOK_UNDER_TEST"
-
-legacy_home="$(make_home legacy-warning-removed)"
-mkdir -p "$legacy_home/.config/superpowers/skills"
-assert_command_output \
-    "SessionStart omits obsolete legacy custom-skill warning" \
-    "nested" \
-    "" \
-    "Superpowers now uses"$'\037'"~/.config/superpowers/skills"$'\037'"~/.claude/skills"$'\037'"legacy" \
-    "$legacy_home" \
-    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
-    bash "$HOOK_UNDER_TEST"
-
-codex_legacy_home="$(make_home codex-legacy-warning-removed)"
-codex_legacy_data="$TEST_ROOT/codex-legacy-warning-removed/data"
-mkdir -p "$codex_legacy_home/.config/superpowers/skills" "$codex_legacy_data"
-assert_command_output \
-    "Codex SessionStart omits obsolete legacy custom-skill warning" \
-    "nested" \
-    "" \
-    "Superpowers now uses"$'\037'"~/.config/superpowers/skills"$'\037'"~/.claude/skills"$'\037'"legacy" \
-    "$codex_legacy_home" \
-    PLUGIN_DATA="$codex_legacy_data" \
-    CLAUDE_PLUGIN_DATA="$codex_legacy_data" \
-    PLUGIN_ROOT="$REPO_ROOT" \
-    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
-    bash "$CODEX_HOOK_UNDER_TEST"
-
-if [[ "$FAILURES" -gt 0 ]]; then
-    echo "STATUS: FAILED ($FAILURES failure(s))"
-    exit 1
-fi
-
-echo "STATUS: PASSED"

tests/kimi/run-tests.sh

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-
-bash "$SCRIPT_DIR/test-plugin-manifest.sh"

tests/kimi/test-plugin-manifest.sh

@@ -1,86 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-MANIFEST="$REPO_ROOT/.kimi-plugin/plugin.json"
-
-python3 - "$MANIFEST" <<'PY'
-import json
-import sys
-from pathlib import Path
-
-manifest_path = Path(sys.argv[1])
-manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
-
-def assert_equal(actual, expected, label):
-    if actual != expected:
-        raise AssertionError(f"{label}: expected {expected!r}, got {actual!r}")
-
-def assert_present(text, needle, label):
-    if needle not in text:
-        raise AssertionError(f"{label}: missing {needle!r}")
-
-assert_equal(manifest.get("name"), "superpowers", "plugin name")
-assert_equal(manifest.get("skills"), "./skills/", "skills path")
-assert_equal(
-    manifest.get("sessionStart", {}).get("skill"),
-    "using-superpowers",
-    "sessionStart.skill",
-)
-
-instructions = manifest.get("skillInstructions")
-if not isinstance(instructions, str) or not instructions.strip():
-    raise AssertionError("skillInstructions must be a non-empty string")
-
-for token in [
-    "AskUserQuestion",
-    "TodoList",
-    "Agent",
-    "Skill",
-    "Read",
-    "Write",
-    "Edit",
-    "Bash",
-    "Grep",
-    "Glob",
-    "FetchURL",
-    "WebSearch",
-]:
-    assert_present(instructions, token, "skillInstructions")
-
-version_config = json.loads(
-    (manifest_path.parents[1] / ".version-bump.json").read_text(encoding="utf-8")
-)
-version_entries = version_config.get("files")
-if not isinstance(version_entries, list):
-    raise AssertionError(".version-bump.json must contain files list")
-
-if not any(
-    entry.get("path") == ".kimi-plugin/plugin.json" and entry.get("field") == "version"
-    for entry in version_entries
-    if isinstance(entry, dict)
-):
-    raise AssertionError(
-        ".version-bump.json must update .kimi-plugin/plugin.json version"
-    )
-
-unsupported_fields = [
-    "tools",
-    "commands",
-    "hooks",
-    "apps",
-    "inject",
-    "configFile",
-    "config_file",
-    "bootstrap",
-]
-present_unsupported = sorted(field for field in unsupported_fields if field in manifest)
-if present_unsupported:
-    raise AssertionError(
-        "unsupported Kimi runtime fields present: "
-        + ", ".join(present_unsupported)
-    )
-
-print("Kimi plugin manifest looks good")
-PY

tests/opencode/test-bootstrap-caching.mjs

@@ -44,10 +44,6 @@ const result = {
   scenario,
   firstBootstrapParts: countBootstrapParts(firstOutput),
   secondBootstrapParts: countBootstrapParts(secondOutput),
-  staleMentionMapping: bootstrapText(firstOutput).includes('@mention'),
-  staleTaskMapping: bootstrapText(firstOutput).includes('`Task` tool with subagents'),
-  mapsSubagentToTask: bootstrapText(firstOutput).includes('`task` with `subagent_type: "general"`'),
-  mapsMutationToApplyPatch: bootstrapText(firstOutput).includes('`apply_patch`'),
   firstReadCount: afterFirst.readCount,
   secondReadCount: afterSecond.readCount,
   firstExistsCount: afterFirst.existsCount,
@@ -87,12 +83,6 @@ function countBootstrapParts(output) {
   ).length;
 }
 
-function bootstrapText(output) {
-  return output.messages[0].parts.find(
-    (part) => part.type === 'text' && part.text.includes('EXTREMELY_IMPORTANT')
-  )?.text || '';
-}
-
 function assertPresentBootstrap(result) {
   const failures = [];
   if (result.firstBootstrapParts !== 1) {
@@ -110,18 +100,6 @@ function assertPresentBootstrap(result) {
   if (result.secondExistsCount !== result.firstExistsCount) {
     failures.push(`expected cached second transform to do no additional exists checks, got ${result.secondExistsCount - result.firstExistsCount}`);
   }
-  if (result.staleMentionMapping) {
-    failures.push('expected OpenCode bootstrap not to teach @mention subagent syntax');
-  }
-  if (result.staleTaskMapping) {
-    failures.push('expected OpenCode bootstrap not to teach stale Task-tool mapping');
-  }
-  if (!result.mapsSubagentToTask) {
-    failures.push('expected OpenCode bootstrap to map general-purpose subagents to task with subagent_type');
-  }
-  if (!result.mapsMutationToApplyPatch) {
-    failures.push('expected OpenCode bootstrap to map file mutation to apply_patch');
-  }
   return failures;
 }
 

tests/pi/test-pi-extension.mjs

@@ -1,128 +0,0 @@
-import assert from 'node:assert/strict';
-import { readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import test from 'node:test';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const repoRoot = resolve(__dirname, '../..');
-const packageJsonPath = resolve(repoRoot, 'package.json');
-const extensionPath = resolve(repoRoot, '.pi/extensions/superpowers.ts');
-const piToolsPath = resolve(repoRoot, 'skills/using-superpowers/references/pi-tools.md');
-
-async function readPackageJson() {
-  return JSON.parse(await readFile(packageJsonPath, 'utf8'));
-}
-
-async function loadExtension() {
-  const handlers = new Map();
-  const pi = {
-    on(event, handler) {
-      if (!handlers.has(event)) handlers.set(event, []);
-      handlers.get(event).push(handler);
-    },
-  };
-  const mod = await import(pathToFileURL(extensionPath).href + `?cachebust=${Date.now()}-${Math.random()}`);
-  mod.default(pi);
-  return { handlers };
-}
-
-function firstHandler(handlers, event) {
-  const eventHandlers = handlers.get(event) ?? [];
-  assert.equal(eventHandlers.length, 1, `expected one ${event} handler`);
-  return eventHandlers[0];
-}
-
-function textOf(message) {
-  if (typeof message.content === 'string') return message.content;
-  return message.content
-    .filter((part) => part.type === 'text')
-    .map((part) => part.text)
-    .join('\n');
-}
-
-test('package.json declares a pi package with skills and extension resources', async () => {
-  const pkg = await readPackageJson();
-
-  assert.equal(pkg.name, 'superpowers');
-  assert.ok(pkg.keywords.includes('pi-package'));
-  assert.deepEqual(pkg.pi.skills, ['./skills']);
-  assert.deepEqual(pkg.pi.extensions, ['./.pi/extensions/superpowers.ts']);
-});
-
-test('extension registers lifecycle hooks without pre-compaction injection', async () => {
-  const { handlers } = await loadExtension();
-
-  for (const event of ['resources_discover', 'session_start', 'session_compact', 'context', 'agent_end']) {
-    assert.equal((handlers.get(event) ?? []).length, 1, `missing ${event} handler`);
-  }
-  assert.equal((handlers.get('session_before_compact') ?? []).length, 0);
-});
-
-test('resources_discover contributes the bundled skills directory', async () => {
-  const { handlers } = await loadExtension();
-  const discover = firstHandler(handlers, 'resources_discover');
-
-  const result = await discover({ type: 'resources_discover', cwd: repoRoot, reason: 'startup' }, {});
-
-  assert.deepEqual(result.skillPaths, [resolve(repoRoot, 'skills')]);
-});
-
-test('startup context injects the bootstrap as one user message until agent_end', async () => {
-  const { handlers } = await loadExtension();
-  const sessionStart = firstHandler(handlers, 'session_start');
-  const context = firstHandler(handlers, 'context');
-  const agentEnd = firstHandler(handlers, 'agent_end');
-
-  await sessionStart({ type: 'session_start', reason: 'startup' }, {});
-
-  const originalMessages = [
-    { role: 'user', content: [{ type: 'text', text: 'Let us make a react todo list' }], timestamp: 1 },
-  ];
-  const result = await context({ type: 'context', messages: originalMessages }, {});
-
-  assert.equal(result.messages.length, 2);
-  assert.equal(result.messages[0].role, 'user');
-  assert.match(textOf(result.messages[0]), /You have superpowers/);
-  assert.match(textOf(result.messages[0]), /Pi tool mapping/);
-  assert.equal(result.messages[1], originalMessages[0]);
-
-  const repeatedProviderRequest = await context({ type: 'context', messages: originalMessages }, {});
-  assert.equal(repeatedProviderRequest.messages.length, 2);
-  assert.match(textOf(repeatedProviderRequest.messages[0]), /You have superpowers/);
-
-  const alreadyInjected = await context({ type: 'context', messages: result.messages }, {});
-  assert.equal(alreadyInjected, undefined, 'bootstrap should not duplicate when already present');
-
-  await agentEnd({ type: 'agent_end', messages: [] }, {});
-  const afterEnd = await context({ type: 'context', messages: originalMessages }, {});
-  assert.equal(afterEnd, undefined, 'startup bootstrap should clear after agent_end');
-});
-
-test('session_compact injects bootstrap after compaction summaries, not before compaction', async () => {
-  const { handlers } = await loadExtension();
-  const sessionCompact = firstHandler(handlers, 'session_compact');
-  const context = firstHandler(handlers, 'context');
-
-  await sessionCompact({ type: 'session_compact', compactionEntry: {}, fromExtension: false }, {});
-
-  const summary = { role: 'compactionSummary', summary: 'Prior work summary', tokensBefore: 123, timestamp: 1 };
-  const user = { role: 'user', content: [{ type: 'text', text: 'Continue' }], timestamp: 2 };
-  const result = await context({ type: 'context', messages: [summary, user] }, {});
-
-  assert.equal(result.messages.length, 3);
-  assert.equal(result.messages[0], summary);
-  assert.equal(result.messages[1].role, 'user');
-  assert.match(textOf(result.messages[1]), /You have superpowers/);
-  assert.equal(result.messages[2], user);
-});
-
-test('pi tools reference documents pi-specific mappings', async () => {
-  assert.equal(existsSync(piToolsPath), true, 'pi-tools.md should exist');
-  const text = await readFile(piToolsPath, 'utf8');
-
-  for (const expected of ['Skill', 'Task', 'TodoWrite', 'read', 'write', 'edit', 'bash']) {
-    assert.match(text, new RegExp(expected));
-  }
-});

tests/shell-lint/test-lint-shell.sh

@@ -1,179 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-SCRIPT_UNDER_TEST="$REPO_ROOT/scripts/lint-shell.sh"
-
-FAILURES=0
-TEST_ROOT="$(mktemp -d)"
-
-cleanup() {
-  rm -rf "$TEST_ROOT"
-}
-trap cleanup EXIT
-
-pass() {
-  echo "  [PASS] $1"
-}
-
-fail() {
-  echo "  [FAIL] $1"
-  FAILURES=$((FAILURES + 1))
-}
-
-assert_contains() {
-  local haystack="$1"
-  local needle="$2"
-  local description="$3"
-
-  if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
-    pass "$description"
-  else
-    fail "$description"
-    echo "    expected to find: $needle"
-    echo "    in:"
-    printf '%s\n' "$haystack" | sed 's/^/      /'
-  fi
-}
-
-assert_not_contains() {
-  local haystack="$1"
-  local needle="$2"
-  local description="$3"
-
-  if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
-    fail "$description"
-    echo "    did not expect to find: $needle"
-    echo "    in:"
-    printf '%s\n' "$haystack" | sed 's/^/      /'
-  else
-    pass "$description"
-  fi
-}
-
-configure_git_identity() {
-  local repo="$1"
-
-  git -C "$repo" config user.name "Test Bot"
-  git -C "$repo" config user.email "test@example.com"
-}
-
-write_stub_tool() {
-  local path="$1"
-  local name="$2"
-
-  cat >"$path" <<EOF
-#!/usr/bin/env bash
-{
-  printf '${name}:'
-  for arg in "\$@"; do
-    printf ' <%s>' "\$arg"
-  done
-  printf '\n'
-} >> "\$SUPERPOWERS_SHELL_LINT_TEST_LOG"
-exit 0
-EOF
-  chmod +x "$path"
-}
-
-make_fixture_repo() {
-  local repo="$1"
-
-  git init -q -b main "$repo"
-  configure_git_identity "$repo"
-
-  mkdir -p "$repo/hooks"
-  cat >"$repo/tracked.sh" <<'EOF'
-#!/usr/bin/env bash
-echo "tracked"
-EOF
-  cat >"$repo/hooks/session-start" <<'EOF'
-#!/bin/sh
-echo "extensionless"
-EOF
-  cat >"$repo/README.md" <<'EOF'
-# Fixture
-
-```bash
-echo "not a shell script"
-```
-EOF
-  cat >"$repo/untracked.sh" <<'EOF'
-#!/usr/bin/env bash
-echo "untracked"
-EOF
-
-  git -C "$repo" add tracked.sh hooks/session-start README.md
-  git -C "$repo" commit -q -m "fixture"
-
-  printf '\necho "changed"\n' >>"$repo/tracked.sh"
-  printf '\necho "changed extensionless"\n' >>"$repo/hooks/session-start"
-}
-
-run_lint_shell() {
-  local repo="$1"
-  local fakebin="$2"
-  local log="$3"
-  shift 3
-
-  (
-    cd "$repo"
-    PATH="$fakebin:$PATH" \
-      SUPERPOWERS_SHELL_LINT_TEST_LOG="$log" \
-      bash "$SCRIPT_UNDER_TEST" "$@"
-  )
-}
-
-echo "Shell lint script tests"
-
-fixture="$TEST_ROOT/repo"
-fakebin="$TEST_ROOT/bin"
-log="$TEST_ROOT/tool.log"
-mkdir -p "$fixture" "$fakebin"
-: >"$log"
-write_stub_tool "$fakebin/shellcheck" "shellcheck"
-write_stub_tool "$fakebin/shfmt" "shfmt"
-make_fixture_repo "$fixture"
-
-if output="$(run_lint_shell "$fixture" "$fakebin" "$log" 2>&1)"; then
-  pass "lint-shell check mode exits successfully with stub tools"
-else
-  fail "lint-shell check mode exits successfully with stub tools"
-  printf '%s\n' "$output" | sed 's/^/      /'
-fi
-
-tool_log="$(cat "$log")"
-assert_contains "$output" "Linting 3 shell files" "reports changed shell file count"
-assert_not_contains "$tool_log" "shfmt:" "does not run shfmt in lint mode"
-assert_contains "$tool_log" "shellcheck:" "runs ShellCheck"
-assert_contains "$tool_log" "<--severity=warning>" "uses warning severity as the baseline"
-assert_contains "$tool_log" "<--external-sources>" "allows ShellCheck to follow sourced files"
-assert_contains "$tool_log" "<--source-path=SCRIPTDIR>" "resolves ShellCheck sources relative to each script"
-assert_contains "$tool_log" "<hooks/session-start>" "includes changed extensionless shell shebang file"
-assert_contains "$tool_log" "<tracked.sh>" "includes changed tracked .sh file"
-assert_contains "$tool_log" "<untracked.sh>" "includes untracked shell files by default"
-assert_not_contains "$tool_log" "README.md" "ignores Markdown with shell snippets"
-
-: >"$log"
-if output="$(run_lint_shell "$fixture" "$fakebin" "$log" --all --format 2>&1)"; then
-  pass "lint-shell --format exits successfully with stub tools"
-else
-  fail "lint-shell --format exits successfully with stub tools"
-  printf '%s\n' "$output" | sed 's/^/      /'
-fi
-
-tool_log="$(cat "$log")"
-assert_contains "$tool_log" "<-w>" "uses shfmt write mode with --format"
-assert_contains "$tool_log" "shellcheck:" "runs ShellCheck after --format"
-assert_contains "$tool_log" "<--severity=warning>" "keeps warning severity after --format"
-assert_contains "$tool_log" "<hooks/session-start>" "--all includes tracked extensionless shell shebang file"
-assert_contains "$tool_log" "<tracked.sh>" "--all includes tracked .sh file"
-assert_not_contains "$tool_log" "untracked.sh" "--all ignores untracked shell files"
-
-if [[ "$FAILURES" -eq 0 ]]; then
-  echo "All shell lint script tests passed"
-else
-  echo "$FAILURES shell lint script test(s) failed"
-  exit 1
-fi