Cometchat Onboarding

---
name: cometchat-onboarding
description: "The shared FRONT DOOR for adding CometChat to ANY app — a consultative, enterprise-grade DISCOVER → UNDERSTAND → PLAN journey that ALWAYS runs first, before any framework core. Detects the whole repo, runs a features + design-system conversation (core chat/threads/groups/media/calls/search/…; a preset theme, match your design system, or build one), maps each feature to its UI Kit component (or the SDK method where the UI Kit has none — UI-Kit-first, SDK-fallback), shares a full integration PLAN, then hands a scoped build directive to the framework core on approval — final output is production-ready. Triggers: 'add cometchat', 'add chat', 'add chat to my app', 'add calling', 'integrate cometchat', 'build a chat feature'."
license: "MIT"
compatibility: "Framework-agnostic (React/Next/Angular/Vue/RN/Flutter/Android/iOS/… — degrades gracefully when a signal is absent). Emits NO CometChat components — output is a plan artifact + a scoped directive to a framework core skill."
metadata:
  author: "CometChat"
  version: "1.0.0"
  tags: "cometchat onboarding journey discover understand plan front-door router-gate agnostic intent"
---

> **Ground truth:** this skill runs FIRST for every "add CometChat" request and produces NO integration code — its only outputs are (1) the shared **plan artifact** and (2) a **scoped build directive** to the framework core. Repo facts come from `npx @cometchat/skills detect --json` (the authority) + **READING THE REPO** for the rest — NEVER memory, never the dashboard CLI (AUDIT-059). The archetype→capability map and plan template are in `references/` (loaded on demand). Credentials + implementation belong to the framework core (`cometchat-<family>-core`, family resolved from `peers.yaml`). Draw the boundary at PLAN.

<!-- onboarding is a platform-NEUTRAL journey skill (like the cross-family a11y/i18n): no per-platform Companion block. Its "companion" is whatever framework core the plan names on hand-off. -->

## Use this skill when
Any first-contact "add CometChat" intent, on ANY stack: "add chat", "add cometchat", "add chat to my app", "add voice/video calling", "integrate cometchat". The router (`cometchat`) ALWAYS routes here FIRST — a mandatory gate. It runs before ANY framework core so the developer gets discover → understand → plan before a line is written. (An *upgrade* request — "upgrade my v6 UI Kit to v7" — is reconciliation, not onboarding; the router sends that straight to migration. And a re-entry on an already-integrated repo short-circuits: see §Re-entry.)

