@complexthings/superpowers-agent 9.2.0 → 10.0.0

package/skills/meta/creating-prompts/examples/do-example.md

@@ -1,65 +0,0 @@
----
-number: 003
-topic: auth-middleware
-purpose: do
-dependencies: [002]
-created: 2025-11-21
----
-
-# Auth Middleware - Do
-
-<objective>
-Implement JWT authentication middleware for Express API
-
-Purpose: Protect API routes from unauthorized access, enable user authentication
-Output: Express middleware function with error handling
-</objective>
-
-<context>
-Based on plan: @.agents/prompts/002-auth-plan/auth-plan-output.md
-
-Current API structure:
-- Express app in src/server.js
-- Routes in src/routes/
-- Using jose library for JWT (from research)
-</context>
-
-<requirements>
-- Verify JWT token from Authorization header
-- Extract user ID from token payload
-- Attach user to request object
-- Return 401 for missing/invalid tokens
-- Return 403 for expired tokens
-- Log authentication failures
-</requirements>
-
-<implementation>
-Use jose library for verification (don't use jsonwebtoken)
-Load JWT secret from environment variable
-Handle all error cases explicitly
-Don't catch generic errors - let Express error handler manage them
-
-Integration: Apply to protected routes in src/routes/api.js
-</implementation>
-
-<output>
-Create files:
-- `src/middleware/auth.js` - Main middleware function
-- `src/middleware/auth.test.js` - Unit tests
-
-Modify:
-- `src/routes/api.js` - Apply middleware to protected routes
-</output>
-
-<verification>
-Before declaring complete:
-- Run: `npm test src/middleware/auth.test.js` - all tests pass
-- Test invalid token returns 401
-- Test expired token returns 403
-- Test valid token attaches user to req.user
-- Start server and hit /api/protected with curl - verify 401 without token
-</verification>
-
-<summary_requirements>
-Create `SUMMARY.md` in same directory with outcome, files created, any decisions needed, and next steps.
-</summary_requirements>

package/skills/meta/creating-prompts/examples/plan-example.md

@@ -1,75 +0,0 @@
----
-number: 002
-topic: auth
-purpose: plan
-dependencies: [001]
-created: 2025-11-21
----
-
-# Auth - Plan
-
-<objective>
-Create implementation plan for JWT authentication system based on research findings
-</objective>
-
-<context>
-Research findings: @.agents/prompts/001-auth-research/auth-research-output.md
-
-Recommendation: jose library with httpOnly cookies
-Current state: No authentication, all routes publicly accessible
-Constraints: Must work with existing Express API, minimal breaking changes
-</context>
-
-<requirements>
-Plan must address:
-- JWT generation and verification
-- Refresh token rotation
-- Cookie configuration (httpOnly, secure, sameSite)
-- Error handling for expired/invalid tokens
-- Migration path from no-auth to auth
-- Testing strategy
-
-Decision points to resolve:
-- Token expiry times (access vs refresh)
-- Where to store refresh tokens (DB vs memory)
-</requirements>
-
-<output_structure>
-Create plan with:
-
-## Phases
-- Phase 1: Core JWT utilities (jose integration, token generation/verification)
-- Phase 2: Authentication middleware (verify tokens, attach user to request)
-- Phase 3: Refresh token system (rotation, secure storage)
-- Phase 4: Route protection (apply middleware, update tests)
-
-## Dependencies
-- Phase 2 needs Phase 1 JWT utilities
-- Phase 3 needs Phase 2 middleware
-- Phase 4 needs all previous phases
-
-## Decision Points
-- **Token expiry**: Access 15min, Refresh 7 days (OWASP standard) vs Access 1hr, Refresh 30 days (more convenient)
-  - Recommendation: Start with OWASP standard, gather feedback
-  
-- **Refresh storage**: PostgreSQL table vs Redis
-  - Recommendation: PostgreSQL for simplicity (already in stack)
-
-## Risk Assessment
-- Breaking existing clients: Gradual rollout, auth optional initially
-- Token compromise: Short expiry + rotation mitigates
-- Performance: JWT verification is fast, minimal impact
-
-## Success Metrics
-- All protected routes return 401 without valid token
-- Refresh rotation working (old tokens invalidated)
-- Zero security warnings from npm audit
-</output_structure>
-
-<summary_requirements>
-Create `SUMMARY.md` with:
-- One-liner: 4-phase implementation plan with OWASP-compliant token expiry
-- Key Findings: Critical insights about approach
-- Decisions Needed: Approve token expiry times
-- Next Step: Implement Phase 1
-</summary_requirements>

package/skills/meta/creating-prompts/examples/refine-example.md

@@ -1,65 +0,0 @@
----
-number: 004
-topic: auth-research
-purpose: refine
-dependencies: [001]
-created: 2025-11-21
----
-
-# Auth Research - Refine
-
-<objective>
-Deepen auth research to address refresh token storage question from @.agents/prompts/001-auth-research/auth-research-output.md
-</objective>
-
-<current_gaps>
-Original research left open: "Where to store refresh tokens server-side?"
-Need to compare DB vs Redis vs in-memory storage
-Security implications unclear
-Performance impact unknown
-</current_gaps>
-
-<preserve>
-Original findings on jose library selection
-httpOnly cookie recommendation
-Refresh rotation requirement
-All original key findings remain valid
-</preserve>
-
-<refinement_focus>
-Research refresh token storage options:
-- PostgreSQL table: persistence, scalability, already in stack
-- Redis: speed, built-in expiry, requires new dependency
-- In-memory: fast, simple, lost on restart
-
-Compare:
-- Security implications of each
-- Performance characteristics
-- Operational complexity
-- Cost of adding Redis vs using existing DB
-</refinement_focus>
-
-<output>
-Update @.agents/prompts/001-auth-research/auth-research-output.md with:
-
-## What Changed
-- Added: Comprehensive refresh token storage analysis
-- Added: Performance benchmarks (DB vs Redis)
-- Strengthened: Security section with storage implications
-- Clarified: Recommendation includes storage strategy
-
-## Changelog
-- v2: 2025-11-21 - Added refresh token storage analysis, resolved open question
-- v1: 2025-11-20 - Initial JWT library and cookie research
-
-Archive previous version to archive/auth-research-v1.md
-</output>
-
-<summary_requirements>
-Update `SUMMARY.md` with:
-- One-liner: JWT with jose library, httpOnly cookies, PostgreSQL for refresh tokens
-- Key Findings: Include new storage recommendation
-- Version: v2
-- Decisions Needed: None - storage question resolved
-- Next Step: Proceed with planning phase
-</summary_requirements>

package/skills/meta/creating-prompts/examples/research-example.md

@@ -1,63 +0,0 @@
----
-number: 001
-topic: auth
-purpose: research
-dependencies: []
-created: 2025-11-21
----
-
-# Auth - Research
-
-<objective>
-Research JWT authentication approaches for Node.js Express API to inform implementation decision
-</objective>
-
-<focus_areas>
-- Compare JWT libraries: jsonwebtoken vs jose vs paseto
-- httpOnly cookies vs localStorage for token storage
-- Refresh token patterns and rotation strategies
-- Security best practices (OWASP recommendations)
-</focus_areas>
-
-<sources>
-OWASP JWT Cheat Sheet
-NPM package comparisons (downloads, maintenance, TypeScript support)
-Existing code: @src/server.js, @src/routes/
-Security advisories for JWT libraries
-</sources>
-
-<output_requirements>
-Provide research findings with:
-
-## Key Findings
-- jose library: Better TypeScript support, actively maintained, smaller bundle
-- jsonwebtoken: More popular but older patterns, maintenance concerns
-- httpOnly cookies required (localStorage vulnerable to XSS)
-- Refresh rotation is OWASP standard (invalidate old tokens on refresh)
-
-## Confidence Level
-High - Multiple authoritative sources agree on best practices
-Medium - jose vs jsonwebtoken (both work, jose has better DX)
-
-## Recommendations
-- Use jose library for JWT operations
-- Store tokens in httpOnly cookies (never localStorage)
-- Implement refresh token rotation
-- Use short access token expiry (15min recommended by OWASP)
-
-## Open Questions
-- Where to store refresh tokens server-side? (DB vs Redis vs memory)
-- Token expiry times: strict (15min) vs convenient (1hr)?
-
-## Assumptions
-- Express API will continue using cookies (not going full SPA)
-- PostgreSQL available for refresh token storage if needed
-</output_requirements>
-
-<summary_requirements>
-Create `SUMMARY.md` with:
-- One-liner: JWT with jose library and httpOnly cookies recommended
-- Key Findings: jose outperforms, cookies required, rotation is standard
-- Decisions Needed: None - clear recommendation
-- Next Step: Create implementation plan
-</summary_requirements>

package/skills/meta/creating-prompts/scripts/get-next-number.sh

@@ -1,27 +0,0 @@
-#!/bin/bash
-# Get the next prompt number based on existing prompts
-
-# Get configured prompts directory
-PROMPTS_DIR=$(.agents/superpowers-agent get-config prompts_dir 2>/dev/null || echo ".agents/prompts")
-
-# If prompts directory doesn't exist, start at 001
-if [ ! -d "$PROMPTS_DIR" ]; then
-    echo "001"
-    exit 0
-fi
-
-# Find highest number from existing prompt directories
-HIGHEST=$(find "$PROMPTS_DIR" -maxdepth 1 -type d -name '[0-9][0-9][0-9]-*' 2>/dev/null | \
-    sed 's/.*\/\([0-9][0-9][0-9]\)-.*/\1/' | \
-    sort -n | \
-    tail -1)
-
-# If no prompts exist yet, start at 001
-if [ -z "$HIGHEST" ]; then
-    echo "001"
-    exit 0
-fi
-
-# Increment and format with leading zeros
-NEXT=$((10#$HIGHEST + 1))
-printf "%03d\n" $NEXT

package/skills/meta/creating-prompts/skill.json

@@ -1,20 +0,0 @@
-{
-    "version": "5.1.0",
-    "name": "superpowers:meta/creating-prompts",
-    "title": "Creating Prompts",
-    "helpers": [
-        "scripts/get-next-number.sh",
-        "examples/do-example.md",
-        "examples/plan-example.md",
-        "examples/refine-example.md",
-        "examples/research-example.md",
-        "templates/do-template.md",
-        "templates/plan-template.md",
-        "templates/refine-template.md",
-        "templates/research-template.md"
-    ],
-    "aliases": [
-        "creating-prompts",
-        "meta/creating-prompts"
-    ]
-}

package/skills/meta/creating-prompts/templates/do-template.md

@@ -1,59 +0,0 @@
----
-number: {NUMBER}
-topic: {TOPIC}
-purpose: do
-dependencies: []
-created: {DATE}
----
-
-# {TOPIC} - Do
-
-<objective>
-{What to build/create/fix}
-
-Purpose: {Why this matters, what it enables}
-Output: {What artifact(s) will be produced}
-</objective>
-
-<context>
-{Referenced files if chained}
-@.agents/prompts/{folder}/{file}.md
-
-{Project context}
-@relevant-files
-</context>
-
-<requirements>
-{Specific functional requirements}
-{Quality requirements}
-{Constraints and boundaries}
-</requirements>
-
-<implementation>
-{Specific approaches or patterns to follow}
-{What to avoid and WHY}
-{Integration points}
-</implementation>
-
-<output>
-Create/modify files:
-- `./path/to/file.ext` - {description}
-
-{For complex outputs, specify structure}
-</output>
-
-<verification>
-Before declaring complete:
-- {Specific test or check}
-- {How to confirm it works}
-- {Edge cases to verify}
-</verification>
-
-<summary_requirements>
-Create `SUMMARY.md` in same directory with:
-- One-liner: Substantive description of outcome
-- Key Findings: Actionable takeaways
-- Decisions Needed: What requires user input
-- Blockers: External impediments or "None"
-- Next Step: Concrete forward action
-</summary_requirements>

package/skills/meta/creating-prompts/templates/plan-template.md

@@ -1,58 +0,0 @@
----
-number: {NUMBER}
-topic: {TOPIC}
-purpose: plan
-dependencies: []
-created: {DATE}
----
-
-# {TOPIC} - Plan
-
-<objective>
-{What to plan + success criteria}
-</objective>
-
-<context>
-{Referenced research outputs}
-@.agents/prompts/{folder}/{file}-output.md
-
-{Current state}
-{Constraints}
-</context>
-
-<requirements>
-{What plan must address}
-{Decision points to resolve}
-{Tradeoffs to evaluate}
-</requirements>
-
-<output_structure>
-Create plan with:
-
-## Phases
-- Phase 1: {Name} - {Clear boundary/deliverable}
-- Phase 2: {Name} - {Clear boundary/deliverable}
-
-## Dependencies
-- {What Phase 2 needs from Phase 1}
-- {External dependencies}
-
-## Decision Points
-- {Decision}: Options A, B, C with tradeoffs
-- {Decision}: Recommendation with rationale
-
-## Risk Assessment
-- {Risk}: {Mitigation strategy}
-
-## Success Metrics
-- {How to measure success}
-</output_structure>
-
-<summary_requirements>
-Create `SUMMARY.md` with:
-- One-liner: Key recommendation or approach
-- Key Findings: Critical insights from planning
-- Decisions Needed: What requires approval/input
-- Blockers: What's blocking progress
-- Next Step: Concrete action to move forward
-</summary_requirements>

package/skills/meta/creating-prompts/templates/refine-template.md

@@ -1,54 +0,0 @@
----
-number: {NUMBER}
-topic: {TOPIC}
-purpose: refine
-dependencies: [{ORIGINAL_NUMBER}]
-created: {DATE}
----
-
-# {TOPIC} - Refine
-
-<objective>
-Improve and deepen @.agents/prompts/{folder}/{file}-output.md
-</objective>
-
-<current_gaps>
-{What's missing or unclear in current output}
-{Questions left unanswered}
-{Areas needing more depth}
-</current_gaps>
-
-<preserve>
-{What to keep from original}
-{Key insights not to lose}
-</preserve>
-
-<refinement_focus>
-{Specific areas to strengthen}
-{New angles to explore}
-{Additional sources to consult}
-</refinement_focus>
-
-<output>
-Update @.agents/prompts/{folder}/{file}-output.md with:
-
-## What Changed
-- {Added: new finding/insight}
-- {Strengthened: expanded section}
-- {Clarified: resolved ambiguity}
-
-## Changelog
-- v2: {Date} - {Summary of changes}
-- v1: {Original date} - Initial version
-
-Archive previous version to archive/{file}-v1.md
-</output>
-
-<summary_requirements>
-Update `SUMMARY.md` with:
-- One-liner: Updated with refinement focus
-- Key Findings: Include new insights
-- Version: v2
-- Decisions Needed: Updated based on new information
-- Next Step: Forward action with refined understanding
-</summary_requirements>

package/skills/meta/creating-prompts/templates/research-template.md

@@ -1,56 +0,0 @@
----
-number: {NUMBER}
-topic: {TOPIC}
-purpose: research
-dependencies: []
-created: {DATE}
----
-
-# {TOPIC} - Research
-
-<objective>
-{What to research + why}
-</objective>
-
-<focus_areas>
-{Specific questions to answer}
-{Comparisons to make}
-{Unknowns to resolve}
-</focus_areas>
-
-<sources>
-{Documentation to review}
-{Code to analyze}
-{Existing files to reference}
-@relevant-files
-</sources>
-
-<output_requirements>
-Provide research findings with:
-
-## Key Findings
-- {Finding with supporting evidence}
-- {Finding with supporting evidence}
-
-## Confidence Level
-- High/Medium/Low with reasoning
-
-## Recommendations
-- {Specific recommendation based on findings}
-
-## Open Questions
-- {What remains uncertain}
-- {What needs further investigation}
-
-## Assumptions
-- {What was assumed during research}
-</output_requirements>
-
-<summary_requirements>
-Create `SUMMARY.md` with:
-- One-liner: Main discovery or recommendation
-- Key Findings: Top 3-5 actionable insights
-- Decisions Needed: What needs decision based on research
-- Blockers: What's preventing deeper research
-- Next Step: How to act on findings
-</summary_requirements>

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

@@ -1,108 +0,0 @@
----
-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.0` > `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/skills/meta/using-superpowers/skill.json

@@ -1,5 +0,0 @@
-{
-    "version": "1.0.0",
-    "name": "using-superpowers",
-    "title": "Using Superpowers"
-}