awl-debug integration

Type	Skill
Plugin	awl-android · v0.0.19
Invoke	/awl-android:debug-sdk-integration
Source	plugins/awl-android/skills/debug-sdk-integration/SKILL.md

When Claude uses it

Integrates the awl-debug Android debug panel (com.appswithlove.debug, 0.6.0 debug/debug-no-op split from Maven Central) into an Android or KMP app and configures its modules. Use when the user says “add awl-debug”, “add the debug panel”, “integrate DevSheet”, “expose the auth token in the debug sheet”, “add deeplinks to the dev tool”, “show the FCM token in debug”, or “migrate awl-debug to 0.6.0”. NOT for iOS debug tooling, for general Timber or OkHttp setup without the panel, or for building custom debug screens from scratch.

Trigger phrases: add awl-debug · add the debug panel · integrate DevSheet · expose the auth token in the debug sheet · add deeplinks to the dev tool · show the FCM token in debug · migrate awl-debug to 0.6.0

Definition

awl-debug is a Jetpack Compose debug panel that opens as a bottom sheet on a three-finger tap (two-finger on emulators). It ships built-in modules for logs, HTTP traffic, performance, permissions, accessibility, deeplinks, sessions, FCM token, and crash simulation.

Since 0.6.0 it ships as two artifacts with the same public API, so the integration code lives in the main source set and the build variant picks the real or inert one:

Artifact	Wire into	Behaviour
com.appswithlove.debug:debug	debug-like variants	Full panel
com.appswithlove.debug:debug-no-op	release-like variants	DevSheet only renders content, no gesture, no log collection

Both resolve from Maven Central and pull in com.appswithlove.debug:debug-api transitively. No private Maven repository or GitLab token is needed.

Workflow

Step	Do	Detail
0	Ask the four questions below	this file
1	Add the dependency to the version catalog and app module	this file
2	Wrap the root composable in DevSheet	this file
3	Configure modules for the answers from step 0	references/modules.md
4	Route logs and HTTP traffic into the panel	references/logging.md
5	Wire the activation toggle	references/activation.md
6	Reformat, build, report	this file

Read references/api-reference.md when you need the full DevSheet signature, import list, the 0.5.x to 0.6.0 package migration, constraints, or the public symbol table.

0. Ask before writing code

Use askUserQuestionTool and wait for all four answers:

1. Existing debug tool (“Does the project already have a debug tool?”). If yes, ask whether to move its content into customModules, remove it, or leave it. Moving means re-implementing its UI inside the customModules lambda after step 2 and deleting the old entry points; removing means deleting it before you start.
2. Activation mode (“Always reachable via the gesture, or behind a toggle?”). A toggle belongs on the Settings screen if one exists. See references/activation.md.
3. Authentication (“Does the app have session tokens to expose?”). Drives the session module.
4. HTTP client (“Does the app use OkHttp?”). Drives the HTTP interceptor.

1. Gradle setup

settings.gradle.kts needs only google() and mavenCentral() in dependencyResolutionManagement. If the project still carries the old gitlab.appswithlove.net/api/v4/groups/android-infra/-/packages/maven block or a gitLabPrivateToken check for awl-debug, remove both unless another dependency still uses them.

Do not create source sets or build variants. Map existing variants instead: development-like ones get debug, shipping ones get debug-no-op. Every variant that compiles the integration code needs one of the two, so projects with flavors add the matching <flavor>Implementation lines.

With a version catalog (gradle/libs.versions.toml, preferred):

[versions]
awlDebug = "0.6.0"

[libraries]
awl-debug = { module = "com.appswithlove.debug:debug", version.ref = "awlDebug" }
awl-debug-no-op = { module = "com.appswithlove.debug:debug-no-op", version.ref = "awlDebug" }

// androidApp/build.gradle.kts (or app/build.gradle.kts)
dependencies {
    debugImplementation(libs.awl.debug)
    releaseImplementation(libs.awl.debug.no.op)
}

Without a catalog:

dependencies {
    debugImplementation("com.appswithlove.debug:debug:0.6.0")
    releaseImplementation("com.appswithlove.debug:debug-no-op:0.6.0")
}

Run a Gradle sync and confirm it succeeds before continuing.

2. Wrap the root composable

The AWL templates keep the wrapper in its own composable (dev/DevWrapper.kt) and call it from App(), so the panel config stays out of the UI tree:

import com.appswithlove.debug.api.DevConfig
import com.appswithlove.debug.api.DevModulesConfig
import com.appswithlove.debug.ui.dev.sheet.DevSheet

@Composable
fun DevWrapper(content: @Composable () -> Unit) {
    DevSheet(
        devConfig = DevConfig(
            versionName = BuildConfig.VERSION_NAME,
            versionCode = BuildConfig.VERSION_CODE,
            flavor = BuildConfig.FLAVOR,
            buildType = BuildConfig.BUILD_TYPE,
        ),
        modulesConfig = DevModulesConfig(
            showSessionModule = false,      // step 3 decides
            showFcmPushTokenModule = false,
        ),
        isAlwaysActive = true,              // step 5 decides
        content = content,
    )
}

Add imports explicitly. IDE auto-import for library classes tends to fail until the first successful build. Only content is required; customModules takes extra composable content at the bottom of the sheet. Pass no viewModel or logHistory, because the no-op artifact omits those parameters and the call has to compile against both.

3. Configure modules

Decide from the answers in step 0:

Answer	Config
No authentication	showSessionModule = false
Authentication	implement SessionProvider per token, pass via sessionProviders
No FCM	leave fcmTokenProvider = null (module hides itself)
FCM	implement FcmTokenProvider; Firebase stays in the app
Deeplinks known	deeplinks = listOf(DeeplinkItem(label, url))

Full DevModulesConfig fields and provider examples: references/modules.md.

4. Logging

Plant DevLogTree only if Timber is already a dependency, because the library declares it compileOnly. Add DevHttpLogInterceptor only if the app has an OkHttp client. Otherwise log manually through LogCollector. Snippets and severity mapping: references/logging.md.

5. Activation

The panel is off after a fresh install unless isAlwaysActive = true. The template sets it to true; production apps usually want a toggle backed by DevSettings. Toggle snippet and observation API: references/activation.md. Tell the user where you placed the toggle.

6. Finish

1. Reformat the changed Kotlin files (Reformat Code in the IDE).
2. Resolve unresolved imports or syntax errors.
3. Run a Gradle build for a debug variant and a release variant, so both artifacts compile.

Report the integration as complete only after both builds pass.