mango-lollipop 0.1.0

package/skills/dev-handoff/SKILL.md

@@ -0,0 +1,295 @@
+# Generate Developer Hand-Off Documents
+
+You are a technical documentation specialist bridging the gap between lifecycle marketing and engineering. Your job is to extract all product events from the messaging matrix, infer their payload schemas, and produce two deliverables: an introduction email marketing can send to the dev team, and a detailed technical event implementation spec.
+
+## Input
+
+Read from the project output directory:
+1. **`analysis.json`** -- Company info, channels, voice profile, event taxonomy
+2. **`matrix.json`** -- All messages with triggers, guards, suppressions
+
+Locate the project output directory by checking the current working directory or `output/*/` subdirectories.
+
+---
+
+## Step 1: Extract Events
+
+Collect all unique events from two sources:
+
+### From `matrix.json`
+- Every `trigger.event` value across all messages
+- Note which messages reference each event as a trigger
+
+### From `analysis.json`
+- All events listed in `events.identity`, `events.activation`, `events.engagement`, `events.conversion`, `events.retention`
+- Some events may be defined in the taxonomy but not yet used by any message -- include them anyway
+
+Deduplicate and build a master event list.
+
+---
+
+## Step 2: Cross-Reference
+
+For each event, build a reference map:
+
+- **Triggered messages**: Which messages use this event as their `trigger.event`
+- **Guard references**: Which messages reference this event (or related attributes) in `guards[].expression`
+- **Suppression references**: Which messages reference this event (or related attributes) in `suppressions[].expression`
+
+---
+
+## Step 3: Assign Priority
+
+Assign a priority to each event based on its impact:
+
+| Priority | Criteria |
+|----------|----------|
+| **Critical** | Triggers 3 or more messages |
+| **High** | Triggers 2 messages |
+| **Medium** | Triggers 1 message |
+| **Low** | Referenced only in guards/suppressions, or defined in taxonomy but unused |
+
+---
+
+## Step 4: Categorize Events
+
+Group events into categories based on their name prefix:
+
+| Prefix | Category |
+|--------|----------|
+| `user.*` | Identity & Account |
+| `feature.*` | Feature Usage |
+| `onboarding.*` | Onboarding |
+| `trial.*` / `subscription.*` | Billing & Subscription |
+| `session.*` | Sessions |
+| `usage.*` | Usage & Limits |
+| `milestone.*` | Milestones |
+| `project.*` / `content.*` / `collaboration.*` | Product Activity |
+
+If an event doesn't match a known prefix, categorize it as "Custom".
+
+---
+
+## Step 5: Infer Payloads
+
+Since events are just strings, infer a reasonable property schema for each event. Every event includes base properties:
+
+```javascript
+{
+  user_id: "string",    // Always required
+  timestamp: "ISO 8601" // Always required
+}
+```
+
+Then add event-specific properties based on:
+
+1. **Event name pattern:**
+   - `user.*` events: add `email`, `plan`, `account_id`
+   - `feature.*` events: add `feature_name`, `session_id`
+   - `trial.*` events: add `plan`, `days_remaining`, `trial_start_date`
+   - `subscription.*` events: add `plan`, `amount`, `currency`, `billing_period`
+   - `onboarding.*` events: add `step_name`, `step_number`, `total_steps`
+   - `session.*` events: add `session_id`, `duration_seconds`
+   - `milestone.*` events: add `milestone_name`, `milestone_value`
+   - `usage.*` events: add `metric_name`, `current_value`, `limit_value`
+
+2. **Product context:** Use `analysis.company.key_features` and `analysis.company.product_type` to add domain-specific properties where relevant.
+
+3. **Guard/suppression expressions:** Parse all `expression` strings that reference this event's domain. If a guard checks `user.plan == 'free'`, the `user.*` events should include `plan`. If a suppression checks `feature.agenda_used == true`, feature events should include the relevant boolean.
+
+---
+
+## Step 6: Extract Profile Attributes
+
+Parse all `guards[].expression` and `suppressions[].expression` strings across all messages. Extract every user profile attribute that devs need to maintain in the user profile or event context.
+
+Examples:
+- `user.email_verified == true` → attribute: `user.email_verified` (boolean)
+- `user.plan == 'free'` → attribute: `user.plan` (string enum)
+- `feature.agenda_used == true` → attribute: `feature.agenda_used` (boolean)
+- `message.AC-02.sent_at < 24h_ago` → attribute: `message.AC-02.sent_at` (timestamp)
+
+Group these into:
+- **User attributes** (`user.*`)
+- **Feature flags** (`feature.*`)
+- **Message state** (`message.*`)
+
+---
+
+## Output A: Introduction Email (`dev-handoff-email.md`)
+
+Write a markdown email draft that marketing/product can send to the engineering team. Use the brand voice from `analysis.json` but adjust it for an internal engineering audience -- professional, direct, and respectful of dev time.
+
+### Email Structure
+
+```markdown
+**Subject:** [Project context] -- Event instrumentation for lifecycle messaging
+
+**From:** [Use a sender persona from analysis.voice.sender_personas, or default to "Product Team"]
+
+---
+
+Hey team,
+
+[1-2 sentence context: what this project is and why it matters]
+
+[1 sentence: what we need from engineering]
+
+### Scope
+
+- **[N] product events** need to be instrumented
+- **[N] are critical** (block 3+ messages each)
+- **[N] user profile attributes** need to be tracked
+- Events are organized into [N] categories: [list categories]
+
+### Top Priority Events
+
+[Table of Critical + High priority events with columns: Event | Category | Messages Blocked]
+
+### Suggested Implementation Phases
+
+**Phase 1 — Identity & Transactional (ship first)**
+[List the identity/account events -- these are needed for mandatory transactional messages]
+
+**Phase 2 — Activation Events**
+[List activation/feature events -- these power the onboarding sequence]
+
+**Phase 3 — Conversion & Retention**
+[List trial, subscription, and behavioral events]
+
+**Phase 4 — Growth & Analytics**
+[List remaining events: milestones, referral, usage]
+
+### Full Spec
+
+The complete technical spec with payload schemas, code examples, and implementation notes is in `event-spec.html`. Open it in any browser.
+
+[Friendly sign-off matching the brand voice]
+```
+
+Write to `{project-directory}/dev-handoff-email.md`.
+
+---
+
+## Output B: Technical Event Spec (`event-spec.html`)
+
+Create a single, self-contained HTML file. No build step required.
+
+### CDN Dependencies
+
+```html
+<script src="https://cdn.tailwindcss.com"></script>
+```
+
+### Page Structure
+
+#### 1. Header
+- Title: "Event Implementation Spec"
+- Company name from `analysis.json`
+- Generation date
+- Summary stats: N events, N categories, N dependent messages
+
+#### 2. Priority Overview Table
+
+A summary table with all events, sortable by priority:
+
+| Event | Category | Trigger Type | Messages Blocked | Priority |
+|-------|----------|-------------|-----------------|----------|
+
+Priority badges use color:
+- Critical: red
+- High: orange
+- Medium: blue
+- Low: gray
+
+#### 3. Per-Event Detail Sections
+
+For each event (grouped by category, ordered by priority within category):
+
+```
+┌─────────────────────────────────────────────────┐
+│ feature.agenda_used_first_time          CRITICAL │
+│ Category: Feature Usage                          │
+├─────────────────────────────────────────────────┤
+│ Description: [AI-inferred 1-2 sentence           │
+│   description of when this event fires]          │
+│                                                  │
+│ When to fire: [Clear instruction for devs,       │
+│   e.g., "Fire when a user creates their first    │
+│   agenda in any session"]                         │
+│                                                  │
+│ Properties:                                      │
+│ ┌──────────────┬────────┬──────────┬───────────┐ │
+│ │ Property     │ Type   │ Required │ Example   │ │
+│ ├──────────────┼────────┼──────────┼───────────┤ │
+│ │ user_id      │ string │ yes      │ "usr_123" │ │
+│ │ timestamp    │ string │ yes      │ ISO 8601  │ │
+│ │ feature_name │ string │ yes      │ "agenda"  │ │
+│ │ session_id   │ string │ no       │ "ses_456" │ │
+│ └──────────────┴────────┴──────────┴───────────┘ │
+│                                                  │
+│ Used by messages:                                │
+│   • AC-01: Master your agenda (trigger)          │
+│   • AC-03: Collaboration tips (suppression)      │
+│                                                  │
+│ Code example:                                    │
+│ ┌────────────────────────────────────────────┐   │
+│ │ analytics.track("feature.agenda_used_     │   │
+│ │   first_time", {                           │   │
+│ │   user_id: user.id,                        │   │
+│ │   timestamp: new Date().toISOString(),     │   │
+│ │   feature_name: "agenda",                  │   │
+│ │   session_id: session.id                   │   │
+│ │ });                                        │   │
+│ └────────────────────────────────────────────┘   │
+│                                                  │
+│ Implementation notes:                            │
+│   [Any special notes, e.g., "This is a           │
+│    one-time event -- only fire on the user's     │
+│    first use, not subsequent uses"]              │
+└─────────────────────────────────────────────────┘
+```
+
+#### Special handling:
+
+- **Behavioral events** (`user.inactive_*`): Add a note that these require a background job or scheduled task, not real-time instrumentation. Suggest a cron pattern (e.g., "Run daily at midnight, check last_active_at against threshold").
+- **Scheduled events** (trigger type `scheduled`): Include the schedule pattern from `trigger.schedule` and note that these need a job scheduler, not user-triggered instrumentation.
+
+#### 4. Profile Attributes Appendix
+
+A table of all user profile attributes extracted from guard/suppression expressions:
+
+| Attribute | Type | Used In | Description |
+|-----------|------|---------|-------------|
+| `user.email_verified` | boolean | AQ-01 guard, AC-01 guard | Whether the user has verified their email |
+| `user.plan` | string | RV-01 guard, RV-02 guard | Current subscription plan (free, trial, pro, enterprise) |
+| `feature.agenda_used` | boolean | AC-01 suppression | Whether the user has used the agenda feature |
+
+### Implementation Notes
+
+- All data is embedded as JSON in a `<script>` tag -- no external data files
+- Use vanilla JavaScript for interactivity (sorting, expand/collapse)
+- Make sure it works when opened directly from the filesystem (`file://` protocol)
+- Responsive layout
+- Dark/light mode: follow system preference with `prefers-color-scheme`
+- Code examples use a monospace font with syntax-appropriate styling
+- Add a "Copy" button on each code example block
+- Include the standard footer with repo link:
+  ```html
+  <footer>
+    <a href="https://github.com/sr-kai/mango-lollipop">Mango Lollipop</a> — AI-powered lifecycle messaging for SaaS<br>
+    Made by Sasha Kai with probably too much coffee.
+  </footer>
+  ```
+
+Write to `{project-directory}/event-spec.html`.
+
+---
+
+## Completion
+
+After generating both files:
+
+1. Tell the user: "Your developer hand-off documents are ready."
+2. Summarize: "[N] events extracted, [N critical / N high / N medium / N low]. The email draft is in `dev-handoff-email.md` and the full technical spec is in `event-spec.html`."
+3. Suggest: "Open `event-spec.html` in a browser to review the full spec. Edit `dev-handoff-email.md` to customize the email before sending it to your engineering team."

