/onboarding-generator

name: onboarding-generator
description: Generates value-moment-first onboarding flows for iOS/macOS apps — the default architecture races a new user to the first felt experience of the app's promised outcome, branching on whether they can experience it right now or need to plan for later. The classic paged welcome-carousel tour is an explicit fallback for genuinely explain-first apps. Use when user wants to add onboarding, welcome screens, first-launch experience, or improve activation/trial conversion.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-23
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Onboarding Generator

Generate onboarding whose job is to get a new user to the **value moment** — the first time they *experience* (never just read about) the outcome the app promises — as fast as their situation allows.

**Default architecture: value-moment-first, branching on readiness.** The user answers one question ("can you do this right now?"), and the path is either the shortest possible route to the value moment, or a captured plan to reach it later. **Fallback architecture: the classic paged welcome carousel** — generate it only when Step 0 below confirms the app is genuinely explain-first.

Read `onboarding-patterns.md` for the full philosophy, the nine implementation lessons (each with a code sketch), and a worked case study.

When This Skill Activates

Use this skill when the user:

• Asks to "add onboarding" or "create onboarding"
• Mentions "welcome screens" or "first launch"
• Wants to "show intro on first launch"
• Asks about "onboarding flow" or "tutorial screens"
• Wants to improve "activation," "time-to-value," or "trial conversion"
• Asks "why do users churn right after signup/purchase" (post-purchase first-run is half of this skill)

Before Anything Else: What Is The Value Moment?

This is the question that decides every downstream choice — ask it before any configuration question. If the requester can't answer it, help them find it: it's the first specific instant a user *feels* the outcome, not a feature list. "Sees a demo of X" is not a value moment; "actually did X and saw the result" is.

Onboarding that ends before the user felt the value moment didn't finish — it just stopped.

Pre-Generation Checks

1. Project Context Detection

• [ ] Check deployment target (`@Observable` needs iOS 17+/macOS 14+; fall back to `ObservableObject` below that)
• [ ] Identify the app's core feature and its existing entry point — the value moment almost always lives inside a feature that already exists (or is being built alongside this flow); this skill wires into it, it does not rebuild it (see `onboarding-patterns.md` Lesson 3)
• [ ] Check whether the app has a launch paywall (`Glob: **/*Paywall*.swift, **/*StoreKit*.swift`, or an installed `generators/paywall-generator` output) — determines free-first vs paywalled-first in Configuration Question 2
• [ ] Check for `UNUserNotificationCenter` usage already in the project — reuse the existing permission seam if one exists rather than creating a second

2. Conflict Detection

Glob: **/*Onboarding*.swift, **/*Welcome*.swift
Grep: "hasCompletedOnboarding" or "isFirstLaunch" or "onboardingCompleted"

If found, ask the user:

• Replace existing onboarding?
• Keep existing, add the value-moment flow as a new post-purchase/post-launch stage?

3. Overlap Check — `generators/quick-win-session`

If the project already has a quick-win-session installation, don't generate a second guided-first-action system. Ask whether the existing quick-win session already *is* the ready-now path (often it is — fold this flow's branch question and later-path in around it) or whether the two should stay separate stages.

Configuration Questions

Ask user via AskUserQuestion:

1. **What's the value moment?** (free text) — the first specific instant the user experiences the app's promise. Push back on feature descriptions ("a calendar sync feature") until you get an outcome ("saw their two calendars merged into one").

2. **Free-first or paywalled-first?**

• Free-first (no launch paywall) — this flow **is** the whole onboarding
• Paywalled-first — personalize → paywall happens before this flow starts; this flow begins at first-run-after-purchase (the half that decides trial conversion and renewals)

3. **What's the ready-now action?** — the shortest real path to the value moment when the user can experience it immediately. Must name an *existing* feature/screen to reuse, never a new one built just for onboarding.

4. **What does "later" capture?** — the concrete implementation intention (a specific *when*, e.g. "Tuesday 6pm," never "someday"), and what happens with it: a local reminder, a home-surface chip, both?

5. **Architecture override — is this genuinely explain-first?** Default is no (value-moment-first). Only say yes if Step 0's test below is met. This is the one question that routes to the carousel fallback instead.

Generation Process

Step 0: Confirm The Architecture (do this before writing any file)

Run this test:

> Would skipping straight to the value moment leave the user unable to understand what they're looking at, in a way no amount of contextual UI (tooltips, empty-state copy, a single explainer inline) could fix — because the domain itself requires orientation (e.g., a professional tool with domain-specific jargon, a multi-role enterprise workflow)?

• **No** (the overwhelming default) → generate the value-moment-first flow (Steps 1–5).
• **Yes** → generate the carousel fallback (Step 6). "We have a lot to say" is not a yes — trim the copy instead.

Step 1: Create Core Files (Value-Moment Default)

Read `templates/value-moment/` for production Swift code, then generate: 1. `OnboardingPhase.swift` — the phase/branch state model (one enum case per screen; every case maps to exactly one decision) 2. `OnboardingStore.swift` — `@Observable` coor