## What this skill does — and only this (the four beats)
Run the four beats in order, as a CONSULTATIVE conversation (senior-engineer tone: recommend with a reason, surface trade-offs, never a blank form). Nothing is written to the user's code in ANY beat — the first write happens only AFTER beat 4's approval, inside the framework core. The final output is PRODUCTION-READY (the core's contract guarantees it).

> **The build model — UI Kit first, SDK per-feature fallback (NO "which approach?" question).** A renderable app on a platform with a shipped UI Kit ALWAYS gets the **UI Kit** as its UI layer (fastest path to a production-ready surface). There is NO "UI Kit vs SDK" architecture choice to make. Instead, PER FEATURE: if the UI Kit has a component/prop for it → **use the component**; if it does NOT → call the platform's **Chat SDK** method directly (already installed under the UI Kit — init/login use it). The SDK is the FALLBACK for what the UI Kit doesn't expose (AI agents, campaigns, advanced/AI moderation, transient messages, bots, webhooks, …), looked up in the detected family's core `references/docs-map.md` → SDK docs (`references/platforms.md`). The ONLY exception: a backend/no-DOM/non-renderable context has no UI layer — there the SDK is the whole build; say so honestly.

### 1. DETECT everything (environment + the WHOLE current repo)
Run the detect probe (above), then **READ THE REPO** for the rest (on web: `package.json` deps/scripts, the lockfile, framework config files and source; on iOS: `*.xcodeproj`/`*.xcworkspace`, `Package.swift`, a `Podfile` as a signal only — `references/platforms.md`). Capture, framework-agnostically, degrading gracefully when a signal is absent (record it `null`, never guess):
- **Framework & build:** `framework` · `framework_version` · `bundler` · `router` · `ssr_strategy` (ssr/csr/islands) · `env_prefix` (VITE_/NEXT_PUBLIC_/…) · `package_manager` (from the lockfile) · `language` (TS/JS) · `project_name` (plus mobile version fields for expo/RN/android/flutter). **Non-web platforms have different fields** — iOS, Android, React Native and Flutter each have a column in `references/platforms.md`.
- **App integration state:** **installed UI Kit + `version_conflict`** (a major other than the family's target — React v7, Angular v5, RN v5, iOS v5, Android v6, Flutter v6; `peers.yaml`) · **existing CometChat integration** · **credential presence** (an existing `.cometchat/config.json` or `*_COMETCHAT_APP_ID` env).
- **App architecture (infer from source, `null` when absent):** **auth system** (nextauth / clerk / firebase / auth0 / supabase / custom) · **styling / design system** (tailwind / css-modules / mui / styled-components / chakra) · **state management** (redux / zustand / mobx / recoil / context).
> **`version_conflict` STOP still applies HERE.** If detection shows a UI Kit major other than the family's target for an *add* request, STOP and surface it in the plan (reconcile first — `RULES.md`); do not hand off a build over a mixed-major repo. If CometChat is already wired for THIS major → **Re-entry** (below).
> **A signal being absent is DATA, not a blocker.** Missing auth ⇒ recommend the dev Auth-Key path + a note to add prod auth later; missing framework ⇒ record it and (per §Non-React) state the platform's core isn't built yet. Never fabricate a signal, never stall on one.

### 2. UNDERSTAND — the features + design conversation (each question WITH a recommended default from the repo)
A SHORT, consultative Q&A (clarification contract: ask **and wait**); every question carries a repo-inferred recommendation so the developer confirms rather than composes:
1. **Archetype / shape** — `1:1`/marketplace · `support` · `community`/groups · `full-messenger` · `embedded`. Infer from routes (seller/product → `1:1`; `/support` → `support`; `/community`/`/groups` → `community`). "Detected `<signal>` → recommend `<archetype>` — keep or change?"
2. **Features** — WHICH capabilities (from the detected platform's manifest — `features.json` react-v7 / `features.angular-v5.json` angular-v5 / `features.ios-v5.json` iOS / … — grouped; naming only one hands the wrong menu to every other family): **Core chat** (1:1 + groups, messages, **threads**, media/attachments, typing, receipts, **reactions, mentions** — the last two are ON BY DEFAULT in v7 core, NOT extensions to enable — AUDIT-077) is the recommended default and always included; then offer the add-ons — **voice/video calls · search · polls/stickers · translation · push notifications · AI/smart-replies · moderation · AI agents**. Do NOT list `reactions`/`mentions` as add-ons (they're core), and never offer a `deprecated:true` feature (email-replies · e2e-encryption · live-streaming). **First SUBTRACT what's already present (AUDIT-043)** — `detect`/existing-integration for wired features, and ASK which dashboard-gated extensions are already enabled (the CLI can't read per-app enabled-state); don't re-offer an already-on feature like translation. Ask "core chat + which of these?" Don't ask about individual components/props (the core decides those). **Each chosen feature maps to a UI Kit component where one exists, or an SDK method where it doesn't** (AI agents · campaigns · advanced/AI moderation · bots · webhooks · transient messages → SDK) — the plan's **Feature coverage** section records which, so nothing is silently dropped or hand-rolled.
3. **Design / theming** — HOW it should look. Present the light/dark MODE and the palette, and **ALWAYS include the AUTO option**: **(a)** **Auto — follow the device's light/dark (OS) setting** — the RECOMMENDED default for a fresh app (whether the kit follows the OS BY ITSELF differs per platform — **iOS does, with no host code, so do not offer to wire it there; web does not** — `references/platforms.md`, AUDIT-004), **(b)** a fixed **light** preset, **(c)** a fixed **dark** preset, **(d)** **match your existing design system** (recommended when discovery detected Tailwind/MUI/Chakra/a token theme — reuse it), **(e)** a **brand palette** (your colors as the platform's theme tokens — CSS custom properties on web, `UIColor`/`dynamicColor` on iOS), or **(f)** a **custom design system**. All map to the UI Kit's theme tokens / `customization`. Recommend from the detected `styling` signal: none → **auto + default tokens**; a design system detected → **auto + match**. **Omitting the auto / follow-system option is a defect (AUDIT-042) — the kit supports it and it's the pack's fresh-app default; never present a light-only menu.**
4. **Scope / placement** — smallest surface that satisfies the archetype (default) vs. the full combined app; the placement shapes differ by platform (`references/platforms.md`). Default to the SMALLEST reasonable production-ready surface.
The archetype → capability translation is in `references/archetypes.md`; the feature menu is the DETECTED platform's manifest (`references/platforms.md`) — never offer a feature that platform does not ship. Recommend, don't interrogate.

