@ivannxbt/ai-config 0.1.0

package/.agents/skills/email-best-practices/tests/scenarios/01-spam-deliverability.md

@@ -0,0 +1,46 @@
+# Scenario 1: Emails Going to Spam
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"My transactional emails (password resets, order confirmations) are going to spam in Gmail. What do I do to fix this?"
+
+Answer with specific, actionable steps. Include exact DNS records, commands to verify, and threshold numbers where relevant.
+
+Format your response as a numbered action plan.
+```
+
+## Expected Correctness Criteria
+
+The agent MUST include these skill-specific details:
+
+### Authentication (deliverability.md)
+- [ ] SPF record example: `v=spf1 include:amazonses.com ~all`
+- [ ] DKIM: provider supplies the record
+- [ ] DMARC: `v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com`
+- [ ] DMARC rollout: `p=none` → `p=quarantine; pct=25` → `p=reject`
+- [ ] Verification commands: `dig TXT yourdomain.com +short`, `dig TXT resend._domainkey.yourdomain.com +short`, `dig TXT _dmarc.yourdomain.com +short`
+
+### Thresholds (deliverability.md)
+- [ ] Bounce targets: <1% good, 1-3% acceptable, 3-4% concerning, >4% critical
+- [ ] Complaint targets: <0.01% excellent, 0.01-0.05% good, >0.05% critical
+
+### IP Warming (deliverability.md)
+- [ ] Week 1: 50-100/day
+- [ ] Week 2: 200-500/day
+- [ ] Week 3: 1,000-2,000/day
+- [ ] Week 4: 5,000-10,000/day
+
+### Infrastructure (deliverability.md)
+- [ ] Dedicated subdomains: `t.yourdomain.com` (transactional), `m.yourdomain.com` (marketing)
+- [ ] DNS TTL: 300s during setup, 3600s+ after stable
+
+### Troubleshooting order (deliverability.md)
+- [ ] Check in order: 1. Authentication, 2. List-Unsubscribe header, 3. Reputation, 4. Content, 5. Sending patterns
+
+### Diagnostic tools (deliverability.md)
+- [ ] Google Postmaster Tools
+- [ ] mail-tester.com
+- [ ] MXToolbox blacklist check

package/.agents/skills/email-best-practices/tests/scenarios/02-multi-region-compliance.md

@@ -0,0 +1,48 @@
+# Scenario 2: Multi-Region Email Compliance
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"I'm building an email newsletter for my SaaS product. I have users in the US, EU, and Canada. What legal requirements do I need to follow? Give me a comparison table of requirements by region and the specific implementation steps."
+
+Be specific about penalty amounts, timing requirements for unsubscribe processing, and consent record requirements.
+```
+
+## Expected Correctness Criteria
+
+### Penalties (compliance.md)
+- [ ] CAN-SPAM: $53k/email
+- [ ] GDPR: EUR 20M or 4% revenue
+- [ ] CASL: $1M (individual) to $10M (organization) CAD
+
+### Consent types (compliance.md)
+- [ ] CAN-SPAM: opt-out model (can send without opt-in)
+- [ ] GDPR: explicit opt-in (no pre-checked boxes)
+- [ ] CASL express: explicit opt-in
+- [ ] CASL implied: existing relationship (2 years) or inquiry (6 months)
+
+### Unsubscribe timing (compliance.md)
+- [ ] CAN-SPAM: 10 business days, must work 30 days after send
+- [ ] GDPR: immediately, as easy as opting in
+- [ ] CASL: 10 business days, must work 60 days after send
+
+### CASL specifics (compliance.md)
+- [ ] Sender identification valid 60 days after send
+- [ ] Keep consent records 3 years after expiration
+
+### Consent records (compliance.md)
+- [ ] Record: email, date/time, method, what consented to, source
+
+### International sending (compliance.md)
+- [ ] Best practice: follow GDPR (most restrictive) for all regions
+
+### Managing preferences vs unsubscribe (compliance.md)
+- [ ] One-click unsubscribe required; preference management is nice-to-have, doesn't replace unsubscribe
+
+### List-Unsubscribe header (compliance.md)
+- [ ] Required by Gmail/Yahoo since Feb 2024
+- [ ] Headers: `List-Unsubscribe` URL + `List-Unsubscribe-Post: List-Unsubscribe=One-Click`
+- [ ] Endpoint: POST returns 200/202, GET shows unsubscribe page
+- [ ] Stop sending within 48 hours

package/.agents/skills/email-best-practices/tests/scenarios/03-retry-idempotency.md

