kai-email-system

name

kai-email-system

description

Plan and batch-produce an entire email system for a product. Maps every lifecycle touchpoint (onboarding, activation, conversion, retention, transactional, win-back), generates all emails with quality gates, outputs Loops-ready copy. Use when "create all emails", "email system", "build email sequences", "lifecycle emails", "onboarding sequence", "set up transactional emails", "plan all the emails for [product]", or any request to systematically produce a complete set of emails for a platform.

Build a complete email system for a product — from lifecycle mapping through batch production with quality gates. All emails target Loops (lifecycle + transactional).

Phase 0: Load Product Context (ALL /kai skills start here)

Check if MARKETING.md exists in the project root (same directory as CLAUDE.md, README.md, package.json).

If it exists: Read it. This is the product bible — it has everything you need. Skip to Phase 2.

If it does NOT exist: Auto-explore to create it. Do NOT ask the user what the product is. Discover it:

1. Read CLAUDE.md, README.md, PROJECT.md, package.json, any project description files in the project root and additional working directories
2. Search for existing email templates, Loops config, or email-related code (grep for "loops", "resend", "email", "transactional")
3. Read landing pages, marketing copy, or product descriptions to understand the value prop
4. Check for user flows, auth systems, billing integrations, database schemas, API routes
5. Look at existing content, social profiles, or marketing materials

Then create MARKETING.md in the project root (next to CLAUDE.md) with this structure:

# MARKETING.md — Product Marketing Bible

> Auto-generated by Kai CMO Harness. Updated [date]. Edit freely — all /kai skills read this.

## Product
- **Name:** [product name]
- **One-liner:** [what it does in one sentence]
- **Category:** [what category it competes in]
- **URL:** [main website]

## ICP (Ideal Customer Profile)

### Primary ICP
- **Title/Role:** [job title or role]
- **Company size:** [employee count / revenue range]
- **Industry:** [verticals]
- **Budget authority:** [yes/no, approval process]
- **Trigger event:** [what makes them start looking for a solution NOW]
- **Current solution:** [what they use today, including "nothing" or manual process]
- **Pain severity:** [1-10 how badly this hurts them]

### Secondary ICP (if applicable)
- **Title/Role:** [different buyer type]
- [same fields as above]

### Anti-ICP (who is NOT a fit)
- [Description of who to avoid targeting and why]

## Personas

Map to the closest harness personas from `knowledge/personas/_persona-index.md`, then customize for this product:

