choose-service-shape

Choose Server-Side JVM Shape

Purpose

Pick the smallest correct JVM backend shape before code changes begin.

The practical decision is whether the work belongs in Java, Scala, future Clojure, a shared JVM library, a service framework, a build-tool maintenance pass, or a handoff to Android guidance.

When To Use

• Use this skill when the user wants JVM backend work but has not chosen Java, Scala, framework, or build shape.
• Use this skill before scaffolding or restructuring a JVM service.
• Use this skill when a repository contains both Android and backend JVM code and ownership is ambiguous.
• Use this skill when the user asks for a functional JVM default and the repository has no stronger language convention.

Source Check

Use repo-local JVM files, checked-out dependency sources, Dash MCP or Dash HTTP for installed JVM docsets, and then official or canonical documentation when Dash/local coverage is missing or stale. Check one of those source-specific paths before making claims about JVM, language, build, or framework behavior:

• Java documentation
• OpenJDK documentation
• Scala documentation
• Gradle User Manual
• Maven documentation
• SBT Reference Manual

Translate any documentation rule into the concrete repository decision it changes.

Classification Workflow

1. Inspect the repository shape:
   • settings.gradle, settings.gradle.kts, build.gradle, build.gradle.kts
   • pom.xml
   • build.sbt, project/
   • gradle.properties
   • .java-version, .sdkmanrc, .tool-versions
   • src/main/java, src/main/scala, src/test/java, src/test/scala
   • Dockerfile, compose.yaml, docker-compose.yml
   • existing CI commands
   • Android markers such as AndroidManifest.xml, com.android.application, or com.android.library
2. Identify the user-visible job:
   • Java service
   • Scala service
   • future Clojure service
   • shared JVM library
   • Gradle, Maven, or SBT multi-module project
   • framework-specific service
   • testing, packaging, CI, upgrade, or diagnostics pass
3. Route Android work away from this plugin when the task is app/platform-specific:
   • Android app modules
   • Android Gradle Plugin configuration
   • manifests, resources, signing, emulator, device, or Play release work
   • Java/Kotlin interop inside Android modules
4. Choose language intentionally:
   • Ask for language preference when the user has not chosen and repo context is mixed or empty.
   • Prefer Scala when the user asks for a functional JVM default and no existing Java framework or team convention dominates.
   • Prefer Java when the repository is Java-dominant and the requested change belongs inside that existing surface.
   • Use mixed Java and Scala only when the boundary is useful and explicit.
   • Keep Clojure as a future candidate unless the repository already uses Clojure or the user explicitly asks for it.
5. Choose validation:
   • Gradle wrapper projects: ./gradlew test or narrower tasks from the changed module.
   • Maven projects: mvn test or narrower module commands.
   • SBT projects: sbt test or scoped project/test commands.
   • Dependency or toolchain issue: run the restore/compile phase before behavior tests.

Recommendations

Java Service

Use Java guidance when the repository is Java-first, the framework defaults to Java, or the change belongs inside an existing Java service.

Handoff:

• server-side-jvm:build-java-service for implementation
• server-side-jvm:build-tooling-workflow for Gradle, Maven, or SBT wiring
• server-side-jvm:testing-workflow for tests

Scala Service

Use Scala guidance when the repository is Scala-first, the user wants functional JVM design, or the service benefits from immutable data and explicit effect or async boundaries.

Handoff:

• server-side-jvm:build-scala-service for implementation
• server-side-jvm:build-tooling-workflow for Gradle, Maven, or SBT wiring
• server-side-jvm:testing-workflow for tests

Shared JVM Library

Use a shared library when Android, backend, CLI, or multiple services need the same non-platform-specific behavior. Keep Android APIs out of a shared non-Android JVM library unless the module is explicitly Android-owned.

Framework-Specific Service

Preserve the existing framework. If starting fresh, decide the framework from constraints first:

• Spring Boot, Micronaut, or Quarkus for broad Java ecosystem support.
• http4s, ZIO HTTP, Akka/Pekko, or Play when the repository is Scala-first and the team accepts those ecosystem choices.
• Framework-neutral modules for domain logic that should not depend on routing or persistence adapters.

Output Shape

Return:

1. Chosen shape: Java service, Scala service, future Clojure service, shared JVM library, framework-specific service, or maintenance pass.
2. Language decision: Java, Scala, mixed, future Clojure, or user decision needed.
3. Build owner: Gradle, Maven, SBT, wrapper command, and relevant modules.
4. Framework fit: existing framework, recommended framework, or framework-neutral.
5. Validation path: exact build and test commands.
6. Next skill: the next server-side JVM or Android skill to use.

Guardrails

• Do not silently choose Java when the user asks for functional JVM work and the repo has no stronger default.
• Do not describe Scala as secondary or niche.
• Do not make Android app/platform work server-side JVM-owned just because it uses Java or Gradle.
• Do not add a new framework, module, or mixed-language boundary without naming the concrete problem it solves.
• Do not publish or deploy by default.