@complexthings/superpowers-agent 9.1.0 → 9.2.1

package/.agents/templates/AGENTS.md.template

@@ -5,51 +5,24 @@ Skills extend your capabilities with proven workflows.
 ### Discover Skills First
 
 **Before starting any task**, check for relevant skills:
-1. Use your native skill tool to list available skills
-2. Review skill frontmatter/descriptions to identify relevant ones
-3. Run `superpowers-agent find-skills [PATTERN]` for superpowers skills
+1. Use your native skill tool to list available skills.
+2. Review skill descriptions/frontmatter to identify relevant ones.
 
 ### Skill Loading Rules
 
-- Load skills **JIT only** — never preload to "understand" them
-- Follow skill instructions **exactly as written** — no skimming, no shortcuts
-- If a skill has a checklist, create a todo for **each item** — no mental tracking
-- Simple tasks benefit from skills as much as complex ones
+- Load skills **JIT only** — never preload to "understand" them.
+- Follow skill instructions **exactly as written** — no skimming, no shortcuts.
+- If a skill has a checklist, create a todo for **each item** — no mental tracking.
+- Simple tasks benefit from skills as much as complex ones.
 
-**Skill priority (highest to lowest):** Project → Personal → Superpowers
+**Skill priority (highest to lowest):** Project → Personal
 
 ### Using Tools with Skills
 
-1. **Native Skill Tool** — Use your platform's native skill tool to load skills.
-2. **Symlinked Skills** — Superpowers skills are symlinked to your platform's skills directory.
-3. **Fallback** — If a skill isn't found via native tool, run `superpowers-agent find-skills [PATTERN]`
-4. **Tool Equivalence** — When a skill references a tool you don't have, substitute your equivalent:
-
-| Skill References | Use Your Equivalent |
-|---|---|
-| File operations | Read / Write / Edit tools |
-| Terminal commands | Bash / Shell tool |
-| Search operations | Grep / Glob / Search tools |
-| Task management | TodoWrite / TodoRead tools |
-| Subagent dispatch | Task / Agent tool — or execute directly |
-| Web fetching | WebFetch / Fetch tool |
-
-### Version Check
-
-**Bootstrapped Version:** `^^SAV:{{VERSION}}^^`
-
-At conversation start:
-1. Run a superpowers-agent command and note the version string `^^SAV:X.Y.Z^^` in output
-2. Compare against bootstrapped version `^^SAV:{{VERSION}}^^`
-3. If they differ, notify the user:
-   Your superpowers-agent may have updates. Run:
-   ```sh
-   superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
-   ```
-
-```sh
-superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
-```
+1. **Native skill tool** — load skills via your platform's native skill tool.
+2. **Symlinked skills** — Superpowers skills are symlinked into your platform's skills directory.
+3. **Fallback** — if a skill isn't found via the native tool, run `superpowers-agent find-skills [PATTERN]`.
+4. **Tool equivalence** — when a skill references a tool you don't have, substitute your equivalent.
 
 ### Why Skills Matter
 
@@ -57,4 +30,21 @@ Skills encode proven techniques that prevent mistakes. Not using them means repe
 
 **If a skill exists for your task, you MUST use it.**
 
-*Generated by Superpowers on {{DATE}}*
+---
+
+## Version Check
+
+Periodically, e.g. once per day check the version of superpowers-agent:
+1. **CURRENT_VERSION** — run a `superpowers-agent` command and extract `X.Y.Z` from the `^^SAV:X.Y.Z^^` string in its output.
+2. **NPM_LATEST_VERSION** — run `npm view @complexthings/superpowers-agent version`.
+3. Compare by **semver precedence, not string comparison** (e.g. `9.10.0` > `9.9.0`). If NPM_LATEST_VERSION is newer, tell the user — do not run these yourself:
+   > Your superpowers-agent has updates (`CURRENT_VERSION` → `NPM_LATEST_VERSION`). Run:
+   > ```sh
+   > npm install -g @complexthings/superpowers-agent
+   > superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
+   > ```
+   If versions match, or either lookup fails (e.g. no network), continue silently.
+
+---
+
+*Generated by Superpowers on {{DATE}}*

package/.agents/templates/SUPERPOWERS.md.template

