agy-superpowers 5.2.2 → 5.2.4

package/template/agent/skills/paid-acquisition-specialist/SKILL.md

@@ -1,119 +0,0 @@
----
-name: paid-acquisition-specialist
-description: Use when running Meta Ads, Google Ads, Apple Search Ads, or any paid user acquisition channel — including creative strategy, ROAS optimization, and CAC management
----
-
-# Paid Acquisition Specialist Lens
-
-> **Philosophy:** Paid acquisition amplifies what already works — it can't fix a leaky product.
-> Never scale spend before unit economics are positive. Fast money in, faster money out.
-
----
-
-## Core Instincts
-
-- **Validate organic before paying** — paid should scale a channel that already converts
-- **Creative is the primary variable** — in Meta/TikTok, the ad creative drives 70%+ of performance
-- **Kill losers fast, scale winners slowly** — most ad sets fail; iterate quickly
-- **Attribution is broken** — last-click undervalues upper-funnel; triangulate with incrementality tests
-- **Never scale a channel where LTV:CAC < 3:1**
-
----
-
-## Platform Comparison
-
-| Platform | Best for | Typical CAC | Targeting |
-|----------|----------|-------------|-----------|
-| **Apple Search Ads** | iOS apps, high-intent | High | Keyword-based |
-| **Google UAC** | Android + iOS apps | Medium-high | AI-driven, broad |
-| **Meta Ads** | B2C, consumer apps | Medium | Interest + lookalike |
-| **TikTok Ads** | Consumer, Gen Z | Low-medium | Interest + algorithmic |
-| **Google Search** | High-intent SaaS | High | Keyword-based |
-
----
-
-## Key Metrics & Benchmarks
-
-| Metric | Formula | Target |
-|--------|---------|--------|
-| **ROAS** | Revenue / Ad Spend | ≥ 3× (sustainable) |
-| **CAC** | Ad Spend / New Customers | < LTV / 3 |
-| **LTV:CAC** | LTV / CAC | ≥ 3:1 |
-| **CTR** (Meta display) | Clicks / Impressions | > 1% (good), > 3% (great) |
-| **CTR** (Apple Search Ads) | Taps / Impressions (TTR) | > 3% |
-| **CPM** (Meta) | Cost per 1000 impressions | $5–$15 (varies by niche) |
-| **Install-to-trial rate** | Trials / Installs | > 30% |
-| **Trial-to-paid rate** | Paid / Trials | > 15% |
-
----
-
-## Apple Search Ads Quick Reference
-
-- **Campaign types:** Search Results, Today Tab, Search Tab, Product Page
-- **Bidding:** CPT (Cost Per Tap) — start at 2× category average, adjust by TTR
-- **TTR (Tap-Through Rate):** > 3% is healthy; < 1% = keyword mismatch
-- **Search Match:** start on, refine with exact match after data
-- **Negative keywords:** critical — prevents spend on competitor brand terms
-
----
-
-## Creative Testing Framework
-
-```
-Week 1–2: Test hooks (3–5 different opening scenes/hooks)
-Week 3–4: Test formats (UGC vs animation vs screen recording vs testimonial)
-Week 5–6: Scale winner + test CTAs and landing pages
-Ongoing: Refresh winning creative every 4–6 weeks (creative fatigue)
-```
-
-**Creative fatigue signal:** Frequency > 3 AND CTR dropping week-over-week → pause and refresh.
-
----
-
-## ❌ Anti-Patterns to Avoid
-
-| ❌ NEVER DO | Why | ✅ DO INSTEAD |
-|------------|-----|--------------|
-| Scale before ROAS > 2× | Scaling losses faster | Validate at $500–$1000 budget first |
-| Change multiple ad variables at once | Can't isolate what worked | One variable per test |
-| Run ads with no landing page match | Message mismatch kills conversion | Dedicated landing page per ad creative |
-| Ignore creative refresh | Creative fatigue → CPM rises, CTR falls | Replace winning creatives every 4–6 weeks |
-| Use broad targeting from day 1 (Google) | Burn budget on irrelevant users | Start with exact/phrase match, expand |
-| Scale too fast | Algorithm destabilizes, CPM spikes | Max 2× budget increase per week |
-
----
-
-## Questions You Always Ask
-
-**Before launching:**
-- Is the organic conversion rate strong enough to justify paid amplification?
-- What is our target CAC, based on LTV?
-- Is the landing page / App Store listing optimized for conversion?
-- What's the attribution setup — are we tracking installs, activations, or purchases?
-
-**When scaling:**
-- Is ROAS ≥ 3× at current spend level?
-- Is creative frequency > 3 (signal of fatigue)?
-- What's the paid CAC vs organic CAC ratio?
-
----
-
-## Red Flags
-
-**Must fix:**
-- [ ] Scaling spend with ROAS < 2× (burning money)
-- [ ] No conversion tracking set up (flying blind)
-- [ ] Single ad creative with no testing
-- [ ] No daily budget cap per campaign
-
-**Should fix:**
-- [ ] No negative keyword list (Apple Search Ads / Google)
-- [ ] No creative refresh in > 6 weeks
-- [ ] Attribution only from last-click (misses upper-funnel contribution)
-
----
-
-## Who to Pair With
-- `conversion-optimizer` — for landing page and paywall optimization
-- `app-store-optimizer` — for Apple Search Ads + product page optimization
-- `data-analyst` — for attribution modeling and ROAS analysis

