@complexthings/superpowers-agent 8.1.0

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

@@ -0,0 +1,349 @@
+---
+name: creating-prompts
+description: Create structured prompts for Do/Plan/Research/Refine workflows with dependency management
+metadata:
+  when_to_use: when you need to create focused, reusable prompts for specific tasks, research, planning, or refinement workflows
+  version: 5.1.0
+  languages: all
+---
+
+# Creating Prompts
+
+## Overview
+
+Create structured, reusable prompts for agent workflows. Prompts are focused instructions for specific tasks (Do), strategic planning (Plan), information gathering (Research), or iterative improvement (Refine).
+
+**Core principle:** Prompts are lightweight, self-contained instructions that can be chained together through dependencies.
+
+**Announce at start:** "I'm using the Creating Prompts skill to create a {purpose} prompt."
+
+## When to Use
+
+**Use this skill when:**
+- Creating focused task instructions for agents
+- Building multi-stage workflows (research → plan → implement)
+- Need reusable prompts that can be executed independently
+- Want to chain prompts with explicit dependencies
+
+**When NOT to use:**
+- For comprehensive implementation plans (use `writing-plans` skill instead)
+- For features >100 LOC (use `writing-plans` for full roadmaps)
+- One-off instructions (just give the instruction directly)
+
+**Decision flowchart:**
+
+```
+Need instructions for agent?
+├─ One-time task → Give instruction directly
+├─ <100 LOC, focused → Create Prompt (this skill)
+└─ >100 LOC, comprehensive → Use writing-plans skill
+```
+
+## Integration with Other Skills
+
+**Before creating prompts:**
+- For complex features → Use `brainstorming` skill to refine requirements first
+- Unsure of approach → Start with Research prompt, then Plan, then Do
+
+**After creating prompts:**
+- Validate clarity → Use `testing-skills-with-subagents` to verify prompt works
+- Execute prompts → Follow execution guidance (see below)
+
+**Prompts vs Plans:**
+- **Prompts**: Lightweight, focused, single-purpose (this skill)
+- **Plans**: Comprehensive, multi-phase, detailed implementation (`writing-plans`)
+
+See skills/collaboration/writing-plans for full implementation plans.
+See skills/collaboration/brainstorming for design refinement before prompting.
+
+## Configuration
+
+Prompts are saved to configured directory (default: `.agents/prompts/`).
+
+**Read config:**
+```bash
+superpowers-agent get-config prompts_dir
+```
+
+**Override globally:** `~/.agents/config.json`
+```json
+{
+  "prompts_dir": "custom/prompts"
+}
+```
+
+**Override per-project:** `.agents/config.json`
+```json
+{
+  "prompts_dir": ".my-prompts"
+}
+```
+
+Priority: Project config > Global config > Default (`.agents/prompts/`)
+
+## Prompt Types
+
+### 1. DO Prompts - Execute and Produce
+
+**When:** Implement feature, fix bug, create document, build component
+
+**Output:** Code files, documentation, configurations, designs
+
+**Template:** `skills/meta/creating-prompts/templates/do-template.md`
+
+**Example:** `skills/meta/creating-prompts/examples/do-example.md`
+
+### 2. PLAN Prompts - Strategy and Roadmap
+
+**When:** Design architecture, plan refactoring, decide approach
+
+**Output:** Structured plans with phases, dependencies, decisions
+
+**Template:** `skills/meta/creating-prompts/templates/plan-template.md`
+
+**Example:** `skills/meta/creating-prompts/examples/plan-example.md`
+
+### 3. RESEARCH Prompts - Gather Information
+
+**When:** Understand library, explore patterns, analyze options
+
+**Output:** Findings with confidence levels, recommendations, open questions
+
+**Template:** `skills/meta/creating-prompts/templates/research-template.md`
+
+**Example:** `skills/meta/creating-prompts/examples/research-example.md`
+
+### 4. REFINE Prompts - Iterative Improvement
+
+**When:** Deepen research, strengthen plan, address gaps
+
+**Output:** Updated version with changelog, archived previous version
+
+**Template:** `skills/meta/creating-prompts/templates/refine-template.md`
+
+**Example:** `skills/meta/creating-prompts/examples/refine-example.md`
+
+## Quick Reference
+
+| Prompt Type | Purpose | Output | Common Chain |
+|-------------|---------|--------|--------------|
+| Research | Gather info | Findings + recommendations | Research → Plan → Do |
+| Plan | Strategy | Phases + decisions | Plan → Do |
+| Do | Execute | Artifacts (code/docs) | Standalone or after Plan |
+| Refine | Improve | Updated version | After any type |
+
+## Workflow Checklist
+
+**IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.**
+
+### Phase 1: Preparation
+- [ ] Determine prompt purpose (Do/Plan/Research/Refine)
+- [ ] If complex feature → Consider using `/brainstorm` first
+- [ ] If >100 LOC implementation → Consider `writing-plans` skill instead
+- [ ] Identify topic for naming (kebab-case: auth, stripe-integration)
+- [ ] Check for existing prompts to reference (creates dependencies)
+
+### Phase 2: Creation
+- [ ] Get next number: `skills/meta/creating-prompts/scripts/get-next-number.sh`
+- [ ] Get prompts directory: `superpowers-agent get-config prompts_dir`
+- [ ] Load appropriate template from `skills/meta/creating-prompts/templates/`
+- [ ] Fill in template with specific details (no placeholders)
+- [ ] Add frontmatter metadata (number, topic, purpose, dependencies)
+- [ ] Reference existing outputs with `@` syntax if chained
+
+### Phase 3: Quality Checks
+- [ ] Objective is clear and specific (not vague)
+- [ ] Context includes all necessary background
+- [ ] Requirements are testable/verifiable
+- [ ] Output specification is concrete
+- [ ] Success criteria are measurable
+- [ ] For Research/Plan: includes confidence/assumptions/open questions
+
+### Phase 4: Validation (Recommended)
+- [ ] Test prompt with subagent (see `testing-skills-with-subagents`)
+- [ ] Verify subagent understands requirements
+- [ ] Check output matches expected structure
+
+### Phase 5: Save and Execute
+- [ ] Create directory: `{prompts_dir}/{number}-{topic}-{purpose}/`
+- [ ] Create `completed/` subdirectory
+- [ ] Save prompt: `{number}-{topic}-{purpose}.md`
+- [ ] Execute prompt (agent reads and follows instructions)
+- [ ] Agent creates output: `{topic}-{purpose}-output.md`
+- [ ] Agent creates `SUMMARY.md` with findings/decisions/next steps
+- [ ] Move prompt to `completed/` after execution
+
+## File Structure
+
+```
+.agents/prompts/                              # Configured location
+├── 001-auth-research/
+│   ├── 001-auth-research.md                  # The prompt
+│   ├── completed/
+│   │   └── 001-auth-research.md              # After execution
+│   ├── auth-research-output.md               # Agent's output
+│   └── SUMMARY.md                            # Executive summary
+├── 002-auth-plan/
+│   ├── 002-auth-plan.md
+│   ├── completed/
+│   ├── auth-plan-output.md
+│   └── SUMMARY.md
+└── 003-auth-do/
+    ├── 003-auth-do.md
+    ├── completed/
+    ├── auth-do-output.md
+    └── SUMMARY.md
+```
+
+## Naming Convention
+
+**Format:** `{number}-{topic}-{purpose}.md`
+
+**Examples:**
+- `001-auth-research.md` - Research authentication options
+- `002-auth-plan.md` - Plan auth implementation
+- `003-stripe-integration-do.md` - Implement Stripe
+- `004-auth-research-refine.md` - Deepen auth research
+
+**Topic naming:**
+- Use kebab-case
+- Be specific but concise
+- Examples: `auth`, `stripe-integration`, `user-profile`, `api-refactor`
+
+## Dependency Detection
+
+Prompts can reference other prompt outputs to create chains.
+
+**Syntax:** `@.agents/prompts/{folder}/{file}-output.md`
+
+**Example in prompt:**
+```markdown
+<context>
+Based on research: @.agents/prompts/001-auth-research/auth-research-output.md
+Based on plan: @.agents/prompts/002-auth-plan/auth-plan-output.md
+</context>
+```
+
+**Frontmatter dependencies:**
+```yaml
+---
+number: 003
+topic: auth-do
+purpose: do
+dependencies: [001, 002]  # Must execute 001 and 002 first
+created: 2025-11-21
+---
+```
+
+## SUMMARY.md Template
+
+Every prompt execution should create a `SUMMARY.md`:
+
+```markdown
+# {Topic} {Purpose} Summary
+
+**One-liner:** [Substantive description of outcome, not generic]
+
+## Key Findings
+- [Actionable takeaway 1]
+- [Actionable takeaway 2]
+- [Actionable takeaway 3]
+
+## Decisions Needed
+- [What requires user input or approval]
+- Or: "None"
+
+## Blockers
+- [External impediments preventing progress]
+- Or: "None"
+
+## Next Step
+[Concrete forward action - what to do next]
+```
+
+## Execution Guidance
+
+**How agents execute prompts:**
+
+1. **Read the prompt** - Load `{number}-{topic}-{purpose}.md`
+2. **Check dependencies** - Ensure referenced prompts completed first
+3. **Follow instructions** - Execute according to prompt sections
+4. **Create output** - Save to `{topic}-{purpose}-output.md`
+5. **Create summary** - Save `SUMMARY.md` with findings
+6. **Archive prompt** - Move to `completed/` subfolder
+
+**For agents with Task/subagent capabilities:**
+- Spawn fresh agent with prompt as instruction
+- Agent produces output and summary
+- Main agent reviews and archives
+
+**For manual execution:**
+- Open prompt in editor
+- Follow instructions step-by-step
+- Create output and summary files
+- Move prompt to completed/
+
+## Common Mistakes
+
+### ❌ Vague objectives
+```markdown
+<objective>
+Research authentication
+</objective>
+```
+
+### ✅ Specific objectives
+```markdown
+<objective>
+Research JWT authentication libraries for Node.js Express API to determine best option for TypeScript project with security focus
+</objective>
+```
+
+### ❌ Missing context
+```markdown
+<context>
+Current codebase
+</context>
+```
+
+### ✅ Concrete context
+```markdown
+<context>
+Express API in src/server.js, routes in src/routes/
+Currently no authentication, all endpoints public
+Must integrate with existing PostgreSQL user table
+@src/server.js
+@src/routes/api.js
+</context>
+```
+
+### ❌ Generic requirements
+```markdown
+<requirements>
+Should work well
+Be secure
+</requirements>
+```
+
+### ✅ Testable requirements
+```markdown
+<requirements>
+- Verify JWT tokens in Authorization header
+- Return 401 for invalid tokens
+- Return 403 for expired tokens
+- Extract user ID and attach to req.user
+- No performance impact >10ms per request
+</requirements>
+```
+
+## Credits
+
+This skill is an agent-agnostic adaptation of TÂCHES' excellent [`create-meta-prompts` skill](https://github.com/glittercowboy/taches-cc-resources/tree/main/skills/create-meta-prompts).
+
+TÂCHES pioneered the concept of structured prompt-to-prompt workflows with dependency management and multi-stage execution. This adaptation maintains the core concepts while making them accessible across all AI coding assistants (OpenCode, GitHub Copilot, Cursor, Gemini, Claude, etc.).
+
+**Original author:** TÂCHES ([@glittercowboy](https://github.com/glittercowboy))
+
+**Original repository:** https://github.com/glittercowboy/taches-cc-resources
+
+Thank you to TÂCHES for the innovative work on meta-prompt patterns!

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

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

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

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

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

@@ -0,0 +1,27 @@
+#!/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

@@ -0,0 +1,20 @@
+{
+    "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"
+    ]
+}