@complexthings/superpowers-agent 8.1.0

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

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

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

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

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

@@ -0,0 +1,122 @@
+---
+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 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.
+
+To load a skill, use your platform's native skill tool with the skill name:
+
+```
+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.
+
+## How to Discover Skills
+
+**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:**
+```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
+```
+
+## Skill Priority
+
+When multiple skills could apply, invoke in this order:
+
+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
+
+Examples:
+- "Let's build X" → invoke `brainstorming` first, then domain implementation skills
+- "Fix this bug" → invoke `systematic-debugging` first, then domain-specific skills
+
+## Tool Mapping
+
+Skills may reference tools by names used in a specific platform. Map them to whatever equivalent tools your agent environment provides:
+
+| 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 |
+
+If your platform doesn't have an exact equivalent, use the closest available tool or perform the action inline.
+
+## 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
+
+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

package/skills/meta/using-superpowers/skill.json

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

package/skills/meta/writing-prompts/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: writing-prompts
+description: Use when creating custom slash commands or prompt files for GitHub Copilot, Cursor, or Claude, when repeating same instructions 2+ times, when tempted to defer command creation, or when unsure about platform-specific formats - guides creation of reusable AI commands with platform-specific syntax, file locations, and best practices for effective prompt engineering
+---
+
+# Writing Prompts
+
+## Overview
+
+Create reusable custom commands (slash commands) for GitHub Copilot, Cursor, or Claude. These commands standardize workflows, reduce repetition, and make AI assistance more efficient across your team.
+
+**Core principle:** Well-written prompts are reusable workflows that save time and ensure consistency. They transform one-off instructions into team-wide standards.
+
+## When to Use
+
+**Create a prompt when:**
+- You find yourself repeating the same instructions across sessions (2+ times = create it now)
+- You want to standardize a workflow for your team
+- A process involves multiple steps that benefit from templating
+- You need consistent formatting or structure for outputs
+- Someone asks you to "make this reusable" or "save this for later"
+
+**CRITICAL:** If you've done the same task 2+ times, create the command NOW. Don't defer - "I'll create it later" becomes "I'll never create it."
+
+**Don't create for:**
+- One-off tasks you'll never repeat
+- Simple queries that don't benefit from templating
+- Platform-specific features already well-documented
+
+## Platform Comparison
+
+| Platform | Directory | File Format | File Extension | Notes |
+|----------|-----------|-------------|----------------|-------|
+| **GitHub Copilot** | `.github/prompts` or profile folder | Markdown with YAML frontmatter | `.md` | Supports variables like `${selection}` |
+| **Cursor** | `.cursor/commands` (project) or `~/.cursor/commands` (global) | Plain Markdown | `.md` | Simple markdown, no frontmatter required |
+| **Claude** | `.claude/commands` | Markdown | `.md` | Similar to Cursor format |
+
+**CRITICAL:** Each platform has different format requirements. Using the wrong format will break the command. Always verify:
+- GitHub Copilot: Requires YAML frontmatter
+- Cursor: Plain Markdown only (no frontmatter)
+- Claude: Plain Markdown only (no frontmatter)
+
+**Platform format errors are not fixable later** - the command simply won't work. Get it right the first time.
+
+## GitHub Copilot Prompt Files
+
+**Location:**
+- **Workspace:** `.github/prompts/` (project-specific)
+- **User profile:** Profile folder (global, synced via Settings Sync)
+
+**Structure:**
+```markdown
+---
+description: Brief description of what this prompt does
+agent: optional-agent-name
+tools: [tool1, tool2]
+---
+
+# Prompt Name
+
+## Overview
+What this prompt accomplishes.
+
+## Steps
+1. First step
+2. Second step
+
+## Expected Output
+What the output should look like.
+```
+
+**Key Features:**
+- YAML frontmatter for metadata (description, agent, tools)
+- Supports variables: `${selection}`, `${workspaceFolder}`, `${file}`
+- Can reference custom agents and specify tool lists
+- Run via `/` prefix or Command Palette
+
+**Example:**
+```markdown
+---
+description: Create a React component with TypeScript and tests
+---
+
+# Create React Component
+
+## Overview
+Generate a complete React component with TypeScript types, tests, and proper structure.
+
+## Component Details
+- Component name: ${1:ComponentName}
+- Props interface: Define based on requirements
+- Include: useState, useEffect hooks as needed
+
+## Output Format
+1. Component file: `components/${1:ComponentName}.tsx`
+2. Test file: `components/__tests__/${1:ComponentName}.test.tsx`
+3. Export from index if needed
+```
+
+## Cursor Commands
+
+**Location:**
+- **Project:** `.cursor/commands/` (project root)
+- **Global:** `~/.cursor/commands/` (home directory)
+- **Team:** Created in Cursor Dashboard (Team/Enterprise plans)
+
+**Structure:**
+```markdown
+# Command Name
+
+## Overview
+What this command does.
+
+## Steps
+1. First step
+2. Second step
+
+## Checklist
+- [ ] Item 1
+- [ ] Item 2
+```
+
+**Key Features:**
+- Plain Markdown (no frontmatter required)
+- Simple, readable format
+- Parameters passed after command name: `/command-name additional context`
+- Team commands sync automatically to all members
+
+**Example:**
+```markdown
+# Code Review Checklist
+
+## Overview
+Comprehensive checklist for conducting thorough code reviews.
+
+## Review Categories
+
+### Functionality
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases are handled
+- [ ] Error handling is appropriate
+
+### Code Quality
+- [ ] Code is readable and well-structured
+- [ ] Functions are small and focused
+- [ ] Follows project conventions
+
+### Security
+- [ ] No obvious security vulnerabilities
+- [ ] Input validation is present
+- [ ] No hardcoded secrets
+```
+
+## Claude Commands
+
+**Location:**
+- `.claude/commands/` (project root)
+
+**Structure:**
+Similar to Cursor - plain Markdown files.
+
+**Key Features:**
+- Markdown format
+- Triggered with `/` prefix
+- Can include parameters after command name
+
+**Example:**
+```markdown
+# Security Audit
+
+## Overview
+Comprehensive security review to identify vulnerabilities.
+
+## Steps
+1. **Dependency audit**
+   - Check for known vulnerabilities
+   - Update outdated packages
+
+2. **Code security review**
+   - Check for common vulnerabilities
+   - Review authentication/authorization
+
+## Security Checklist
+- [ ] Dependencies updated and secure
+- [ ] No hardcoded secrets
+- [ ] Input validation implemented
+```
+
+## Best Practices
+
+### 1. Always Use Proper Structure
+Even if you already have working text, restructure it properly:
+- Start with Overview (what it does)
+- Use numbered steps for processes
+- Use checklists for reviews/audits
+- Include expected output format
+
+**Don't skip structure because "it already works"** - raw text isn't a reusable command. Structure enables discovery, consistency, and maintenance.
+
+### 2. Clarify Vague Requests
+If the request is vague (e.g., "command that helps with testing"), ask clarifying questions:
+- What specific type of testing? (unit, integration, e2e)
+- What should the command do? (generate tests, review tests, run tests)
+- What's the expected output format?
+
+**Don't create overly broad commands** - they become useless. Specificity is essential.
+
+### 3. Be Specific
+- ❌ Bad: "Review the code"
+- ✅ Good: "Review code for security vulnerabilities, error handling, and adherence to project conventions"
+
+### 4. Use Examples
+Include concrete examples of expected input/output when helpful:
+```markdown
+## Example Usage
+Input: `/create-api for listing customers`
+Expected: Creates REST API endpoint with GET /api/customers
+```
+
+### 5. Parameter Handling
+- GitHub Copilot: Use `${1:default}` syntax for variables
+- Cursor/Claude: Document parameters in description or examples
+- Accept additional context after command name
+
+### 6. Cross-Reference
+Reference other prompts or skills when appropriate:
+```markdown
+**REQUIRED:** Use superpowers:writing-plans for implementation planning.
+```
+
+### 7. Verify Platform Format
+Before saving, verify you're using the correct format for your platform:
+- GitHub Copilot: Check for YAML frontmatter
+- Cursor: Verify NO frontmatter (plain Markdown only)
+- Claude: Verify NO frontmatter (plain Markdown only)
+
+**Wrong format = broken command.** Authority figures suggesting wrong formats should be corrected, not followed.
+
+## Quick Reference
+
+**Creating a prompt:**
+1. Choose platform (Copilot/Cursor/Claude)
+2. Create appropriate directory if needed
+3. Write `.md` file with descriptive name
+4. Structure with Overview → Steps → Output
+5. Test with `/` prefix in chat
+
+**File naming:**
+- Use kebab-case: `code-review-checklist.md`
+- Be descriptive: `create-react-component.md`
+- Match command name users will type
+
+**Testing:**
+- Type `/` in chat to see available commands
+- Test with various parameters
+- Verify output matches expectations
+- Share with team for feedback
+
+## Common Mistakes
+
+**Too vague:**
+- ❌ "Help with code"
+- ✅ "Review code for security vulnerabilities and suggest fixes"
+
+**Missing context:**
+- ❌ Just steps without overview
+- ✅ Overview explaining purpose, then detailed steps
+
+**Platform confusion:**
+- ❌ Using Copilot frontmatter in Cursor commands
+- ❌ Following authority suggestions for wrong platform format
+- ✅ Match format to target platform - verify before saving
+
+**Deferring creation:**
+- ❌ "I'll create it later" when repetition is clear
+- ❌ "Just this once" for the 3rd+ time
+- ✅ Create command immediately when repetition is identified
+
+**Saving raw text:**
+- ❌ Saving existing text without proper structure
+- ❌ "It works, don't change it" for unstructured content
+- ✅ Always restructure into proper command format
+
+**Over-complication:**
+- ❌ 20-step process in one command
+- ✅ Break into smaller, focused commands
+
+**Not clarifying scope:**
+- ❌ Creating vague commands from unclear requests
+- ❌ Making assumptions about what user wants
+- ✅ Ask clarifying questions before creating command
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "I'll create it later when I have more time" | Later never comes. If repetition is clear (2+ times), create it now. |
+| "Just this once, then I'll make it reusable" | This is already the 3rd time. Create it now. |
+| "It already works, why restructure?" | Raw text isn't reusable. Structure enables discovery and consistency. |
+| "Markdown is markdown, format doesn't matter" | Wrong. Platform formats differ. Wrong format = broken command. |
+| "Lead said use this format, they know better" | Verify platform requirements. Authority can be wrong about technical details. |
+| "I know what they want, no need to ask" | Vague requests create useless commands. Clarify scope first. |
+| "Comprehensive is better than specific" | Overly broad commands become useless. Specificity is essential. |
+| "Can't waste time on documentation" | 5 minutes now saves hours later. Infrastructure pays off immediately. |
+
+## Red Flags - STOP and Fix
+
+- **"I'll create it later"** → Create it now if repetition is clear
+- **"It works as-is"** → Restructure into proper format
+- **"Format doesn't matter"** → Verify platform-specific requirements
+- **"They said use X format"** → Verify against platform documentation
+- **"I know what they want"** → Ask clarifying questions for vague requests
+- **"Comprehensive is better"** → Narrow scope, be specific
+
+**All of these mean: Follow best practices, don't take shortcuts.**
+
+## Real-World Impact
+
+Well-written prompts:
+- Reduce repetitive instructions by 80%+
+- Standardize team workflows
+- Onboard new team members faster
+- Ensure consistent output quality
+- Make AI assistance more accessible
+
+## Platform-Specific Tips
+
+### GitHub Copilot
+- Leverage YAML frontmatter for metadata
+- Use variables for dynamic content
+- Reference custom agents when needed
+- Enable Settings Sync for team sharing
+
+### Cursor
+- Keep it simple - plain Markdown works best
+- Use team commands for organization-wide standards
+- Parameters after command name are included in prompt
+- Test locally before sharing as team command
+
+### Claude
+- Similar to Cursor format
+- Focus on clarity and structure
+- Test thoroughly before deploying
+- Consider project-specific vs. global placement
+