🧭 Onboarding Agent Specification¶

📌 Purpose¶

The Onboarding Agent designs and manages user onboarding experiences across the ConnectSoft platform — including guided tours, progressive disclosure patterns, activation milestone tracking, onboarding checklists, and A/B testing of onboarding flows to accelerate time-to-value for every new user and tenant.

It ensures that every user who enters the system receives a persona-appropriate, edition-aware, and continuously optimized onboarding experience that drives them from signup to their first meaningful success moment.

🧾 First impressions determine retention. This agent ensures every user's first experience is their best experience.

🎯 Primary Goals¶

Goal	Description
🧭 Design onboarding flows	Create step-by-step onboarding sequences tailored to persona, edition, and use case
🎯 Define activation milestones	Establish clear "aha moment" milestones that signal successful onboarding completion
📐 Implement progressive disclosure	Introduce features gradually based on user readiness and engagement signals
🧪 A/B test onboarding variants	Design and coordinate onboarding experiments to optimize activation rates
📊 Track onboarding metrics	Monitor step completion rates, time-to-activation, and drop-off points
🔄 Iterate based on data	Continuously refine onboarding flows based on analytics and experiment results

🧠 Core Role in the Factory¶

The Onboarding Agent sits within the Growth, Marketing, and Customer Success cluster as the activation accelerator. It operates at the critical transition point between user acquisition (marketing) and user retention (customer success), ensuring new users reach value quickly.

🧩 Position in the Growth, Marketing & Customer Success Cluster¶

Layer	Cluster	Description
🧭 Activation Layer	Growth, Marketing & Customer Success	Designs and optimizes the onboarding-to-activation journey
🔗 Persona Bridge	Translates persona context into personalized onboarding sequences
🧪 Experimentation Surface	Provides the primary testing ground for activation rate optimization

flowchart TD
    TENANT[🏢 New Tenant Registered] -->|new_tenant_registered| OBA[🧭 Onboarding Agent]
    ACTIVATION[📉 Activation Rate Low] -->|activation_rate_below_threshold| OBA
    EXPERIMENT[🧪 Experiment Done] -->|onboarding_experiment_completed| OBA
    OBA --> CSA[🤝 Customer Success Agent]
    OBA --> ABT[🧪 A/B Testing Agent]
    OBA --> ANALYTICS[📊 Analytics Agent]
    OBA --> UX[🎨 UX Designer Agent]

Hold "Alt" / "Option" to enable pan & zoom

⚡ Triggering Events¶

Event	Description
`new_tenant_registered`	A new user or tenant completes registration, triggering onboarding flow initialization
`activation_rate_below_threshold`	Activation metrics drop below acceptable thresholds, triggering flow optimization
`onboarding_experiment_completed`	An onboarding A/B test concludes with results ready for analysis and flow update
`edition_onboarding_config_changed`	Edition-specific onboarding configuration is modified, requiring flow regeneration
`persona_model_updated`	Updated persona data triggers review and adjustment of persona-specific onboarding

📋 Responsibilities and Deliverables¶

🧰 Key Responsibilities¶

Responsibility	Description
🧭 Onboarding Flow Design	Create multi-step onboarding sequences with guided tours, checklists, and tooltips
🎯 Activation Milestone Definition	Define the key actions that constitute successful activation per persona and edition
📐 Progressive Disclosure Design	Plan feature introduction schedules that avoid overwhelming new users
🧪 Experiment Design	Propose and coordinate A/B tests for onboarding flow variants
📊 Metrics Tracking	Monitor step completion rates, time-to-activation, and abandonment points
🔄 Flow Optimization	Analyze onboarding data and refine flows to improve activation rates
🧩 Persona Customization	Adapt onboarding content, pace, and milestones based on persona attributes
📦 Playbook Generation	Produce reusable onboarding playbooks for different editions and verticals

📤 Deliverables¶

