agy-superpowers 5.0.6 → 5.0.8

package/template/agent/skills/backend-developer/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: backend-developer
+description: Use when designing APIs, working on server-side logic, database schemas, or reviewing backend code — regardless of stack
+---
+
+# Backend Developer Lens
+
+> **Philosophy:** Design for contracts, failure modes, and observability.
+> If you can't observe it failing, you can't fix it. If you can't roll it back, don't ship it.
+
+---
+
+## ⚠️ ASK BEFORE ASSUMING
+
+If the stack is unspecified, **DO NOT default to Express + MongoDB**. Ask:
+
+| What | Why it matters |
+|------|----------------|
+| **Language/framework?** Node / Python / Go / etc. | Determines idioms and patterns |
+| **Database?** SQL / NoSQL / in-memory | Shapes the entire data model |
+| **Auth model?** JWT / session / API key / OAuth | Must be decided before the first endpoint |
+| **Deployment?** Container / serverless / VM | Affects scaling, connection pooling |
+| **Existing API contract?** | Determines versioning constraints |
+
+When stack is unspecified, assume Node.js + PostgreSQL + REST.
+
+---
+
+## Core Instincts
+
+- **API contracts are public** — breaking changes require versioning; consumers break silently
+- **N+1 is always lurking** — query patterns that work in dev collapse at scale
+- **Fail loudly in dev, gracefully in prod** — errors must be observable; silent failures are unacceptable
+- **Auth is load-bearing** — authentication and authorization must be in the design from the start
+- **Schema changes are permanent** — migrations must be backward-compatible; rollback path required
+
+---
+
+## Performance & Scale Thresholds
+
+| Metric | Target | Investigate |
+|--------|--------|-------------|
+| API response time (p99) | < 500ms | > 1s |
+| Database query time (p99) | < 100ms | > 500ms |
+| DB connection pool size | CPU cores × 2–4 | > 100 (connection thrash) |
+| Max payload size (JSON) | < 1MB | > 5MB → stream or paginate |
+| Background job retry limit | 3–5 retries | Unbounded = infinite loops |
+| Rate limit (public API) | 60–100 req/min per IP | Application-specific |
+| Pagination page size | 20–100 items | > 500 → server load + slow clients |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Database queries in a loop | N+1 = catastrophic at scale | Batch query with `IN (...)`, JOIN, or eager load |
+| Silent `catch {}` blocks | Failures invisible, impossible to debug | Log with context (req ID, user ID), re-throw or return structured error |
+| Secrets in source code | Leaked via git, logs, stack traces | `process.env` + secret manager (Vault, AWS Secrets Manager) |
+| No input validation | Injection, crashes, bad data in DB | Validate at the API boundary (Zod, Joi, Pydantic, etc.) |
+| No rate limiting on public endpoints | Trivially abused, DDoS surface | Rate limit per IP + per user at gateway or middleware |
+| Schema migration without rollback | One bad deploy = DB emergency | Always write `up` AND `down` migration |
+| Breaking API change without versioning | Consumers silently break in prod | `/v2/` prefix + deprecation headers + sunset date |
+| Business logic in controllers | Untestable, duplicated across routes | Service layer for all business rules |
+| Unbounded queries | Full table scan in prod at 10M rows | Always paginate: `LIMIT` + `OFFSET` or cursor-based |
+| Storing plaintext passwords | One breach = all accounts compromised | `bcrypt` (cost ≥ 12) or `argon2id` |
+
+---
+
+## HTTP Status Code Reference
+
+| Situation | Status | Notes |
+|-----------|--------|-------|
+| Success, returns data | 200 | |
+| Created resource | 201 | Include `Location` header |
+| Success, no body | 204 | |
+| Permanent redirect | 301 | Browser caches; use with care |
+| Temporary redirect | 302 | Common for auth flows |
+| Bad input from client | 400 | Include field-level validation errors |
+| Missing / invalid auth token | 401 | Trigger re-auth on client |
+| Valid auth, no permission | 403 | Do NOT reveal resource existence |
+| Resource not found | 404 | |
+| Method not allowed | 405 | Include `Allow` header |
+| Duplicate or state conflict | 409 | Idempotency conflicts, duplicate key |
+| Business rule violation | 422 | Structurally valid, semantically wrong |
+| Rate limit exceeded | 429 | Include `Retry-After` header |
+| Our fault (unhandled error) | 500 | Log full context; return safe message |
+| Upstream service down | 502 / 503 | |
+
+---
+
+## Auth Quick Rules
+
+| Concern | Rule |
+|---------|------|
+| JWT expiry | Access token: 15 min–1h. Refresh token: 7–30 days |
+| JWT secret rotation | Rotate on breach; support multiple valid secrets during rotation |
+| Password hashing | `bcrypt` with cost factor ≥ 12, or `argon2id` |
+| API keys | Store as SHA-256 hash; show plaintext only once on creation |
+| Session cookies | `HttpOnly`, `Secure`, `SameSite=Strict` or `Lax` |
+| OAuth PKCE | Required for all public clients (SPAs, mobile apps) |
+
+---
+
+## Questions You Always Ask
+
+**When designing APIs:**
+- What's the auth model? Who can call this and how?
+- What happens if a downstream service is unavailable?
+- How does this behave at 10x current load?
+- What gets logged when this fails in production?
+
+**When reviewing database work:**
+- Is this query indexed? What does `EXPLAIN ANALYZE` show at scale?
+- Does this migration have a safe rollback path?
+- Are we handling concurrent writes correctly (race conditions, optimistic locking)?
+- Will this schema change break existing clients before the code deploy?
+
+---
+
+## Red Flags in Code Review
+
+**Must fix:**
+- [ ] Missing input validation or sanitization
+- [ ] Silent `catch` blocks (errors swallowed without logging)
+- [ ] N+1 queries (fetching inside loops)
+- [ ] Secrets or credentials in source code or logs
+- [ ] Plaintext password storage
+
+**Should fix:**
+- [ ] No rate limiting on public-facing endpoints
+- [ ] Schema migrations without a rollback (`down`) strategy
+- [ ] Auth logic duplicated across controllers (not centralized in middleware)
+- [ ] Unstructured error responses (no error code, no field references)
+- [ ] Unbounded queries without pagination
+
+---
+
+## Async Pattern Selection
+
+| Pattern | Use when |
+|---------|----------|
+| `async/await` | Sequential operations with dependencies |
+| `Promise.all()` | Parallel independent operations (all must succeed) |
+| `Promise.allSettled()` | Parallel where some can fail independently |
+| Message queue (BullMQ, SQS) | Fire-and-forget, retry logic, spike buffering |
+| Cron / scheduler | Periodic background jobs |
+| Streaming | Large payloads, real-time updates, long-running responses |

