agy-superpowers 5.0.7 → 5.0.9

package/template/agent/skills/mobile-developer/references/react-native.md

@@ -0,0 +1,345 @@
+# React Native + Expo Reference
+
+> **Philosophy:** JavaScript-first, native-quality. Ship fast with OTA updates, but never sacrifice 60fps.
+> Expo is the default — eject only when you must.
+
+---
+
+## Project Setup & Detection
+
+**Stack indicators:** `package.json` with `react-native` or `expo` dependency.
+
+**Key config files:**
+
+| File | Purpose |
+|------|---------|
+| `app.json` / `app.config.js` | Expo configuration (app name, version, plugins) |
+| `metro.config.js` | Metro bundler configuration |
+| `babel.config.js` | Babel presets and plugins |
+| `tsconfig.json` | TypeScript configuration |
+| `eas.json` | EAS Build/Submit/Update configuration |
+
+**Recommended project structure (feature-based):**
+
+```
+src/
+  features/
+    auth/
+      screens/LoginScreen.tsx
+      components/AuthForm.tsx
+      hooks/useAuth.ts
+      store/authStore.ts
+    home/
+      screens/HomeScreen.tsx
+      components/FeedList.tsx
+  shared/
+    components/    # Reusable UI components
+    hooks/         # Shared hooks
+    utils/         # Pure utility functions
+    services/      # API clients, storage wrappers
+    constants/     # Theme, config values
+app/               # expo-router file-based routing
+  _layout.tsx
+  (tabs)/
+    _layout.tsx
+    index.tsx
+    settings.tsx
+```
+
+---
+
+## Architecture Patterns
+
+### State Management
+
+| Approach | Use When |
+|----------|----------|
+| **Zustand** (recommended) | Most apps — simple API, selector-based subscriptions, minimal boilerplate |
+| **Redux Toolkit** | Large teams, complex state with many reducers, need Redux DevTools |
+| **Jotai** | Atomic state, when individual pieces of state are independent |
+| **React Context** | Infrequently-changing values (theme, locale, auth status) |
+
+**State design principles:**
+- State should be the **minimal source of truth**. If a value can be derived from other state or props, derive it during render — don't store it.
+- Use **selector functions** in Zustand to subscribe to specific slices and avoid unnecessary re-renders.
+- Keep UI state local (`useState`), share only what multiple components need.
+
+### Navigation
+
+Use **native navigators** over JS-based navigators for performance:
+
+| Navigator | Correct | Incorrect |
+|-----------|---------|-----------|
+| Stack | `createNativeStackNavigator` / `expo-router Stack` | `createStackNavigator` (JS-based, slow transitions) |
+| Tabs | `createNativeBottomTabNavigator` / `expo-router NativeTabs` | `createBottomTabNavigator` (JS-based) |
+
+Native navigators run transitions on the UI thread, provide platform-native gestures, large titles (iOS), search bars, and proper safe area handling automatically.
+
+**Prefer native header options over custom header components.** Native headers support iOS large titles, blur effects, and search bars out of the box.
+
+### New Architecture
+
+React Native's New Architecture includes:
+- **TurboModules** — lazy-loaded, synchronous native module access (replaces Bridge)
+- **Fabric** — concurrent renderer with synchronous layout (replaces old renderer)
+- **Bridgeless mode** — eliminates the JS-native bridge entirely
+- **React Compiler** — automatic memoization (eliminates `React.memo`, `useCallback`, `useMemo`)
+
+When using **React Compiler**, `memo()` and `useCallback()` are unnecessary. However, **object reference stability** still matters for list virtualization.
+
+---
+
+## Performance Optimization
+
+### Critical Thresholds
+
+| Metric | Target | Critical |
+|--------|--------|----------|
+| Cold start (JS bundle ready) | < 1s | > 2s |
+| Time to interactive | < 2s | > 4s |
+| List scroll frame rate | 60fps | < 45fps |
+| JS bundle size (gzipped) | < 1MB | > 3MB |
+| IPA/APK download size | < 30MB | > 100MB |
+
+### List Performance (CRITICAL)
+
+**Always use a list virtualizer** — even for short lists. Virtualizers only render visible items, reducing memory and mount time.
+
+| Library | When to Use |
+|---------|------------|
+| **LegendList** | Default choice — excellent recycling, great performance |
+| **FlashList** (@shopify) | Alternative — well-tested, widely adopted |
+| **FlatList** (built-in) | Legacy — avoid if possible, use LegendList/FlashList |
+
+**Key rules for list performance:**
+
+1. **Stable object references** — don't `.map()` or `.filter()` data before passing to lists. Transform data inside list items instead.
+2. **Pass primitives to list items** — enables shallow comparison in `memo()`. Pass `id`, `name`, `email` instead of entire objects.
+3. **Hoist callbacks to list root** — extract `renderItem` and callbacks outside the component, or use `useCallback` if not using React Compiler.
+4. **No inline objects in renderItem** — every render creates new references, causing full re-renders of all visible items.
+5. **Use compressed images** — large images in lists destroy scroll performance.
+6. **Use item types** for heterogeneous lists — helps the virtualizer recycle views correctly.
+
+```tsx
+// ❌ Bad: creates new references on every render
+<LegendList
+  data={items.map(i => ({ ...i, label: i.name.toUpperCase() }))}
+  renderItem={({ item }) => <ItemCard item={item} />}
+/>
+
+// ✅ Good: stable data, transform inside item
+const renderItem = ({ item }) => <ItemCard item={item} />
+
+<LegendList
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={(item) => item.id}
+  estimatedItemSize={80}
+/>
+```
+
+### Animation (HIGH)
+
+**Only animate GPU-accelerated properties:** `transform` (translate, scale, rotate) and `opacity`. Animating `width`, `height`, `top`, `left`, `margin`, `padding` triggers layout recalculation on every frame.
+
+```tsx
+// ❌ Bad: animates height (layout recalc every frame)
+useAnimatedStyle(() => ({ height: withTiming(expanded ? 200 : 0) }))
+
+// ✅ Good: animates transform (GPU-accelerated)
+useAnimatedStyle(() => ({
+  transform: [{ scaleY: withTiming(expanded ? 1 : 0) }],
+  opacity: withTiming(expanded ? 1 : 0),
+}))
+```
+
+- Use `useDerivedValue` over `useAnimatedReaction` for computed animations.
+- Use `GestureDetector` (from `react-native-gesture-handler`) for press animations instead of `Pressable`.
+
+### Scroll Performance
+
+**Never track scroll position in useState** — it triggers a JS re-render on every frame. Use `useSharedValue` from Reanimated instead.
+
+### Hermes Engine
+
+Hermes is the default JS engine. It pre-compiles JavaScript to bytecode at build time, reducing cold start time and memory usage. Ensure Hermes is enabled in your project (`"jsEngine": "hermes"` in `app.json`).
+
+---
+
+## Common Libraries Ecosystem
+
+| Category | Recommended | Alternative |
+|----------|-------------|-------------|
+| **Navigation** | `expo-router` (file-based) | `@react-navigation/native` (imperative) |
+| **State** | `zustand` | `@reduxjs/toolkit`, `jotai` |
+| **Server State** | `@tanstack/react-query` | `swr` |
+| **HTTP** | `fetch` (built-in) | `axios`, `ky` |
+| **Storage (non-sensitive)** | `react-native-mmkv` | `@react-native-async-storage/async-storage` |
+| **Storage (sensitive)** | `expo-secure-store` | `react-native-keychain` |
+| **Images** | `expo-image` | `react-native-fast-image` |
+| **Animation** | `react-native-reanimated` | `react-native-animated` (built-in, limited) |
+| **Gestures** | `react-native-gesture-handler` | — |
+| **Lists** | `@legendapp/list` (LegendList) | `@shopify/flash-list` (FlashList) |
+| **Forms** | `react-hook-form` | `formik` |
+| **Modals** | Native `Modal` with `formSheet` | `react-native-bottom-sheet` |
+| **Menus** | `zeego` (native context/dropdown) | — |
+| **Image Gallery** | `galeria` | — |
+| **Icons** | `expo-symbols` (SF Symbols) | `@expo/vector-icons` |
+| **Fonts** | Config plugin (native load) | `expo-font` (runtime load) |
+
+---
+
+## Anti-Patterns & Gotchas
+
+| ❌ Don't | Why | ✅ Do Instead |
+|----------|-----|---------------|
+| `ScrollView` with `.map()` for lists | Renders ALL items, memory explodes | `LegendList` / `FlashList` |
+| `TouchableOpacity` for press | Legacy, limited API | `Pressable` — standard, more flexible |
+| Text not wrapped in `<Text>` | Crashes on Android, undefined behavior | Always wrap strings in `<Text>` |
+| `{condition && <Component/>}` with falsy value | `0` or `NaN` renders as text on Android | `{condition ? <Component/> : null}` |
+| `useState` for scroll position | Re-renders on every frame, janky | `useSharedValue` from Reanimated |
+| Inline objects in `style` prop | New reference every render | `StyleSheet.create()` or `borderCurve: 'continuous'` |
+| `shadowColor`/`elevation` for shadows | Legacy, inconsistent cross-platform | CSS `boxShadow` string syntax |
+| Margin between siblings | Fragile, breaks when children change | `gap` on parent container |
+| `LinearGradient` third-party | Extra dependency | `experimental_backgroundImage: 'linear-gradient(...)'` |
+| Custom header components | Misses native features (large titles, blur) | Native header `options` |
+| `{ borderRadius: 12 }` alone | Sharp iOS corners | Add `borderCurve: 'continuous'` for smooth corners |
+| Import entire lodash | Bundle bloat | `import debounce from 'lodash/debounce'` |
+| `console.log` in production | Blocks JS thread, leaks data | Use a logger with levels, strip in release |
+| Tokens in `AsyncStorage` | Plaintext, exposed on rooted device | `expo-secure-store` / Keychain |
+
+### React Compiler Gotchas
+
+When React Compiler is enabled:
+- **Destructure functions early** — the compiler optimizes better with destructured function references.
+- **Use `.get()`/`.set()` for Reanimated shared values** — the compiler cannot optimize `.value` property access patterns.
+
+---
+
+## Testing
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| **Unit** | Jest + React Native Testing Library | Component logic, hooks, utils |
+| **Component** | `@testing-library/react-native` | Render + interact with components |
+| **E2E** | Maestro | Full flow testing, easy YAML syntax |
+| **E2E (alt)** | Detox (Wix) | Full flow testing, JS-based |
+
+**Testing principles:**
+- Test behavior, not implementation (don't test component internals)
+- Use `screen.getByRole()` and `getByText()` over `getByTestId()`
+- Mock native modules at the module level (`jest.mock('expo-secure-store')`)
+- Test loading, error, and empty states for every async component
+
+---
+
+## Deployment & Distribution
+
+### EAS (Expo Application Services)
+
+| Service | Purpose |
+|---------|---------|
+| **EAS Build** | Cloud builds for iOS and Android (no local Xcode/Android Studio needed) |
+| **EAS Submit** | Publish to App Store / Google Play directly from CLI |
+| **EAS Update** | OTA JavaScript updates (code push without app store review) |
+
+**OTA update strategy:**
+- Use `expo-updates` for JS-only changes (bug fixes, UI tweaks)
+- Native changes (new native modules, SDK version bump) require a full build + store submission
+- Set update channels: `production`, `staging`, `preview`
+
+### Build commands
+
+```bash
+# Development build (with dev client)
+eas build --profile development --platform ios
+
+# Production build
+eas build --profile production --platform all
+
+# Submit to stores
+eas submit --platform ios
+eas submit --platform android
+
+# OTA update
+eas update --branch production --message "Fix login bug"
+```
+
+### App size optimization
+- Enable Hermes (pre-compiled bytecode, smaller bundle)
+- Use `expo-image` instead of `Image` (optimized loading)
+- Tree-shake unused code with Metro bundler
+- Use `expo-asset` for preloading critical assets
+- Audit dependencies with `npx expo-doctor`
+
+---
+
+## Quick Reference — Granular Rules
+
+Individual rule files in `react-native-rules/` with detailed incorrect/correct
+code examples. Read the specific rule when working in that area.
+
+> Source: [Vercel agent-skills](https://github.com/vercel-labs/agent-skills/tree/main/skills/react-native-skills)
+
+### CRITICAL — Core Rendering
+
+- [rendering-text-in-text-component.md](react-native-rules/rendering-text-in-text-component.md) — All text must be inside `<Text>`
+- [rendering-no-falsy-and.md](react-native-rules/rendering-no-falsy-and.md) — Avoid falsy `&&` rendering
+
+### HIGH — List Performance
+
+- [list-performance-virtualize.md](react-native-rules/list-performance-virtualize.md) — Always use LegendList/FlashList
+- [list-performance-function-references.md](react-native-rules/list-performance-function-references.md) — Stable object references
+- [list-performance-item-memo.md](react-native-rules/list-performance-item-memo.md) — Pass primitives for memo
+- [list-performance-callbacks.md](react-native-rules/list-performance-callbacks.md) — Hoist callbacks
+- [list-performance-inline-objects.md](react-native-rules/list-performance-inline-objects.md) — No inline objects
+- [list-performance-images.md](react-native-rules/list-performance-images.md) — Compressed images in lists
+- [list-performance-item-types.md](react-native-rules/list-performance-item-types.md) — Item types for recycling
+- [list-performance-item-expensive.md](react-native-rules/list-performance-item-expensive.md) — Defer expensive items
+
+### HIGH — Animation
+
+- [animation-gpu-properties.md](react-native-rules/animation-gpu-properties.md) — GPU-only properties (transform, opacity)
+- [animation-derived-value.md](react-native-rules/animation-derived-value.md) — useDerivedValue over useAnimatedReaction
+- [animation-gesture-detector-press.md](react-native-rules/animation-gesture-detector-press.md) — GestureDetector for press animations
+
+### HIGH — Scroll & Navigation
+
+- [scroll-position-no-state.md](react-native-rules/scroll-position-no-state.md) — Never track scroll in useState
+- [navigation-native-navigators.md](react-native-rules/navigation-native-navigators.md) — Native stack/tab navigators
+
+### MEDIUM — React State
+
+- [react-state-minimize.md](react-native-rules/react-state-minimize.md) — Minimize state, derive values
+- [react-state-dispatcher.md](react-native-rules/react-state-dispatcher.md) — Dispatch pattern for state
+- [react-state-fallback.md](react-native-rules/react-state-fallback.md) — Fallback rendering pattern
+- [state-ground-truth.md](react-native-rules/state-ground-truth.md) — State ground truth principles
+
+### MEDIUM — React Compiler
+
+- [react-compiler-destructure-functions.md](react-native-rules/react-compiler-destructure-functions.md) — Destructure functions early
+- [react-compiler-reanimated-shared-values.md](react-native-rules/react-compiler-reanimated-shared-values.md) — .get()/.set() for shared values
+
+### MEDIUM — UI Patterns
+
+- [ui-expo-image.md](react-native-rules/ui-expo-image.md) — Use expo-image
+- [ui-pressable.md](react-native-rules/ui-pressable.md) — Pressable over TouchableOpacity
+- [ui-native-modals.md](react-native-rules/ui-native-modals.md) — Native modal presentations
+- [ui-menus.md](react-native-rules/ui-menus.md) — Native context/dropdown menus (zeego)
+- [ui-image-gallery.md](react-native-rules/ui-image-gallery.md) — Native image gallery (galeria)
+- [ui-measure-views.md](react-native-rules/ui-measure-views.md) — Measure views correctly
+- [ui-safe-area-scroll.md](react-native-rules/ui-safe-area-scroll.md) — Safe area with scroll
+- [ui-scrollview-content-inset.md](react-native-rules/ui-scrollview-content-inset.md) — ScrollView content inset
+- [ui-styling.md](react-native-rules/ui-styling.md) — Modern styling patterns (gap, boxShadow, borderCurve)
+
+### MEDIUM — Design System
+
+- [design-system-compound-components.md](react-native-rules/design-system-compound-components.md) — Compound component pattern
+
+### LOW — Monorepo, Dependencies, JS, Fonts
+
+- [monorepo-native-deps-in-app.md](react-native-rules/monorepo-native-deps-in-app.md) — Native deps in app package
+- [monorepo-single-dependency-versions.md](react-native-rules/monorepo-single-dependency-versions.md) — Single dependency versions
+- [imports-design-system-folder.md](react-native-rules/imports-design-system-folder.md) — Re-export third-party deps
+- [js-hoist-intl.md](react-native-rules/js-hoist-intl.md) — Hoist Intl formatters
+- [fonts-config-plugin.md](react-native-rules/fonts-config-plugin.md) — Config plugin for fonts

package/template/agent/skills/monetization-strategist/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: monetization-strategist
+description: Use when designing pricing models, planning freemium strategy, setting up IAP, optimizing upgrade flows, or modeling unit economics
+---
+
+# Monetization Strategist Lens
+
+> **Philosophy:** Pricing is product strategy. How you charge shapes who uses you and how.
+> Charge too little = sustainability problem. Charge too late = habit without payment.
+
+---
+
+## Core Instincts
+
+- **Price is positioning** — low price signals low value; premium price signals quality
+- **Willingness to pay > cost-plus pricing** — price based on value delivered, not cost of building
+- **Free trial ≠ free forever** — time-limit trials; gate meaningful features behind paywall
+- **Upgrade at the aha moment** — show the paywall after users experience value, not before
+- **Churn is a pricing signal** — high churn often means price/value mismatch, not product failure
+
+---
+
+## Pricing Model Comparison
+
+| Model | Best for | Risk |
+|-------|----------|------|
+| **One-time purchase** | Tools, utilities; no recurring infrastructure | Hard to sustain; no expansion revenue |
+| **Subscription (monthly)** | SaaS, apps with ongoing value | High churn pressure; needs retention |
+| **Subscription (annual)** | SaaS with sticky users | Lower churn; requires trust upfront |
+| **Freemium** | Network effects, viral products | Conversion typically 2–5% free → paid |
+| **Usage-based** | APIs, infrastructure, variable-value products | Revenue unpredictability |
+| **IAP (consumable)** | Games, one-time unlocks | Requires volume; App Store cut (15–30%) |
+
+**Indie hacker default:** Subscription (monthly + annual discount) or one-time if the product is a clear tool.
+
+---
+
+## Freemium Design Rules
+
+- **Free tier must be genuinely useful** — users who don't get value won't upgrade
+- **Paid tier must be obviously better** — upgrade should feel like an obvious next step
+- **Free-to-paid conversion benchmark:** 2–5% is typical; > 5% is strong
+- **Don't give away features that should be paid** — you're training users to expect them free
+- **Paywall trigger:** after activation event, not first open; after Nth use, not immediately
+
+---
+
+## Pricing Thresholds (Mobile Apps, 2024 benchmarks)
+
+| Tier | Monthly | Annual | One-time |
+|------|---------|--------|----------|
+| Entry | $2.99–$4.99 | $19.99–$29.99 | $9.99 |
+| Mid | $7.99–$9.99 | $49.99–$69.99 | $19.99–$29.99 |
+| Premium | $14.99–$19.99 | $99.99–$149.99 | $49.99–$99.99 |
+
+**Annual discount should be ~40–50% off monthly** to incentivize without undermining monthly revenue.
+
+---
+
+## Key Formulas
+
+```
+LTV       = ARPU / monthly_churn_rate
+LTV:CAC   ≥ 3:1 (sustainable), ≥ 5:1 (great)
+Payback   = CAC / monthly_gross_margin_per_customer (target < 12 months)
+MRR       = paying_users × ARPU
+ARR       = MRR × 12
+Churn     = churned_users_this_month / users_at_start_of_month
+```
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Paywall on first open | Users leave before experiencing value | Paywall after activation event |
+| Pricing without testing | First price is almost always wrong | A/B test 2–3 price points |
+| One price tier only | No upgrade path, no upsell | 2–3 tiers (entry, pro, enterprise/lifetime) |
+| Free trial < 7 days | Not enough time to build habit | 14 days minimum; 30 for complex products |
+| Grandfathering everyone on price increases | Unsustainable | Clear communication + fair grandfathering period |
+| Hiding pricing | Kills trust, attracts wrong users | Show pricing clearly on landing page |
+
+---
+
+## Questions You Always Ask
+
+**When designing pricing:**
+- What's the activation event after which users clearly understand value?
+- What's the minimum viable paid tier — what features justify the price?
+- What's the churn rate, and does it suggest a pricing mismatch?
+- Is there an annual plan? (Annual users churn 3–5× less than monthly)
+
+**When reviewing monetization:**
+- What % of users convert free → paid? What's the target?
+- What's the most common reason users cancel? (Exit survey data)
+- Is LTV:CAC ≥ 3:1?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] No pricing page / pricing hidden
+- [ ] Paywall shown before any activation event
+- [ ] LTV:CAC < 1:1 (actively losing money per customer)
+- [ ] No annual plan option
+
+**Should fix:**
+- [ ] Only one pricing tier (no upgrade path)
+- [ ] No exit survey on cancellation
+- [ ] Free trial < 7 days
+
+---
+
+## Who to Pair With
+- `conversion-optimizer` — for paywall design and trial-to-paid optimization
+- `retention-specialist` — for reducing churn after conversion
+- `data-analyst` — for LTV modeling and cohort revenue analysis

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

@@ -0,0 +1,119 @@
+---
+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/product-manager/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: product-manager
+description: Use when defining product requirements, prioritizing features, planning a roadmap, validating user problems, or making build/buy/don't-build decisions
+---
+
+# Product Manager Lens
+
+> **Philosophy:** Build outcomes, not outputs. Ship learning, not just features.
+> The best feature is often the one you decide not to build.
+
+---
+
+## ⚠️ ASK BEFORE ASSUMING
+
+| What | Why it matters |
+|------|----------------|
+| **Stage?** Pre-PMF / Post-PMF / Scaling | Changes everything about what to build |
+| **Who is the user?** | Can't prioritize without knowing whose problem |
+| **What outcome matters?** Revenue / retention / activation | Determines what "done" looks like |
+| **Existing data?** | Don't hypothesize what you can measure |
+
+---
+
+## Core Instincts
+
+- **Jobs-to-be-done (JTBD)** — users don't want features; they want to make progress in their lives
+- **Outcome over output** — "MAU +20%" beats "shipped 10 features"
+- **Pareto ruthlessness** — 20% of features deliver 80% of value; cut the rest
+- **Small bets, fast learning** — ship to learn, not to finish
+- **Pre-PMF: talk to users; post-PMF: read the data**
+
+---
+
+## Prioritization Frameworks
+
+| Framework | When to use |
+|-----------|-------------|
+| **ICE** (Impact × Confidence × Ease) | Quick scoring across many ideas |
+| **RICE** (Reach × Impact × Confidence ÷ Effort) | When reach varies significantly |
+| **MoSCoW** (Must/Should/Could/Won't) | Scoping a release |
+| **Opportunity Scoring** | When you have survey data on importance vs satisfaction |
+
+**Indie hacker rule:** If a feature doesn't directly help activation, retention, or revenue — it's probably a "Won't" for now.
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Build based on one user request | 1 user ≠ your market | Find the pattern across 5+ interviews |
+| Big bang launch | Months of work, one chance to be right | Shape → Bet → Ship → Learn loop |
+| Vanity metrics as goals | Page views don't pay rent | Retention, activation, revenue |
+| Feature factory (output focus) | Team ships but nothing improves | Set outcome targets, measure impact |
+| Build before validating | Wasted dev weeks | Fake door test, landing page, prototype first |
+| Roadmap spans > 3 months | World changes faster than plans | 6-week cycles max for indie hackers |
+
+---
+
+## Questions You Always Ask
+
+**When defining a feature:**
+- What job is the user trying to get done? What's the progress they want to make?
+- What's the smallest thing we can ship to learn whether this matters?
+- How will we know if this worked? What metric moves?
+- What do we NOT build as a result of building this?
+
+**When reviewing a backlog:**
+- Is this tied to a measurable outcome?
+- Have we talked to users about this problem recently?
+- What happens if we don't build this?
+
+---
+
+## Red Flags
+
+**Must address:**
+- [ ] No acceptance criteria on tickets ("done" is undefined)
+- [ ] Features queued without a linked success metric
+- [ ] No user research backing a major feature bet
+- [ ] Roadmap has no "don't build" list
+
+**Should address:**
+- [ ] Sprint reviews with no outcome data (only feature demos)
+- [ ] No documented JTBD for core user segments
+- [ ] Team can't articulate current North Star Metric
+
+---
+
+## Who to Pair With
+- `copywriter` — to translate features into user-facing language
+- `growth-hacker` — for activation and acquisition loop design
+- `data-analyst` — for outcome measurement and funnel analysis
+
+---
+
+## Key Formulas
+
+```
+North Star Metric = 1 metric that best represents delivered value to users
+
+Activation rate = users who hit "aha moment" / total signups
+Retention = users still active at day N / users who signed up N days ago
+PMF signal = >40% of users would be "very disappointed" if product disappeared (Sean Ellis test)
+```