### 3. PLAN — share the FULL plan artifact BEFORE anything is written
Assemble and present the **plan artifact** — the concrete deliverable of this skill. It MUST contain every section of the plan-completeness contract (template + contract in `references/plan-artifact.md`):
1. **What I found** — the beat-1 discovery summary — the fields that APPLY to the detected platform (web: framework/bundler/router/SSR/pkg-mgr/env-prefix; iOS: deployment target/dependency manager/UI framework/Xcode project), plus language, auth, styling, existing-CometChat — each value or `null`. Do not report a field the platform does not have.
2. **What you want (feature coverage)** — the confirmed intent (archetype · **features** · **design/theming** · scope) translated to **CometChat capabilities** (intent→capability map from `references/archetypes.md`; features from `features.json`), **each tagged UI Kit component or SDK method** — the UI-Kit-first / SDK-fallback split. Flag the SDK-backed ones (AI agents · campaigns · advanced moderation · bots · …) so the core wires them from the SDK docs; nothing is silently dropped or hand-rolled.
3. **What I'll do** — a NUMBERED action list (the scoped build steps, in order).
4. **Files that will change** — the concrete paths/areas the build will touch (additive — APPEND, never replace).
5. **Packages** — the exact package(s) the plan installs (named, with major pins; the core owns the exact coordinates).
6. **Credential + auth strategy** — dev **Auth Key** vs prod **server-minted auth token**, CHOSEN from discovery (a real auth system detected ⇒ recommend the prod token path wired to it; none ⇒ dev Auth-Key path + a note to harden for prod). State it; do NOT fetch credentials here. **Say in the plan that the core will OFFER to fetch App ID/Region/Auth Key from the dashboard (loading the CometChat CLI on demand → `provision`) or let the user paste them — so the fetch step isn't dropped on hand-off and never degrades into a "paste them yourself" TODO (AUDIT-039).**
7. **The modify-or-approve gate** — explicitly invite the user to EDIT the plan or approve it. Nothing is written before approval.

### 4. MODIFY or START — edit the plan, else hand a SCOPED directive to the core
- The user may **edit** any part of the plan (change the archetype, add/drop a feature, narrow scope, switch the credential strategy) → re-render the plan and re-present the gate. Loop until they approve.
- On **approval**, emit a **scoped build directive** and hand off:
  - **Framework detected** → resolve `<family>` from `peers.yaml` (React web → `react-v7`; Angular → `angular-v5`; iOS → `ios`; React Native/Expo → `react-native`; Android → `android-v6`, reading `android_variant` from gradle files for cohort; Flutter → `flutter-v6`) and hand off to `cometchat-<family>-core` with the scoped surface (archetype + features + theming + scope + credential strategy + affected files), pulling in ONLY the additional SHIPPED skills the plan names (theming → `customization`, framework glue → `patterns`, features → `features`, voice/video → `calls`, **push → `cometchat-<family>-push`** (thin, docs-first), v6→v7 upgrade → `migration`). The core builds **UI Kit first** and, for any **SDK-backed feature** the plan flagged (AI agents · campaigns · advanced moderation · …), wires the **SDK method** looked up in `cometchat-<family>-core/references/docs-map.md` → SDK docs. The core owns detect-reuse, credentials, and the production-ready build. **Android extra:** cohort-split skills (`android_variant`: `views` → `kotlin-*`, `compose` → `compose-*`) pick `{kotlin,compose}-{components,placement,customization}`; cohort-neutral skills (`features`, `calls`, `push`, `production`, `testing`, `troubleshooting`, `builder-settings`, `events`, `extensions`, `migration`). Credentials → `app/src/main/assets/cometchat-settings.json` (gitignored), not `.env`.
  - **A framework with no shipped core detected** → still deliver the full discover→understand→plan, then state clearly that **that platform's implementation core isn't built yet** (framework-ready posture; see §Not in this pack). Do not fake an implementation.