package/template/agent/skills/brainstorming/SKILL.md

@@ -114,7 +114,9 @@ digraph brainstorming {
 - Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
   - (User preferences for spec location override this default)
 - Use elements-of-style:writing-clearly-and-concisely skill if available
-- Commit the design document to git
+- **Commit the design document to git** — but first check `.agent/config.yml`:
+    - If `auto_commit: true` (default): run `git add <path> && git commit -m "docs: add <topic> design spec"`
+    - If `auto_commit: false`: skip commit and staging entirely. Print: "Skipping commit (auto_commit: false in .agent/config.yml). File is ready for manual commit."
 
 **Spec Review Loop:**
 After writing the spec document:

package/template/agent/skills/community-manager/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: community-manager
+description: Use when building and managing communities on Discord, Reddit, Slack, or social platforms — including moderation, engagement strategy, and community-led growth
+---
+
+# Community Manager Lens
+
+> **Philosophy:** Communities are built on belonging, not broadcasting. The best communities make members feel seen, not sold to.
+> A thriving community is retention infrastructure — users who belong don't churn.
+
+---
+
+## Core Instincts
+
+- **Give before you take** — provide value for months before asking for anything
+- **10× rule** — for every self-promotional post, create 10 pieces of pure value
+- **Lurkers are members too** — 90% of community members never post; they still get value and stay
+- **Rules enable culture** — clear community guidelines protect the vibe early; retrofit is painful
+- **First 100 members make or break the culture** — seed with high-quality people
+
+---
+
+## Community Growth Stages
+
+| Stage | Size | Focus |
+|-------|------|-------|
+| **Seeding** | 0–50 | Hand-recruit ideal members; personal invitations only |
+| **Nurturing** | 50–500 | Daily engagement, create rituals, establish culture |
+| **Scaling** | 500–5K | Empower moderators, create sub-channels, systematize onboarding |
+| **Sustaining** | 5K+ | Ambassador programs, community-led content, governance |
+
+---
+
+## Platform Comparison
+
+| Platform | Best for | Retention | Discovery |
+|----------|----------|-----------|-----------|
+| **Discord** | Real-time, developer tools, games | High | Low (invite-only) |
+| **Reddit** | SEO, async discussion, niche topics | Medium | High (searchable) |
+| **Slack** | B2B SaaS, professional communities | Medium | Low |
+| **Circle / Mighty Networks** | Paid communities, courses | High | Low |
+| **X (Twitter)** | Thought leadership, broad reach | Low | High |
+
+---
+
+## Engagement Health Metrics
+
+| Metric | Below avg | Average | Healthy |
+|--------|-----------|---------|---------|
+| Monthly active members / total | < 5% | 10–20% | > 25% |
+| Post-to-member ratio (monthly) | < 0.5 | 1–3 | > 5 |
+| Average replies per thread | < 1 | 2–4 | > 5 |
+| Moderation actions / posts | > 20% | 5–10% | < 3% |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Launch with 0 content | Ghost town = no one stays | Pre-seed with 10–20 threads before inviting |
+| Broadcast-only (announcements, no discussion) | Feels like a newsletter, not a community | Invite discussion; ask questions more than announce |
+| No moderation in first week | Bad actors set the culture early | Establish rules + remove violators immediately |
+| Ignore members' questions | Signals you don't care | Respond to every post in first 3 months |
+| Open community too early | Wrong early members = culture damage | Curated waitlist; invite manually first 50–100 |
+| Over-channel too early | Channel sprawl kills activity | Start with 3–5 channels; add only when needed |
+
+---
+
+## Questions You Always Ask
+
+**When launching a community:**
+- Who are the ideal first 10 members? Can I personally invite them?
+- What's the community promise — why should someone join AND stay?
+- What weekly ritual will drive recurring engagement? (Show & Tell, Feedback Friday, etc.)
+- What are the 3 non-negotiable community rules?
+
+**When diagnosing a declining community:**
+- What's the monthly active rate? (< 10% = engagement problem)
+- When was the last "member-initiated" post (not admin-started)?
+- What do lapsed members say when you reach out directly?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] Community active rate < 5% (mostly lurkers with no engagement)
+- [ ] Only admins posting — no member-initiated discussions
+- [ ] No community guidelines posted or enforced
+- [ ] Questions from members going unanswered > 24 hours
+
+**Should fix:**
+- [ ] No onboarding flow for new members (first experience = blank discord)
+- [ ] No weekly recurring engagement ritual
+- [ ] > 20 channels with similar topics (channel sprawl)
+
+---
+
+## Who to Pair With
+- `retention-specialist` — community is a retention channel
+- `content-marketer` — for content seeding and distribution within community
+- `growth-hacker` — for community-led referral and viral loops
+
+---
+
+## Community Onboarding Template
+
+```
+New member joins →
+1. Auto-welcome message with 3 things to do first
+2. Introduce yourself thread (pinned)
+3. Highlight 3 best threads from last month
+4. Personal DM from founder/moderator within 48h
+```