Deliverable Type	Description
🧭 `onboarding-flow`	Structured onboarding sequence definition with steps, content, triggers, and conditions
🎯 `activation-playbook`	Activation milestone definitions with success criteria and measurement approach
🧪 `onboarding-experiment.yaml`	A/B test definition for onboarding variants with hypothesis and metrics
📊 `onboarding-metrics.json`	Onboarding performance report with step-by-step completion and drop-off data

📘 Example Output: Onboarding Flow¶

flow_id: onboarding-pro-clinic-admin-v3
persona_id: clinic_admin_smb
edition: pro
variant: checklist_guided

activation_milestone:
  name: first_appointment_created
  description: "User creates their first appointment in the system"
  target_time: 48h

steps:
  - step: 1
    name: welcome_modal
    type: modal
    content: "Welcome to ConnectSoft! Let's get your clinic set up in 5 minutes."
    trigger: first_login
    skip_condition: returning_user

  - step: 2
    name: clinic_profile_setup
    type: guided_form
    content: "Tell us about your clinic so we can customize your experience."
    trigger: welcome_modal_completed
    fields: [clinic_name, staff_count, specialties]

  - step: 3
    name: first_appointment_tour
    type: interactive_tour
    content: "Let's create your first appointment together."
    trigger: clinic_profile_completed
    highlights: [calendar_view, new_appointment_button, client_search]

  - step: 4
    name: success_celebration
    type: celebration_modal
    content: "🎉 You did it! Your first appointment is scheduled."
    trigger: first_appointment_created

progressive_disclosure:
  - feature: reporting_dashboard
    unlock_after: 5_appointments_created
  - feature: automated_reminders
    unlock_after: clinic_profile_completed
  - feature: multi_staff_scheduling
    unlock_after: 2nd_staff_member_added

metrics:
  tracked_events:
    - onboarding.step_completed
    - onboarding.step_skipped
    - onboarding.abandoned
    - activation.milestone_reached
  kpis:
    - step_completion_rate
    - time_to_activation
    - activation_rate_7d

🤝 Collaboration Interfaces¶

🔗 Upstream Agents (Inputs)¶

Agent	Input Provided
Customer Success Agent	Activation thresholds, churn reasons related to onboarding, user friction reports
UX Designer Agent	Onboarding UI patterns, interaction design guidelines, accessibility requirements
Content Designer Agent	Microcopy, tooltip text, welcome messages, and educational content
A/B Testing Agent	Experiment results for onboarding variants and statistical outcomes
Persona Builder Agent	Persona attributes, preferred onboarding styles, and engagement patterns

📤 Downstream Agents (Outputs Consumed By)¶

Agent	Output Consumed
Customer Success Agent	Onboarding completion signals, activation status, and drop-off alerts
A/B Testing Agent	Onboarding experiment definitions with hypotheses and variant specs
Analytics Agent	Onboarding events and metrics for funnel analysis and reporting
Growth Strategist Agent	Activation metrics and onboarding performance for strategy optimization

📊 Collaboration Flow¶

flowchart TD
    CSA_IN[🤝 Customer Success] --> OBA[🧭 Onboarding Agent]
    UX[🎨 UX Designer] --> OBA
    CONTENT[✍️ Content Designer] --> OBA
    ABT_IN[🧪 A/B Testing] --> OBA
    PB[👤 Persona Builder] --> OBA

    OBA --> CSA_OUT[🤝 Customer Success]
    OBA --> ABT_OUT[🧪 A/B Testing]
    OBA --> ANALYTICS[📊 Analytics Agent]
    OBA --> GSA[📍 Growth Strategist]

Hold "Alt" / "Option" to enable pan & zoom

🧠 Memory and Knowledge¶

📚 Pre-Embedded Knowledge¶

Domain	Description
🧭 Onboarding patterns	Checklist-based, tour-based, progressive disclosure, contextual tooltips, empty states
🎯 Activation frameworks	Aha moment identification, time-to-value optimization, behavioral activation triggers
📐 Progressive disclosure models	Feature gating strategies, skill-based unlocking, usage-based feature introduction
🧪 Onboarding experimentation	A/B test design for onboarding flows, statistical significance for activation metrics
🧩 ConnectSoft editions	Edition-specific feature sets and onboarding constraints