package/template/agent/skills/pricing-psychologist/SKILL.md

@@ -1,58 +0,0 @@
----
-name: pricing-psychologist
-description: Use when designing pricing, paywalls, free-to-paid conversion, or optimizing upgrade flows
----
-
-# Pricing Psychologist Lens
-
-## Identity
-You focus on value capture, anchoring, and conversion math. You believe pricing is a feature, not an afterthought. You optimize for revenue and retention, not just user acquisition.
-
-## Core Instincts
-- **Value dictates price** — charge based on the value delivered, not the cost to build it
-- **Friction is the enemy of conversion** — every extra step in the checkout flow kills conversion
-- **Perception is reality** — how a price is presented matters as much as the amount itself
-- **Different products need different models** — a mobile app paywall requires a different strategy than a B2B SaaS
-
-## Core Knowledge
-
-**Pricing Models by Product Type:**
-- **Mobile app:** Freemium + subscription ($2.99-$9.99/mo) or one-time IAP ($4.99-$29.99)
-- **SaaS:** Free tier → $9-$29/mo starter → $49-$99/mo pro (3-tier standard is best)
-- **Chrome extension:** Freemium most common; premium at $3-$10/mo or $29-$99 lifetime
-
-**Pricing Page Psychology:**
-- **Anchoring:** Show the most expensive plan first or highlight the middle plan
-- **Decoy pricing:** Add a plan that makes the target plan look like a no-brainer deal
-- **Annual discount:** Show explicit savings (e.g., "Save 20%", "2 months free") for annual plans
-
-**Free-to-Paid Strategy:**
-- **Feature gating:** Lock premium features (best for mobile and extensions)
-- **Usage limits:** E.g., 5 free uses/day (excellent for AI wrappers and utilities)
-- **Time trials:** 7/14/30 days (time trials convert better for SaaS products)
-
-**Price Testing Shortcuts:**
-- For low traffic: sequential A/B testing (change price for 2 weeks, measure) or customer interviews ("Would you pay $X?")
-- For high traffic: Stripe test mode with active price variations
-
-**Upgrade Triggers:**
-- Hit usage limit
-- Discover locked feature
-- In-app prompt following an "Aha!" value moment
-- Email sequence after trial day 3/7/12
-
-**Key Formulas:**
-- Trial-to-paid conversion: target > 15% (SaaS), > 5% (mobile)
-- LTV = ARPU × (1 / monthly_churn_rate)
-- Payback period = CAC / monthly_revenue_per_user (Target < 3 months for indie)
-
-## Questions You Always Ask
-- What is the specific product type (SaaS, mobile, extension, info product)?
-- What is the "Aha!" moment, and how quickly can we get the user there before asking them to pay?
-- Are we using Stripe Purchasing Power Parity (PPP) or Apple's regional pricing tiers?
-
-## Red Flags / Anti-Patterns
-- [ ] Asking a user to pay before they've experienced any value
-- [ ] Over-complicating tiers with too many variables
-- [ ] Not offering an annual subscription discount
-- [ ] Building custom billing infrastructure instead of using Stripe Checkout/Customer Portal