@@ -1,42 +1,37 @@
 # SUPERPOWERS Reference Guide
 
-You are an autonomous agent with access to the `superpowers-agent` system. Reference documentation is in the `AGENTS.md` and the detailed reference guide below.
+You are an autonomous agent with access to the `superpowers-agent` system.
 
-> This is detailed reference documentation for the superpowers-agent system.
-> Load this file only when you need specific information not covered in AGENTS.md.
-
-**Bootstrapped Version:** `^^SAV:{{VERSION}}^^`
+> Loaded at conversation start. `AGENTS.md` is the primary reference; this guide is the detailed supplement.
 
 ---
 
 ## Installation
 
-If `superpowers-agent` is not available, install it:
-
-```bash
-npm install -g @complexthings/superpowers-agent
-```
+If `superpowers-agent` is not available, install it: `npm install -g @complexthings/superpowers-agent`
 
 ---
 
 ## Version Check
 
-At conversation start:
-1. Run a superpowers-agent command and note the version string `^^SAV:X.Y.Z^^` in output
-2. Compare against bootstrapped version `^^SAV:{{VERSION}}^^`
-3. If they differ, notify the user:
-   Your superpowers-agent may have updates. Run:
-   ```sh
-   superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
-   ```
+Periodically, e.g. once per day check the version of superpowers-agent:
+1. **CURRENT_VERSION** — run a `superpowers-agent version` command and extract `X.Y.Z` from the `X.Y.Z` string in its output.
+2. **NPM_LATEST_VERSION** — run `npm view @complexthings/superpowers-agent version`.
+3. Compare by **semver precedence, not string comparison** (e.g. `9.10.0` > `9.9.0`). If NPM_LATEST_VERSION is newer, tell the user — do not run these yourself:
+   > Your superpowers-agent has updates (`CURRENT_VERSION` → `NPM_LATEST_VERSION`). Run:
+   > ```sh
+   > npm install -g @complexthings/superpowers-agent
+   > superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
+   > ```
+   If versions match, or either lookup fails (e.g. no network), continue silently.
 
 ---
 
 ## Skill Loading Rules
 
-- Load skills **JIT only** — never preload to "understand" them
-- Follow skill instructions **exactly as written** — no skimming, no shortcuts
-- If a skill has a checklist, create a todo for **each item** — no mental tracking
-- Simple tasks benefit from skills as much as complex ones
+- Load skills **JIT only** — never preload to "understand" them.
+- Follow skill instructions **exactly as written** — no skimming, no shortcuts.
+- If a skill has a checklist, create a todo for **each item** — no mental tracking.
+- Simple tasks benefit from skills as much as complex ones.
 
-**Skill priority (highest to lowest):** Project → Personal → Superpowers
+**Skill priority (highest to lowest):** Project → Personal → Superpowers

package/.github/copilot-instructions.md

@@ -1,3 +1,111 @@
 <!-- SUPERPOWERS_-_INSTRUCTIONS_START -->