@@ -0,0 +1,36 @@
+# Scenario 3: Retry Logic + Idempotency
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"I'm using the Resend API to send transactional emails. I need to implement retry logic with idempotency to prevent duplicate sends. Show me a TypeScript implementation with idempotency keys, exponential backoff, and proper error code handling."
+
+Include specific HTTP error codes and which ones to retry vs not retry, idempotency key generation strategies, and backoff timing.
+```
+
+## Expected Correctness Criteria
+
+### Idempotency keys (sending-reliability.md)
+- [ ] Event-based key example: `order-confirm-${orderId}` (recommended)
+- [ ] Request-scoped example: `reset-${userId}-${resetRequestId}`
+- [ ] UUID fallback: `crypto.randomUUID()` — generate once, reuse on retry
+- [ ] Warns against `Date.now()` or random values generated fresh on each attempt
+- [ ] Key expiration: 24 hours — complete retry logic within this window
+
+### Error codes (sending-reliability.md)
+- [ ] Retry: 5xx (server error), 429 (rate limit), network timeout, DNS failure
+- [ ] Do NOT retry: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 422 (validation)
+
+### Backoff (sending-reliability.md)
+- [ ] Exponential: 1s -> 2s -> 4s -> 8s
+- [ ] Cap at 30 seconds
+- [ ] Jitter to prevent thundering herd
+- [ ] Max retries: 3
+
+### Timeout (sending-reliability.md)
+- [ ] AbortController pattern with 10-30 second timeout
+
+### Queuing (sending-reliability.md)
+- [ ] Queue pattern for critical emails: write pending -> attempt send -> mark sent/schedule retry -> mark failed + alert

package/.agents/skills/email-best-practices/tests/scenarios/04-webhook-bounce-handling.md

@@ -0,0 +1,52 @@
+# Scenario 4: Webhook Bounce/Complaint Handling
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"I need to set up Resend webhooks to handle bounces and complaints. Show me how to implement this with signature verification using svix, idempotent event processing, and proper bounce/complaint handling (when to suppress, when to retry). Include TypeScript code."
+
+Be specific about: svix verification headers, hard vs soft bounce handling thresholds, and complaint handling requirements.
+```
+
+## Expected Correctness Criteria
+
+### Webhook setup (webhooks-events.md)
+- [ ] Endpoint must return 2xx within 5 seconds
+- [ ] Return 200 immediately, process asynchronously
+
+### Svix verification (webhooks-events.md)
+- [ ] Import from 'svix'
+- [ ] Headers: `svix-id`, `svix-timestamp`, `svix-signature`
+- [ ] Verify before processing, return 400 on invalid signature
+
+### Idempotent processing (webhooks-events.md)
+- [ ] Use event ID to deduplicate
+- [ ] Check if already processed before handling
+- [ ] Mark as processed after handling
+
+### Event types (webhooks-events.md)
+- [ ] `email.sent`, `email.delivered`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`
+
+### Bounce handling (webhooks-events.md + list-management.md)
+- [ ] Hard bounce: suppress immediately, remove from all lists
+- [ ] Soft bounce: track count, suppress after 3 failures
+- [ ] Suppression entry schema includes: email, reason, created_at, source_email_id
+
+### Complaint handling (webhooks-events.md + list-management.md)
+- [ ] Immediate suppression — no exceptions
+- [ ] Remove from all lists
+- [ ] Log for analysis
+
+### Suppression unsuppress rules (list-management.md)
+- [ ] Hard bounce: cannot unsuppress (address invalid)
+- [ ] Complaint: cannot unsuppress (legal requirement)
+- [ ] Soft bounce (3x): can unsuppress after 30-90 days
+- [ ] Manual removal: only if user requests
+
+### Pre-send check (list-management.md)
+- [ ] Always check suppression before sending
+
+### Retry behavior (webhooks-events.md)
+- [ ] Non-2xx triggers retries: ~30s -> ~1min -> ~5min (continues ~24 hours)

package/.agents/skills/email-best-practices/tests/scenarios/05-new-saas-email-plan.md

@@ -0,0 +1,51 @@
+# Scenario 5: New SaaS Email Infrastructure Plan
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"I'm building a new SaaS app and need to plan my entire email infrastructure. I need to know: (1) what types of transactional emails I should plan for, (2) how to set up DNS authentication, (3) how to warm up my sending domain, (4) how to handle bounces/complaints in production, and (5) what compliance requirements I need for international users. Give me a comprehensive implementation roadmap."
+
+Be specific about: IP warming schedules (daily volumes by week), bounce rate thresholds, complaint rate thresholds, DNS record formats, and legal requirements by region.
+```
+
+## Expected Correctness Criteria
+
+### Email planning (transactional-email-catalog.md)
+- [ ] References the transactional email catalog for SaaS planning
+- [ ] Covers at minimum: verification, password reset, OTP/2FA, security alerts, billing
+
+### DNS authentication (deliverability.md)
+- [ ] SPF, DKIM, DMARC records with examples
+- [ ] DMARC rollout strategy (none -> quarantine; pct=25 -> reject)
+- [ ] Dedicated subdomains for transactional vs marketing
+
+### Warming (deliverability.md)
+- [ ] Correct weekly schedule: 50-100 / 200-500 / 1k-2k / 5k-10k
+- [ ] Start with engaged users, send consistently
+
+### Bounce/complaint handling (deliverability.md + list-management.md + webhooks-events.md)
+- [ ] Bounce thresholds: <1% good, >4% critical
+- [ ] Complaint thresholds: <0.01% excellent, >0.05% critical
+- [ ] Hard bounce: immediate suppression
+- [ ] Soft bounce: suppress after 3 failures
+- [ ] Complaint: immediate suppression
+- [ ] Pre-send suppression check
+
+### Compliance (compliance.md)
+- [ ] Covers CAN-SPAM, GDPR, CASL
+- [ ] Correct penalty amounts
+- [ ] Correct unsubscribe timing by region
+- [ ] Recommends GDPR as global standard
+
+### Data retention (list-management.md)
+- [ ] Send attempts: 90 days
+- [ ] Bounce/complaint events: 3 years
+- [ ] Suppression list: indefinite
+- [ ] Email content: 30 days
+- [ ] Consent records: 3 years after expiry
+
+### Cross-resource synthesis
+- [ ] Agent references multiple resource files (not just one)
+- [ ] "Start Here" routing from SKILL.md is followed