package/template/agent/skills/content-marketer/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: content-marketer
+description: Use when planning content strategy, SEO content, social media, email newsletters, or building an audience-driven growth channel
+---
+
+# Content Marketer Lens
+
+> **Philosophy:** Distribution > creation. A great post no one reads is a wasted asset.
+> Build an audience once; it compounds. Ad spend stops the moment you stop paying.
+
+---
+
+## Core Instincts
+
+- **Audience-first** — write for a specific person with a specific problem, not "everyone"
+- **Distribution is 80% of the work** — repurpose and distribute before writing something new
+- **SEO content compounds; social content decays** — prioritize search-indexed content for long-term ROI
+- **Consistency beats brilliance** — publishing schedule > single viral posts
+- **Content-market fit** — content that your audience shares is content aligned with their identity
+
+---
+
+## Content Funnel (TOFU / MOFU / BOFU)
+
+| Stage | Goal | Content Types |
+|-------|------|--------------|
+| **ToFU** (Top of Funnel) | Awareness | Blog posts, social threads, short videos, podcasts |
+| **MoFU** (Middle of Funnel) | Consideration | Case studies, comparison pages, email sequences, webinars |
+| **BoFU** (Bottom of Funnel) | Conversion | Landing pages, testimonials, free trial CTAs, pricing explainers |
+
+**Indie hacker allocation:** 60% ToFU (audience building), 30% MoFU (nurture), 10% BoFU (convert).
+
+---
+
+## Distribution Channels (Ranked by Compounding ROI)
+
+| Channel | Compounding? | Time to results | Best for |
+|---------|-------------|----------------|----------|
+| SEO blog | ✅ High | 3–12 months | B2B SaaS, tools |
+| Email newsletter | ✅ Medium | 1–6 months | Direct relationship, loyalty |
+| YouTube | ✅ Medium | 6–18 months | Tutorial/educational products |
+| Twitter/X threads | ❌ Low | Days | Brand building, distribution boosts |
+| Reddit / Hacker News | ❌ Low | Hours | Launch spikes, community credibility |
+| TikTok / Reels | ❌ Low | Days | Consumer apps, B2C |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Write content without SEO research | Invisible to search, no compounding | Keyword research first |
+| Post on all platforms simultaneously | Mediocre everywhere | Own 1–2 channels deeply |
+| Copy competitor content strategy | Different audience, different context | Find your unique POV |
+| Create content without repurposing plan | 1x effort, 1x reach | 1 blog → 5 tweets → 1 email → 1 short video |
+| No call to action | Content without conversion intent | Every piece has one next step |
+| Publish once, never promote | Content ROI is mostly in distribution | Promote each piece for 30 days post-publish |
+
+---
+
+## Content Benchmarks
+
+| Metric | Good | Great |
+|--------|------|-------|
+| Email open rate | > 25% | > 40% |
+| Email CTR | > 3% | > 8% |
+| Blog organic traffic growth (MoM) | > 10% | > 25% |
+| Social follower-to-click rate | > 1% | > 3% |
+| Newsletter subscriber monthly growth | > 5% | > 15% |
+
+---
+
+## Questions You Always Ask
+
+**When planning content:**
+- Who specifically is reading this? What's their pain, and what's their next question?
+- What's the keyword or search intent behind this piece? (Even for social content: what would someone search to find this?)
+- How will we distribute this after publishing?
+- What's the one action we want the reader to take?
+
+**When auditing a content strategy:**
+- What % of content is indexed by search (long-term asset) vs ephemeral?
+- Is there a consistent publishing schedule? (Consistency signals authority)
+- What's the email list growth rate? (Email = owned audience)
+
+---
+
+## Red Flags
+
+**Must address:**
+- [ ] No keyword research behind blog content
+- [ ] No email list / owned audience being built
+- [ ] Team creates content but has no distribution plan
+- [ ] Publishing inconsistently (< 2 posts/month)
+
+**Should address:**
+- [ ] No repurposing workflow (each piece used only once)
+- [ ] No content calendar (reactive publishing)
+- [ ] No measurement of content-attributed signups
+
+---
+
+## Who to Pair With
+- `seo-specialist` — for keyword strategy and technical SEO
+- `copywriter` — for copy quality and audience resonance
+- `data-analyst` — for content attribution and funnel tracking
+
+---
+
+## Tools
+Beehiiv · Substack · ConvertKit (email) · Ahrefs · Semrush (keyword research) · Buffer · Typefully (social scheduling) · Notion / Airtable (content calendar)

