@complexthings/superpowers-agent 9.2.1 → 10.0.1

package/.agents/superpowers-bootstrap.md

@@ -4,7 +4,7 @@
 You have superpowers. Superpowers teach you new skills and capabilities.
 
 **Tool for running skills:**
-- `superpowers-agent execute <skill-name>`
+- Use your platform's native skill tool, or read the skill's `SKILL.md` directly.
 
 **Platform-specific tool mappings:**
 Tool mappings for your detected platforms are automatically included in your platform-specific configuration files:
@@ -26,8 +26,8 @@ Project skills override Claude skills, which override personal skills, which ove
 
 **Critical Rules:**
 - Before ANY task, review the skills list (shown at bootstrap)
-- If a relevant skill exists, you MUST use `superpowers-agent execute` to load it and follow instructions.
-  - YOU MUST USE YOUR `Read` TOOL TO READ THE SKILL FILE FROM THE PATH SHOWN. YOU MUST NOT `cat` the file or `print` it to yourself.
+- If a relevant skill exists, you MUST load it with your platform's native skill tool and follow its instructions.
+  - YOU MUST USE YOUR `Read` TOOL TO READ THE SKILL FILE. YOU MUST NOT `cat` or print it to yourself.
 - Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
 - Skills with checklists require `manage_todo_list` todos for each item (or manual tracking if unavailable)
 - NEVER skip mandatory workflows (brainstorming before coding, TDD, systematic debugging)

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

@@ -1,50 +1,27 @@
 ## 🎯 SKILLS
 
-Skills extend your capabilities with proven workflows.
+[superpowers-agent Docs](.agents/docs/SUPERPOWERS.md)
 
-### Discover Skills First
-
-**Before starting any task**, check for relevant 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.
-
-**Skill priority (highest to lowest):** Project → Personal
-
-### Using Tools with 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
-
-Skills encode proven techniques that prevent mistakes. Not using them means repeating solved problems and missing edge cases.
-
-**If a skill exists for your task, you MUST use it.**
+- Skills encode proven techniques that prevent mistakes.
+   - Not using them means repeating solved problems and missing edge cases.
+   - If a skill exists for your task, you MUST use it.
+- **Before starting any task**, check for relevant skills, use your native skill tool to do so.
+- Review skill descriptions/frontmatter to identify relevant ones.
+— when a skill references a tool you don't have, substitute your equivalent.
 
 ---
 
 ## 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.
+Once per day, check for updates:
+1. **CURRENT_VERSION** — run any `superpowers-agent` command, extract `X.Y.Z` from `^^SAV:X.Y.Z^^` in the 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:
+3. Compare by semver, not string order (`9.10.0` > `9.9.0`). If newer, tell the user — don't 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.
+   Match, or a lookup fails → stay silent.
 
 ---
-
-*Generated by Superpowers on {{DATE}}*

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

@@ -14,16 +14,16 @@ If `superpowers-agent` is not available, install it: `npm install -g @complexthi
 
 ## Version Check
 
-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.
+Once per day, check for updates:
+1. **CURRENT_VERSION** — run `superpowers-agent version`, extract `X.Y.Z` from the 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:
+3. Compare by semver, not string order (`9.10.0` > `9.9.0`). If newer, tell the user — don't 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.
+   Match, or a lookup fails → stay silent.
 
 ---
 

package/.github/copilot-instructions.md

@@ -1,111 +1,35 @@
 <!-- SUPERPOWERS_-_INSTRUCTIONS_START -->
----
-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."
----
+# Superpowers Skills
 
-# Using Superpowers
+[superpowers-agent Docs](../.agents/docs/SUPERPOWERS.md)
 
-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.
+Use your platform's native skill tool to discover and load installed skills relevant to the task. If no native tool is available, inspect the configured skill directories and read the needed `SKILL.md` file.
+<!-- SUPERPOWERS_-_INSTRUCTIONS_END -->
 
-To load a skill's full instructions:
+<!-- rtk-instructions v2 -->
+# RTK — Token-Optimized CLI
 
-- **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.
+**rtk** is a CLI proxy that filters and compresses command outputs, saving 60-90% tokens.
 
-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.
+## Rule
 
-**CLI fallback** (use when the skills list isn't already in your context):
+Always prefix shell commands with `rtk`:
 
 ```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
