---
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.