/java-android-workflow

name: java-android-workflow
description: Maintain Java-only Android projects and Kotlin/Java interoperability inside Android apps or libraries, including Java source sets, AndroidX Java APIs, annotations, nullability, SAM boundaries, generated bytecode expectations, public API compatibility, tests, lint, and migration guardrails.
license: Apache-2.0
compatibility: Designed for Codex and compatible Agent Skills clients working with Java Android projects or mixed Kotlin/Java Android modules.
metadata:
  owner: gaelic-ghost
  repo: socket
  category: android-java
allowed-tools: Read Edit Bash(rg:*) Bash(git:*) Bash(java:*) Bash(javac:*) Bash(./gradlew:*) Bash(gradle:*)

Java Android Workflow

Purpose

Preserve Java Android codebases and make Kotlin/Java boundaries explicit when Android modules are mixed-language.

The practical decision is whether to stay Java-only, add Kotlin interop carefully, or route implementation to Kotlin-first guidance without forcing a migration.

Source Check

Use repo-local Java, Kotlin, Gradle, and Android files first. Use Dash.app Java or Gradle docsets opportunistically for installed local reference. Use official documentation as authority for Android-specific APIs, Kotlin Java interop, AndroidX behavior, and version-sensitive rules:

• [Android Developers documentation](https://developer.android.com/docs)
• [Java documentation](https://docs.oracle.com/en/java/)
• [Kotlin Java interoperability documentation](https://kotlinlang.org/docs/java-interop.html)
• [AndroidX documentation](https://developer.android.com/jetpack/androidx)
• [Android build documentation](https://developer.android.com/build)

Translate documentation into concrete API, annotation, source-set, or validation choices.

Inspection Workflow

1. Inspect source ownership:

• `src/main/java`
• `src/main/kotlin`
• generated sources
• public Android library APIs
• Java callers of Kotlin code and Kotlin callers of Java code

2. Identify interop boundaries:

• nullability annotations
• `@JvmName`, `@JvmOverloads`, `@JvmStatic`, `@JvmField`, or `@Throws`
• SAM conversions and functional interfaces
• checked exceptions and callback APIs
• data classes, sealed classes, objects, companion objects, and generated bytecode as seen from Java

3. Preserve Java-only projects:

• keep Java examples and implementation idiomatic for the existing codebase
• do not add Kotlin plugin or Kotlin sources without user approval
• keep AndroidX and Java language level aligned with repo configuration

4. Maintain mixed projects:

• keep public APIs friendly from both languages when they already cross the boundary
• use annotations for nullability and threading where the repo already does
• keep generated binding, Room, Hilt, KSP, KAPT, or annotation processing behavior explicit

5. Validate:

• compile or assemble the affected module
• run unit tests that exercise the Java/Kotlin boundary
• run lint when annotations, threading, lifecycle, resources, or Android APIs changed

Implementation Guidance

• Prefer Java implementation in Java-dominant Android modules.
• Prefer Kotlin implementation in Kotlin-dominant modules unless Java API compatibility owns the change.
• Keep Android callbacks, listeners, and lifecycle methods readable from the language that owns the file.
• Preserve binary and source compatibility for Android libraries unless the user approves a breaking change.
• Document migration decisions in repo-facing docs only when the task changes project policy.

Output Shape

Return:

1. `Language owner`: Java-only, Kotlin-first, mixed, or migration decision needed. 2. `Interop boundary`: APIs, annotations, generated code, callbacks, nullability, or bytecode concerns. 3. `Affected modules`: module, source set, public APIs, tests, and generated sources. 4. `Validation path`: exact Gradle commands. 5. `Risk`: migration, binary compatibility, annotation processing, nullability, or public API risk.

Guardrails

• Do not rewrite Java Android code to Kotlin just because Kotlin is preferred for new Android work.
• Do not add Kotlin to a Java-only project without an explicit user decision.
• Do not expose awkward Kotlin APIs to Java callers when public interop matters.
• Do not drop nullability, threading, or lifecycle annotations casually.
• Do not route backend Java services through this skill.