Onboarding Builder

---
name: onboarding-builder
description: |
  Trigger when the user asks to build an onboarding flow, create a welcome
  experience, or design first-time user setup. Phrases: "onboarding flow",
  "welcome experience", "setup wizard", "first-run", "user activation".
allowed-tools:
  - Read
  - Write
  - Edit
---

# Onboarding Builder

Design and build the first-run experience of a web app. Focus on time-to-
value, not completeness. The goal is the user's first meaningful action
inside five minutes.

## Prerequisites

- App has a core value proposition the user can reach
- Authentication layer exists
- Clear definition of "aha moment" (what does success on day one look like?)

## Steps

1. **Pin the aha moment.** Everything in onboarding aims at it. Usual
   candidates: first project created, first message sent, first integration
   wired, first result returned.

2. **Count the steps to the aha.** If it takes more than five screens,
   the flow is too long. Cut or defer to later.

3. **Design the minimum path:**
   - Sign up / sign in (auth provider UI)
   - One or two config steps (just the required minimum, no optional)
   - Land on a useful first screen
   - Guided action that produces the aha

4. **Defer everything deferable.** Ask the bare minimum at signup. Team
   setup, billing, integrations, preferences all live behind dashboard
   settings. Never block activation on them.

5. **Pre-fill intelligently.** If the user signed up via Google, you know
   their name. Use it. Do not ask again.

6. **Offer a template or demo project.** Empty state is the enemy of
   onboarding. Every new account should land with something already in
   it (a demo project, sample data, a guided tutorial).

7. **Measure drop-off per step.** Instrument with whatever analytics you
   have. The biggest onboarding improvements come from finding the one
   step where 40% of users bail, then fixing that specific step.

## Patterns that work

- **Progress indicator** if the flow is four or more steps
- **Skippable tutorials** never mandatory
- **In-app tooltips** over a "docs tour" modal that pops up first
- **Empty states with a CTA** not just "no projects yet"

## Anti-patterns

- Forced credit card entry before the aha
- 10-question "tell us about yourself" form that delays the product
- Multi-step setup that cannot be exited and resumed
- Video onboarding that auto-plays

## Output

- Onboarding flow implementation
- Analytics events at each step
- Time-to-aha measurement before/after
- "Resume onboarding" link in user settings for users who exit mid-flow