package/template/agent/skills/conversion-optimizer/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: conversion-optimizer
+description: Use when optimizing landing pages, trial-to-paid funnels, paywall design, onboarding flows, or running CRO experiments
+---
+
+# Conversion Optimizer Lens
+
+> **Philosophy:** Conversion is about removing friction and increasing trust simultaneously.
+> Every unnecessary step, field, or decision is a drop in conversion rate.
+
+---
+
+## Core Instincts
+
+- **Remove friction before adding persuasion** — simplify the path before optimizing copy
+- **Trust before conversion** — social proof, testimonials, and guarantees reduce purchase anxiety
+- **One page, one goal** — landing pages with multiple CTAs convert less than focused ones
+- **Mobile conversion is different** — form fields on mobile cost 20–30% more friction than desktop
+- **Test, don't guess** — opinions on what will convert are unreliable; data is not
+
+---
+
+## Landing Page Above-the-Fold Formula
+
+```
+┌─────────────────────────────────────┐
+│  NAV: Logo | Pricing | Log in       │
+├─────────────────────────────────────┤
+│  HEADLINE: Clear benefit in <8 words│
+│  SUBHEADLINE: Who it's for + how    │
+│  CTA: [Single action button]        │
+│  SOCIAL PROOF: X users / logos /    │
+│               star rating           │
+├─────────────────────────────────────┤
+│  HERO IMAGE / VIDEO / SCREENSHOT    │
+└─────────────────────────────────────┘
+```
+
+**Required above-the-fold:** Headline + CTA + 1 trust signal. Everything else is below.
+
+---
+
+## Conversion Benchmarks
+
+| Funnel Stage | Poor | Average | Good | Great |
+|-------------|------|---------|------|-------|
+| Visitor → Sign up | < 1% | 2–4% | 5–8% | > 10% |
+| Sign up → Activated | < 20% | 30–50% | 50–70% | > 75% |
+| Trial → Paid | < 5% | 8–15% | 15–25% | > 30% |
+| Paid → Annual (upsell) | < 20% | 25–35% | 35–50% | > 55% |
+| App Store impression → Install | < 2% | 3–5% | 6–8% | > 10% |
+
+---
+
+## A/B Testing Rules
+
+| Rule | Detail |
+|------|--------|
+| **One variable per test** | Headline OR CTA OR layout — never multiple |
+| **Minimum sample size** | ≥ 1,000 visitors per variant before reading results |
+| **Statistical significance** | ≥ 95% confidence (p < 0.05) before declaring winner |
+| **Test duration** | Minimum 2 weeks (captures weekly seasonality) |
+| **Business significance** | > 5% lift is actionable; < 2% is noise regardless of p-value |
+
+---
+
+## Paywall Design Principles
+
+- **Show upgrade prompt after activation event** — not before, not on open
+- **Anchor with annual** — show annual price first, monthly as secondary
+- **Offer 3 options max** — choice paralysis above 3 tiers
+- **Include a free trial CTA** — "Try free for 14 days" converts higher than "Subscribe now"
+- **Social proof on paywall** — "Join 12,000 users" or star rating
+- **Money-back guarantee** — even 7-day guarantee increases conversion 10–20%
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Multiple CTAs on one page | Users don't know what to do | One primary CTA per page/section |
+| Long sign-up form (> 3 fields) | Each field costs ~10% conversion | Minimum viable info: email only or SSO |
+| No social proof | Users don't trust new products | Number of users, testimonials, press logos |
+| Generic CTA ("Get Started") | No benefit communicated | Benefit-first CTA ("Start saving 2h/week") |
+| Testing without hypothesis | Unfalsifiable, results misinterpreted | Write hypothesis before running test |
+| Reading results too early | False positives from underpowered tests | Wait for 1000+ per variant + 2 weeks |
+| Paywall on first open (mobile) | Users haven't experienced value | Trigger after Nth use or activation event |
+
+---
+
+## Onboarding Flow Optimization
+
+| Principle | Detail |
+|-----------|--------|
+| **Aha moment ASAP** | Every onboarding step that doesn't lead toward aha moment is a churn risk |
+| **Progressive disclosure** | Show only what's needed for the current step |
+| **No walls** | Avoid mandatory email verification before first experience |
+| **Personalization prompt** | 1 question to customize experience dramatically improves activation |
+| **Empty state = opportunity** | Show what the product looks like full, not an empty blank slate |
+
+---
+
+## Questions You Always Ask
+
+**When auditing a landing page:**
+- Does the headline communicate the primary benefit in < 8 words?
+- Is there exactly one primary CTA?
+- Is there social proof visible above the fold?
+- What's the current visitor → signup conversion rate? (Benchmark: 3–8%)
+
+**When auditing a funnel:**
+- Where is the biggest drop-off in the funnel?
+- Has this been A/B tested, or is it based on opinion?
+- Is the paywall appearing before or after the activation event?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] Conversion rate tracking not set up (can't optimize what you can't measure)
+- [ ] Landing page has more than 2 CTAs
+- [ ] No social proof on landing page or paywall
+- [ ] Paywall shown before activation event
+
+**Should fix:**
+- [ ] Sign-up form has > 3 fields
+- [ ] No A/B testing tooling in place
+- [ ] No exit-intent capture on pricing page
+
+---
+
+## Who to Pair With
+- `copywriter` — for headline and CTA copy
+- `monetization-strategist` — for paywall and pricing strategy
+- `data-analyst` — for funnel analysis and test significance
+
+---
+
+## Tools
+Statsig · Optimizely · VWO (A/B testing) · Hotjar · Microsoft Clarity (session recording) · PostHog · Google Optimize (deprecated — use Statsig/VWO instead)

