@soulcraft/kits 1.0.0

package/kits/saas-app/kit.json

@@ -0,0 +1,405 @@
+{
+  "id": "saas-app",
+  "type": "soulcraft",
+  "role": "primary",
+  "status": "released",
+  "name": "SaaS Application",
+  "description": "Full-stack SaaS platform with recurring subscriptions, customer accounts, AI-powered support, and integrated marketing. Built for digital-first software businesses.",
+  "longDescription": "A complete SaaS platform kit covering subscription billing, customer lifecycle management, onboarding flows, and product analytics. Designed for digital-first software businesses that need to move fast without sacrificing operational clarity.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "💻",
+  "tags": [
+    "saas",
+    "software",
+    "subscriptions",
+    "digital",
+    "developer",
+    "b2b",
+    "b2c"
+  ],
+  "variables": [
+    {
+      "key": "productName",
+      "label": "Product Name",
+      "description": "The name of your software product (e.g. \"Acme Analytics\")",
+      "type": "string",
+      "required": true,
+      "example": "Acme Analytics"
+    },
+    {
+      "key": "tagline",
+      "label": "Tagline",
+      "description": "A short phrase describing what your product does (shown under the logo)",
+      "type": "string",
+      "required": false,
+      "example": "The analytics platform that grows with you"
+    },
+    {
+      "key": "supportEmail",
+      "label": "Support Email",
+      "description": "Customer-facing support email address",
+      "type": "email",
+      "required": true,
+      "example": "support@acmeanalytics.com"
+    },
+    {
+      "key": "websiteUrl",
+      "label": "Website URL",
+      "description": "Your product's public website (used for links in transactional emails)",
+      "type": "url",
+      "required": false,
+      "example": "https://acmeanalytics.com"
+    },
+    {
+      "key": "twitter",
+      "label": "Twitter / X Handle",
+      "description": "Twitter username without the @",
+      "type": "string",
+      "required": false,
+      "example": "acmeanalytics"
+    },
+    {
+      "key": "trialDays",
+      "label": "Free Trial Length (days)",
+      "description": "Number of days in the free trial before payment is required. Set to 0 to disable trials.",
+      "type": "number",
+      "required": false,
+      "example": "14",
+      "default": "14"
+    }
+  ],
+  "shared": {
+    "industry": "saas",
+    "category": "business",
+    "glossary": {
+      "MRR": "Monthly Recurring Revenue — the predictable monthly revenue from active subscriptions, excluding one-time charges",
+      "ARR": "Annual Recurring Revenue — MRR multiplied by 12, used for annual business reporting",
+      "churn": "The rate at which customers cancel their subscriptions, expressed as a percentage over a given period",
+      "ARPU": "Average Revenue Per User — total MRR divided by number of active subscribers",
+      "CAC": "Customer Acquisition Cost — total sales and marketing spend divided by new customers acquired",
+      "LTV": "Lifetime Value — average revenue a customer generates over their entire relationship with the product",
+      "NRR": "Net Revenue Retention — measures revenue growth or contraction within the existing customer base, accounting for expansions, contractions, and churn",
+      "activation": "The moment a new user reaches the 'aha moment' — the point where they've experienced the core value of the product",
+      "trial conversion": "The percentage of free trial users who become paying subscribers",
+      "expansion revenue": "Additional revenue from existing customers upgrading their plan or adding seats/usage",
+      "cohort": "A group of customers who started at the same time (e.g. all customers who signed up in January 2026)"
+    },
+    "aiExpertise": [
+      "SaaS metrics and business model analysis",
+      "subscription pricing strategy and packaging",
+      "customer churn analysis and retention",
+      "user onboarding and activation optimization",
+      "product-led growth (PLG) strategies",
+      "unit economics (CAC, LTV, payback period)",
+      "SaaS financial modeling and forecasting"
+    ],
+    "dataModelHints": [
+      "subscription",
+      "subscription_plan",
+      "customer",
+      "transaction",
+      "usage_event",
+      "support_ticket"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "customer",
+          "type": "Person",
+          "description": "A registered user or organization with an active or trialing account in the SaaS product.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "👤"
+            },
+            "academy": {
+              "mapsTo": "learner",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "subscription",
+          "type": "Event",
+          "description": "An active, trialing, or canceled subscription linking a customer to a plan with billing cycle and status.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "🔄"
+            },
+            "academy": {
+              "mapsTo": "practice-session",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "subscription_plan",
+          "type": "Product",
+          "description": "A pricing tier (e.g. Starter, Pro, Enterprise) defining feature access, usage limits, and monthly price.",
+          "products": {
+            "workshop": {
+              "view": "gallery",
+              "icon": "💳"
+            },
+            "academy": {
+              "mapsTo": "skill-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "transaction",
+          "type": "Measurement",
+          "description": "A billing event — charge, refund, or credit — always stored in cents and linked to a subscription.",
+          "products": {
+            "workshop": {
+              "view": "timeline",
+              "icon": "💰"
+            }
+          }
+        },
+        {
+          "domain": "usage_event",
+          "type": "Measurement",
+          "description": "A recorded product usage metric such as API calls, seats used, or storage consumed in a billing period.",
+          "products": {
+            "workshop": {
+              "view": "stats",
+              "icon": "📊"
+            }
+          }
+        },
+        {
+          "domain": "support_ticket",
+          "type": "Event",
+          "description": "An inbound support request from a customer, tracked through triage, assignment, and resolution.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "🎫"
+            }
+          }
+        },
+        {
+          "domain": "content_page",
+          "type": "Document",
+          "description": "A CMS-managed page such as Pricing, Documentation overview, or Terms of Service.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "📄"
+            },
+            "academy": {
+              "mapsTo": "learning-resource",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "blog_post",
+          "type": "Document",
+          "description": "A published post covering product updates, tutorials, engineering stories, or company news.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "✍️"
+            },
+            "academy": {
+              "mapsTo": "learning-resource",
+              "assessable": false
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "customer",
+          "to": "subscription",
+          "verb": "Creates",
+          "description": "Customer signs up for or upgrades to a subscription plan."
+        },
+        {
+          "from": "subscription",
+          "to": "subscription_plan",
+          "verb": "References",
+          "description": "Subscription is bound to a specific pricing plan defining feature flags and usage limits."
+        },
+        {
+          "from": "transaction",
+          "to": "subscription",
+          "verb": "References",
+          "description": "Billing transaction links back to the subscription it charges or credits."
+        },
+        {
+          "from": "usage_event",
+          "to": "subscription",
+          "verb": "References",
+          "description": "Usage metric is attributed to the subscription account that consumed it."
+        },
+        {
+          "from": "customer",
+          "to": "support_ticket",
+          "verb": "Creates",
+          "description": "Customer opens a support ticket that is triaged, assigned, and resolved by the team."
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Design pricing tiers",
+        "prompt": "Help me design my subscription pricing tiers — plans, features, and pricing strategy."
+      },
+      {
+        "label": "Map onboarding flow",
+        "prompt": "Let's map out the ideal onboarding flow from signup to activation for my product."
+      },
+      {
+        "label": "Analyze churn drivers",
+        "prompt": "I want to understand why customers are churning and build a retention strategy."
+      },
+      {
+        "label": "Visualize knowledge graph",
+        "prompt": "Show me a visualization of my product knowledge graph."
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "saas-product-management",
+    "level": "intermediate",
+    "learningObjectives": [
+      "Product analytics and key SaaS metric interpretation",
+      "User lifecycle management and activation strategies",
+      "Feature prioritization frameworks and roadmap planning",
+      "SaaS metrics modeling: MRR, churn, LTV, and NRR"
+    ],
+    "assessmentTypes": [
+      "portfolio",
+      "peer-review"
+    ],
+    "certificationSlug": "saas-builder"
+  },
+  "venue": {
+    "features": {
+      "subscriptions": true,
+      "customerAccounts": true,
+      "apps": true,
+      "documents": true,
+      "support": true,
+      "blog": true,
+      "cms": true,
+      "website": true,
+      "notifications": true
+    },
+    "theme": {
+      "primary": "oklch(0.52 0.24 258)",
+      "bgBase": "oklch(0.99 0.005 258)",
+      "accent": "oklch(0.62 0.18 195)",
+      "textPrimary": "oklch(0.22 0.03 258)",
+      "displayFont": "Plus Jakarta Sans",
+      "bodyFont": "Inter"
+    },
+    "experienceTypes": [],
+    "chatSuggestions": [
+      {
+        "label": "Manage subscription",
+        "message": "I'd like to view or make changes to my subscription.",
+        "emoji": "💳"
+      },
+      {
+        "label": "Billing question",
+        "message": "I have a question about my bill or invoice.",
+        "emoji": "🧾"
+      },
+      {
+        "label": "Get help",
+        "message": "I need help with something. Can you assist me?",
+        "emoji": "💬"
+      },
+      {
+        "label": "Upgrade my plan",
+        "message": "I'm interested in upgrading to a higher plan. What are my options?",
+        "emoji": "🚀"
+      }
+    ]
+  },
+  "workshop": {
+    "workspaceConfig": {
+      "paradigm": "analyst",
+      "defaultTab": "explore",
+      "defaultView": "graph"
+    },
+    "aiPersona": {
+      "role": "You are a senior SaaS architect and product strategist with deep experience building subscription software businesses. You think in unit economics, product-led growth loops, and scalable architecture. You are direct and practical — you help founders and product teams make clear, evidence-based decisions.",
+      "expertise": [
+        "SaaS metrics and business model analysis",
+        "subscription pricing and packaging strategy",
+        "customer churn analysis and retention playbooks",
+        "user onboarding and activation flow design",
+        "API design and developer experience",
+        "product-led growth (PLG) and self-serve funnels",
+        "SaaS financial modeling and scenario analysis"
+      ],
+      "tone": "collaborator",
+      "avoidances": [
+        "Don't over-engineer — prefer the simplest solution that solves the actual problem",
+        "Don't design for scale that doesn't exist yet — validate first, optimize later",
+        "Don't recommend tooling without understanding the team's context and constraints"
+      ]
+    },
+    "publishConfig": {
+      "contentType": "document",
+      "publishable": true
+    },
+    "remoteWorkspace": {
+      "connectedWorkbenches": [
+        {
+          "name": "Customer Accounts",
+          "view": "board",
+          "entityTypes": [
+            "customer"
+          ],
+          "description": "Track customers by plan tier, trial status, and lifecycle stage"
+        },
+        {
+          "name": "Revenue Metrics",
+          "view": "stats",
+          "entityTypes": [
+            "transaction"
+          ],
+          "description": "MRR, ARR, churn, ARPU, and expansion revenue at a glance"
+        },
+        {
+          "name": "Support Queue",
+          "view": "board",
+          "entityTypes": [
+            "event"
+          ],
+          "description": "Triage and resolve open support tickets by priority"
+        },
+        {
+          "name": "App Analytics",
+          "view": "timeline",
+          "entityTypes": [
+            "measurement"
+          ],
+          "description": "Usage events and activation milestones over time"
+        },
+        {
+          "name": "Subscription Graph",
+          "view": "graph",
+          "entityTypes": [
+            "customer",
+            "transaction"
+          ],
+          "description": "Graph of customer relationships, plans, and revenue flows"
+        }
+      ]
+    }
+  }
+}

package/kits/saas-app/skills/churn-analysis/SKILL.md

@@ -0,0 +1,219 @@
+---
+id: churn-analysis
+name: Churn Analyst
+description: Cohort churn analysis for {{productName}} — calculates churn rate by period and plan, identifies cancellation patterns, compares cohorts, and surfaces actionable retention recommendations.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Churn Analyst
+
+You produce churn analysis reports for {{productName}}. Given a time period and plan filter (defaulting to the last 90 days across all plans), you pull cancellation data from Brainy, calculate churn rates, compare cohorts, and identify the most actionable retention levers.
+
+## When to Trigger
+
+Invoke this skill when someone asks:
+
+- "Churn analysis"
+- "Why are customers leaving?"
+- "What's our churn rate?"
+- "Show me cancellations for [period]"
+- "Which plan has the highest churn?"
+- "Retention report"
+- "How are we doing on churn?"
+- Any request for cancellation data, customer loss analysis, or retention metrics
+
+## Default Period
+
+Default to the **last 90 days**. Accept natural language overrides: "last month", "Q1", "this year", "last 30 days".
+
+When comparing cohorts, group by the month the customer first subscribed (not when they cancelled).
+
+## Data to Pull
+
+### Cancellations for Period
+
+```typescript
+brain.defineAggregate('cancellationsForPeriod', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'subscription' },
+      { field: 'metadata.status',     value: 'cancelled'    }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.planId'           },
+    { field: 'metadata.cancelledAt', window: 'month' }
+  ],
+  metrics: {
+    churnCount:    { op: 'COUNT'                                  },
+    totalLostMrr:  { op: 'SUM', field: 'metadata.monthlyAmountInCents' },
+    avgTenure:     { op: 'AVG', field: 'metadata.tenureMonths'         },
+    minTenure:     { op: 'MIN', field: 'metadata.tenureMonths'         },
+    maxTenure:     { op: 'MAX', field: 'metadata.tenureMonths'         }
+  }
+});
+
+const cancellations = await brain.find({
+  aggregate: 'cancellationsForPeriod',
+  where: [
+    { field: 'metadata.cancelledAt', value: { gte: START_DATE, lte: END_DATE } }
+  ]
+});
+```
+
+### Active Subscribers at Period Start (for rate calculation)
+
+```typescript
+const activeAtStart = await brain.find({
+  where: [
+    { field: 'metadata.entityType', value: 'subscription' },
+    { field: 'metadata.status',     value: 'active'       },
+    { field: 'metadata.startedAt',  value: { lte: START_DATE } }
+  ]
+});
+// Count by plan for per-plan churn rate
+```
+
+### Cohort Retention (monthly cohorts, last 6 months)
+
+```typescript
+brain.defineAggregate('cohortRetention', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'subscription' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.startedAt', window: 'month' },
+    { field: 'metadata.status'                      }
+  ],
+  metrics: {
+    count: { op: 'COUNT' }
+  }
+});
+```
+
+### Cancellation Reasons (if exit survey data exists)
+
+```typescript
+const exitSurveys = await brain.find({
+  where: [
+    { field: 'metadata.entityType', value: 'subscription' },
+    { field: 'metadata.status',     value: 'cancelled'    },
+    { field: 'metadata.cancelReason', value: { exists: true } },
+    { field: 'metadata.cancelledAt',  value: { gte: START_DATE } }
+  ]
+});
+```
+
+## Output Structure
+
+Present the report in this order. Use markdown throughout.
+
+---
+
+### 1. Period Summary
+
+```
+Churn Analysis: {{productName}}
+Period: Oct 27 – Jan 23, 2026 (90 days)
+─────────────────────────────────────────
+Total Cancellations:  28
+MRR Lost to Churn:    $1,842
+Avg Subscriber Tenure: 3.2 months
+Overall Churn Rate:   5.1% (period)
+Monthly Rate Equiv.:  ~1.7%/month
+```
+
+**Churn Rate Formula:**
+```
+Period Churn Rate = Cancellations ÷ Active Subscribers at Period Start
+Monthly Equivalent = 1 - (1 - Period Rate)^(1/months_in_period)
+```
+
+### 2. Churn by Plan
+
+| Plan | Active (start) | Cancelled | Churn Rate | MRR Lost | Avg Tenure |
+|------|---------------|-----------|-----------|----------|-----------|
+| Starter | 285 | 18 | 6.3% | $342 | 2.1 mo |
+| Pro | 174 | 8 | 4.6% | $392 | 3.8 mo |
+| Business | 54 | 2 | 3.7% | $298 | 6.2 mo |
+| Enterprise | 8 | 0 | 0% | — | — |
+| **Total** | **521** | **28** | **5.4%** | **$1,032** | **3.2 mo** |
+
+Flag the plan with the highest churn rate. Flag any plan where churn is accelerating (compare to prior period if available).
+
+### 3. Monthly Churn Trend
+
+| Month | Cancellations | MRR Lost | Churn Rate | vs. Prior |
+|-------|--------------|----------|-----------|-----------|
+| Nov | 8 | $312 | 1.5% | — |
+| Dec | 11 | $564 | 2.1% | +40% ⚠️ |
+| Jan | 9 | $456 | 1.7% | -19% |
+
+Mark months where churn jumped > 30% vs. prior with ⚠️. These warrant investigation (product changes, competitor actions, pricing changes, billing cycle effects).
+
+### 4. Cohort Retention Table
+
+Shows what % of each monthly cohort is still active:
+
+| Cohort (signup month) | Month 1 | Month 2 | Month 3 | Month 4 | Month 5 | Month 6 |
+|-----------------------|---------|---------|---------|---------|---------|---------|
+| Aug 2025 | 100% | 87% | 78% | 72% | 68% | 65% |
+| Sep 2025 | 100% | 89% | 80% | 75% | 71% | — |
+| Oct 2025 | 100% | 85% | 76% | 72% | — | — |
+| Nov 2025 | 100% | 88% | 81% | — | — | — |
+| Dec 2025 | 100% | 86% | — | — | — | — |
+
+Use `—` where data isn't available yet (cohort hasn't reached that month).
+
+Key to watch: **Month 1 and Month 2 retention.** If > 20% churn by Month 2, activation is the root cause — the customer never understood the product's value.
+
+### 5. Cancellation Reasons
+
+If exit survey data is available, produce a ranked list:
+
+| Reason | Count | % of Cancellations |
+|--------|-------|-------------------|
+| Too expensive | 9 | 32% |
+| Not using it enough | 8 | 29% |
+| Missing a feature | 5 | 18% |
+| Switching to competitor | 4 | 14% |
+| Closing the business | 2 | 7% |
+
+Distinguish between **fixable reasons** (missing feature, too expensive, not using it) and **uncontrollable reasons** (closing business, switching for a required integration).
+
+If no exit survey data exists: state clearly: "No exit survey data available. Add a cancellation reason prompt to the cancel flow to capture this data — it's the highest-leverage churn insight available."
+
+### 6. Revenue Impact
+
+```
+MRR Lost to Churn (period):   $1,842
+Annualized Run Rate:          $7,368
+LTV per Cancelled Customer:   $156  (avg)
+Cost of This Churn (at 3× CAC): ~$84,000 in customer acquisition investment lost
+```
+
+Multiply the annualized MRR loss by 3× CAC if known (rough cost of replacing this revenue with new customers). This reframes churn as a marketing spend problem — often gets leadership attention.
+
+### 7. Retention Recommendations
+
+Based on the data, give 2–4 specific, evidence-based actions. Prioritize by expected impact:
+
+1. **[If Month 1–2 churn > 20%]:** Fix activation before anything else. Run 3 customer interviews with people who cancelled in month 1 — understand what they expected vs. what they got. Activation improvements often cut early churn in half.
+2. **[If "not using it enough" is top reason]:** Set up a usage-drop alert at the 50% engagement threshold. A triggered email at 14 days of no activity with a specific re-engagement hook outperforms generic newsletters.
+3. **[If December had a spike]:** Investigate whether a product change, pricing change, or a competitor moved around that time. This churn may be event-driven, not structural.
+4. **[If Starter churn is > 2× Pro churn]:** Evaluate whether Starter customers are actually getting value from the product or just experimenting. A shorter, lower-price "Starter" plan often performs better than a full-feature cheap plan.
+
+## Formatting Rules
+
+- Churn rates: always show monthly equivalent alongside period rate
+- MRR figures: divide cents by 100, format as `$X,XXX`
+- Tenure: `X.X months` format, never round to whole numbers
+- Use `—` in table cells for unavailable data
+- Never call 5% churn "good" — contextualize against the benchmark for the business type (B2B vs. B2C, price point, acquisition channel)