android-sdd 1.0.0

package/skills/Google Ecosystem/Analytics/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: analytics
+description: >
+  Firebase Analytics setup and event tracking for Android.
+  Load this skill when implementing event tracking, screen tracking,
+  user properties, conversion funnels, or integrating analytics
+  with the app's architecture.
+---
+
+# Analytics
+
+## Overview
+Firebase Analytics provides free, unlimited event tracking for Android apps. It automatically tracks some events (first_open, session_start) and allows custom events. Events appear in the Firebase console and can be forwarded to Google Analytics, BigQuery, and Ads.
+
+---
+
+## Core Principles
+
+- Analytics must be **disabled in debug builds** — dev events pollute production data
+- Track **meaningful user actions** — not every tap, only business-relevant events
+- Use a **centralized analytics wrapper** — never call Firebase directly from UI
+- Define an **event taxonomy** before implementation — consistent naming is critical
+- User PII (name, email) must **never** be sent as event parameters
+
+---
+
+## Setup
+
+```kotlin
+dependencies {
+    implementation(platform(libs.firebase.bom))
+    implementation(libs.firebase.analytics)
+}
+```
+
+---
+
+## Analytics Wrapper
+
+```kotlin
+// ✅ Centralized wrapper — never call FirebaseAnalytics directly from UI/ViewModel
+interface Analytics {
+    fun logEvent(event: AnalyticsEvent)
+    fun setUserId(userId: String?)
+    fun setUserProperty(name: String, value: String?)
+    fun logScreenView(screenName: String, screenClass: String)
+}
+
+class FirebaseAnalyticsImpl @Inject constructor(
+    @ApplicationContext context: Context
+) : Analytics {
+
+    private val firebaseAnalytics = FirebaseAnalytics.getInstance(context)
+
+    override fun logEvent(event: AnalyticsEvent) {
+        firebaseAnalytics.logEvent(event.name, event.toBundle())
+    }
+
+    override fun setUserId(userId: String?) {
+        firebaseAnalytics.setUserId(userId)
+    }
+
+    override fun setUserProperty(name: String, value: String?) {
+        firebaseAnalytics.setUserProperty(name, value)
+    }
+
+    override fun logScreenView(screenName: String, screenClass: String) {
+        firebaseAnalytics.logEvent(FirebaseAnalytics.Event.SCREEN_VIEW) {
+            param(FirebaseAnalytics.Param.SCREEN_NAME, screenName)
+            param(FirebaseAnalytics.Param.SCREEN_CLASS, screenClass)
+        }
+    }
+}
+
+// ✅ No-op implementation for debug builds
+class NoOpAnalytics @Inject constructor() : Analytics {
+    override fun logEvent(event: AnalyticsEvent) = Unit
+    override fun setUserId(userId: String?) = Unit
+    override fun setUserProperty(name: String, value: String?) = Unit
+    override fun logScreenView(screenName: String, screenClass: String) = Unit
+}
+```
+
+---
+
+## Event Taxonomy
+
+```kotlin
+// ✅ Sealed class for type-safe event definitions
+sealed class AnalyticsEvent(val name: String) {
+
+    abstract fun toBundle(): Bundle
+
+    // Auth events
+    object Login : AnalyticsEvent("login") {
+        override fun toBundle() = bundleOf(
+            FirebaseAnalytics.Param.METHOD to "email"
+        )
+    }
+
+    object Logout : AnalyticsEvent("logout") {
+        override fun toBundle() = Bundle.EMPTY
+    }
+
+    data class SignUp(val method: String) : AnalyticsEvent("sign_up") {
+        override fun toBundle() = bundleOf(
+            FirebaseAnalytics.Param.METHOD to method
+        )
+    }
+
+    // Content events
+    data class ViewItem(val itemId: String, val itemName: String, val category: String)
+        : AnalyticsEvent(FirebaseAnalytics.Event.VIEW_ITEM) {
+        override fun toBundle() = bundleOf(
+            FirebaseAnalytics.Param.ITEM_ID to itemId,
+            FirebaseAnalytics.Param.ITEM_NAME to itemName,
+            FirebaseAnalytics.Param.ITEM_CATEGORY to category
+        )
+    }
+
+    data class Search(val query: String) : AnalyticsEvent(FirebaseAnalytics.Event.SEARCH) {
+        override fun toBundle() = bundleOf(
+            FirebaseAnalytics.Param.SEARCH_TERM to query
+        )
+    }
+
+    // Error events
+    data class ErrorOccurred(val errorType: String, val errorMessage: String)
+        : AnalyticsEvent("error_occurred") {
+        override fun toBundle() = bundleOf(
+            "error_type" to errorType,
+            "error_message" to errorMessage.take(100)  // max 100 chars
+        )
+    }
+
+    // Feature usage
+    data class FeatureUsed(val featureName: String) : AnalyticsEvent("feature_used") {
+        override fun toBundle() = bundleOf("feature_name" to featureName)
+    }
+}
+```
+
+---
+
+## Usage in ViewModel
+
+```kotlin
+// ✅ Log events from ViewModel — not from Compose/UI
+@HiltViewModel
+class ProductViewModel @Inject constructor(
+    private val repository: ProductRepository,
+    private val analytics: Analytics
+) : ViewModel() {
+
+    fun onProductViewed(product: Product) {
+        analytics.logEvent(
+            AnalyticsEvent.ViewItem(
+                itemId = product.id,
+                itemName = product.name,
+                category = product.category
+            )
+        )
+    }
+
+    fun onSearchPerformed(query: String) {
+        analytics.logEvent(AnalyticsEvent.Search(query))
+    }
+}
+```
+
+---
+
+## Screen Tracking
+
+```kotlin
+// ✅ Track screen views automatically via Navigation
+@Composable
+fun AppNavHost(navController: NavHostController, analytics: Analytics) {
+
+    val currentEntry by navController.currentBackStackEntryAsState()
+
+    LaunchedEffect(currentEntry) {
+        currentEntry?.destination?.route?.let { route ->
+            analytics.logScreenView(
+                screenName = route,
+                screenClass = route
+            )
+        }
+    }
+
+    NavHost(navController, startDestination = HomeRoute) {
+        // routes...
+    }
+}
+```
+
+---
+
+## User Properties
+
+```kotlin
+// ✅ Set stable user attributes for segmentation
+class UserAnalyticsManager @Inject constructor(private val analytics: Analytics) {
+
+    fun onUserLoggedIn(user: User) {
+        analytics.setUserId(user.id)
+        analytics.setUserProperty("account_type", user.accountType)
+        analytics.setUserProperty("subscription_plan", user.plan)
+        // ❌ Never set PII
+        // analytics.setUserProperty("email", user.email)  // WRONG
+    }
+
+    fun onUserLoggedOut() {
+        analytics.setUserId(null)
+    }
+}
+```
+
+---
+
+## Hilt Binding by Build Type
+
+```kotlin
+// ✅ Inject NoOp in debug, real impl in release
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class AnalyticsModule {
+
+    @Binds
+    @Singleton
+    abstract fun bindAnalytics(
+        // Switch based on build type
+        impl: FirebaseAnalyticsImpl  // or NoOpAnalytics in debug flavor
+    ): Analytics
+}
+
+// ✅ Better — use BuildConfig
+@Module
+@InstallIn(SingletonComponent::class)
+object AnalyticsModule {
+
+    @Provides
+    @Singleton
+    fun provideAnalytics(@ApplicationContext context: Context): Analytics =
+        if (BuildConfig.DEBUG) NoOpAnalytics()
+        else FirebaseAnalyticsImpl(context)
+}
+```
+
+---
+
+## Event Naming Rules
+
+```
+✅ snake_case — user_signed_up, product_viewed, checkout_started
+✅ Max 40 characters for event name
+✅ Max 25 parameters per event
+✅ Max 100 characters for parameter value (strings)
+❌ No spaces, no special characters except underscore
+❌ No reserved prefixes: firebase_, google_, ga_
+❌ No PII in any parameter
+```
+
+---
+
+## Anti-Patterns
+
+- Calling `FirebaseAnalytics` directly from Composable — not testable, hard to disable
+- Logging analytics in debug builds — pollutes production dashboards
+- Sending PII (email, name, phone) as event parameters — compliance violation
+- Tracking every user interaction — noise, hard to find signal
+- Inconsistent event names (`user_login` vs `login_user` vs `userLogin`) — breaks funnels
+- No event taxonomy document — events drift over time, become meaningless
+
+---
+
+## Related Skills
+- `firebase` — Firebase core setup
+- `crashlytics` — crash reporting alongside analytics
+- `remote-config` — feature flags informed by analytics
+- `side-effect-management` — analytics as a side effect in ViewModel