-${content}
+---
+name: using-superpowers
+description: "Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions. CRITICAL: this skill is already loaded in your context — do NOT invoke it again. It defines the foundational rule: if a skill might apply, you must invoke it first."
+---
+
+# Using Superpowers
+
+Superpowers is a skills system that gives you access to proven workflows, encoded as SKILL.md files. Skills prevent you from reinventing solved problems and repeating known mistakes. This skill establishes the foundational rule for how to use the entire system.
+
+## The Core Rule
+
+**Before any response or action, check whether a skill applies — then invoke it.**
+
+This means BEFORE writing code, BEFORE asking clarifying questions, BEFORE exploring files. Even a 1% chance a skill might apply means you invoke it to check. If the invoked skill turns out not to fit the situation, you don't need to follow it — but you must check.
+
+Why this matters: skills encode hard-won workflows for tasks like debugging, TDD, and brainstorming. Skipping the check means you may skip a workflow that would have prevented a costly mistake.
+
+## How to Discover and Invoke Skills
+
+Skills appear in your context as an available-skills list — scan it at the start of every task. That list is the same workflow library no matter which agent platform you run on (Claude Code, Copilot, OpenCode, Pi, or anything else); only the tools around it differ.
+
+To load a skill's full instructions:
+
+- **If your platform has a native skill-loading tool**, call it with the skill's name.
+- **If it doesn't**, load the skill the way you'd open any file: read its SKILL.md directly with your file-read tool. Find the path in the skills list, or via the CLI fallback below.
+
+Either path has the same result — the skill's content enters your context and you follow it directly. Don't assume a native tool exists; if you can't find one, read the file. The point is to get the skill's content in front of you, not to use any particular mechanism.
+
+**CLI fallback** (use when the skills list isn't already in your context):
+
+```bash
+superpowers-agent find-skills              # list all skills
+superpowers-agent find-skills | grep test  # filter by topic
+superpowers-agent execute <skill-name>     # print a skill to load and follow
+```
+
+**Announce when using a skill:**
+> "Using Skill: [name] to [purpose]"
+
+This keeps the conversation clear and lets the user know which workflow you're following.
+
+## Skill Priority
+
+When several skills could apply, load them in order of how much each reframes the problem — broadest understanding first, narrowest execution last. Loading a skill is cheap (you are only reading); committing to the wrong workflow is expensive.
+
+1. **Domain / context skills first.** A skill about the specific technology or domain you are working in teaches you the territory — and often tells you which approach fits, or that a generic workflow does not. Read it before you commit to a process, and before you brainstorm or plan: knowing the territory makes the brainstorm sharper and can rule a planning skill in or out. A domain skill outranks even an intent-gathering skill like brainstorming.
+2. **Process / approach skills next.** brainstorming, planning, systematic-debugging, test-driven-development — chosen *informed by* what the domain skill told you.
+3. **Implementation skills last.** Step-by-step execution guides, once the approach is set.
+
+Why this order: if you lock into a planning or process workflow before reading the domain skill, you may follow steps that do not fit the problem — and by the time you read the domain skill you are already mid-workflow and cannot switch cleanly. Read first, the domain skill can still redirect you to the right process, or tell you to skip one.
+
+**Worked example** — "Let's build a subscription checkout on Stripe," with a Stripe domain skill, a payment-flow planning skill, and a Stripe-checkout implementation skill available:
+
+→ `stripe-payments-domain` (learn the territory; it may change how you plan) → `planning-payment-flows` (map states and failure modes) → `implementing-stripe-checkout` (execute).
+
+When no domain skill applies, the leading process skill comes first: "Fix this bug" → `systematic-debugging`, then any domain or implementation skill it points you to.
+
+The first skill you load may change the rest of the plan — reassess after each one rather than committing to the whole sequence up front.
+
+## Mapping Skill Instructions to Your Tools
+
+A skill may name a tool using one platform's vocabulary — a todo tracker, a subagent dispatcher, a file editor, a shell, a search tool, a web fetcher. Map each to the closest equivalent your environment provides and use it. If your platform has no equivalent for something a skill calls for, perform the action inline yourself. The skill's intent is what matters, not the specific tool name it happens to use.
+
+## Red Flags — You're Rationalizing
+
+These thoughts mean STOP and check for a skill first:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
+
+## Skill Types
+
+**Rigid skills** (TDD, systematic-debugging): Follow exactly. The structure is the value — adapting away the discipline defeats the purpose.
+
+**Flexible skills** (patterns, guides): Adapt principles to context. The skill itself will indicate when flexibility is appropriate.
+
+## Checklists
+
+If a skill contains a checklist, create a task or todo entry for each item using your platform's task-tracking tool. Mental tracking causes steps to get skipped. Every time.
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows. A specific instruction is when skill discipline matters most.
+
+## Version Monitoring
+
+At conversation start (periodically thereafter, e.g. once per day), check your version:
+1. **CURRENT_VERSION** — run a `superpowers-agent version` command and extract `X.Y.Z` from the `X.Y.Z` string in its output.
+2. **NPM_LATEST_VERSION** — run `npm view @complexthings/superpowers-agent version`.
+3. Compare by **semver precedence, not string comparison** (e.g. `9.2.1` > `9.0.1`). If NPM_LATEST_VERSION is newer, tell the user — do not run these yourself:
+   > Your superpowers-agent has updates (`CURRENT_VERSION` → `NPM_LATEST_VERSION`). Run:
+   > ```sh
+   > npm install -g @complexthings/superpowers-agent
+   > superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
+   > ```
+   If versions match, or either lookup fails (e.g. no network), continue silently.
+
 <!-- SUPERPOWERS_-_INSTRUCTIONS_END -->

package/AGENTS.md

@@ -8,41 +8,24 @@ Skills extend your capabilities with proven workflows.
 ### Discover Skills First
 
 **Before starting any task**, check for relevant skills:
-1. Use your native skill tool to list available skills
-2. Review skill frontmatter/descriptions to identify relevant ones
-3. `superpowers-agent find-skills [PATTERN]` for superpowers skills
+1. Use your native skill tool to list available skills.
+2. Review skill descriptions/frontmatter to identify relevant ones.
 
-### Load Just-In-Time
+### Skill Loading Rules
 
-Only read the full skill content when you're ready to execute it:
-1. **Load fully** when about to use (not before)
-2. **Follow exactly** as written
-3. **Announce:** "Using Skill: {Name} to {Purpose}"
+- Load skills **JIT only** — never preload to "understand" them.
+- Follow skill instructions **exactly as written** — no skimming, no shortcuts.
+- If a skill has a checklist, create a todo for **each item** — no mental tracking.
+- Simple tasks benefit from skills as much as complex ones.
 
-### Using Tools with Skills
-
-**1. Native Skill Tool:** Use your platform's native skill tool for loading skills.
-
-**2. Symlinked Skills:** Superpowers skills are symlinked to your platform's skills directory.
-
-**3. Fallback:** If a skill isn't found via native tool, use `superpowers-agent find-skills [PATTERN]`
-
-**4. Tool Equivalence:** When skills reference tools you don't have, use your equivalent:
-   - File operations -> your Read/Write/Edit tools
-   - Terminal commands -> your Bash/Shell tool
-   - Search operations -> your Grep/Glob/Search tools
-   - Task management -> your TodoWrite/TodoRead tools
-   - Subagent dispatch -> your Task/Agent tool (or execute the work yourself)
-   - Web fetching -> your WebFetch/Fetch tool
-
-### Version Monitoring
+**Skill priority (highest to lowest):** Project → Personal
 
-**Bootstrapped:** ^^SAV:7.1.2^^
+### Using Tools with Skills
 
-If superpowers-agent commands show a different version, inform user:
-```
-superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
-```
+1. **Native skill tool** — load skills via your platform's native skill tool.
+2. **Symlinked skills** — Superpowers skills are symlinked into your platform's skills directory.
+3. **Fallback** — if a skill isn't found via the native tool, run `superpowers-agent find-skills [PATTERN]`.
+4. **Tool equivalence** — when a skill references a tool you don't have, substitute your equivalent.
 
 ### Why Skills Matter
 
@@ -52,10 +35,22 @@ Skills encode proven techniques that prevent mistakes. Not using them means repe
 
 ---
 
-**Detailed reference for `superpowers-agent` if needed by agents:** `.agents/docs/SUPERPOWERS.md`
+## Version Check
 
-*Generated by Superpowers on 2026-03-13*
+Periodically, e.g. once per day check the version of superpowers-agent:
+1. **CURRENT_VERSION** — run a `superpowers-agent` command and extract `X.Y.Z` from the `^^SAV:X.Y.Z^^` string in its output.
+2. **NPM_LATEST_VERSION** — run `npm view @complexthings/superpowers-agent version`.
+3. Compare by **semver precedence, not string comparison** (e.g. `9.10.0` > `9.9.0`). If NPM_LATEST_VERSION is newer, tell the user — do not run these yourself:
+   > Your superpowers-agent has updates (`CURRENT_VERSION` → `NPM_LATEST_VERSION`). Run:
+   > ```sh
+   > npm install -g @complexthings/superpowers-agent
+   > superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
+   > ```
+   If versions match, or either lookup fails (e.g. no network), continue silently.
+
+---
 
+*Generated by Superpowers on 2026-06-01*
 <!-- SUPERPOWERS_SKILLS_END -->
 
 ## What This Project Is

package/README.md

@@ -6,6 +6,14 @@ A comprehensive skills library of proven techniques, patterns, and workflows for
 
 ## What's New
 
+**v9.2.1 (June 1, 2026):**
+
+- **GitHub agents now reach the Copilot CLI** — `add` and `pull` now also symlink GitHub agents (`.github/agents/<name>.agent.md`) into `~/.copilot/agents/`, alongside the existing VS Code `prompts/` install, so the same agents are usable by the GitHub Copilot CLI. `rm` cleans up both locations.
+- **npm-based version monitoring** — the `using-superpowers` skill and `AGENTS.md` template now check for updates by querying the npm registry (`npm view @complexthings/superpowers-agent version`) and comparing by semver precedence, prompting you to update only when npm is actually newer (replaces the old bundled-version-string comparison).
+- **Smarter skill-priority guidance** — `using-superpowers` now tells agents to load domain/context skills first, then process skills (brainstorming, planning, debugging, TDD), then implementation skills, so the domain skill can shape which process fits.
+- **`leveraging-cli-tools` nudge broadened** — the session-start context now also points agents at the skill whenever a task involves using Bash.
+- **Template cleanup** — removed `TOOLS.md.template` and the `{{TOOL_MAPPINGS}}` bootstrap placeholder; tool-equivalence guidance now lives inline in the refreshed `AGENTS.md`/`SUPERPOWERS.md` templates. `AGENTS.md` skill priority simplified to Project → Personal.
+
 **v9.1.0 (May 30, 2026):**
 
 - **Session-start hooks installed by `bootstrap`** — `bootstrap` now installs a Claude Code `SessionStart` hook into `~/.claude/settings.json` and a GitHub Copilot CLI `sessionStart` hook at `~/.copilot/hooks/superpowers.json`, so the Superpowers context is injected at the start of every session. The Claude merge is idempotent and preserves your other hooks/settings. (This replaces the old Claude Code plugin hook, which has been removed.)
@@ -51,29 +59,6 @@ A comprehensive skills library of proven techniques, patterns, and workflows for
 - 📋 **Smart Copilot Instructions** - `bootstrap` and `update` now process `~/.github/copilot-instructions.md` as a template, injecting the `using-superpowers` skill content and supporting marker-based idempotent updates with automatic backups
 - 📊 **Mermaid Flowcharts** - Replaced DOT-format flowcharts with Mermaid syntax across 8 skills for better rendering in GitHub, VS Code, and agent contexts
 
-**v6.5.0 (January 24, 2026):**
-
-- 🔄 **Upstream Sync** - Ported advanced features from Jesse Vincent's [obra/superpowers](https://github.com/obra/superpowers) v4.1.1:
-  - **OpenCode Plugin** (`.opencode/plugins/superpowers-agent.js`) - Session bootstrap injection via system prompt transform
-  - **using-superpowers Skill** - Behavioral enforcement with Red Flags rationalization table (12 anti-patterns)
-  - **Two-Stage Code Review** - Spec compliance review + code quality review workflow
-  - **Test Infrastructure** (`tests/`) - Agent-agnostic test scripts for skill triggering
-
-- 🔌 **OpenCode Plugin** - Native plugin for OpenCode that injects superpowers context at every session start using `experimental.chat.system.transform` hook
-
-- 📋 **Two-Stage Review Process** - Updated `subagent-driven-development` skill with spec reviewer and code quality reviewer prompts for comprehensive code review
-
-**v6.4.x (January 23-24, 2026):**
-
-- 📐 **Context Optimization** - Reduced AGENTS.md context size by ~60-70% with separate SUPERPOWERS.md reference file
-- 🔗 **Project-Level Symlinks** - `setup-skills` now creates symlinks from agent directories to `.agents/skills`
-
-**Previous Releases:**
-
-- **v6.3.x** - Codex platform support, native skill tools, extended symlinks for OpenCode/Cursor/Gemini
-- **v6.0.0** - Complete codebase modernization with 90% bundle reduction
-- **v5.4.0** - Dynamic tool mappings, automated platform detection
-
 **Key Features:**
 
 - 🎯 **Smart Skill Matching** - Just type `superpowers execute brainstorming` instead of full paths
@@ -272,8 +257,9 @@ Repositories can include an `agents.json` manifest to automatically install AI a
 
 | Platform | Source Directory | Destination |
 |----------|----------------|-------------|
-| `github` | `.github/agents/<name>.agent.md` | VS Code `prompts/` directory |
+| `github` | `.github/agents/<name>.agent.md` | VS Code `prompts/` directory **and** `~/.copilot/agents/` (GitHub Copilot CLI) |
 | `opencode` | `.opencode/agents/<name>.md` | `~/.config/opencode/agents/` |
+| `claude` | `.claude/agents/<name>.md` | `~/.claude/agents/` |
 
 **How it works:**
 1. After skills are installed, the system checks for `agents.json` at the repository root

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@complexthings/superpowers-agent",
-  "version": "9.1.0",
+  "version": "9.2.1",
   "description": "Superpowers agent CLI — skills system for AI coding agents",
   "type": "module",
   "bin": {

package/skills/meta/using-superpowers/SKILL.md

@@ -15,62 +15,51 @@ This means BEFORE writing code, BEFORE asking clarifying questions, BEFORE explo
 
 Why this matters: skills encode hard-won workflows for tasks like debugging, TDD, and brainstorming. Skipping the check means you may skip a workflow that would have prevented a costly mistake.
 
-## How to Invoke Skills
+## How to Discover and Invoke Skills
 
-Your platform's skill tool is the primary way to load a skill. Available skills are listed in your system context — scan this list before starting any task.
+Skills appear in your context as an available-skills list — scan it at the start of every task. That list is the same workflow library no matter which agent platform you run on (Claude Code, Copilot, OpenCode, Pi, or anything else); only the tools around it differ.
 
-To load a skill, use your platform's native skill tool with the skill name:
+To load a skill's full instructions:
 
-```
-skill("brainstorming")
-skill("systematic-debugging")
-skill("test-driven-development")
-```
-
-When a skill is invoked, its full content is loaded into context. Follow it directly.
-
-**Announce when using a skill:**
-> "Using Skill: [name] to [purpose]"
-
-This keeps the conversation clear and lets the user know which workflow you're following.
+- **If your platform has a native skill-loading tool**, call it with the skill's name.
+- **If it doesn't**, load the skill the way you'd open any file: read its SKILL.md directly with your file-read tool. Find the path in the skills list, or via the CLI fallback below.
 
-## How to Discover Skills
+Either path has the same result — the skill's content enters your context and you follow it directly. Don't assume a native tool exists; if you can't find one, read the file. The point is to get the skill's content in front of you, not to use any particular mechanism.
 
-**Primary method:** Scan the `available_skills` list in your system context. It's always there — review it at the start of every conversation.
+**CLI fallback** (use when the skills list isn't already in your context):
 
-**CLI fallback:**
 ```bash
 superpowers-agent find-skills              # list all skills
 superpowers-agent find-skills | grep test  # filter by topic
-superpowers-agent execute <skill-name>     # load and follow a skill
+superpowers-agent execute <skill-name>     # print a skill to load and follow
 ```
 
+**Announce when using a skill:**
+> "Using Skill: [name] to [purpose]"
+
+This keeps the conversation clear and lets the user know which workflow you're following.
+
 ## Skill Priority
 
-When multiple skills could apply, invoke in this order:
+When several skills could apply, load them in order of how much each reframes the problem — broadest understanding first, narrowest execution last. Loading a skill is cheap (you are only reading); committing to the wrong workflow is expensive.
+
+1. **Domain / context skills first.** A skill about the specific technology or domain you are working in teaches you the territory — and often tells you which approach fits, or that a generic workflow does not. Read it before you commit to a process, and before you brainstorm or plan: knowing the territory makes the brainstorm sharper and can rule a planning skill in or out. A domain skill outranks even an intent-gathering skill like brainstorming.
+2. **Process / approach skills next.** brainstorming, planning, systematic-debugging, test-driven-development — chosen *informed by* what the domain skill told you.
+3. **Implementation skills last.** Step-by-step execution guides, once the approach is set.
+
+Why this order: if you lock into a planning or process workflow before reading the domain skill, you may follow steps that do not fit the problem — and by the time you read the domain skill you are already mid-workflow and cannot switch cleanly. Read first, the domain skill can still redirect you to the right process, or tell you to skip one.
 
-1. **Process skills first** (brainstorming, systematic-debugging, test-driven-development) — these determine HOW to approach the task
-2. **Implementation skills second** (domain-specific guides) — these guide execution
+**Worked example** — "Let's build a subscription checkout on Stripe," with a Stripe domain skill, a payment-flow planning skill, and a Stripe-checkout implementation skill available:
 
-Examples:
-- "Let's build X" → invoke `brainstorming` first, then domain implementation skills
-- "Fix this bug" → invoke `systematic-debugging` first, then domain-specific skills
+→ `stripe-payments-domain` (learn the territory; it may change how you plan) → `planning-payment-flows` (map states and failure modes) → `implementing-stripe-checkout` (execute).
 
-## Tool Mapping
+When no domain skill applies, the leading process skill comes first: "Fix this bug" → `systematic-debugging`, then any domain or implementation skill it points you to.
 
-Skills may reference tools by names used in a specific platform. Map them to whatever equivalent tools your agent environment provides:
+The first skill you load may change the rest of the plan — reassess after each one rather than committing to the whole sequence up front.
 
-| Skill instruction | What it means |
-|-------------------|---------------|
-| `TodoWrite` / task list | Your platform's todo or task-tracking tool |
-| `Task` / subagent dispatch | Your subagent or agent-spawning tool |
-| `Skill` tool | Your platform's native skill-loading tool |
-| File read/write/edit | Your file read, write, and edit tools |
-| Terminal / shell commands | Your bash or shell execution tool |
-| Search | Your grep, glob, or search tools |
-| Web fetching | Your web fetch or browser tool |
+## Mapping Skill Instructions to Your Tools
 
-If your platform doesn't have an exact equivalent, use the closest available tool or perform the action inline.
+A skill may name a tool using one platform's vocabulary — a todo tracker, a subagent dispatcher, a file editor, a shell, a search tool, a web fetcher. Map each to the closest equivalent your environment provides and use it. If your platform has no equivalent for something a skill calls for, perform the action inline yourself. The skill's intent is what matters, not the specific tool name it happens to use.
 
 ## Red Flags — You're Rationalizing
 
@@ -107,16 +96,13 @@ Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
 
 ## Version Monitoring
 
-Superpowers version in AGENTS.md: `^^SAV:7.1.2^^`
-
-If `superpowers-agent` commands display a different version, notify the user:
-```
-superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
-```
-
-## Related Skills
-
-- **finding-skills** — Detailed guide for discovering and filtering available skills
-- **using-a-skill** — How to load and apply a specific skill by name
-- **brainstorming** — Required before any creative work or feature implementation
-- **writing-skills** — How to create new skills using TDD
+At conversation start (periodically thereafter, e.g. once per day), check your version:
+1. **CURRENT_VERSION** — run a `superpowers-agent version` command and extract `X.Y.Z` from the `X.Y.Z` string in its output.
+2. **NPM_LATEST_VERSION** — run `npm view @complexthings/superpowers-agent version`.
+3. Compare by **semver precedence, not string comparison** (e.g. `9.2.1` > `9.0.1`). If NPM_LATEST_VERSION is newer, tell the user — do not run these yourself:
+   > Your superpowers-agent has updates (`CURRENT_VERSION` → `NPM_LATEST_VERSION`). Run:
+   > ```sh
+   > npm install -g @complexthings/superpowers-agent
+   > superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
+   > ```
+   If versions match, or either lookup fails (e.g. no network), continue silently.

package/.agents/templates/TOOLS.md.template

@@ -1,15 +0,0 @@
-### Using Tools with Skills
-
-**1. Native Skill Tool:** Use your platform's native skill tool for loading skills.
-
-**2. Symlinked Skills:** Superpowers skills are symlinked to your platform's skills directory.
-
-**3. Fallback:** If a skill isn't found via native tool, use `superpowers-agent find-skills [PATTERN]`
-
-**4. Tool Equivalence:** When skills reference tools you don't have, use your equivalent:
-   - File operations -> your Read/Write/Edit tools
-   - Terminal commands -> your Bash/Shell tool
-   - Search operations -> your Grep/Glob/Search tools
-   - Task management -> your TodoWrite/TodoRead tools
-   - Subagent dispatch -> your Task/Agent tool (or execute the work yourself)
-   - Web fetching -> your WebFetch/Fetch tool