package/template/agent/skills/copywriter/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: copywriter
+description: Use when writing landing page copy, app store descriptions, onboarding flows, email sequences, push notifications, or any user-facing text
+---
+
+# Copywriter Lens
+
+> **Philosophy:** Clarity over cleverness. Benefits over features. The reader first, always.
+> Good copy makes the right people say "this is for me" and the wrong people self-select out.
+
+---
+
+## Core Instincts
+
+- **Benefits, not features** — "Save 2 hours/week" beats "Automated scheduling"
+- **One job per piece of copy** — headlines inform or intrigue, CTAs convert; never both
+- **Specificity builds trust** — "used by 12,000 developers" > "used by thousands"
+- **Above the fold is everything** — users decide in <5 seconds; earn the scroll
+- **The reader's self-interest is the only interest** — they don't care about you; they care about their problem
+
+---
+
+## Copywriting Frameworks
+
+### AIDA (Attention → Interest → Desire → Action)
+Best for: landing pages, email sequences, long-form ads
+
+### PAS (Problem → Agitate → Solution)
+Best for: short form ads, push notifications, homepage heroes
+
+### JTBD Framing: "When I [situation], I want to [motivation], so I can [outcome]"
+Best for: writing copy that resonates with a specific user segment
+
+### The 4 U's (Urgent · Unique · Ultra-specific · Useful)
+Best for: headlines, subject lines, CTAs
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Lead with features | Users care about their outcome, not your tech | Lead with the transformation/benefit |
+| Vague superlatives ("best", "amazing") | Zero credibility, no information | Specific proof ("ranked #1 by AppFollow") |
+| Weak CTA ("click here", "submit") | No reason to act | Action + benefit ("Start saving time") |
+| Passive voice | Weak, distant | Active voice, direct |
+| Jargon and acronyms | Confuses, excludes | Plain language at 8th grade reading level |
+| Wall of text | No one reads it | Short paragraphs, bullets, scannable |
+| First open asks for email | Friction before value | Show value first, gate later |
+
+---
+
+## App Store Copy Rules
+
+**iOS App Store:**
+- Title: ≤ 30 characters (including keyword)
+- Subtitle: ≤ 30 characters (keyword-rich, benefit-focused)
+- Keywords field: ≤ 100 characters, comma-separated, no spaces, no words from title
+- Description: first 255 characters shown before "more" — make them count
+- Promo text: ≤ 170 characters, update without resubmission (use for limited offers)
+
+**Google Play:**
+- Title: ≤ 30 characters
+- Short description: ≤ 80 characters (shown in search results)
+- Long description: ≤ 4000 characters (first 167 chars most important)
+- Repeat primary keyword 3–5× naturally in long description
+
+---
+
+## Questions You Always Ask
+
+**Before writing anything:**
+- Who is the primary reader? What do they already believe about their problem?
+- What's the ONE thing I want them to feel/do after reading this?
+- What objection will they have, and does the copy address it?
+- What social proof can be made specific? (numbers, names, credentials)
+
+**When reviewing copy:**
+- Does the headline communicate the main benefit in <8 words?
+- Is there a clear, single CTA?
+- Does any sentence start with "We" or "Our"? (Rewrite to focus on reader)
+- Can a 12-year-old understand this?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] Headline doesn't communicate a clear benefit or hook
+- [ ] CTA is vague ("Learn more", "Get started")
+- [ ] No social proof (testimonials, user counts, ratings)
+- [ ] Copy leads with company/product, not user's problem
+
+**Should fix:**
+- [ ] Paragraphs longer than 3 lines
+- [ ] Features listed without framing as benefits
+- [ ] No urgency or specific reason to act now
+
+---
+
+## Who to Pair With
+- `app-store-optimizer` — for ASO-specific copy strategy
+- `conversion-optimizer` — for landing page and paywall copy testing
+- `product-manager` — for understanding JTBD before writing
+
+---
+
+## Email Benchmarks (SaaS / Indie)
+
+| Metric | Good | Great |
+|--------|------|-------|
+| Open rate | > 25% | > 40% |
+| Click-through rate | > 3% | > 8% |
+| Unsubscribe rate | < 0.5% | < 0.2% |