@complexthings/superpowers-agent 8.1.0

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

@@ -0,0 +1,108 @@
+# SUPERPOWERS Reference Guide
+
+> 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:{{VERSION}}^^
+
+---
+
+## Installation
+
+If `superpowers-agent` is not available, install it:
+
+```bash
+npm install -g @complexthings/superpowers-agent
+```
+
+---
+
+## Version Detection Details
+
+When superpowers-agent runs, it displays its version as `^^SAV:X.Y.Z^^` in output.
+
+**How to check for updates:**
+1. Note the bootstrapped version in AGENTS.md: `^^SAV:{{VERSION}}^^`
+2. Compare with version shown when running superpowers-agent commands
+3. If versions differ, inform user:
+   ```
+   Your superpowers-agent may have updates. Run:
+   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.
+
+---
+
+## 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
+
+---
+
+*Generated by Superpowers on {{DATE}}*

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

@@ -0,0 +1,15 @@
+### 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

package/.github/workflows/main.yaml

@@ -0,0 +1,32 @@
+name: "Publish Package"
+
+on:
+  workflow_dispatch
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        node-version: [24]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6.3.0
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: "https://registry.npmjs.org"
+          scope: "@complexthings"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

package/AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md
+
+<!-- SUPERPOWERS_SKILLS_START -->
+## 🎯 SKILLS
+
+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
+
+### Load Just-In-Time
+
+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}"
+
+### 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
+
+**Bootstrapped:** ^^SAV:7.1.2^^
+
+If superpowers-agent commands show a different version, inform user:
+```
+superpowers-agent update && superpowers-agent bootstrap && superpowers-agent setup-skills
+```
+
+### 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.**
+
+---
+
+**Detailed reference for `superpowers-agent` if needed by agents:** `.agents/docs/SUPERPOWERS.md`
+
+*Generated by Superpowers on 2026-03-13*
+
+<!-- SUPERPOWERS_SKILLS_END -->
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.