cometchat-android-v6-migration— agent skill

Ground truth: the live page /ui-kit/android/upgrading-from-v5 (the authoritative breaking-change map — every mapping below is quoted from it) + catalog android-v6.json (what exists AFTER the upgrade) + COVERAGE.md (the v5→v6 verdict table). Removed/renamed v5 names appear in PROSE only — never emit a v5 symbol in a code fence.

⚠️ Before you touch code: a v5→v6 upgrade hits two build blockers the moment the new artifact resolves. Set android.useAndroidX=true + android.enableJetifier=true in gradle.properties (the Chat SDK still pulls a pre-AndroidX transitive → Duplicate class android.support.v4.*) and keep configurations.all { exclude(group = "org.jetbrains", module = "annotations-java5") }. Floors also rise: minSdk 28 · Kotlin 2.1 · AGP 8.9.1.

Companion skills (read first)

• cometchat-android-v6-core — the v6 install, credentials (assets/cometchat-settings.json), initFromSettings → login → render. The migration ENDS in core's golden path; this skill gets you there.
• After migrating: cometchat-android-v6-{kotlin,compose}-customization (styling moved), cometchat-android-v6-events (events moved).

Use this skill when

"upgrade our Android UI Kit from v5 to v6", "we're on the Java UI Kit, move us to Kotlin/Compose", "what breaks in v6?", "fix these v5 imports". This is reconciliation, not onboarding — a version_conflict is expected here and resolving it IS the job.

Prerequisites & install

Before touching code: confirm the current artifact + version, that the app builds, and minSdk. v6 requires minSdk 28 (v5 allowed 24) — if the app targets lower, that's a product decision to raise it; surface it FIRST, it can block the whole migration.

Breaking-change map (from the docs table)

Component renames — only ONE: CometChatThreadedMessagesHeader → `CometChatThreadHeader`. Everything else (CometChatConversations, CometChatUsers, CometChatGroups, CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer, CometChatIncomingCall, CometChatOutgoingCall, CometChatCallButtons, CometChatCallLogs, CometChatGroupMembers) keeps its name and only moves package.

Codemod / steps (in this order)

1. Decide the cohort — staying on XML Views (chatuikit-kotlin-android, smallest diff) or moving to Compose (chatuikit-compose-android, a UI rewrite of the chat screens). Ask; don't assume. Never ship both.
2. Raise minSdk to 28 and confirm Kotlin/AGP/JVM 11 are in place.
3. Swap the dependency to the 6.x artifact for the chosen cohort (+ the CometChat Maven repo, core §Install). Remove the v5 artifact — grep the build file for `com.cometchat:chat-uikit-android` (that is the v5 id) — entirely — a leftover v5 dependency is the duplicate-class/version_conflict failure.
4. Rewrite imports (the bulk of the diff, mechanical):

• com.cometchat.chatuikit.shared.cometchatuikit.CometChatUIKit → com.cometchat.uikit.core.CometChatUIKit (same for UIKitSettings).
• com.cometchat.chatuikit.<area>.<Component> → com.cometchat.uikit.kotlin.presentation.<area>.ui.<Component> (XML Views) or …uikit.compose.presentation.<area>.ui.<Component> (Compose).
• Grep targets: com.cometchat.chatuikit. (any hit is v5) and CometChatThreadedMessagesHeader (the one rename).

1. Migrate init to v6 — the v6 default is CometChatUIKit.initFromSettings(context, callback) reading app/src/main/assets/cometchat-settings.json, then login in onSuccess (core). Move credentials out of source while you're here.
2. Events — replace every addListener/removeListener pair with a CometChatEvents.<domain>Events.collect { } in lifecycleScope (Views) or LaunchedEffect (Compose). No manual removal (→ cometchat-android-v6-events).
3. State — LiveData.observe(...) → collecting StateFlow in a lifecycle-aware scope.
4. Styling/theming — style objects → theme attributes (themes.xml extending CometChatTheme.DayNight) or Compose style data classes (→ cometchat-android-v6-{kotlin,compose}-customization).
5. Compose only: rebuild the chat screens as composables (core's golden path / cometchat-android-v6-{kotlin,compose}-placement recipes) — XML layouts hosting kit views don't carry over.
6. Build, then run — fix per component using the docs page's "Component-by-Component Migration" section (fetch it: /ui-kit/android/upgrading-from-v5.md).

Before → after patterns

// V5 (Java) — imports + init
import com.cometchat.chatuikit.shared.cometchatuikit.CometChatUIKit;
import com.cometchat.chatuikit.conversations.CometChatConversations;

// V6 (Kotlin, XML Views cohort)
import com.cometchat.uikit.core.CometChatUIKit
import com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations

// V6 events — the old addListener/removeListener pair becomes a scoped collect
lifecycleScope.launch {
    CometChatEvents.messageEvents.collect { event -> /* when (event) { … } */ }
}

The thread header is the one rename to grep for; everything else is a package move. Full per-component diffs (Conversations, Users, Groups, Message Header/List/Composer): the docs page's component sections.

Common pitfalls

Leaving the v5 artifact in the tree (duplicate classes) · mixing both v6 cohorts · missing the minSdk 28 bump · migrating imports but keeping LiveData observers · keeping addListener/removeListener for UI-Kit events (now flows) · missing the CometChatThreadedMessagesHeader → CometChatThreadHeader rename · carrying v5 style objects forward · keeping the classic init(...) instead of moving to initFromSettings · assuming Compose is a drop-in for XML screens · migrating code but leaving credentials hardcoded.

Verify it works

Zero matches for com.cometchat.chatuikit. and CometChatThreadedMessagesHeader in the source; only ONE cometchat UI-Kit artifact resolves (./gradlew :app:dependencies); the fence gate compiles (./gradlew :app:assembleDebug # in YOUR app (npm run verify:fences:android-v6 is a pack-repo gate)). On device: init + login succeed, conversations → messages works, threads/search round-trip, events fire once, theming still matches the brand, calls/push (if used) still work. Any capability that existed in v5 and has no v6 equivalent must be reported to the user, not silently dropped — see COVERAGE.md.