@complexthings/superpowers-agent 8.2.2 → 8.3.0

package/.agents/docs/SUPERPOWERS.md

@@ -1,9 +1,11 @@
 # 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.
+
 > This is detailed reference documentation for the superpowers-agent system.
 > Load this file only when you need specific information not covered in AGENTS.md.
 
-**Current Version:** ^^SAV:7.1.2^^
+**Bootstrapped Version:** `^^SAV:7.1.2^^`
 
 ---
 
@@ -17,92 +19,24 @@ npm install -g @complexthings/superpowers-agent
 
 ---
 
-## Version Detection Details
-
-When superpowers-agent runs, it displays its version as `^^SAV:X.Y.Z^^` in output.
+## Version Check
 
-**How to check for updates:**
-1. Note the bootstrapped version in AGENTS.md: `^^SAV:7.1.2^^`
-2. Compare with version shown when running superpowers-agent commands
-3. If versions differ, inform user:
-   ```
+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:7.1.2^^`
+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
    ```
 
-**When to check:**
-- At conversation start
-- When commands behave unexpectedly
-- When user asks about updates or capabilities
-
----
-
-## Skill Locations
-
-### Project Skills (highest priority)
-- `.agents/skills/`
-- `.claude/skills/`
-- `.copilot/skills/`
-- `.opencode/skill/`
-- `.cursor/skills/`
-- `.gemini/skills/`
-- `.codex/skills/`
-
-### Personal Skills
-- `~/.agents/skills/`
-- `~/.claude/skills/`
-- `~/.copilot/skills/`
-- `~/.config/opencode/skill/`
-- `~/.cursor/skills/`
-- `~/.gemini/skills/`
-- `~/.codex/skills/`
-
-### Superpowers Skills
-- `~/.agents/superpowers/skills/`
-
-**Priority:** Project > Personal > Superpowers (when names match)
-
----
-
-## Skill Naming Conventions
-
-| Prefix | Source |
-|--------|--------|
-| `skill-name` | Project skills |
-| `claude:skill-name` | Claude skills |
-| `copilot:skill-name` | Copilot skills |
-| `opencode:skill-name` | OpenCode skills |
-| `cursor:skill-name` | Cursor skills |
-| `gemini:skill-name` | Gemini skills |
-| `codex:skill-name` | Codex skills |
-| `superpowers:skill-name` | Superpowers skills |
-
 ---
 
-## Creating New Skills
-
-1. Use the `brainstorming` skill to plan the skill
-2. Use the `writing-skills` skill to create it
-3. Test with `testing-skills-with-subagents`
-4. Save to `.agents/skills/` (project) or `~/.agents/superpowers/skills/` (global)
-
----
-
-## Skills with Checklists
-
-If a skill has a checklist, create todos for EACH item. Mental tracking = steps get skipped.
+## Skill Loading Rules
 
----
-
-## Common Mistakes to Avoid
-
-Reject these rationalizations:
-
-- "I'll read all the skills upfront to understand them" -> Load JIT only
-- "This is too simple for a skill" -> Simple tasks benefit most from proven process
-- "I already know how to do this" -> Skills encode edge cases you'll miss
-- "I'll just skim the skill" -> Follow instructions exactly as written
-
----
+- 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
 
-*Generated by Superpowers on 2026-03-13*
+**Skill priority (highest to lowest):** Project → Personal → Superpowers