Cometchat Onboarding

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.