+# Instead of:              Use:
+git status                 rtk git status
+git log -10                rtk git log -10
+cargo test                 rtk cargo test
+docker ps                  rtk docker ps
+kubectl get pods           rtk kubectl pods
 ```
 
-**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
+## Meta commands (use directly)
 
-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 -->
+```bash
+rtk gain              # Token savings dashboard
+rtk gain --history    # Per-command savings history
+rtk discover          # Find missed rtk opportunities
+rtk proxy <cmd>       # Run raw (no filtering) but track usage
+```
+<!-- /rtk-instructions -->

package/.github/hooks/rtk-rewrite.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "rtk hook copilot",
+        "cwd": ".",
+        "timeout": 5
+      }
+    ],
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "rtk hook copilot",
+        "powershell": "rtk hook copilot",
+        "cwd": ".",
+        "timeoutSec": 5
+      }
+    ]
+  }
+}

package/AGENTS.md

@@ -24,7 +24,7 @@ Skills extend your capabilities with proven workflows.
 
 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]`.
+3. **Fallback** — if a skill isn't found via the native tool, inspect the configured skill directories and read its `SKILL.md` directly.
 4. **Tool equivalence** — when a skill references a tool you don't have, substitute your equivalent.
 
 ### Why Skills Matter
@@ -50,7 +50,7 @@ Periodically, e.g. once per day check the version of superpowers-agent:
 
 ---
 
-*Generated by Superpowers on 2026-06-01*
+*Generated by Superpowers on 2026-07-12*
 <!-- SUPERPOWERS_SKILLS_END -->
 
 ## What This Project Is
@@ -76,7 +76,7 @@ The CLI has **no runtime dependencies** (pure Node.js/Bun built-ins). The only d
 
 ## Testing
 
-There is **no automated test runner** and no `test` script. Verification is manual: run the CLI commands directly, or drive the saved prompt scenarios in `.agents/prompts/`. State this plainly rather than inventing a test command.
+Run the automated test suite from `.agents` with `bun test`. There is no root-level test script; run CLI commands directly for manual acceptance checks.
 
 ## Architecture
 
@@ -104,15 +104,14 @@ From `.agents/src/cli.js` dispatch table:
 
 - **Core:** `bootstrap [--no-update] [--force]`, `version`, `check-updates`, `update [--no-reinstall]`
 - **Config:** `config-get`, `config-set <key> <value>`
-- **Skills:** `setup-skills`, `find-skills [pattern]`, `use-skill <name>`, `execute <name>`, `dir <name>`, `path <name>`, `get-helpers <skill> <search-term>`
+- **Skills:** `setup-skills`, `session-context [--format=claude|copilot|raw]`
 - **Install/manage skills:** `add <url-or-path|@alias> [path]`, `add-repository <git-url> [--as=@alias]`, `list-repositories`, `pull <url-or-path|@alias>`, `rm <url-or-path|@alias>`
 - **Integrations:** `install-cursor-hooks`, `install-aliases`
 
 ### Key Flows
 
 - **`bootstrap`** → detects installed AI platforms → symlinks skills into each platform's skills dir → writes platform config files
-- **`find-skills [pattern]`** → searches all three skill tiers → returns name/path/description
-- **`execute <skill-name>`** → locates skill → outputs SKILL.md content for the agent to follow
+- **Native skill tools** → discover and load skills from their configured directories
 - **`add <url-or-path|@alias>`** → clones a git repo or copies a local path → installs skills into `~/.agents/superpowers/skills/`
 - **`update`** → checks the npm registry for a newer version → reports if an update is available
 
@@ -150,3 +149,5 @@ The five canonical triage roles use their default label strings (`needs-triage`,
 ### Domain docs
 
 Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root (created lazily). See `docs/agents/domain.md`.
+
+@RTK.md