agy-superpowers 5.0.7 → 5.0.8

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

@@ -0,0 +1,130 @@
+---
+name: seo-specialist
+description: Use when working on technical SEO, keyword research, on-page optimization, backlink strategy, or improving organic search rankings
+---
+
+# SEO Specialist Lens
+
+> **Philosophy:** SEO is long-term compounding equity. Get indexed → get ranked → get traffic → repeat.
+> Google ranks pages, not websites. Every page is its own opportunity.
+
+---
+
+## Core Instincts
+
+- **Search intent first** — understand WHY someone searches before writing
+- **Crawl → Index → Rank** — a page can't rank if it's not indexed; can't be indexed if not crawled
+- **E-E-A-T matters for every niche** — Experience, Expertise, Authoritativeness, Trustworthiness
+- **Backlinks = votes** — quality beats quantity; one DR70 link > 100 DR10 links
+- **Core Web Vitals are a ranking signal** — performance and UX directly affect SEO
+
+---
+
+## On-Page SEO Exact Rules
+
+| Element | Rule | Why |
+|---------|------|-----|
+| `<title>` tag | ≤ 60 characters | Truncated in SERPs beyond this |
+| Meta description | ≤ 160 characters | Truncated; influences CTR not ranking |
+| `<h1>` | 1 per page; include primary keyword | Strongest on-page keyword signal |
+| URL slug | Short, hyphenated, keyword-rich | Clarity + keyword signal |
+| Alt text (images) | Descriptive, include keyword naturally | Accessibility + image search |
+| Primary keyword | In first 100 words, title, H1, 1 H2 | Keyword density ≈ 1–2%, no stuffing |
+| Internal links | ≥ 3 to related pages | Passes link equity, improves crawl |
+| Page load speed | LCP < 2.5s, CLS < 0.1, INP < 200ms | Core Web Vitals ranking signal |
+
+---
+
+## Keyword Research Process
+
+1. **Seed terms** — brainstorm 20–30 core topics
+2. **Expand** — use Ahrefs / Semrush "keyword ideas" to 5× the list
+3. **Cluster by intent** — Informational / Navigational / Commercial / Transactional
+4. **Score by KD + Volume** — prioritize: Volume > 100/month + KD < 30 (for new sites)
+5. **Long-tail first** — easier to rank; signals authority for head terms
+6. **Map to pages** — 1 primary keyword per page, 2–5 secondary
+
+---
+
+## Keyword Difficulty by Domain Rating
+
+| Your Site DR | Target KD (Keyword Difficulty) |
+|-------------|-------------------------------|
+| 0–20 | < 15 |
+| 20–40 | < 25 |
+| 40–60 | < 40 |
+| 60+ | < 60 |
+
+*(DR = Domain Rating, KD = Keyword Difficulty, both 0–100 scale in Ahrefs)*
+
+---
+
+## Technical SEO Checklist
+
+- [ ] `sitemap.xml` submitted to Google Search Console + Bing Webmaster
+- [ ] `robots.txt` not accidentally blocking important pages
+- [ ] Canonical tags on duplicate/near-duplicate pages
+- [ ] HTTPS on all pages (non-HTTPS = ranking penalty)
+- [ ] Mobile-friendly (Google uses mobile-first indexing)
+- [ ] Core Web Vitals passing (LCP, CLS, INP) — verify in GSC
+- [ ] Structured data (JSON-LD) on applicable pages (FAQ, Product, Review, Breadcrumb)
+- [ ] No orphan pages (every important page linked to from at least 1 other page)
+- [ ] Hreflang tags for multilingual sites
+
+---
+
+## Backlink Strategy
+
+| Tactic | Effort | ROI |
+|--------|--------|-----|
+| Content linkbait (tools, data studies, guides) | High | ✅ Very high |
+| Guest posting on relevant sites | Medium | ✅ High |
+| HARO / journalist requests | Low | ✅ High |
+| Broken link building | Medium | Medium |
+| Directory and startup listings | Low | Low-medium |
+| Buying links | — | ❌ Google penalty risk |
+
+**Anchor text diversity:** Branded (40%) > Natural ("click here", 25%) > Keyword-rich (25%) > Naked URL (10%). Keyword-heavy anchor = manipulation signal.
+
+---
+
+## Questions You Always Ask
+
+**When auditing a site:**
+- Is the site indexed? (Check `site:domain.com` in Google, or GSC Index report)
+- What's the current DR/DA? What's the plan to grow it?
+- Are there pages cannibalizing each other for the same keyword?
+- What does GSC show for impressions with 0 clicks? (Position 8–20 = low-hanging optimization)
+
+**When planning new content:**
+- What's the search intent — informational, commercial, or transactional?
+- Is there current ranking content to optimize, or do we need a new page?
+- What would earn a featured snippet for this query?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] Important pages not indexed (check GSC)
+- [ ] Multiple pages targeting the same keyword (cannibalization)
+- [ ] No `<h1>` or multiple `<h1>` on a page
+- [ ] Core Web Vitals failing in GSC
+
+**Should fix:**
+- [ ] No internal linking between related posts
+- [ ] meta description missing or > 160 chars
+- [ ] Title tags > 60 chars
+- [ ] No structured data on applicable pages
+
+---
+
+## Who to Pair With
+- `content-marketer` — for content strategy and topic selection
+- `frontend-developer` — for Core Web Vitals and technical implementation
+- `data-analyst` — for GSC data analysis and ranking tracking
+
+---
+
+## Tools
+Google Search Console (free, essential) · Ahrefs · Semrush · Screaming Frog (site audits) · PageSpeed Insights · Moz · Answer the Public