package/template/agent/skills/real-time-features/SKILL.md

@@ -1,194 +0,0 @@
----
-name: real-time-features
-description: Use when implementing WebSockets, Server-Sent Events (SSE), live collaboration, presence indicators, real-time notifications, or choosing between real-time transport options
----
-
-# Real-Time Features Lens
-
-> **Philosophy:** Real-time is expensive infrastructure. Use it only where it's perceptibly better than polling.
-> The cheapest real-time solution is a fast refresh interval with good UX.
-
----
-
-## Core Instincts
-
-- **Start with polling** — 5-second polling covers 90% of "live" use cases with zero infra complexity
-- **SSE before WebSockets** — SSE is simpler, HTTP/2-compatible, easy to scale; use WebSockets only for bidirectional needs
-- **Connection lifecycle is state** — track connect/disconnect, handle reconnects, never assume connection is alive
-- **Scale out = sticky sessions or pub/sub** — WebSockets break horizontal scaling without Redis Pub/Sub or a broker
-- **Real-time is optional** — always design a fallback (last-write-wins, reconciliation on reconnect)
-
----
-
-## Technology Selection
-
-```
-Which real-time tech to use?
-
-Need bidirectional (client AND server send)?
-├── YES → WebSocket
-│         (chat, collaborative editing, gaming, live cursors)
-└── NO → Server-Sent Events (SSE) or Polling
-          │
-          └── Data changes frequently + immediate delivery matters?
-              ├── YES → SSE
-              │         (live notifications, dashboards, feeds)
-              └── NO → Long polling or periodic polling
-                        (< 5 changes/min: just poll every 5s)
-```
-
----
-
-## Technology Comparison
-
-| Feature | Polling | SSE | WebSocket |
-|---------|---------|-----|-----------|
-| Complexity | ⭐ Low | ⭐⭐ Medium | ⭐⭐⭐ High |
-| Bidirectional | ❌ | ❌ | ✅ |
-| HTTP/2 compatible | ✅ | ✅ | ❌ |
-| Horizontal scaling | ✅ Easy | ⚠️ Sticky sessions | ⚠️ Redis Pub/Sub needed |
-| Firewall / proxy friendly | ✅ | ✅ | ⚠️ Sometimes blocked |
-| Browser reconnect | N/A | ✅ Automatic (EventSource) | Manual |
-| Use case | Dashboards, status | Notifications, feeds | Chat, collab |
-
----
-
-## SSE Implementation Pattern
-
-```javascript
-// Server (Node.js / Express)
-app.get('/events', (req, res) => {
-  // Auth first!
-  if (!req.user) return res.sendStatus(401);
-
-  res.writeHead(200, {
-    'Content-Type':  'text/event-stream',
-    'Cache-Control': 'no-cache',
-    'Connection':    'keep-alive',
-  });
-
-  // Send keepalive every 15s (prevents proxy timeout at 30s)
-  const keepalive = setInterval(() => res.write(': keepalive\n\n'), 15000);
-
-  // Register client
-  clients.set(req.user.id, res);
-
-  // Cleanup on disconnect
-  req.on('close', () => {
-    clearInterval(keepalive);
-    clients.delete(req.user.id);
-  });
-});
-
-// Push to client
-function pushToUser(userId, event, data) {
-  const client = clients.get(userId);
-  if (client) client.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
-}
-```
-
----
-
-## WebSocket Scaling Pattern
-
-```
-Single server: Direct WebSocket connection works fine
-Multi-server:  Client connects to Server A, event fires on Server B
-               → Server B can't reach Server A's client
-               → Solution: Redis Pub/Sub
-
-Architecture:
-  [Client] ←WS→ [Server A] ←→ [Redis Pub/Sub] ←→ [Server B] ←WS→ [Client]
-
-Server publishes to Redis channel:
-  await redis.publish(`user:${userId}`, JSON.stringify(event))
-
-Server subscribes on connect:
-  await redis.subscribe(`user:${userId}`, (message) => {
-    ws.send(message)
-  })
-```
-
----
-
-## Reconnection & State Reconciliation
-
-```javascript
-// Client-side: always implement reconnect with backoff
-const MAX_RETRIES = 5;
-let retries = 0;
-
-function connect() {
-  const ws = new WebSocket(url);
-  
-  ws.onopen = () => { retries = 0; };
-  
-  ws.onclose = () => {
-    if (retries < MAX_RETRIES) {
-      setTimeout(connect, Math.min(1000 * 2 ** retries, 30000));
-      retries++;
-    }
-  };
-}
-
-// Server-side: on reconnect, send missed events since lastEventId
-// SSE: browser sends Last-Event-ID header automatically
-// WebSocket: client sends lastEventId on connect message
-```
-
----
-
-## ❌ Anti-Patterns to Avoid
-
-| ❌ NEVER DO | Why | ✅ DO INSTEAD |
-|------------|-----|--------------|
-| WebSocket for unidirectional updates | SSE is simpler for same use case | Use SSE for server→client only |
-| In-memory client registry | Breaks on horizontal scale | Redis Pub/Sub for multi-instance |
-| No keepalive messages | Proxy kills idle connections at 30–60s | Send `: keepalive` every 15s |
-| No reconnect logic on client | Single network hiccup = broken UI | Exponential backoff reconnect |
-| Auth skipped on WebSocket handshake | WS connections are permanent — auth must be first | Auth during HTTP upgrade (before WS established) |
-| Sending all state on every event | Expensive; clients drift on missed events | Send diffs; reconcile on reconnect |
-
----
-
-## Questions You Always Ask
-
-**When choosing real-time:**
-- Does this require bidirectional communication, or is server→client enough?
-- Would polling every 5–10 seconds give acceptable UX?
-- How many concurrent connections do we expect at peak? (Connection limit planning)
-
-**When implementing:**
-- Is there auth on the WebSocket handshake/SSE endpoint?
-- Is there a keepalive to prevent proxy timeouts?
-- What's the reconnection strategy on the client?
-- How is this scaled across multiple server instances?
-
----
-
-## Red Flags
-
-**Must fix:**
-- [ ] No auth on WebSocket / SSE endpoint
-- [ ] In-memory client registry on multi-instance deployment
-- [ ] No keepalive (proxy will terminate idle connections)
-
-**Should fix:**
-- [ ] No reconnect logic on client
-- [ ] WebSocket used where SSE would suffice
-- [ ] No strategy for clients that miss events while disconnected
-
----
-
-## Who to Pair With
-- `backend-developer` — for server architecture and Redis Pub/Sub
-- `frontend-developer` — for client-side connection management
-- `devops-engineer` — for WebSocket-aware load balancer config
-
----
-
-## Tools
-**Managed:** Supabase Realtime · Pusher · Ably · Liveblocks (collaboration)  
-**Self-hosted:** Socket.IO (WebSocket + SSE fallback) · ws (raw WebSocket)  
-**Browser:** `EventSource` (SSE, built-in) · `WebSocket` (built-in)  
-**Scaling:** Upstash Redis · Redis with ioredis

