agy-superpowers 5.0.7 → 5.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-superpowers",
-  "version": "5.0.7",
+  "version": "5.0.9",
   "description": "Superpowers skills library for Google Antigravity agent — scaffold .agent/ with one command",
   "type": "module",
   "bin": {

package/template/agent/rules/superpowers.md

@@ -14,6 +14,8 @@ All skills are symlinked into `.agent/skills/` and are automatically available.
 
 ## Available Skills
 
+### Development Workflow
+
 | Skill | When to Use |
 |---|---|
 | `brainstorming` | Before ANY creative work — adding features, building components, modifying behavior |
@@ -29,6 +31,57 @@ All skills are symlinked into `.agent/skills/` and are automatically available.
 | `finishing-a-development-branch` | When tasks complete — merge / PR / discard |
 | `dispatching-parallel-agents` | When running concurrent subagent workflows |
 | `writing-skills` | When creating new skills |
+| `using-superpowers` | When starting any conversation — find and use skills |
+
+### Technical Roles
+
+| Skill | When to Use |
+|---|---|
+| `frontend-developer` | Web UI, component architecture, React/Vue/Svelte/Vanilla. Has `react-rules/` (66 Vercel rules) and `vue-rules/` (44 antfu rules) |
+| `backend-developer` | APIs, server-side logic, database schemas |
+| `mobile-developer` | Mobile apps — React Native, Flutter, iOS, Android. Has `react-native-rules/` (38), `flutter-rules/` (8), `android-rules/` (17), `ios-rules/` (19) |
+| `game-developer` | Mobile game features, architecture decisions |
+| `game-design` | Game mechanics, core loops, progression, monetization |
+| `cto-architect` | System design, tech debt, scaling, architecture |
+| `saas-architect` | Multi-tenant SaaS architecture, tenant isolation |
+| `devops-engineer` | CI/CD, infrastructure, deployment, monitoring |
+| `security-engineer` | App security, auth, GDPR, security audits |
+
+### Business & Growth
+
+| Skill | When to Use |
+|---|---|
+| `product-manager` | Product requirements, feature prioritization, roadmap |
+| `data-analyst` | Metrics, funnels, cohort analysis, A/B tests |
+| `growth-hacker` | User acquisition, viral loops, activation funnels |
+| `monetization-strategist` | Pricing, freemium, IAP, unit economics |
+| `conversion-optimizer` | Landing pages, trial-to-paid, onboarding, CRO |
+| `retention-specialist` | Onboarding flows, churn reduction, re-engagement |
+| `customer-success-manager` | User support, feedback loops, NPS/CSAT |
+| `app-store-optimizer` | ASO, keyword strategy, screenshots, ratings |
+| `ux-designer` | UI design, wireframes, user research, IA |
+| `copywriter` | Landing copy, app descriptions, email sequences |
+
+### Marketing & Content
+
+| Skill | When to Use |
+|---|---|
+| `content-marketer` | Content strategy, SEO content, social media |
+| `seo-specialist` | Technical SEO, keywords, backlinks, organic search |
+| `community-manager` | Discord, Reddit, Slack community management |
+| `influencer-marketer` | UGC, creator partnerships, affiliate programs |
+| `paid-acquisition-specialist` | Meta Ads, Google Ads, Apple Search Ads, ROAS |
+
+### Infrastructure & Integration
+
+| Skill | When to Use |
+|---|---|
+| `api-design` | REST/GraphQL APIs, versioning, rate limiting |
+| `auth-and-identity` | Auth, SSO/SAML/OIDC, RBAC, session management |
+| `subscription-billing` | Stripe, IAP, trials, dunning flows |
+| `email-infrastructure` | Transactional email, SPF/DKIM/DMARC, deliverability |
+| `real-time-features` | WebSockets, SSE, live collaboration, presence |
+| `i18n-localization` | Internationalization, translations, localized ASO |
 
 ## How to Read a Skill (Antigravity)
 
@@ -50,3 +103,4 @@ Example: `.agent/skills/brainstorming/SKILL.md`
 - **TDD always**: Write failing tests first, then code
 - **Systematic over ad-hoc**: Follow the skill process, don't guess
 - **Evidence over claims**: Verify before declaring success
+

package/template/agent/skills/api-design/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: api-design
+description: Use when designing REST or GraphQL APIs, defining versioning strategy, implementing rate limiting, pagination, or writing API documentation
+---
+
+# API Design Lens
+
+> **Philosophy:** An API is a contract. Breaking it breaks your users' production systems.
+> Design APIs for the client's needs, not the server's convenience.
+
+---
+
+## Core Instincts
+
+- **API contracts are forever** — breaking changes in v1 are unforgivable; version aggressively
+- **Design for the consumer** — the client's workflow, not the server's data model, drives resource design
+- **Idempotency is non-negotiable** — safe to retry = safe to build reliable systems on top of
+- **Errors must be informative** — vague errors waste developer hours
+- **Consistency over cleverness** — a boring, predictable API is a beloved API
+
+---
+
+## REST Resource Design Rules
+
+```
+Resource naming:
+  ✅ /users/{id}/projects          (noun, plural, hierarchical)
+  ❌ /getProjectsForUser/{id}      (verb, confusing)
+  ❌ /user-projects/{userId}       (mixed conventions)
+
+HTTP verbs:
+  GET    /resources        → list (paginated)
+  GET    /resources/{id}   → get one
+  POST   /resources        → create
+  PUT    /resources/{id}   → full replace (idempotent)
+  PATCH  /resources/{id}   → partial update
+  DELETE /resources/{id}   → delete (idempotent)
+
+Idempotency:
+  GET, PUT, DELETE = always idempotent
+  POST = not idempotent by default → use Idempotency-Key header
+```
+
+---
+
+## HTTP Status Codes (Precise Usage)
+
+| Status | Use when | Body |
+|--------|----------|------|
+| 200 | Success, returns data | Resource |
+| 201 | Created | Resource + `Location` header |
+| 204 | Success, no body | Empty |
+| 400 | Malformed request / validation failure | Error with field details |
+| 401 | Missing or invalid auth | Error |
+| 403 | Auth valid, no permission | Error (don't reveal resource existence) |
+| 404 | Resource not found | Error |
+| 409 | Conflict (duplicate, state clash) | Error with conflict detail |
+| 422 | Valid format, business rule violation | Error with reason |
+| 429 | Rate limited | Error + `Retry-After` header |
+| 500 | Unexpected server error | Generic error (log full details server-side) |
+
+---
+
+## Error Response Standard (RFC 7807 / Problem Details)
+
+```json
+{
+  "type": "https://docs.myapp.com/errors/validation-failed",
+  "title": "Validation Failed",
+  "status": 422,
+  "detail": "One or more fields are invalid",
+  "errors": [
+    { "field": "email", "message": "Must be a valid email address" },
+    { "field": "name",  "message": "Required" }
+  ],
+  "requestId": "01HX7Y3Z..."
+}
+```
+
+**Always include `requestId`** — allows support to find logs immediately.
+
+---
+
+## Pagination
+
+```
+Offset-based (simple, less scalable):
+  GET /users?page=2&limit=20
+  ✅ Good for: admin UIs, small datasets
+  ❌ Bad for: large datasets (OFFSET N scans N rows)
+
+Cursor-based (scalable, real-time safe):
+  GET /users?cursor=eyJpZCI6MTIzfQ&limit=20
+  Response: { data: [...], nextCursor: "eyJpZCI6MTQzfQ", hasMore: true }
+  ✅ Good for: feeds, large datasets, infinite scroll
+  ❌ Bad for: jump-to-page UI
+
+Default recommendation: Cursor-based with opaque base64 cursors.
+Expose total count only when necessary (expensive for large tables).
+```
+
+---
+
+## Rate Limiting
+
+```
+Strategy: Token bucket or sliding window
+
+Headers to include:
+  X-RateLimit-Limit:     1000    (max requests per window)
+  X-RateLimit-Remaining: 847     (requests left)
+  X-RateLimit-Reset:     1711234567  (Unix timestamp when window resets)
+  Retry-After:           60      (seconds to wait, on 429 only)
+
+Recommended limits for SaaS APIs:
+  Authenticated:   1000 req/min per user
+  Unauthenticated: 60 req/min per IP
+  Sensitive (auth endpoints): 5 req/15min per IP
+```
+
+---
+
+## API Versioning
+
+```
+Strategy options:
+  URL versioning:    /v1/users   ← RECOMMENDED (explicit, cacheable)
+  Header versioning: Accept: application/vnd.myapp.v1+json  (less visible)
+  Query param:       /users?version=1  (ugly, cache issues)
+
+Breaking vs non-breaking changes:
+  Non-breaking (safe without versioning):
+    ✅ Adding new optional fields to response
+    ✅ Adding new optional request parameters
+    ✅ Adding new endpoints
+  
+  Breaking (requires new version):
+    ❌ Removing fields from response
+    ❌ Changing field types
+    ❌ Changing endpoint behavior
+    ❌ Renaming fields
+```
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Return 200 for errors | Clients parse status codes; 200 failure = broken integrations | Use correct status codes |
+| Expose internal IDs (auto-increment integers) | Enumerable, leaks count of records | UUIDs always |
+| Breaking changes without versioning | Clients' production breaks silently | `/v2/` or deprecation period |
+| Unbounded list endpoints | OOM at scale | Always paginate; default limit 20, max 100 |
+| Verbose errors in production | Leaks internals to attackers | Generic message to client; details in server logs only |
+| Synchronous long-running operations | Timeout at 30s+, bad UX | Accept → 202 Accepted → polling or webhook |
+
+---
+
+## Questions You Always Ask
+
+**When designing a new endpoint:**
+- Is this resource name a noun (not a verb)?
+- What's the idempotency story? Can the client safely retry?
+- What's the pagination strategy? What's the max page size?
+- Is this a breaking change to existing consumers?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] `200 OK` returned for error responses
+- [ ] No pagination on list endpoints
+- [ ] Auto-increment integer IDs exposed
+- [ ] Breaking API change without version bump
+
+**Should fix:**
+- [ ] No rate limiting on public endpoints
+- [ ] Error responses without field-level details
+- [ ] No `requestId` in error responses (prevents support lookup)
+- [ ] No OpenAPI/Swagger spec
+
+---
+
+## Who to Pair With
+- `backend-developer` — for implementation of API patterns
+- `auth-and-identity` — for auth design on API endpoints
+- `saas-architect` — for multi-tenant API context
+
+---
+
+## Tools
+OpenAPI / Swagger (spec) · Scalar / Stoplight (docs) · Hono / Fastify / Express (Node.js) · Zod / Joi (validation) · `express-rate-limit` / Upstash Rate Limit · Postman / Insomnia (testing)

package/template/agent/skills/app-store-optimizer/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: app-store-optimizer
+description: Use when working on App Store / Google Play listing optimization, keyword strategy, screenshots, ratings, or app store A/B testing
+---
+
+# App Store Optimizer Lens
+
+> **Philosophy:** ASO is SEO for app stores. Discoverability + conversion = downloads.
+> Most apps lose 60%+ of potential downloads to a weak listing, not a weak product.
+
+---
+
+## Core Instincts
+
+- **Title keyword is the highest-ranking signal** — include your primary keyword in the title
+- **First 3 screenshots convert or kill** — most users never scroll past them
+- **Ratings velocity > average rating** — a burst of fresh 5-stars beats a stale 4.8
+- **Keyword field is invisible to users but critical to ranking** — use every character
+- **Localize for top markets** — EN + your top 3 markets = 80% of opportunity
+
+---
+
+## Platform Limits (Know These Cold)
+
+### iOS App Store
+| Field | Limit | Notes |
+|-------|-------|-------|
+| Title | **30 chars** | Primary keyword weight = 2× |
+| Subtitle | **30 chars** | Secondary keyword, benefit-focused |
+| Keywords | **100 chars** | Comma-separated, no spaces, no repeats from title |
+| Description | **4000 chars** | First **255 chars** shown before "more" |
+| Promo text | **170 chars** | Updates without review; use for time-limited offers |
+| Screenshots | Up to **10** | Sizes vary by device; first 3 drive 80% of conversion |
+| Preview video | **15–30 seconds** | First 3 seconds must hook without sound |
+
+### Google Play
+| Field | Limit | Notes |
+|-------|-------|-------|
+| Title | **30 chars** | Keyword-rich |
+| Short description | **80 chars** | Shown in search; make it scannable |
+| Long description | **4000 chars** | First 167 chars auto-expanded; repeat keyword 3–5× |
+| Screenshots | Up to **8** | 16:9 or 9:16 preferred |
+| Feature graphic | **1024 × 500px** | Shown in featured slots |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Title = just the brand name | Zero keyword signal | Brand + primary keyword (e.g., "Todoist: To-Do List & Tasks") |
+| Leave keywords field blank (iOS) | 100 chars of free ranking wasted | Fill every character with non-title keywords |
+| First screenshot = app logo splash | Users bounce, no context | First screenshot = core value prop as hero text |
+| Ask for review on first open | Users hate it, Apple rejects manipulative prompts | Ask after a success action (task completed, streak hit) |
+| Ignore 1-star reviews | Review responses shown publicly; silence = neglect | Respond within 48h; apologize + explain fix |
+| Use keywords that appear in title (iOS) | Apple ignores duplicates | Every keyword field word must be unique |
+| Generic description | No differentiation, no keywords | Keyword-rich first paragraph, benefit bullets |
+
+---
+
+## Keyword Research Process
+
+1. **Seed keywords** — brainstorm 20–30 relevant terms
+2. **Competitor analysis** — check top 5 competitor titles/subtitles
+3. **Volume + difficulty** — use Sensor Tower / AppTweak / AppFollow to score
+4. **Priority matrix** — High volume + Low difficulty = target first
+5. **Long-tail focus** — easier to rank for "meditation app for anxiety" than "meditation"
+6. **Update every 60–90 days** — track rank changes, iterate
+
+---
+
+## Ratings Strategy
+
+**When to prompt:** After user completes a meaningful success action, NOT on launch.
+- Good triggers: completed task, reached streak, finished session, saved something
+- Bad triggers: app open, screen view, after onboarding
+
+**Target benchmarks:**
+| Metric | Floor | Target |
+|--------|-------|--------|
+| Average rating | > 4.0 | > 4.5 |
+| Review count (for featuring) | > 100 | > 500 |
+| Response rate to 1-star | — | > 80% within 48h |
+
+**Recovering from bad ratings:** Respond to every 1-star, release fix quickly, request updated review from resolved users.
+
+---
+
+## Questions You Always Ask
+
+**When auditing a listing:**
+- Is the primary keyword in the title?
+- Do the first 3 screenshots tell a complete story without reading any text?
+- Is the keyword field 100% utilized (iOS)?
+- What's the current conversion rate from impression to download? (Benchmark: 3–7%)
+
+**When planning ASO strategy:**
+- Which markets are we localizing for?
+- What keywords are competitors ranking for that we're missing?
+- When was the last time we A/B tested screenshots?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] Title is brand name only (no keyword)
+- [ ] iOS keyword field < 90 characters used
+- [ ] First screenshot is a splash screen or abstract illustration
+- [ ] No response to 1-star reviews
+
+**Should fix:**
+- [ ] Description first 255 chars (iOS) / 167 chars (Play) not benefit-focused
+- [ ] No preview video
+- [ ] Listing not localized for top 3 markets
+
+---
+
+## Who to Pair With
+- `copywriter` — for listing copy strategy
+- `growth-hacker` — for launch burst strategy (ratings velocity)
+- `conversion-optimizer` — for screenshot A/B testing
+
+---
+
+## Tools
+AppFollow · Sensor Tower · AppTweak · AppFigures · MobileAction · Apple Search Ads Intelligence