package/skills/Google Ecosystem/Crashlytics/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: crashlytics
+description: >
+  Firebase Crashlytics setup and usage for Android crash reporting.
+  Load this skill when configuring Crashlytics, logging custom events,
+  adding user context to crash reports, or handling non-fatal errors.
+---
+
+# Crashlytics
+
+## Overview
+Firebase Crashlytics is a real-time crash reporter that helps track, prioritize, and fix stability issues. It automatically captures fatal crashes and provides detailed stack traces, device info, and custom context. Non-fatal errors can also be reported manually.
+
+---
+
+## Core Principles
+
+- **Disable** Crashlytics in debug builds — don't pollute production data with dev crashes
+- Add **user context** before crashes happen — userId, screen, and key attributes help diagnose
+- Report **non-fatal errors** explicitly — caught exceptions that indicate problems
+- Use **custom keys** to add state context — what the user was doing before the crash
+- Always pair Crashlytics with **proper logging** — crash reports alone miss context
+
+---
+
+## Setup
+
+```kotlin
+// build.gradle.kts (app)
+plugins {
+    alias(libs.plugins.firebase.crashlytics)
+}
+
+dependencies {
+    implementation(platform(libs.firebase.bom))
+    implementation(libs.firebase.crashlytics)
+}
+```
+
+---
+
+## Enable / Disable by Build Type
+
+```kotlin
+// ✅ Disable in debug — only report in release
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        FirebaseCrashlytics.getInstance()
+            .setCrashlyticsCollectionEnabled(!BuildConfig.DEBUG)
+    }
+}
+```
+
+---
+
+## User Context
+
+```kotlin
+// ✅ Set user identity — helps group crashes by user
+class CrashlyticsUserTracker @Inject constructor() {
+
+    fun setUser(userId: String, email: String?) {
+        FirebaseCrashlytics.getInstance().apply {
+            setUserId(userId)
+            email?.let { setCustomKey("user_email", it) }
+        }
+    }
+
+    fun clearUser() {
+        FirebaseCrashlytics.getInstance().apply {
+            setUserId("")
+            setCustomKey("user_email", "")
+        }
+    }
+}
+```
+
+---
+
+## Custom Keys — State Context
+
+```kotlin
+// ✅ Log app state before a crash
+class CrashlyticsContext @Inject constructor() {
+
+    fun setScreen(screenName: String) {
+        FirebaseCrashlytics.getInstance()
+            .setCustomKey("current_screen", screenName)
+    }
+
+    fun setFeatureFlag(key: String, value: Boolean) {
+        FirebaseCrashlytics.getInstance()
+            .setCustomKey("flag_$key", value)
+    }
+
+    fun setApiEndpoint(endpoint: String) {
+        FirebaseCrashlytics.getInstance()
+            .setCustomKey("last_api_endpoint", endpoint)
+    }
+
+    fun setDatabaseVersion(version: Int) {
+        FirebaseCrashlytics.getInstance()
+            .setCustomKey("db_version", version)
+    }
+}
+```
+
+---
+
+## Breadcrumb Logging
+
+```kotlin
+// ✅ Log events leading up to a crash
+class CrashlyticsLogger @Inject constructor() {
+
+    fun log(message: String) {
+        FirebaseCrashlytics.getInstance().log(message)
+    }
+
+    fun logUserAction(action: String) {
+        FirebaseCrashlytics.getInstance().log("USER_ACTION: $action")
+    }
+
+    fun logNetworkCall(endpoint: String, statusCode: Int) {
+        FirebaseCrashlytics.getInstance()
+            .log("NETWORK: $endpoint -> $statusCode")
+    }
+}
+```
+
+---
+
+## Non-Fatal Error Reporting
+
+```kotlin
+// ✅ Report caught exceptions that indicate a problem
+class UserRepository @Inject constructor(
+    private val crashlytics: CrashlyticsLogger
+) {
+    suspend fun getUser(id: String): Result<User> {
+        return try {
+            val user = api.getUser(id)
+            Result.success(user.toDomain())
+        } catch (e: HttpException) {
+            if (e.code() == 500) {
+                // ✅ Server errors are worth tracking
+                FirebaseCrashlytics.getInstance().recordException(e)
+            }
+            Result.failure(e)
+        } catch (e: Exception) {
+            // ✅ Unexpected exceptions always reported
+            FirebaseCrashlytics.getInstance().recordException(e)
+            Result.failure(e)
+        }
+    }
+}
+
+// ✅ In global error handler
+class GlobalExceptionHandler @Inject constructor() {
+
+    fun report(throwable: Throwable, context: String) {
+        FirebaseCrashlytics.getInstance().apply {
+            setCustomKey("error_context", context)
+            recordException(throwable)
+        }
+    }
+}
+```
+
+---
+
+## Integration with Timber
+
+```kotlin
+// ✅ Route Timber ERROR logs to Crashlytics
+class CrashlyticsTree : Timber.Tree() {
+    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
+        if (priority < Log.ERROR) return
+
+        FirebaseCrashlytics.getInstance().apply {
+            tag?.let { setCustomKey("log_tag", it) }
+            log(message)
+            t?.let { recordException(it) }
+        }
+    }
+}
+
+// Plant in Application
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        if (BuildConfig.DEBUG) {
+            Timber.plant(Timber.DebugTree())
+        } else {
+            Timber.plant(CrashlyticsTree())
+        }
+    }
+}
+```
+
+---
+
+## Testing Crashes
+
+```kotlin
+// ✅ Force a test crash (debug only)
+if (BuildConfig.DEBUG) {
+    Button(onClick = {
+        FirebaseCrashlytics.getInstance().log("Test crash triggered")
+        throw RuntimeException("Test crash")
+    }) {
+        Text("Test Crash")
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Enabling Crashlytics in debug builds — pollutes crash data with dev noise
+- No user context — impossible to reproduce user-specific crashes
+- Reporting every caught exception — noise drowns out real issues; be selective
+- No custom keys — crash report without state context is hard to diagnose
+- Not logging breadcrumbs — no trail of events leading to the crash
+
+---
+
+## Related Skills
+- `firebase` — Firebase core setup
+- `analytics` — event tracking alongside crash reporting
+- `logging` — structured logging complementing Crashlytics
+- `error-handling` — error handling policy across layers

package/skills/Google Ecosystem/Firebase/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: firebase
+description: >
+  Firebase setup and core configuration for Android.
+  Load this skill when initializing Firebase, configuring google-services.json,
+  setting up multiple Firebase environments (dev/prod), or integrating Firebase
+  into a multi-module project.
+---
+
+# Firebase
+
+## Overview
+Firebase is Google's app development platform providing backend services — authentication, messaging, crash reporting, analytics, remote config, and more. Each service is a separate SDK added independently. The core setup is shared across all Firebase services.
+
+---
+
+## Core Principles
+
+- One `google-services.json` per app variant — dev and prod must use separate Firebase projects
+- Initialize Firebase **once** in `Application.onCreate()` — never in Activity or Fragment
+- Use **separate Firebase projects** for debug and release — never mix environments
+- Add only the Firebase SDKs you actually use — each adds APK size and startup overhead
+- Never commit `google-services.json` with production credentials to public repos
+
+---
+
+## Setup
+
+```toml
+[versions]
+firebase-bom = "33.5.1"
+google-services = "4.4.2"
+
+[libraries]
+firebase-bom = { module = "com.google.firebase:firebase-bom", version.ref = "firebase-bom" }
+# Individual SDKs — version managed by BOM
+firebase-analytics    = { module = "com.google.firebase:firebase-analytics-ktx" }
+firebase-crashlytics  = { module = "com.google.firebase:firebase-crashlytics-ktx" }
+firebase-messaging    = { module = "com.google.firebase:firebase-messaging-ktx" }
+firebase-auth         = { module = "com.google.firebase:firebase-auth-ktx" }
+firebase-config       = { module = "com.google.firebase:firebase-config-ktx" }
+
+[plugins]
+google-services  = { id = "com.google.gms.google-services", version.ref = "google-services" }
+firebase-crashlytics = { id = "com.google.firebase.crashlytics", version = "3.0.2" }
+```
+
+```kotlin
+// build.gradle.kts (root)
+plugins {
+    alias(libs.plugins.google.services) apply false
+    alias(libs.plugins.firebase.crashlytics) apply false
+}
+
+// build.gradle.kts (app)
+plugins {
+    alias(libs.plugins.google.services)
+    alias(libs.plugins.firebase.crashlytics)
+}
+
+dependencies {
+    implementation(platform(libs.firebase.bom))  // ✅ BOM manages all versions
+    implementation(libs.firebase.analytics)
+    implementation(libs.firebase.crashlytics)
+    implementation(libs.firebase.messaging)
+}
+```
+
+---
+
+## Application Setup
+
+```kotlin
+// ✅ Firebase auto-initializes via ContentProvider — no manual init needed
+// FirebaseApp.initializeApp() is called automatically
+
+@HiltAndroidApp
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        // Firebase is already initialized here
+        // Configure per-service settings if needed
+    }
+}
+```
+
+---
+
+## Multiple Environments (Dev / Prod)
+
+```
+// ✅ Separate google-services.json per build variant
+app/
+├── src/
+│   ├── debug/
+│   │   └── google-services.json    ← dev Firebase project
+│   └── release/
+│       └── google-services.json    ← prod Firebase project
+```
+
+```kotlin
+// ✅ Or configure via build flavors
+android {
+    flavorDimensions += "environment"
+    productFlavors {
+        create("dev") {
+            dimension = "environment"
+            applicationIdSuffix = ".dev"
+        }
+        create("prod") {
+            dimension = "environment"
+        }
+    }
+}
+
+// Files:
+// app/src/dev/google-services.json
+// app/src/prod/google-services.json
+```
+
+---
+
+## Manual Firebase App Initialization (Multi-Module / KMP)
+
+```kotlin
+// ✅ When automatic initialization isn't sufficient
+val options = FirebaseOptions.Builder()
+    .setApiKey(BuildConfig.FIREBASE_API_KEY)
+    .setApplicationId(BuildConfig.FIREBASE_APP_ID)
+    .setProjectId(BuildConfig.FIREBASE_PROJECT_ID)
+    .build()
+
+FirebaseApp.initializeApp(context, options, "secondary")
+val secondaryApp = Firebase.app("secondary")
+val secondaryDb = Firebase.database(secondaryApp)
+```
+
+---
+
+## Hilt Integration
+
+```kotlin
+// ✅ Provide Firebase services via Hilt
+@Module
+@InstallIn(SingletonComponent::class)
+object FirebaseModule {
+
+    @Provides
+    @Singleton
+    fun provideFirebaseAnalytics(): FirebaseAnalytics =
+        FirebaseAnalytics.getInstance(get())  // or inject context
+
+    @Provides
+    @Singleton
+    fun provideFirebaseRemoteConfig(): FirebaseRemoteConfig =
+        FirebaseRemoteConfig.getInstance().also { config ->
+            config.setConfigSettingsAsync(
+                remoteConfigSettings {
+                    minimumFetchIntervalInSeconds = if (BuildConfig.DEBUG) 0 else 3600
+                }
+            )
+        }
+}
+```
+
+---
+
+## Disable Firebase in Debug
+
+```kotlin
+// ✅ Disable analytics and crashlytics in debug builds
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        if (BuildConfig.DEBUG) {
+            FirebaseAnalytics.getInstance(this).setAnalyticsCollectionEnabled(false)
+            FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(false)
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Single Firebase project for dev and prod — production data polluted with test events
+- Committing `google-services.json` with prod keys to public repo — security risk
+- Initializing Firebase in Activity — causes multiple initializations
+- Adding all Firebase SDKs without using them — increases APK size and startup time
+- Not using BOM — version conflicts between Firebase SDKs
+
+---
+
+## Related Skills
+- `firebase-messaging` — push notifications with FCM
+- `crashlytics` — crash reporting setup
+- `analytics` — event tracking
+- `remote-config` — feature flags from Firebase
+- `firebase-auth` — authentication (not in current skill list — add if needed)