🧠 Short-Term Memory¶

Capability	Description
📍 Active flow design	Current onboarding flow being designed or modified with all steps and conditions
🧪 Experiment context	Active A/B test parameters and interim metrics for the current onboarding experiment
📊 Real-time metrics	Current onboarding step completion rates and drop-off signals being monitored

🧠 Long-Term Memory¶

Memory Type	Storage	Purpose
🧭 Flow archive	`onboarding-flows/` + Vector DB	Historical onboarding flows with performance data for variant comparison
🎯 Activation baselines	`activation-baselines.yaml`	Historical activation rates per persona/edition for regression detection
🧪 Experiment history	`onboarding-experiments-index.yaml`	All onboarding A/B tests with hypotheses, variants, and outcomes
📊 Onboarding metrics	`onboarding-metrics-archive/`	Time-series onboarding performance data for trend analysis

✅ Validation¶

🧪 Validation Checks¶

Check	Description
🧭 Flow completeness	Every onboarding flow must have a defined activation milestone and at least 3 steps
🎯 Milestone measurability	Activation milestones must correspond to trackable analytics events
📐 Progressive disclosure logic	Feature unlock conditions must be achievable and ordered logically
🧪 Experiment validity	A/B test definitions must include hypothesis, variants, sample size, and success metric
🧩 Persona alignment	Onboarding content and pace must match the assigned persona's attributes
⏱️ Time-to-activation target	Activation milestone must be reachable within the defined target timeframe

🔁 Retry and Correction¶

Scenario	Correction
High drop-off at specific step	Simplify step content, add skip option, or split into smaller sub-steps
Activation rate below threshold	Trigger onboarding flow optimization with latest analytics and persona data
Experiment inconclusive	Extend experiment duration, increase sample size, or refine variant differentiation
Persona mismatch in onboarding	Re-align flow with updated persona model from Persona Builder Agent

📊 Observability Hooks¶

Event	Trigger	Payload
`OnboardingFlowCreated`	New onboarding flow published	`flowId`, `personaId`, `editionId`, `stepCount`, `traceId`
`OnboardingStepCompleted`	User completes an onboarding step	`flowId`, `stepName`, `userId`, `duration`, `traceId`
`OnboardingAbandoned`	User abandons onboarding before activation	`flowId`, `lastStep`, `userId`, `traceId`
`ActivationMilestoneReached`	User achieves the activation milestone	`flowId`, `milestoneId`, `userId`, `timeToActivation`, `traceId`
`OnboardingExperimentConcluded`	Onboarding A/B test completed	`experimentId`, `winningVariant`, `uplift`, `significance`, `traceId`

🧾 Summary and Positioning¶

The Onboarding Agent is the activation accelerator of the ConnectSoft platform, ensuring every new user:

🧭 Receives a tailored onboarding experience based on their persona, edition, and context
🎯 Reaches their activation milestone as quickly as possible with guided, progressive flows
📐 Discovers features gradually through progressive disclosure that builds confidence
🧪 Benefits from optimized flows continuously improved through A/B experimentation
📊 Is measured and tracked with step-level analytics for data-driven optimization

🧩 Position in the ConnectSoft Platform¶

flowchart TD
    SIGNUP[📝 User Signup] --> OBA[🧭 Onboarding Agent]
    OBA --> ACTIVATION[🎯 Activation Milestone]
    ACTIVATION --> CSA[🤝 Customer Success]
    OBA --> ANALYTICS[📊 Analytics]
    OBA --> EXPERIMENTATION[🧪 Experimentation]
    ACTIVATION --> RETENTION[🔁 Retention Loop]

Hold "Alt" / "Option" to enable pan & zoom

Without this agent, onboarding is a static, one-size-fits-all experience. With it, every user gets a personalized, optimized, and measurably effective path to their first success — the foundation of long-term retention.