package/template/agent/skills/auth-and-identity/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: auth-and-identity
+description: Use when implementing authentication, authorization, SSO/SAML/OIDC, multi-tenant identity, session management, or role-based access control for a SaaS product
+---
+
+# Auth & Identity Lens
+
+> **Philosophy:** Authentication proves who you are. Authorization proves what you can do.
+> Mixing them up is the most common source of privilege escalation bugs.
+
+---
+
+## Core Instincts
+
+- **AuthN ≠ AuthZ** — always handle them as separate concerns
+- **Every request must be authenticated AND authorized** — auth middleware is not authorization
+- **Tenant context must be established on every request** — after AuthN, before any DB query
+- **Fail closed** — when in doubt, deny; never default to permissive
+- **Never roll your own crypto** — use proven libraries and protocols
+
+---
+
+## Multi-Tenant Auth Flow
+
+```
+Request arrives →
+1. Verify token/session (AuthN) → get user_id
+2. Load user + tenant membership → get tenant_id, role
+3. Set tenant context (RLS / app context)
+4. Check permission for this route/resource (AuthZ)
+5. Execute request
+```
+
+**Order matters:** If you skip step 3, RLS doesn't know which tenant. If you skip step 4, any authenticated user can do anything.
+
+---
+
+## Auth Strategy Selection
+
+| Method | Best for | Not for |
+|--------|----------|---------|
+| **JWT (stateless)** | Stateless APIs, microservices | When you need instant revocation |
+| **Session cookie** | Web apps, SSR | Mobile-first or API-only |
+| **API key** | Machine-to-machine, developer APIs | User-facing login |
+| **SAML 2.0** | Enterprise SSO (Okta, Azure AD) | Consumer apps |
+| **OIDC / OAuth 2.0** | Social login, federated identity | Internal-only systems |
+
+**Indie hacker default:** Session cookies for web (HttpOnly, Secure, SameSite=Strict) + JWT for API endpoints.
+
+---
+
+## JWT Rules
+
+```
+Access token:
+- Expiry: 15 minutes (short-lived; compromised → limited damage window)
+- Payload: user_id, tenant_id, role, exp — NO sensitive data
+- Store: Memory (never localStorage) or HttpOnly cookie
+
+Refresh token:
+- Expiry: 7–30 days
+- Store: HttpOnly cookie ONLY
+- Rotate on every use (refresh token rotation)
+- Invalidate all refresh tokens on password change/logout all
+
+Signing:
+- Algorithm: RS256 (asymmetric, allows public verification) or HS256 (simpler, shared secret)
+- Secret: ≥ 32 random bytes; rotate if compromised (support multiple valid secrets during rotation)
+```
+
+---
+
+## RBAC Pattern (Role-Based Access Control)
+
+```typescript
+// Roles per tenant membership (not global)
+type TenantRole = 'owner' | 'admin' | 'member' | 'viewer';
+
+// Permissions defined as capability strings
+const PERMISSIONS = {
+  owner:  ['billing:manage', 'members:manage', 'data:delete', 'data:write', 'data:read'],
+  admin:  ['members:manage', 'data:write', 'data:read'],
+  member: ['data:write', 'data:read'],
+  viewer: ['data:read'],
+} satisfies Record<TenantRole, string[]>;
+
+// Check at every protected route/action
+function can(user: User, permission: string): boolean {
+  return PERMISSIONS[user.tenantRole]?.includes(permission) ?? false;
+}
+```
+
+---
+
+## SSO / SAML Integration (Enterprise)
+
+```
+When to build SAML:
+- Enterprise customers require it (Okta, Azure AD, Google Workspace)
+- Single "SAML" request in a deal is worth building immediately
+
+Implementation options for indie hackers:
+1. WorkOS — $0 to start, pay per enterprise connection; fastest path
+2. Auth0 / Clerk — SAML add-on; higher cost at scale
+3. Roll your own — samlify / passport-saml; significant complexity
+
+SAML Flow:
+  User → Your SP (Service Provider) → IdP (Okta/AzureAD) → SAML assertion → SP → Session
+```
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| JWT in `localStorage` | XSS attack steals token, unlimited access | `HttpOnly` cookie |
+| Long-lived access tokens (> 1 hour) | Compromised token = long exposure window | 15 min expiry + refresh token rotation |
+| Storing passwords as anything but bcrypt/argon2id | Rainbow table crack in seconds | bcrypt cost ≥12 or argon2id |
+| Checking auth at route level only | Bypassed by internal calls | Check permissions at the service/data layer |
+| Global admin role without per-tenant scope | One compromised admin = all tenants affected | Admin role always scoped to a tenant |
+| No rate limiting on auth endpoints | Brute force, credential stuffing | Max 5 attempts / 15 min per IP |
+| Email as unique identifier across tenants | Same email in multiple tenants = collision | `(email, tenant_id)` composite unique |
+
+---
+
+## Questions You Always Ask
+
+**When designing auth:**
+- Is tenant context established before any DB query happens?
+- Does AuthZ happen at the service layer, not just route middleware?
+- Are refresh tokens rotated on every use?
+- What's the logout flow? Does it invalidate server-side session/refresh token?
+
+**When adding a new role or permission:**
+- Is this the least privilege needed for this action?
+- Have we tested that a lower-privileged role cannot access this?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] JWT stored in `localStorage`
+- [ ] No tenant_id in auth context (tenant isolation can't work)
+- [ ] Authorization only checked at route level (not service/data layer)
+- [ ] No rate limiting on `/login`, `/forgot-password`, `/reset-password`
+
+**Should fix:**
+- [ ] Refresh tokens not rotated on use
+- [ ] No MFA option for admin/owner roles
+- [ ] Email uniqueness checked globally (not per-tenant)
+
+---
+
+## Who to Pair With
+- `saas-architect` — for tenant context in data model
+- `security-engineer` — for token storage and auth security audit
+- `backend-developer` — for middleware and session management
+
+---
+
+## Tools
+**Hosted auth:** Clerk · Auth0 · Supabase Auth · Firebase Auth  
+**Self-hosted:** NextAuth.js / Auth.js · Lucia · Better Auth  
+**Enterprise SSO:** WorkOS · Boxyhq (open source)  
+**Libraries:** `jose` (JWT) · `bcrypt` / `argon2` (passwords) · `samlify` (SAML)