### Persona 1: [Name] — based on [harness persona name]
- **Who they are:** [1-2 sentences]
- **Core frustration:** [the thing that keeps them up at night]
- **Language they use:** [actual phrases, jargon, complaints — pull from reviews, forums, support tickets]
- **Objections:** [top 3 reasons they'd say no]
- **Decision trigger:** [what makes them finally act]
- **Channels they trust:** [where they get information]

### Persona 2: [Name] — based on [harness persona name]
- [same structure]

### User Segments (product-level)
- [Segment 1]: [description — e.g. "Admin who sets up the account"]
- [Segment 2]: [description — e.g. "Team member who uses daily"]

## Value Prop
- **Core transformation:** [what changes for the user — before vs after]
- **Key actions:** [3-5 things users do in the product]
- **Activation moment:** [when users first get value]
- **Aha moment:** [the specific action that predicts retention]

## Business Model
- **Monetization:** [free tier, trial, paid plans — what triggers upgrade]
- **Pricing:** [price points if known]
- **Stage:** [pre-launch / early / growth / scale + MRR if known]

## Current Marketing
- **Channels active:** [SEO, email, ads, social, etc.]
- **Email platform:** [Loops, Resend, etc.]
- **Ad platforms:** [Meta, Google, etc.]
- **Social:** [which platforms, handles]
- **Content:** [blog, newsletter, podcast, etc.]

## Brand Voice
- **Tone:** [professional, casual, bold, technical, etc.]
- **Banned patterns:** [anything off-brand]
- **Examples:** [1-2 example sentences in the right voice]

## Competitive Landscape
- **Top 3 competitors:** [names]
- **Our differentiation:** [what makes us different]

## Key Metrics (if known)
- **Traffic:** [monthly visitors]
- **Conversion rate:** [signup/purchase rate]
- **Email list size:** [subscriber count]
- **MRR/ARR:** [revenue]

Fill in what you can discover. Leave unknowns as [unknown — ask user]. Present the draft to the user for confirmation before saving.

---

Phase 2: Lifecycle Map

Read MARKETING.md for product context. Generate a complete email map organized by stage. Output as a markdown table in workspace/email-system-map.md.

Standard B2B SaaS Stages

Stage	Trigger Type	Emails
Welcome	Transactional	Welcome + getting started
Onboarding	Behavioral	Setup incomplete, first value moment, invite team
Activation	Behavioral	Feature discovery, usage milestone
Conversion	Time + behavioral	Trial expiring (T-3, T-1, T-0), upgrade prompt
Engagement	Behavioral + scheduled	Weekly digest, new feature announcement
Retention	Behavioral	Usage drop, re-engagement, churn risk
Win-back	Time-based	Churned user sequence (D+7, D+14, D+30)
Transactional	Event-driven	Password reset, invoice, plan change, security alert
Referral	Milestone	Referral ask after value moment

Adapt this map to the actual product. Remove irrelevant stages, add product-specific ones.

For each email in the map, specify:

• Email name (becomes the Loops template name)
• Trigger (Loops event name, e.g. user.signed_up, trial.expiring_3d)
• Stage (lifecycle stage)
• Priority (P0 = launch blocker, P1 = week 1, P2 = month 1)
• Segment (which users receive this)

Approval Gate

Present the email map to the user. Get approval before producing any emails. Ask:

• "Anything missing?"
• "Any emails you definitely don't need?"
• "Which priority tier should I produce first?"

Phase 3: Batch Production

Produce emails in priority order (P0 first). For each email:

3a. Load Context

Read these harness files before writing:

• knowledge/channels/email-lifecycle.md — lifecycle patterns, subject line formulas, anti-patterns
• harness/skill-contracts/email-lifecycle.yaml — quality gates and output format
• harness/skill-contracts/email.yaml — general email contract

For cold outreach emails, also load:

• harness/skill-contracts/cold-email.yaml
• harness/references/cold-email-rules.md

3b. Write Each Email

Use the brand voice from MARKETING.md. Output format per email (matches Loops template structure):

# [Email Name]

**Trigger:** `event.name` (Loops event)
**Segment:** [who receives this]
**Stage:** [lifecycle stage]
**Send timing:** [immediate | delay | time-of-day preference]

## Subject Line
Primary: [subject]
Variant A: [subject]
Variant B: [subject]

## Preview Text
[40-90 chars shown before open]

## Body
[Email body in markdown — 200-500 words max]

## CTA
[Single primary CTA — text and destination]

## Quality Gate Results
- Four U's: [score]/16 (min 10)
- Banned words: [PASS/FAIL]
- Subject length: [chars]/50
- Preview text length: [chars]/90
- Word count: [count]/500
- Single CTA: [PASS/FAIL]

3c. Quality Gates (per email)

Run these checks. Every email must pass ALL gates:

1. Four U's score >= 10/16 — Score each U (Unique, Useful, Ultra-specific, Urgent) 1-4
2. Zero banned words (Tier 1: leverage, utilize, synergy, innovative, deep dive, circle back, touch base, moving forward, at the end of the day)
3. Zero AI slop ("In conclusion", "It's important to note", "In today's rapidly evolving", "This comprehensive guide", "Without further ado", "It's worth noting that")
4. Subject line <= 50 chars (mobile truncation)
5. Preview text 40-90 chars
6. Body <= 500 words
7. Single primary CTA (one action per email)
8. First line not generic (no "I hope this email finds you well")

If an email fails: fix the specific issue and re-check. Max 2 retries per email. After 2 failures, flag it and move to the next.

3d. Batch Output

Write all produced emails to workspace/emails/[stage]/[email-name].md.

workspace/emails/
├── _email-system-map.md          # The full lifecycle map
├── welcome/
│   └── welcome-getting-started.md
├── onboarding/
│   ├── setup-incomplete.md
│   ├── first-value-moment.md
│   └── invite-team.md
├── conversion/
│   ├── trial-expiring-3d.md
│   ├── trial-expiring-1d.md
│   └── trial-expired-grace.md
├── retention/
│   ├── usage-drop.md
│   └── re-engagement.md
├── transactional/
│   ├── password-reset.md
│   ├── invoice.md
│   └── plan-change.md
└── _quality-report.md            # Gate results for all emails

Phase 4: Quality Report

After all emails are produced, generate workspace/emails/_quality-report.md:

# Email System Quality Report

## Summary
- Total emails: [N]
- Passed all gates: [N]
- Failed (flagged for human review): [N]
- Average Four U's score: [X]/16

## Per-Email Results
| Email | Stage | Four U's | Banned | Slop | Subject | CTA | Status |
|-------|-------|----------|--------|------|---------|-----|--------|
| ...   | ...   | .../16   | PASS   | PASS | XX/50   | PASS| PASS   |

## Flagged for Review
[List any emails that failed after 2 retries with specific failure reasons]

Phase 5: Loops Implementation Notes

After producing all emails, generate workspace/emails/_loops-setup.md with:

1. Events to create in Loops — list every trigger event name
2. Segments/groups needed — user segments referenced by emails
3. Sequence flows — which emails chain together (onboarding sequence, trial expiration sequence, win-back sequence) with delays between them
4. Transactional vs marketing — which emails are transactional (no unsubscribe needed) vs marketing (require unsubscribe)

Parallelization

When producing emails, use parallel agents for independent emails. Emails within the same sequence should be written sequentially (tone must flow). Emails in different stages can be written in parallel.

Persona Application

If MARKETING.md specifies a persona, load the full persona file from knowledge/personas/ and match email tone to the persona's language patterns and pain points. If no persona applies, use the brand voice from MARKETING.md.