package/template/agent/skills/retention-specialist/SKILL.md

@@ -1,123 +0,0 @@
----
-name: retention-specialist
-description: Use when improving user retention, designing onboarding flows, reducing churn, analyzing engagement, or building re-engagement campaigns
----
-
-# Retention Specialist Lens
-
-> **Philosophy:** Retention is the multiplier on everything else. Double retention = double LTV.
-> Acquisition brings users in; retention determines if your business exists in 12 months.
-
----
-
-## Core Instincts
-
-- **Retention is a product problem, not a marketing problem** — you can't lifecycle-email your way out of a bad product
-- **Find the aha moment first** — the single action most correlated with long-term retention
-- **Day 1 retention is the most important** — users who don't return on Day 1 rarely return at all
-- **Habit formation takes 21–66 days** — retention strategy must operate over weeks, not days
-- **Segment by engagement tier** — power users, casual users, and at-risk users need different interventions
-
----
-
-## Retention Benchmarks
-
-### Mobile Apps (by category) — 2024 benchmarks
-
-| Category | D1 (good) | D7 (good) | D30 (good) |
-|----------|-----------|-----------|------------|
-| Games | > 28% | > 12% | > 6% |
-| Finance / Fintech | > 25% | > 16% | > 10% |
-| Education | > 26% | > 16% | > 7% |
-| Entertainment | > 27% | > 16% | > 5% |
-| Health & Fitness | > 25% | > 10% | > 5% |
-| Social / Messaging | > 27% | > 11% | > 6% |
-| Productivity / Utilities | > 24% | > 15% | > 5% |
-
-**Context:** Industry-wide D1 average is ~25–28%; D7 ~13–18%; D30 ~5–8%. Apps hitting D30 > 15% are genuinely strong performers.
-**General rule:** D30 < 5% = investigate immediately. D30 > 12% = strong. D30 > 20% = exceptional.
-
-### SaaS / Web Apps — 2024 benchmarks
-| Metric | Poor | Average | Good |
-|--------|------|---------|------|
-| Monthly churn (B2B SaaS) | > 8% | 3.5–5% | < 2% |
-| Monthly churn (B2C / consumer) | > 10% | 5–8% | < 3% |
-| Annual churn (B2B) | > 60% | 30–50% | < 20% |
-| NPS | < 20 | 30–50 | > 50 |
-
-**Context:** Industry average B2B SaaS monthly churn is ~4.2% (Recurly 2024). "< 2% monthly" is excellent / enterprise-level, not just "good".
-
----
-
-## Push Notification Benchmarks
-
-| Platform | Average open rate | Good open rate |
-|----------|------------------|---------------|
-| iOS | 3–5% | > 7% |
-| Android | 4–7% | > 10% |
-| Email re-engagement | 10–15% | > 20% |
-
-**Push notification rules:**
-- Personalized > generic (2–3× higher open rate)
-- Time-based (sent at user's local peak usage time) > blast sends
-- Opt-in rate drops if you send > 1 notification/day
-
----
-
-## ❌ Anti-Patterns to Avoid
-
-| ❌ NEVER DO | Why | ✅ DO INSTEAD |
-|------------|-----|--------------|
-| Lifecycle emails before finding aha moment | Emails can't fix a broken product | Find and shorten path to aha moment first |
-| Generic "come back" push notifications | Low open rate, high unsubscribe | Trigger-based, personalized context |
-| Daily active user target only | DAU ignores depth of engagement | Track DAU + session depth + feature usage |
-| Ignore Day 1 drop-off | 60–80% of users churn on Day 1 | Instrument and fix Day 1 experience first |
-| Same onboarding for all user types | Different users need different paths | Personalize onboarding from first question |
-| Cancel flow with no save attempt | 20–40% of cancellers are saveable | Offer pause, downgrade, or discount before cancel |
-
----
-
-## Questions You Always Ask
-
-**When diagnosing retention:**
-- What does the Day 1/7/30 retention curve look like? Where's the steepest drop?
-- What's the aha moment, and what % of users reach it in session 1?
-- What do retained users do differently from churned users in week 1?
-
-**When designing retention interventions:**
-- Is this a product problem (users don't understand value) or a habit problem (value understood, not habitual)?
-- What's the churn reason? (Run exit survey — "I didn't use it enough" vs "too expensive" vs "found alternative")
-
----
-
-## Red Flags
-
-**Must fix:**
-- [ ] Day 1 retention < 20% (broken first experience)
-- [ ] No aha moment defined or instrumented
-- [ ] Monthly churn > 8% with no active investigation
-- [ ] No exit survey / churn reason tracking
-
-**Should fix:**
-- [ ] No push notification strategy (relying only on email)
-- [ ] No in-app re-engagement for users inactive > 7 days
-- [ ] Onboarding identical for all user segments
-- [ ] No cancel flow / save attempt
-
----
-
-## Who to Pair With
-- `product-manager` — for aha moment and activation event design
-- `growth-hacker` — for AARRR funnel optimization
-- `data-analyst` — for cohort analysis and retention curve modeling
-
----
-
-## Key Formulas
-
-```
-Retention rate (Day N) = users_still_active_on_day_N / users_who_signed_up_N_days_ago
-Monthly churn          = churned_users_this_month / users_at_start_of_month
-Annual churn           ≈ 1 - (1 - monthly_churn)^12
-NPS                    = % Promoters (9–10) - % Detractors (0–6)
-```