package/.agents/skills/email-sequence/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: email-sequence
+description: When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," or "lifecycle emails." For in-app onboarding, see onboarding-cro.
+metadata:
+  version: 1.1.0
+---
+
+# Email Sequence Design
+
+You are an expert in email marketing and automation. Your goal is to create email sequences that nurture relationships, drive action, and move people toward conversion.
+
+## Initial Assessment
+
+**Check for product marketing context first:**
+If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Before creating a sequence, understand:
+
+1. **Sequence Type**
+   - Welcome/onboarding sequence
+   - Lead nurture sequence
+   - Re-engagement sequence
+   - Post-purchase sequence
+   - Event-based sequence
+   - Educational sequence
+   - Sales sequence
+
+2. **Audience Context**
+   - Who are they?
+   - What triggered them into this sequence?
+   - What do they already know/believe?
+   - What's their current relationship with you?
+
+3. **Goals**
+   - Primary conversion goal
+   - Relationship-building goals
+   - Segmentation goals
+   - What defines success?
+
+---
+
+## Core Principles
+
+### 1. One Email, One Job
+- Each email has one primary purpose
+- One main CTA per email
+- Don't try to do everything
+
+### 2. Value Before Ask
+- Lead with usefulness
+- Build trust through content
+- Earn the right to sell
+
+### 3. Relevance Over Volume
+- Fewer, better emails win
+- Segment for relevance
+- Quality > frequency
+
+### 4. Clear Path Forward
+- Every email moves them somewhere
+- Links should do something useful
+- Make next steps obvious
+
+---
+
+## Email Sequence Strategy
+
+### Sequence Length
+- Welcome: 3-7 emails
+- Lead nurture: 5-10 emails
+- Onboarding: 5-10 emails
+- Re-engagement: 3-5 emails
+
+Depends on:
+- Sales cycle length
+- Product complexity
+- Relationship stage
+
+### Timing/Delays
+- Welcome email: Immediately
+- Early sequence: 1-2 days apart
+- Nurture: 2-4 days apart
+- Long-term: Weekly or bi-weekly
+
+Consider:
+- B2B: Avoid weekends
+- B2C: Test weekends
+- Time zones: Send at local time
+
+### Subject Line Strategy
+- Clear > Clever
+- Specific > Vague
+- Benefit or curiosity-driven
+- 40-60 characters ideal
+- Test emoji (they're polarizing)
+
+**Patterns that work:**
+- Question: "Still struggling with X?"
+- How-to: "How to [achieve outcome] in [timeframe]"
+- Number: "3 ways to [benefit]"
+- Direct: "[First name], your [thing] is ready"
+- Story tease: "The mistake I made with [topic]"
+
+### Preview Text
+- Extends the subject line
+- ~90-140 characters
+- Don't repeat subject line
+- Complete the thought or add intrigue
+
+---
+
+## Sequence Types Overview
+
+### Welcome Sequence (Post-Signup)
+**Length**: 5-7 emails over 12-14 days
+**Goal**: Activate, build trust, convert
+
+Key emails:
+1. Welcome + deliver promised value (immediate)
+2. Quick win (day 1-2)
+3. Story/Why (day 3-4)
+4. Social proof (day 5-6)
+5. Overcome objection (day 7-8)
+6. Core feature highlight (day 9-11)
+7. Conversion (day 12-14)
+
+### Lead Nurture Sequence (Pre-Sale)
+**Length**: 6-8 emails over 2-3 weeks
+**Goal**: Build trust, demonstrate expertise, convert
+
+Key emails:
+1. Deliver lead magnet + intro (immediate)
+2. Expand on topic (day 2-3)
+3. Problem deep-dive (day 4-5)
+4. Solution framework (day 6-8)
+5. Case study (day 9-11)
+6. Differentiation (day 12-14)
+7. Objection handler (day 15-18)
+8. Direct offer (day 19-21)
+
+### Re-Engagement Sequence
+**Length**: 3-4 emails over 2 weeks
+**Trigger**: 30-60 days of inactivity
+**Goal**: Win back or clean list
+
+Key emails:
+1. Check-in (genuine concern)
+2. Value reminder (what's new)
+3. Incentive (special offer)
+4. Last chance (stay or unsubscribe)
+
+### Onboarding Sequence (Product Users)
+**Length**: 5-7 emails over 14 days
+**Goal**: Activate, drive to aha moment, upgrade
+**Note**: Coordinate with in-app onboarding—email supports, doesn't duplicate
+
+Key emails:
+1. Welcome + first step (immediate)
+2. Getting started help (day 1)
+3. Feature highlight (day 2-3)
+4. Success story (day 4-5)
+5. Check-in (day 7)
+6. Advanced tip (day 10-12)
+7. Upgrade/expand (day 14+)
+
+**For detailed templates**: See [references/sequence-templates.md](references/sequence-templates.md)
+
+---
+
+## Email Types by Category
+
+### Onboarding Emails
+- New users series
+- New customers series
+- Key onboarding step reminders
+- New user invites
+
+### Retention Emails
+- Upgrade to paid
+- Upgrade to higher plan
+- Ask for review
+- Proactive support offers
+- Product usage reports
+- NPS survey
+- Referral program
+
+### Billing Emails
+- Switch to annual
+- Failed payment recovery
+- Cancellation survey
+- Upcoming renewal reminders
+
+### Usage Emails
+- Daily/weekly/monthly summaries
+- Key event notifications
+- Milestone celebrations
+
+### Win-Back Emails
+- Expired trials
+- Cancelled customers
+
+### Campaign Emails
+- Monthly roundup / newsletter
+- Seasonal promotions
+- Product updates
+- Industry news roundup
+- Pricing updates
+
+**For detailed email type reference**: See [references/email-types.md](references/email-types.md)
+
+---
+
+## Email Copy Guidelines
+
+### Structure
+1. **Hook**: First line grabs attention
+2. **Context**: Why this matters to them
+3. **Value**: The useful content
+4. **CTA**: What to do next
+5. **Sign-off**: Human, warm close
+
+### Formatting
+- Short paragraphs (1-3 sentences)
+- White space between sections
+- Bullet points for scanability
+- Bold for emphasis (sparingly)
+- Mobile-first (most read on phone)
+
+### Tone
+- Conversational, not formal
+- First-person (I/we) and second-person (you)
+- Active voice
+- Read it out loud—does it sound human?
+
+### Length
+- 50-125 words for transactional
+- 150-300 words for educational
+- 300-500 words for story-driven
+
+### CTA Guidelines
+- Buttons for primary actions
+- Links for secondary actions
+- One clear primary CTA per email
+- Button text: Action + outcome
+
+**For detailed copy, personalization, and testing guidelines**: See [references/copy-guidelines.md](references/copy-guidelines.md)
+
+---
+
+## Output Format
+
+### Sequence Overview
+```
+Sequence Name: [Name]
+Trigger: [What starts the sequence]
+Goal: [Primary conversion goal]
+Length: [Number of emails]
+Timing: [Delay between emails]
+Exit Conditions: [When they leave the sequence]
+```
+
+### For Each Email
+```
+Email [#]: [Name/Purpose]
+Send: [Timing]
+Subject: [Subject line]
+Preview: [Preview text]
+Body: [Full copy]
+CTA: [Button text] → [Link destination]
+Segment/Conditions: [If applicable]
+```
+
+### Metrics Plan
+What to measure and benchmarks
+
+---
+
+## Task-Specific Questions
+
+1. What triggers entry to this sequence?
+2. What's the primary goal/conversion action?
+3. What do they already know about you?
+4. What other emails are they receiving?
+5. What's your current email performance?
+
+---
+
+## Tool Integrations
+
+For implementation, see the [tools registry](../../tools/REGISTRY.md). Key email tools:
+
+| Tool | Best For | MCP | Guide |
+|------|----------|:---:|-------|
+| **Customer.io** | Behavior-based automation | - | [customer-io.md](../../tools/integrations/customer-io.md) |
+| **Mailchimp** | SMB email marketing | ✓ | [mailchimp.md](../../tools/integrations/mailchimp.md) |
+| **Resend** | Developer-friendly transactional | ✓ | [resend.md](../../tools/integrations/resend.md) |
+| **SendGrid** | Transactional email at scale | - | [sendgrid.md](../../tools/integrations/sendgrid.md) |
+| **Kit** | Creator/newsletter focused | - | [kit.md](../../tools/integrations/kit.md) |
+
+---
+
+## Related Skills
+
+- **churn-prevention**: For cancel flows, save offers, and dunning strategy (email supports this)
+- **onboarding-cro**: For in-app onboarding (email supports this)
+- **copywriting**: For landing pages emails link to
+- **ab-test-setup**: For testing email elements
+- **popup-cro**: For email capture popups
+- **revops**: For lifecycle stages that trigger email sequences

package/.agents/skills/email-sequence/references/copy-guidelines.md

@@ -0,0 +1,113 @@
+# Email Copy Guidelines
+
+## Contents
+- Structure
+- Formatting
+- Tone
+- Length
+- CTA Buttons vs. Links
+- Personalization (merge fields, dynamic content, triggered emails)
+- Segmentation Strategies (by behavior, by stage, by profile)
+- Testing and Optimization (what to test, how to test, metrics to track)
+
+## Structure
+
+1. **Hook**: First line grabs attention
+2. **Context**: Why this matters to them
+3. **Value**: The useful content
+4. **CTA**: What to do next
+5. **Sign-off**: Human, warm close
+
+## Formatting
+
+- Short paragraphs (1-3 sentences)
+- White space between sections
+- Bullet points for scanability
+- Bold for emphasis (sparingly)
+- Mobile-first (most read on phone)
+
+## Tone
+
+- Conversational, not formal
+- First-person (I/we) and second-person (you)
+- Active voice
+- Match your brand but lean friendly
+- Read it out loud—does it sound human?
+
+## Length
+
+- Shorter is usually better
+- 50-125 words for transactional
+- 150-300 words for educational
+- 300-500 words for story-driven
+- If it's long, it better be good
+
+## CTA Buttons vs. Links
+
+- Buttons: Primary actions, high-visibility
+- Links: Secondary actions, in-text
+- One clear primary CTA per email
+- Button text: Action + outcome
+
+---
+
+## Personalization
+
+### Merge Fields
+- First name (fallback to "there" or "friend")
+- Company name (B2B)
+- Relevant data (usage, plan, etc.)
+
+### Dynamic Content
+- Based on segment
+- Based on behavior
+- Based on stage
+
+### Triggered Emails
+- Action-based sends
+- More relevant than time-based
+- Examples: Feature used, milestone hit, inactivity
+
+---
+
+## Segmentation Strategies
+
+### By Behavior
+- Openers vs. non-openers
+- Clickers vs. non-clickers
+- Active vs. inactive
+
+### By Stage
+- Trial vs. paid
+- New vs. long-term
+- Engaged vs. at-risk
+
+### By Profile
+- Industry/role (B2B)
+- Use case / goal
+- Company size
+
+---
+
+## Testing and Optimization
+
+### What to Test
+- Subject lines (highest impact)
+- Send times
+- Email length
+- CTA placement and copy
+- Personalization level
+- Sequence timing
+
+### How to Test
+- A/B test one variable at a time
+- Sufficient sample size
+- Statistical significance
+- Document learnings
+
+### Metrics to Track
+- Open rate (benchmark: 20-40%)
+- Click rate (benchmark: 2-5%)
+- Unsubscribe rate (keep under 0.5%)
+- Conversion rate (specific to sequence goal)
+- Revenue per email (if applicable)