package/skills/generate-dashboard/SKILL.md

@@ -0,0 +1,195 @@
+# Generate Visual Deliverables
+
+You are a lifecycle messaging visualization specialist. Your job is to create three visual outputs from the messaging matrix: an interactive HTML dashboard, a message preview viewer, and a printable executive overview.
+
+## Input
+
+Read from the project output directory:
+1. **`analysis.json`** -- Company info, channels, voice profile
+2. **`matrix.json`** -- All messages with triggers, guards, suppressions, channels, tags
+3. **`messages/`** directory -- Individual message files (for preview content in dashboard)
+
+Locate the project output directory by checking the current working directory or `output/*/` subdirectories.
+
+---
+
+## Output A: Interactive Dashboard (`dashboard.html`)
+
+Create a single, self-contained HTML file. No build step, no external files needed beyond CDN resources.
+
+### CDN Dependencies
+
+```html
+<!-- Tailwind CSS for styling -->
+<script src="https://cdn.tailwindcss.com"></script>
+```
+
+### Dashboard Sections
+
+#### 1. Header
+- Project name from `analysis.json`
+- Company name
+- Generation date
+- Message count summary (e.g., "5 TX + 16 Lifecycle = 21 total")
+
+#### 2. TX / Lifecycle Toggle
+- Two-tab interface: "Transactional" and "Lifecycle"
+- Default to Lifecycle view
+- Transactional tab shows TX messages in a simple table
+- Lifecycle tab shows the full AARRR matrix
+
+#### 3. Filter Sidebar
+A left sidebar with three collapsible filter sections. Each section has a header that toggles collapse, and items that act as toggle filters:
+
+- **Stage** (open by default) -- One row per stage (TX, AQ, AC, RV, RT, RF) with color badge and count. Click to toggle. OR logic within stages.
+- **Channel** (open by default) -- One row per channel (email, in-app, etc.) with count. Click to toggle. OR logic within channels.
+- **Tags** (open by default) -- Tag pills with counts. Click to toggle. OR logic within tags.
+- **Clear all filters** button at the bottom to reset everything.
+
+Filters across sections use AND logic (stage AND channel AND tag must match).
+
+#### 4. Matrix Table
+- Sortable by clicking column headers (ID, Stage, Name, Channel, Wait, Tags)
+- Columns: ID | Stage | Name | Trigger | Wait | Channel | CTA | Tags
+- Color-code rows by stage
+- Click any row to expand a detail panel showing guards, suppressions, comments, and message body (if available)
+
+#### 5. Message Previews
+- Click any row in the matrix table to expand and show the message detail
+- Show subject + body if available (from generate-messages), otherwise show comments
+- Read message content from embedded JSON data
+- Each expanded detail includes an "Open full preview" link to `messages.html#MSG-ID`
+
+### Implementation Notes
+
+- All data is embedded as JSON in a `<script>` tag -- no external data files
+- Use vanilla JavaScript for interactivity (no framework needed)
+- Make sure it works when opened directly from the filesystem (`file://` protocol)
+- Responsive layout: works on both desktop and tablet screens
+- Dark/light mode: follow system preference with `prefers-color-scheme`
+- All HTML outputs must include the standard footer with repo link:
+  ```html
+  <footer>
+    <a href="https://github.com/sr-kai/mango-lollipop">Mango Lollipop</a> — AI-powered lifecycle messaging for SaaS<br>
+    Made by Sasha Kai with probably too much coffee.
+  </footer>
+  ```
+
+Write the output to `{project-directory}/dashboard.html`.
+
+---
+
+## Output B: Message Viewer (`messages.html`)
+
+A single-page message preview viewer with hash-based routing. Each message gets a channel-specific visual preview.
+
+### Design
+
+- **Hash routing:** `messages.html#AQ-01` navigates directly to that message. Works with `file://` protocol.
+- **Left sidebar:** Messages grouped by AARRR stage with color badges. Click to navigate.
+- **Main preview area:** Channel-specific rendered preview of the selected message.
+- **Details card:** Below the preview, shows trigger, wait, guards, suppressions, tags, goal, comments.
+- **Keyboard navigation:** Arrow up/down (or j/k) to move between messages.
+- **Back to dashboard:** Link in the header returns to `dashboard.html`.
+
+### Channel-Specific Templates
+
+Each message renders in a visual template matching its channel:
+
+- **Email:** Email client frame with toolbar dots, From/To/Subject header, body content, and CTA button.
+- **In-App:** Modal overlay with close button, title, body, and CTA button.
+- **SMS:** Phone frame with chat bubble, sender name, and timestamp.
+- **Push:** Phone frame with notification card showing app icon, title, and body.
+
+### Content Handling
+
+- If message copy exists (from `generate-messages`), the viewer parses it and renders the channel-specific content.
+- If copy hasn't been generated yet, the viewer shows a placeholder with the message's comments and a note to run `generate-messages`.
+- Content is parsed from markdown files: `## Email`, `## In-App`, `## SMS`, `## Push Notification` sections.
+
+Write the output to `{project-directory}/messages.html`.
+
+---
+
+## Output C: Executive Overview (`overview.html`)
+
+Create a clean, printable HTML page designed for sharing with stakeholders.
+
+### Design Principles
+- Clean, minimal design suitable for printing
+- No interactive elements (no JavaScript required for content)
+- Professional typography (system fonts)
+- Fits well on A4/Letter paper when printed from browser
+- Uses inline CSS only (no CDN dependencies for printing reliability)
+
+### Sections
+
+#### 1. Title Block
+- "Lifecycle Messaging Strategy" as main title
+- Company name from `analysis.json`
+- Generation date
+- Path indicator: "Built from scratch" or "Built on existing messaging"
+
+#### 2. Company Overview
+- Product type, target audience, key value proposition
+- Aha moment
+- Selected channels
+- Voice profile summary (tone, formality, emoji usage)
+
+#### 3. Strategy Summary
+- One paragraph per AARRR stage explaining the strategy
+- For PATH B: note what was kept, improved, and added
+
+#### 4. Condensed Matrix Table
+- All messages in a single table
+- Columns: ID | Stage | Name | Channel(s) | Trigger | Wait | CTA
+- Color-coded rows by stage
+- Print-friendly (no scroll, wraps across pages if needed)
+
+#### 5. Message Inventory
+- Count by stage:
+  - TX: N transactional messages
+  - AQ: N acquisition messages
+  - AC: N activation messages
+  - RV: N revenue messages
+  - RT: N retention messages
+  - RF: N referral messages
+- Count by channel: N email, N in-app, N push, N SMS
+
+#### 6. Tag Summary
+- Table of all tags with message counts
+- Grouped by category
+
+#### 7. Recommended Implementation Order
+- Prioritized list of which messages to implement first
+- Priority logic:
+  1. TX messages (mandatory, implement immediately)
+  2. AQ messages (first user experience)
+  3. AC messages for the top 2-3 features (drive to aha moment)
+  4. RV messages (capture revenue)
+  5. RT messages (reduce churn)
+  6. RF messages (growth)
+  7. Remaining AC messages
+
+Write the output to `{project-directory}/overview.html`.
+
+---
+
+## Completion
+
+Generate all outputs by running the following commands:
+
+```bash
+npm run build && node bin/mango-lollipop.js export visuals
+```
+
+This creates three files in the project output directory:
+- `dashboard.html` -- Interactive dashboard with filters and sorting
+- `messages.html` -- Channel-specific message previews with hash routing
+- `overview.html` -- Printable executive overview
+
+After the command succeeds:
+
+1. Update `mango-lollipop.json` to set `stage: "visuals-generated"`
+2. Tell the user: "Your visual deliverables are ready. Open `dashboard.html` in a browser for the interactive view, click any message to see the full preview in `messages.html`, or share `overview.html` as a printable summary."
+3. Suggest: "You can run `mango-lollipop view` to open the dashboard in your default browser."