package/template/agent/skills/subscription-billing/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: subscription-billing
+description: Use when integrating subscription billing, handling Stripe webhooks, implementing trial logic, managing upgrades/downgrades, or building dunning flows
+---
+
+# Subscription Billing Lens
+
+> **Philosophy:** Billing is load-bearing infrastructure. A bug in billing = lost revenue or incorrect charges.
+> Build it like critical path code: idempotent, webhook-driven, logged exhaustively.
+
+---
+
+## Core Instincts
+
+- **Webhook-first** — Stripe's webhook is the source of truth, not your API response
+- **Idempotency everywhere** — billing operations must be safe to retry
+- **Never trust client state for billing** — always fetch subscription status from Stripe server-side
+- **All clock-sensitive operations use `event.created`** — not `Date.now()`
+- **Soft failures, never hard block** — grace period on payment failures protects revenue
+
+---
+
+## Stripe Integration Architecture
+
+```
+User upgrades plan →
+  1. Client: Stripe.js → Payment Method → PaymentIntent / SetupIntent
+  2. Server: Create/Update Subscription on Stripe
+  3. Stripe: Processes payment → emits webhook event
+  4. Server: Webhook handler updates DB subscription status
+  5. Server: Return state from DB (never from Stripe API response)
+
+⚠️ Anti-pattern: updating DB from API response
+✅ Pattern: update DB only from webhook confirmation
+```
+
+---
+
+## Critical Webhook Events to Handle
+
+| Event | What to do |
+|-------|-----------|
+| `checkout.session.completed` | Provision access, send welcome email |
+| `customer.subscription.created` | Set status = `active`, log |
+| `customer.subscription.updated` | Update plan, seats, feature flags |
+| `customer.subscription.deleted` | Set status = `canceled`, begin grace period |
+| `invoice.payment_succeeded` | Extend access, reset dunning state |
+| `invoice.payment_failed` | Start dunning, notify user, DON'T revoke access immediately |
+| `invoice.upcoming` | Warn user of upcoming charge |
+| `customer.subscription.trial_will_end` | 3-day warning email before trial ends |
+
+---
+
+## Trial Logic Rules
+
+```
+Trial best practices:
+- Default trial: 14 days (Stripe default is 30; reduce for faster conversion signal)
+- Require payment method at trial start (reduces churn at trial end)
+- Free trial without CC = high trial-end churn; use for virality, not conversion
+- trial_will_end webhook fires 3 days before → trigger upgrade prompt
+
+Trial states:
+  trialing → (payment method on file) → auto-converts to active
+  trialing → (no payment method) → needs_payment_method → upgrade prompt
+```
+
+---
+
+## Dunning Flow (Failed Payment Recovery)
+
+```
+Day 0: Payment fails → invoice.payment_failed webhook
+  → Set subscription status = past_due
+  → Email: "Your payment failed — please update your card"
+  → DO NOT revoke access
+
+Day 3: Stripe auto-retries
+  → On success: subscription back to active
+  → On fail: email #2 "We'll try again in 4 days"
+
+Day 7: Stripe auto-retries
+  → On fail: email #3 with prominent card update CTA
+
+Day 14: Final retry → if fails → subscription.deleted webhook
+  → Begin grace period (7–14 days before revoking access)
+  → Final email: "Your account will be suspended on [date]"
+
+Configure in: Stripe Dashboard → Billing → Subscriptions → Retry schedule
+```
+
+---
+
+## Proration & Plan Changes
+
+```javascript
+// Upgrading mid-cycle: charge difference immediately
+await stripe.subscriptions.update(subscriptionId, {
+  items: [{ id: itemId, price: newPriceId }],
+  proration_behavior: 'create_prorations', // Default — charge difference now
+});
+
+// Downgrading: apply at end of period (no refund)
+await stripe.subscriptions.update(subscriptionId, {
+  items: [{ id: itemId, price: lowerPriceId }],
+  proration_behavior: 'none',
+  billing_cycle_anchor: 'unchanged',
+});
+```
+
+---
+
+## Idempotency Pattern
+
+```javascript
+// All Stripe API calls should use idempotency keys
+await stripe.subscriptions.create(params, {
+  idempotencyKey: `sub_create_${userId}_${planId}`,
+});
+
+// Webhook handlers must be idempotent
+async function handleWebhook(event) {
+  // Check if already processed
+  if (await db.webhookEvents.find(event.id)) return;
+  
+  await db.webhookEvents.create({ id: event.id, processedAt: new Date() });
+  // ... handle event
+}
+```
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Update subscription status from API response | Stripe may succeed but your server errors | Only from webhook |
+| Revoke access immediately on payment failure | Kills goodwill; many recover | Grace period + dunning |
+| No idempotency on webhook handler | Duplicate events → double-provision | Store processed event IDs |
+| Store card details in your DB | PCI violation | Use Stripe tokens only |
+| Use `Date.now()` for billing timestamps | Clock drift causes subtle bugs | Use `event.created` from Stripe |
+| Hardcode price IDs in code | Can't change pricing without deploy | Store in env vars or DB |
+
+---
+
+## Questions You Always Ask
+
+**When building billing:**
+- Is the webhook handler idempotent? What happens if it fires twice?
+- Are we testing with Stripe test mode webhooks via `stripe listen`?
+- What's the grace period on failed payments before access revocation?
+- Is there a webhook signature verification (`stripe.webhooks.constructEvent`)?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] Subscription status updated from API response (not webhook)
+- [ ] No webhook signature verification
+- [ ] Access revoked immediately on `invoice.payment_failed`
+- [ ] No idempotency on webhook handler
+
+**Should fix:**
+- [ ] No dunning email sequence
+- [ ] No handling of `customer.subscription.trial_will_end`
+- [ ] Price IDs hardcoded in application code
+
+---
+
+## Who to Pair With
+- `saas-architect` — for subscription status in the tenant data model
+- `backend-developer` — for API design around billing operations
+- `monetization-strategist` — for pricing model decisions
+
+---
+
+## Tools
+Stripe (billing) · `stripe-node` · Stripe CLI (`stripe listen` for local webhooks) · Stripe Test Cards (4242 4242 4242 4242) · Paddle (alternative with VAT/tax handling)

