mango-lollipop 0.1.0

package/lib/schema.ts

@@ -0,0 +1,394 @@
+// =============================================================================
+// Mango Lollipop — TypeScript Schema & Validation
+// =============================================================================
+
+// -----------------------------------------------------------------------------
+// Type Aliases
+// -----------------------------------------------------------------------------
+
+export type Channel = "email" | "sms" | "in-app" | "push";
+
+export type AARRRStage = "AQ" | "AC" | "RV" | "RT" | "RF";
+
+// -----------------------------------------------------------------------------
+// Core Message Interfaces
+// -----------------------------------------------------------------------------
+
+export interface Trigger {
+  event: string;
+  type: "event" | "scheduled" | "behavioral";
+  schedule?: string;
+}
+
+export interface Guard {
+  condition: string;
+  expression: string;
+}
+
+export interface Suppression {
+  condition: string;
+  expression: string;
+}
+
+export interface CTA {
+  text: string;
+  url?: string;
+}
+
+export interface Message {
+  id: string;
+  stage: AARRRStage | "TX";
+  name: string;
+  classification: "transactional" | "lifecycle";
+  trigger: Trigger;
+  wait: string;
+  guards: Guard[];
+  suppressions: Suppression[];
+  subject: string;
+  preheader?: string;
+  body: string;
+  cta: CTA;
+  channel: Channel;
+  format: "plain" | "rich";
+  from: string;
+  segment: string;
+  tags: string[];
+  goal: string;
+  comments: string;
+}
+
+// -----------------------------------------------------------------------------
+// Voice & Persona Interfaces
+// -----------------------------------------------------------------------------
+
+export interface SenderPersona {
+  name: string;
+  role: string;
+  use_for: string[];
+}
+
+export interface VoiceProfile {
+  tone: string;
+  formality: number; // 1-5
+  emoji_usage: "none" | "light" | "heavy";
+  signature_style: string;
+  sample_phrases: string[];
+  sender_personas: SenderPersona[];
+}
+
+// -----------------------------------------------------------------------------
+// Event Taxonomy
+// -----------------------------------------------------------------------------
+
+export interface EventTaxonomy {
+  identity: string[];
+  activation: string[];
+  engagement: string[];
+  conversion: string[];
+  retention: string[];
+}
+
+// -----------------------------------------------------------------------------
+// Analysis (analysis.json output from the analyze skill)
+// -----------------------------------------------------------------------------
+
+export interface AnalysisCompany {
+  name: string;
+  product_type: string;
+  target_audience: string;
+  key_value_prop: string;
+  aha_moment: string;
+  key_features: string[];
+  pricing_model: string;
+}
+
+export interface AnalysisTags {
+  sources: string[];
+  plans: string[];
+  segments: string[];
+  features: string[];
+}
+
+export interface ExistingPerformance {
+  open_rate_avg: string;
+  click_rate_avg: string;
+  problem_areas: string[];
+}
+
+export interface ExistingMessaging {
+  messages_count: number;
+  stages_covered: (AARRRStage | "TX")[];
+  stages_missing: (AARRRStage | "TX")[];
+  channels_used: Channel[];
+  performance: ExistingPerformance;
+  primary_goal: string;
+  messages: unknown[];
+}
+
+export interface Analysis {
+  path: "fresh" | "existing";
+  company: AnalysisCompany;
+  channels: Channel[];
+  voice: VoiceProfile;
+  events: EventTaxonomy;
+  tags: AnalysisTags;
+  existing?: ExistingMessaging;
+  recommendations: string[];
+}
+
+// -----------------------------------------------------------------------------
+// Project Config (mango-lollipop.json)
+// -----------------------------------------------------------------------------
+
+export interface ProjectConfig {
+  name: string;
+  version: string;
+  created: string;
+  stage: string;
+  path: "fresh" | "existing" | null;
+  channels: Channel[];
+  analysis: Analysis | null;
+  matrix: { messages: Message[] } | null;
+}
+
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+
+const VALID_CHANNELS: Channel[] = ["email", "sms", "in-app", "push"];
+const VALID_STAGES: (AARRRStage | "TX")[] = ["AQ", "AC", "RV", "RT", "RF", "TX"];
+const VALID_AARRR_STAGES: AARRRStage[] = ["AQ", "AC", "RV", "RT", "RF"];
+
+// ISO 8601 duration pattern: P[nY][nM][nD][T[nH][nM][nS]] or PnW
+const ISO_8601_DURATION_RE =
+  /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$|^P(\d+)W$/;
+
+// -----------------------------------------------------------------------------
+// Type Guards
+// -----------------------------------------------------------------------------
+
+export function isValidChannel(ch: unknown): ch is Channel {
+  return typeof ch === "string" && VALID_CHANNELS.includes(ch as Channel);
+}
+
+export function isValidStage(stage: unknown): stage is AARRRStage {
+  return typeof stage === "string" && VALID_AARRR_STAGES.includes(stage as AARRRStage);
+}
+
+// -----------------------------------------------------------------------------
+// Validation Helpers
+// -----------------------------------------------------------------------------
+
+export function isValidWaitDuration(wait: unknown): boolean {
+  if (typeof wait !== "string") return false;
+  return ISO_8601_DURATION_RE.test(wait);
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+export function validateMessage(msg: unknown): ValidationResult {
+  const errors: string[] = [];
+
+  if (typeof msg !== "object" || msg === null) {
+    return { valid: false, errors: ["Message must be a non-null object"] };
+  }
+
+  const m = msg as Record<string, unknown>;
+
+  // Required string fields
+  const requiredStrings: [string, string][] = [
+    ["id", "id"],
+    ["name", "name"],
+    ["subject", "subject"],
+    ["body", "body"],
+    ["from", "from"],
+    ["segment", "segment"],
+    ["goal", "goal"],
+    ["wait", "wait"],
+  ];
+
+  for (const [field, label] of requiredStrings) {
+    if (typeof m[field] !== "string" || (m[field] as string).length === 0) {
+      errors.push(`Missing or empty required field: ${label}`);
+    }
+  }
+
+  // Stage
+  const validStagesAll = VALID_STAGES;
+  if (typeof m.stage !== "string" || !validStagesAll.includes(m.stage as AARRRStage | "TX")) {
+    errors.push(`Invalid stage: "${String(m.stage)}". Must be one of: ${validStagesAll.join(", ")}`);
+  }
+
+  // Classification
+  if (m.classification !== "transactional" && m.classification !== "lifecycle") {
+    errors.push(`Invalid classification: "${String(m.classification)}". Must be "transactional" or "lifecycle"`);
+  }
+
+  // Wait duration
+  if (typeof m.wait === "string" && !isValidWaitDuration(m.wait)) {
+    errors.push(`Invalid wait duration: "${m.wait}". Must be ISO 8601 duration (e.g. "P0D", "PT5M", "P2D")`);
+  }
+
+  // Format
+  if (m.format !== "plain" && m.format !== "rich") {
+    errors.push(`Invalid format: "${String(m.format)}". Must be "plain" or "rich"`);
+  }
+
+  // Channel (singular)
+  if (!isValidChannel(m.channel)) {
+    errors.push(`Invalid channel: "${String(m.channel)}". Must be one of: ${VALID_CHANNELS.join(", ")}`);
+  }
+
+  // Tags
+  if (!Array.isArray(m.tags)) {
+    errors.push("tags must be an array");
+  }
+
+  // Guards
+  if (!Array.isArray(m.guards)) {
+    errors.push("guards must be an array");
+  }
+
+  // Suppressions
+  if (!Array.isArray(m.suppressions)) {
+    errors.push("suppressions must be an array");
+  }
+
+  // Trigger
+  if (typeof m.trigger !== "object" || m.trigger === null) {
+    errors.push("trigger must be a non-null object");
+  } else {
+    const t = m.trigger as Record<string, unknown>;
+    if (typeof t.event !== "string" || t.event.length === 0) {
+      errors.push("trigger.event is required");
+    }
+    if (t.type !== "event" && t.type !== "scheduled" && t.type !== "behavioral") {
+      errors.push(`Invalid trigger.type: "${String(t.type)}". Must be "event", "scheduled", or "behavioral"`);
+    }
+  }
+
+  // CTA
+  if (typeof m.cta !== "object" || m.cta === null) {
+    errors.push("cta must be a non-null object");
+  } else {
+    const c = m.cta as Record<string, unknown>;
+    if (typeof c.text !== "string" || c.text.length === 0) {
+      errors.push("cta.text is required");
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function validateAnalysis(analysis: unknown): ValidationResult {
+  const errors: string[] = [];
+
+  if (typeof analysis !== "object" || analysis === null) {
+    return { valid: false, errors: ["Analysis must be a non-null object"] };
+  }
+
+  const a = analysis as Record<string, unknown>;
+
+  // Path
+  if (a.path !== "fresh" && a.path !== "existing") {
+    errors.push(`Invalid path: "${String(a.path)}". Must be "fresh" or "existing"`);
+  }
+
+  // Company
+  if (typeof a.company !== "object" || a.company === null) {
+    errors.push("company is required");
+  } else {
+    const c = a.company as Record<string, unknown>;
+    const companyFields = ["name", "product_type", "target_audience", "key_value_prop", "aha_moment", "pricing_model"];
+    for (const field of companyFields) {
+      if (typeof c[field] !== "string" || (c[field] as string).length === 0) {
+        errors.push(`Missing or empty company.${field}`);
+      }
+    }
+    if (!Array.isArray(c.key_features) || c.key_features.length === 0) {
+      errors.push("company.key_features must be a non-empty array");
+    }
+  }
+
+  // Channels
+  if (!Array.isArray(a.channels) || a.channels.length === 0) {
+    errors.push("Must have at least one channel");
+  } else {
+    for (const ch of a.channels) {
+      if (!isValidChannel(ch)) {
+        errors.push(`Invalid channel: "${String(ch)}". Must be one of: ${VALID_CHANNELS.join(", ")}`);
+      }
+    }
+  }
+
+  // Voice
+  if (typeof a.voice !== "object" || a.voice === null) {
+    errors.push("voice profile is required");
+  } else {
+    const v = a.voice as Record<string, unknown>;
+    if (typeof v.tone !== "string" || (v.tone as string).length === 0) {
+      errors.push("voice.tone is required");
+    }
+    if (typeof v.formality !== "number" || v.formality < 1 || v.formality > 5) {
+      errors.push("voice.formality must be a number between 1 and 5");
+    }
+    if (v.emoji_usage !== "none" && v.emoji_usage !== "light" && v.emoji_usage !== "heavy") {
+      errors.push(`Invalid voice.emoji_usage: "${String(v.emoji_usage)}". Must be "none", "light", or "heavy"`);
+    }
+    if (!Array.isArray(v.sample_phrases)) {
+      errors.push("voice.sample_phrases must be an array");
+    }
+    if (!Array.isArray(v.sender_personas)) {
+      errors.push("voice.sender_personas must be an array");
+    }
+  }
+
+  // Events
+  if (typeof a.events !== "object" || a.events === null) {
+    errors.push("events taxonomy is required");
+  } else {
+    const e = a.events as Record<string, unknown>;
+    const eventCategories = ["identity", "activation", "engagement", "conversion", "retention"];
+    for (const cat of eventCategories) {
+      if (!Array.isArray(e[cat])) {
+        errors.push(`events.${cat} must be an array`);
+      }
+    }
+  }
+
+  // Tags
+  if (typeof a.tags !== "object" || a.tags === null) {
+    errors.push("tags is required");
+  }
+
+  // Recommendations
+  if (!Array.isArray(a.recommendations)) {
+    errors.push("recommendations must be an array");
+  }
+
+  // PATH B: existing (only validated if path is "existing")
+  if (a.path === "existing") {
+    if (typeof a.existing !== "object" || a.existing === null) {
+      errors.push('existing messaging data is required when path is "existing"');
+    } else {
+      const ex = a.existing as Record<string, unknown>;
+      if (typeof ex.messages_count !== "number") {
+        errors.push("existing.messages_count must be a number");
+      }
+      if (!Array.isArray(ex.stages_covered)) {
+        errors.push("existing.stages_covered must be an array");
+      }
+      if (!Array.isArray(ex.stages_missing)) {
+        errors.push("existing.stages_missing must be an array");
+      }
+      if (typeof ex.primary_goal !== "string") {
+        errors.push("existing.primary_goal is required");
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "mango-lollipop",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "AI-powered lifecycle messaging generator for SaaS companies",
+  "license": "MIT",
+  "author": "Sasha Kai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sr-kai/mango-lollipop.git"
+  },
+  "keywords": [
+    "lifecycle-messaging",
+    "saas",
+    "aarrr",
+    "email-marketing",
+    "claude-code",
+    "ai"
+  ],
+  "bin": {
+    "mango-lollipop": "bin/mango-lollipop.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "skills/",
+    "templates/",
+    "lib/",
+    "CLAUDE.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "open": "^10.1.0",
+    "xlsx-js-style": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "typescript": "^5.7.3"
+  }
+}

package/skills/audit/SKILL.md

@@ -0,0 +1,248 @@
+# Audit Existing Lifecycle Messaging
+
+You are a lifecycle messaging auditor. Your job is to perform a deep analysis of a company's existing messaging system, score its maturity, identify gaps, and provide actionable recommendations for improvement.
+
+This skill can be used:
+- As part of PATH B onboarding (called from the `start` skill)
+- Standalone, to audit messaging at any time after initial setup
+- To re-audit after changes have been made via the `iterate` skill
+
+---
+
+## Step 1: Accept Input
+
+The user can provide their existing messages in any format. Accept all of the following:
+
+### Paste
+The user pastes message content directly into the conversation. This could be:
+- Full email bodies
+- Subject lines only
+- A list of message descriptions
+- Screenshots (describe what you see and ask for confirmation)
+
+### Upload
+The user provides a file:
+- Spreadsheet (CSV, XLSX) -- parse rows as messages
+- Document (PDF, DOCX, TXT) -- extract message descriptions
+- HTML files -- parse as email templates
+- JSON/YAML -- parse structured data
+
+### Natural Language Description
+The user describes their setup conversationally:
+- "We have a 5-email welcome series, a trial expiring email, and a weekly digest"
+- "We use Intercom for in-app messages and Mailchimp for email"
+- "We send about 12 emails total across the customer lifecycle"
+
+### Combination
+The user may provide a mix of the above. Aggregate all information.
+
+For each input, ask clarifying questions if needed:
+- "What channel is this message sent on?" (if not clear)
+- "When does this message get sent?" (if timing is unclear)
+- "Who receives this?" (if segment is unclear)
+
+---
+
+## Step 2: Normalize into Message Schema
+
+Convert whatever the user provided into the standard Message schema. For each message, extract or infer:
+
+| Field | Extract from input | Infer if missing |
+|-------|-------------------|------------------|
+| `id` | Assign sequentially (EX-01, EX-02, ...) | Always assign |
+| `stage` | Map to AARRR based on content/timing | Based on trigger and content |
+| `name` | Subject line or title | Generate from content |
+| `classification` | TX if transactional, lifecycle otherwise | Based on content type |
+| `trigger` | What event or timing initiates it | Infer from description |
+| `wait` | Delay after trigger | Default to P0D if unclear |
+| `guards` | Any conditions mentioned | Leave empty if unknown |
+| `suppressions` | Any skip conditions | Leave empty if unknown |
+| `channels` | Email, SMS, in-app, push | Ask if unclear |
+| `cta` | Button/link text | Extract from body |
+| `tags` | Any categorization | Suggest based on content |
+
+Present the normalized list back to the user: "Here's what I understood from your existing messages. Is this accurate?"
+
+---
+
+## Step 3: Analyze
+
+Perform a comprehensive analysis across these dimensions:
+
+### 3a. AARRR Stage Mapping
+Map each existing message to an AARRR stage. Identify:
+- Which stages have coverage
+- Which stages are completely missing
+- Which stages have partial coverage (some messages but gaps remain)
+
+### 3b. TX vs. Lifecycle Classification
+Classify each message:
+- **Transactional:** Email verification, password reset, receipts, alerts triggered by user action
+- **Lifecycle:** Welcome series, feature education, re-engagement, trial prompts, referral asks
+
+Flag any messages that are misclassified in the user's current system (e.g., marketing content sent as transactional).
+
+### 3c. Coverage Scoring (0-5 per stage)
+Score each AARRR stage on a 0-5 scale:
+
+| Score | Meaning |
+|-------|---------|
+| 0 | No messages for this stage |
+| 1 | 1 basic message, minimal effort |
+| 2 | 2-3 messages, covers basics but gaps remain |
+| 3 | Good coverage, most key scenarios handled |
+| 4 | Strong coverage with good timing and guards |
+| 5 | Excellent -- comprehensive, well-timed, multi-channel, with suppressions |
+
+### 3d. Channel Diversity
+- Are they using only email? Missing in-app, push, SMS opportunities?
+- For each message, is it on the right channel(s)?
+- Identify messages that would benefit from additional channels
+
+### 3e. Timing Analysis
+- Are messages well-spaced or clustered?
+- Are there long silent periods where no messages are sent?
+- Is the cadence too aggressive (e.g., daily emails for a week)?
+- Are wait durations appropriate for each stage?
+
+### 3f. Guard & Suppression Logic
+- Are they suppressing messages for users who already completed the desired action?
+- Are there guard conditions to prevent irrelevant sends?
+- Identify messages that should have guards/suppressions but don't
+
+### 3g. Voice Consistency
+- Is the tone consistent across all messages?
+- Are sender personas used appropriately?
+- Are there jarring tone shifts between messages?
+- Does the formality level match across stages?
+
+### 3h. CTA Clarity
+- Does every lifecycle message have a clear, specific CTA?
+- Are CTAs action-oriented (verb-first)?
+- Is there only one primary CTA per message?
+- Are CTAs relevant to the message's goal?
+
+### 3i. Personalization
+- Are personalization tokens used effectively?
+- Is there over-personalization (feels creepy) or under-personalization (feels generic)?
+- Are there opportunities for dynamic content based on user behavior?
+
+### 3j. Tag Opportunities
+- Suggest tags that could improve organization and filtering
+- Identify patterns that could benefit from tagging (by feature, plan, segment, etc.)
+
+---
+
+## Step 4: Score Overall Maturity (1-5)
+
+Calculate an overall maturity score:
+
+| Level | Name | Description |
+|-------|------|-------------|
+| 1 | **Basic** | Only transactional messages. No lifecycle strategy. |
+| 2 | **Developing** | Some lifecycle messages (welcome, maybe trial expiring). Big gaps in activation and retention. |
+| 3 | **Established** | Covers most AARRR stages. Reasonable timing. Some personalization. Missing advanced features (multi-channel, suppressions, tags). |
+| 4 | **Advanced** | Multi-channel, good suppression logic, personalized, well-timed. Minor gaps only. |
+| 5 | **Best-in-class** | Comprehensive coverage, multi-channel, excellent timing, smart suppressions, fully personalized, tagged and organized. |
+
+---
+
+## Step 5: Benchmark Performance (if data provided)
+
+If the user shared performance metrics (open rates, click rates, conversion rates, unsubscribe rates):
+
+### Industry Benchmarks (SaaS)
+| Metric | Poor | Average | Good | Excellent |
+|--------|------|---------|------|-----------|
+| Open Rate | < 15% | 15-25% | 25-35% | > 35% |
+| Click Rate | < 1.5% | 1.5-3% | 3-5% | > 5% |
+| Click-to-Open | < 8% | 8-12% | 12-18% | > 18% |
+| Unsubscribe | > 1% | 0.5-1% | 0.2-0.5% | < 0.2% |
+| Trial Conversion | < 5% | 5-10% | 10-20% | > 20% |
+
+Compare each message's metrics against these benchmarks. Flag underperformers.
+
+Correlate timing and content with performance:
+- Do messages with shorter wait times perform better or worse?
+- Do personalized subject lines outperform generic ones?
+- Which CTAs drive the highest click rates?
+
+---
+
+## Output
+
+Present the audit results in a structured report format:
+
+### 1. Maturity Scorecard
+
+```
+Overall Maturity: 2.5/5 -- Developing
+
+  Acquisition: [===------] 3/5 -- Welcome + verification present
+  Activation:  [=--------] 1/5 -- Only 1 feature email, big gap
+  Revenue:     [==-------] 2/5 -- Trial expiring exists, no in-app
+  Retention:   [---------] 0/5 -- No re-engagement messaging
+  Referral:    [---------] 0/5 -- No referral or invite prompts
+```
+
+### 2. Gap Analysis
+
+For each gap found, provide:
+- **Gap:** What's missing
+- **Impact:** Why it matters (e.g., "Users who don't discover Feature X in the first week are 3x more likely to churn")
+- **Priority:** Critical / High / Medium / Low
+- **Recommendation:** Specific action to take
+
+### 3. Priority Recommendations
+
+Ranked list of improvements, ordered by impact:
+1. Most impactful improvement first
+2. Quick wins early (low effort, high impact)
+3. Strategic investments later (high effort, high impact)
+
+For each recommendation:
+- What to do
+- Why it matters
+- Expected impact
+- Effort level (low/medium/high)
+
+### 4. Suggested New Messages
+
+For each gap, suggest specific messages to fill it:
+- Message name and ID
+- AARRR stage
+- Trigger and timing
+- Channel(s)
+- Brief description of content
+- Why this message is needed
+
+---
+
+## File Output
+
+If an `analysis.json` exists in the project directory, update it with audit results in the `existing` field.
+
+If running standalone (no existing project), write the audit results to `{project-directory}/audit-results.json` with this structure:
+
+```json
+{
+  "audit_date": "2025-01-15T10:30:00Z",
+  "maturity_score": 2.5,
+  "stage_scores": {
+    "AQ": 3,
+    "AC": 1,
+    "RV": 2,
+    "RT": 0,
+    "RF": 0
+  },
+  "existing_messages": [...],
+  "gaps": [...],
+  "recommendations": [...],
+  "suggested_messages": [...],
+  "performance_benchmarks": {...}
+}
+```
+
+After presenting the audit, ask: "Would you like me to generate a complete matrix that incorporates your existing messages and fills these gaps? I'll preserve what's working and improve what isn't."
+
+If yes, proceed to run the `generate-matrix` skill with the audit data.