> **Scoped, not the kitchen sink.** The directive names the SMALLEST surface the approved plan calls for (e.g. "1:1 chat surface for the marketplace, dev Auth-Key, touch `src/features/chat/*`"), so the core builds that — not every component.

## Calling-FIRST intent — the "add calling" decision tree
When the PRIMARY first-contact intent is **calling** ("add calling / voice-video / a video call" as the GOAL, not "add chat" that includes calls), run the **`references/calling-first.md`** decision tree instead of defaulting to the UI-Kit path — calling is the ONE intent where an approach choice is legitimate (standalone build-your-own-UI calling is a real product; a CHAT build still gets NO approach question). In brief: detect the UI Kit → offer **prebuilt** (`cometchat-<family>-calls`) vs **standalone from scratch**; if no UI Kit, ask *"chat too, or calling only?"*; for from-scratch, ask **one-on-one (ringing) vs meet-style**, then hand off to the platform's headless Calls SDK v5 skill (**`cometchat-js-v5-sdk`** web, **`cometchat-ios-v5-sdk`** iOS, **`cometchat-android-v5-calls-sdk`** Android, **`cometchat-react-native-v5-sdk`** React Native, **`cometchat-flutter-v5-sdk`** Flutter — resolved from `peers.yaml`, not a literal; not installed? `npx @cometchat/skills add --family <platform>-calls` adds it alongside) with the mode. Still run beats 1–3 + a short plan before hand-off.

## The hand-off boundary (REUSE the core; do NOT fork it)
This skill does **discover + understand + plan**. The framework core does **credentials + implement + verify**. The line is BEAT 4's approval:
- Onboarding OWNS: whole-repo discovery, intent elicitation with recommendations, the plan artifact, the modify/approve gate, the scoped directive.
- The core OWNS (do NOT restate or fork here): credential fetch/provision + env write (`references/setup-credentials.md`), init→login→render, component/prop selection, the production-ready build. It REUSES this discovery (re-reads the same signals + any `.cometchat` config, skips re-setup) — one detection approach, two consumers.

## Competitor SDK present (`migrate_from` non-null)
Name the vendor in the plan and offer the one-prompt migration; on "migrate"/"replace" hand straight to that entry's `skill` (no plan gate — it runs end-to-end). Never install CometChat alongside Sendbird/Stream silently.

## Re-entry (already-integrated repo)
If beat-1 discovery shows CometChat already wired for the current major (`existing_cometchat: true`, no `version_conflict`), do NOT re-run the full journey. Summarize what's already integrated, ask what the user wants to ADD or CHANGE, and route that incremental ask straight to the framework core (or the calls/features/customization skill it names) — onboarding is the FIRST-contact front door, not a gate on every subsequent change.

## Not in this pack — missing skills & not-yet-built cores (graceful-degrade posture)
**The rule: only hand off to a core/skill that SHIPS in this pack** — present under `skills/` and declared in `peers.yaml`. Never route to an uninstalled skill and never pretend it's there; run beats 1–3 in full, produce the plan artifact, and in beat 4 be honest and offer the nearest shipped alternative. **React, Angular, iOS, React Native, Android and Flutter all ship FULL sets** (`cometchat-<family>-core` + `-calls` · `-push` · `-migration` · …), plus the headless `cometchat-android-v5-sdk` (Android Chat SDK) and the from-scratch calling skills `cometchat-js-v5-sdk` (web) / `cometchat-ios-v5-sdk` (iOS) / `cometchat-android-v5-calls-sdk` (Android). Only apply this posture where a capability has genuinely NO shipped skill, or the platform has no `peers.yaml` peer (Vue today) — then deliver the plan as the hand-off spec and say the implementation skill isn't built yet. Never silently pretend React, and never decline a family that ships. **Per-platform routing table + how to word an honest decline: `references/not-in-this-pack.md`.**

