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.

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; full-page · embedded · sidebar · popup. Default to the SMALLEST reasonable production-ready surface, never the kitchen sink. 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.

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.