package/template/agent/skills/ux-designer/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: ux-designer
+description: Use when designing UI, creating wireframes, running user research, defining information architecture, or reviewing design decisions — regardless of tool (Figma, Sketch, etc.)
+---
+
+# UX Designer Lens
+
+> **Philosophy:** Design is problem solving, not decoration. Good UX is invisible — users accomplish their goal without noticing the interface.
+> The best design eliminates decisions the user shouldn't have to make.
+
+---
+
+## ⚠️ ASK BEFORE ASSUMING
+
+| What | Why it matters |
+|------|----------------|
+| **Platform?** iOS / Android / Web / Desktop | Each has distinct patterns and constraints |
+| **Stage?** Early exploration / Detailed design / Polish | Changes fidelity needed |
+| **User research available?** | Can't design for a user you haven't talked to |
+| **Design system exists?** | Whether to extend or create from scratch |
+
+---
+
+## Core Instincts
+
+- **Design for the job-to-be-done** — what is the user trying to accomplish? Remove everything that doesn't serve that
+- **Hierarchy guides the eye** — size, color, and position communicate importance; every screen needs one clear primary action
+- **Friction has a cost** — every tap, field, and decision users must make is a drop in task completion
+- **Don't make me think (Steve Krug)** — if users have to figure it out, the design failed
+- **Test with 5 users** — 5 usability test sessions reveal ~85% of usability problems
+
+---
+
+## Hick's Law & Fitts' Law Applied
+
+```
+Hick's Law: Decision time = log2(N choices)
+→ More options = slower decisions = more friction
+→ Max 5–7 items in navigation; fewer primary actions per screen
+
+Fitts' Law: Time to tap = a + b × log2(distance/size + 1)
+→ Bigger targets = faster taps
+→ Primary CTA: minimum 44×44pt (iOS) / 48×48dp (Android) / 44×44px (web)
+→ Place common actions closer to thumb (bottom of screen on mobile)
+```
+
+---
+
+## Design Hierarchy Checklist
+
+Every screen needs exactly:
+- 1 primary action (largest, highest contrast, most prominent)
+- 0–2 secondary actions (smaller, lower contrast)
+- 0–1 tertiary action (text link or icon)
+
+If a screen has 3+ things competing for attention → redesign.
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Design in isolation without user feedback | Solving assumed problems | User interviews before wireframing |
+| 5+ items in primary navigation | Cognitive overload, users freeze | 4–5 items max; progressive disclosure for the rest |
+| Decorative animations only | Distraction without purpose | Animations that communicate state change or guide attention |
+| Red for non-error states | Deep-wired association: red = danger | Reserve red for errors/destructive actions only |
+| Long onboarding before value | Users leave before experiencing product | Show value first, teach later |
+| Placeholder text as labels | Disappears on input, user forgets context | Floating labels or static labels above inputs |
+| Custom gestures with no affordance | Undiscoverable | Teach novel gestures with a coach mark on first encounter |
+
+---
+
+## Color & Contrast Rules (WCAG 2.1)
+
+| Text type | Minimum contrast ratio |
+|-----------|----------------------|
+| Normal text (< 18pt) | **4.5:1** |
+| Large text (≥ 18pt or bold 14pt) | **3:1** |
+| UI components, icons | **3:1** |
+| Decorative, disabled | No requirement |
+
+**Check with:** WebAIM Contrast Checker · Figma Contrast plugin · Stark
+
+---
+
+## Questions You Always Ask
+
+**When designing a new screen:**
+- What is the single primary action on this screen?
+- What does the user need to know to complete their goal here?
+- What happens when there's no data (empty state)?
+- How does this look on a 375px screen?
+
+**When reviewing existing design:**
+- Can a new user complete the core task without instruction?
+- Is the visual hierarchy immediately clear — what's most important?
+- Are touch targets large enough? (Use a 44pt grid overlay)
+- Does every animation serve a purpose?
+
+---
+
+## Red Flags in Design Review
+
+**Must fix:**
+- [ ] No empty state designed (blank screen = broken feel)
+- [ ] Primary action competes with 2+ other elements for attention
+- [ ] Touch targets < 44pt / 48dp on mobile
+- [ ] Text/background contrast < 4.5:1 for body text
+
+**Should fix:**
+- [ ] Navigation > 5 items
+- [ ] Onboarding > 4 screens before first value delivery
+- [ ] Placeholder text used as the only label for form inputs
+- [ ] Loading state not designed
+
+---
+
+## Who to Pair With
+- `mobile-developer` — for mobile interaction constraints and platform conventions
+- `frontend-developer` — for web accessibility and component design
+- `conversion-optimizer` — for conversion-focused landing page design
+- `product-manager` — for JTBD alignment before starting design
+
+---
+
+## Tools
+Figma (design + prototyping) · FigJam (whiteboarding) · Maze / Useberry (usability testing) · Stark (accessibility) · Mobbin (UI reference/inspiration) · Lottie (animations)