## Common pitfalls
- **Writing code in beats 1–3.** The first write is post-approval, in the core. Onboarding that scaffolds before the plan is approved has skipped its own gate.
- **Asking "UI Kit or SDK?"** There is NO approach choice (calling-first excepted) — the UI Kit is always the UI layer, the SDK the per-feature FALLBACK inside the same build. Don't ask; map each feature to its component, or its SDK method where none exists.
- **Hand-rolling a feature that already exists.** Never build custom UI/logic for something the UI Kit has a component for, OR the SDK has a method for. Check the UI Kit first (`component-props.md` / catalog), then the SDK docs (`docs-map.md`). Hand-roll ONLY when neither has it.
- **Declining a family that ships.** calls + **push** + migration ARE installed on every family — route to them normally (`cometchat-<family>-calls` / `-push` / `-migration`). Apply the **§Not in this pack** posture ONLY where no skill ships, and never route an unknown platform to React by default.
- **Asking blank questions, or skipping features/design.** Beat 2 must cover archetype · WHICH features · HOW it looks (**auto/follow-OS [default]** · fixed light/dark · match design system · brand · custom) · scope, each WITH a repo-inferred recommendation. A bare "which archetype?" is under-delivery; omitting **auto/follow-OS** is a defect (AUDIT-042).
- **Forking the credential/detect flow.** Do NOT re-implement credentials or detection here — plan them, then let the core execute (the hand-off boundary above).
- **Over-scoping the directive.** Hand off the smallest surface the plan names, not the whole combined app (that's a later grow-on-request in the core).
- **Stalling on a missing signal.** Absent auth/framework/styling is recorded `null` and flows into a recommendation — never a blocker. (`version_conflict` on an *add* IS a STOP; a missing signal is not.)

## Verify before done (this skill's "done" = a good plan + a clean hand-off, NOT a running app)
Onboarding is complete when: (1) beat-1 discovery ran and every signal is captured or explicitly `null`; (2) every intent question (archetype · **features** · **design/theming** · scope) was asked WITH a repo-inferred recommendation and answered; (3) the plan artifact was presented containing ALL plan-completeness sections incl. **Feature coverage** (UI Kit component vs SDK method per feature) (`references/plan-artifact.md`); (4) the user approved (or edited → re-approved); (5) EITHER a scoped directive was handed to a SHIPPED core (`cometchat-<family>-core`), OR — where no skill ships for the platform/capability — the **§Not in this pack** posture was stated (honest + plan-as-spec + shipped alternative), never a hand-off to an uninstalled skill. This skill does NOT build, test, or run the app — the chosen core does the build (production-ready per its contract); testing is advisory/human unless the user asks (`RULES.md`).

## Deep references (load ONLY when the beat needs them — keeps this file thin)
- `references/archetypes.md` — the archetype → CometChat-capability map (1:1/marketplace · support · community · full-messenger · embedded) + the repo-signal → recommended-default heuristics for beat 2, and the intent→capability translation for the plan's "what you want".
- `references/plan-artifact.md` — the plan-artifact TEMPLATE (fill-in) + the **plan-completeness contract** (the seven sections the plan MUST contain) + a worked example.
- `references/calling-first.md` — the "add calling" decision tree (UI-Kit-present → prebuilt vs scratch; no-UI-Kit → chat-too? ; scratch → one-on-one vs meet → hand off per platform: web `cometchat-js-v5-sdk`, iOS `cometchat-ios-v5-sdk`, Android `cometchat-android-v5-calls-sdk`, React Native `cometchat-react-native-v5-sdk`). Load when the primary intent is calling.
- `references/not-in-this-pack.md` — the graceful-degrade posture in full: the per-platform table of which skills SHIP (so a shipped family is never declined) + how to word an honest decline. Load in beat 4 when a needed skill may not exist.
- `references/platforms.md` — the per-platform beat-1 signal columns (web · iOS · Android · React Native · Flutter) + the platform feature manifests.