java-tooling-specialist

name	Java Tooling Specialist
slug	tooling-java-generator
description	Generate Java project scaffolding with Maven/Gradle, JUnit 5, Mockito, Checkstyle/SpotBugs, and packaging (JAR/WAR/native-image).
capabilities	["Project structure generation (library, application, Spring Boot, microservice)","Build tool setup (Maven, Gradle, multi-module)","Testing framework configuration (JUnit 5, Mockito, TestContainers)","Code quality tools (Checkstyle, SpotBugs, PMD, Error Prone)","Packaging and distribution (JAR, WAR, Docker, GraalVM native-image)","CI/CD integration (GitHub Actions, Jenkins)"]
inputs	[{"project_type":"library | application | spring-boot | microservice (string)"},{"build_tool":"maven | gradle (string)"},{"java_version":"11 | 17 | 21 (string)"},{"project_name":"Name of the project (string)"}]
outputs	[{"project_structure":"Directory layout with all config files (JSON)"},{"build_config":"Complete pom.xml or build.gradle configuration"},{"ci_config":"GitHub Actions or Jenkins pipeline (YAML)"},{"dockerfile":"Multi-stage Dockerfile (optional)"}]
keywords	["java","tooling","maven","gradle","junit","spring-boot","mockito","checkstyle","packaging"]
version	1.0.0
owner	cognitive-toolworks
license	MIT
security	Public; no secrets or PII; safe for open repositories
links	["https://maven.apache.org/guides/","https://docs.gradle.org/current/userguide/userguide.html","https://junit.org/junit5/docs/current/user-guide/","https://spring.io/projects/spring-boot","https://www.graalvm.org/latest/reference-manual/native-image/"]

Purpose & When-To-Use

Trigger conditions:

• Starting a new Java project requiring modern tooling
• Migrating legacy Java projects to contemporary best practices (Java 11+)
• Standardizing build configuration across multiple Java projects
• Setting up Spring Boot microservices with testing infrastructure
• Creating multi-module Maven/Gradle projects

Not for:

• Android projects (use tooling-kotlin-generator instead)
• Legacy Java 8 projects (use framework-specific generators)
• Simple scripts without dependencies

---

Pre-Checks

Time normalization:

• Compute NOW_ET using NIST/time.gov semantics (America/New_York, ISO-8601)
• Use NOW_ET for all citation access dates

Input validation:

• project_type must be one of: library, application, spring-boot, microservice
• build_tool must be one of: maven, gradle
• java_version must be one of: 11, 17, 21 (LTS versions)
• project_name must be valid Java package name (lowercase, dots/hyphens allowed)

Source freshness:

• Maven docs must be accessible accessed 2025-10-26
• Gradle docs must be accessible accessed 2025-10-26
• JUnit 5 docs must be accessible accessed 2025-10-26
• Spring Boot docs must be accessible accessed 2025-10-26

---

Procedure

T1: Basic Project Structure (≤2k tokens)

Fast path for common cases:

1. Directory Layout Generation

   • Maven standard directory structure:

     project-name/
       src/
         main/
           java/com/example/project/
           resources/
         test/
           java/com/example/project/
           resources/
       pom.xml (Maven) or build.gradle (Gradle)
       README.md
       .gitignore
     

2. Core Build Configuration

   • Maven (pom.xml) accessed 2025-10-26
     • Project metadata (groupId, artifactId, version)
     • Java version configuration (maven.compiler.source/target)
     • Basic dependencies (JUnit 5, logging)
   • Gradle (build.gradle) accessed 2025-10-26
     • Plugins: java-library, application
     • Java toolchain configuration
     • Dependency management

3. Basic .gitignore

   • Build outputs (target/, build/, *.class)
   • IDE files (.idea/, *.iml, .vscode/)
   • OS files (.DS_Store)

Decision: If only basic scaffolding needed → STOP at T1; otherwise proceed to T2.

---

T2: Full Tooling Setup (≤6k tokens)

Extended configuration with testing and quality tools:

1. Testing Framework Configuration

   JUnit 5 + Mockito accessed 2025-10-26

   Maven dependencies:

   <dependency>
     <groupId>org.junit.jupiter</groupId>
     <artifactId>junit-jupiter</artifactId>
     <version>5.10.1</version>
     <scope>test</scope>
   </dependency>
   <dependency>
     <groupId>org.mockito</groupId>
     <artifactId>mockito-core</artifactId>
     <version>5.8.0</version>
     <scope>test</scope>
   </dependency>
   <dependency>
     <groupId>org.mockito</groupId>
     <artifactId>mockito-junit-jupiter</artifactId>
     <version>5.8.0</version>
     <scope>test</scope>
   </dependency>
   

   Gradle (build.gradle):

   dependencies {
       testImplementation 'org.junit.jupiter:junit-jupiter:5.10.1'
       testImplementation 'org.mockito:mockito-core:5.8.0'
       testImplementation 'org.mockito:mockito-junit-jupiter:5.8.0'
   }
   
   test {
       useJUnitPlatform()
   }
   

2. Code Quality Tools

   Checkstyle accessed 2025-10-26

   • Maven plugin configuration
   • Google Java Style or Sun checks

   SpotBugs accessed 2025-10-26

   • Static analysis for bug patterns
   • Integration with Maven/Gradle

   PMD (optional)

   • Code quality rules
   • Copy-paste detection (CPD)

3. Build Plugins

   • maven-surefire-plugin (test execution)
   • maven-failsafe-plugin (integration tests)
   • jacoco-maven-plugin (code coverage)
   • maven-enforcer-plugin (dependency convergence)

4. Spring Boot Configuration (if project_type == spring-boot)

   <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
     <version>3.2.0</version>
   </parent>
   

---

T3: Packaging and Distribution (≤12k tokens)

Deep configuration for production deployment:

1. JAR/WAR Packaging accessed 2025-10-26

   • Executable JAR with manifest (Main-Class, Class-Path)
   • Fat JAR with maven-shade-plugin or gradle shadow plugin
   • WAR for servlet containers

2. Multi-Module Project Structure

   • Parent POM with dependency management
   • Module structure (api, core, service, integration-tests)
   • Build reactor configuration

3. GraalVM Native Image accessed 2025-10-26

   • native-maven-plugin configuration
   • Reflection configuration (reflect-config.json)
   • Resource configuration
   • Build optimizations

4. Docker Packaging

   • Multi-stage Dockerfile:

     FROM maven:3.9-eclipse-temurin-21 AS build
     WORKDIR /app
     COPY pom.xml .
     RUN mvn dependency:go-offline
     COPY src src
     RUN mvn package -DskipTests
     
     FROM eclipse-temurin:21-jre-alpine
     COPY --from=build /app/target/*.jar app.jar
     ENTRYPOINT ["java", "-jar", "/app.jar"]
     

5. CI/CD Pipeline

   • GitHub Actions workflow (build, test, package, deploy)
   • Jenkins declarative pipeline
   • SonarQube integration
   • Artifact publishing (Maven Central, GitHub Packages)

6. TestContainers Integration (for integration tests)

   @Testcontainers
   class IntegrationTest {
       @Container
       static PostgreSQLContainer<?> postgres =
           new PostgreSQLContainer<>("postgres:16-alpine");
   }
   

---

Decision Rules

Build Tool Selection:

• Maven: Enterprise projects, strict dependency management, plugin ecosystem
• Gradle: Modern build performance, Kotlin DSL, flexible configuration

Project Type Structure:

• library: JAR packaging, no main class, extensive testing
• application: Executable JAR, main class, CLI or batch processing
• spring-boot: Spring Boot parent POM, auto-configuration, embedded server
• microservice: Spring Boot + Docker + health checks + observability

Abort Conditions:

• Invalid project_name (contains spaces, uppercase, invalid chars) → error
• Unsupported java_version (<11) → error "Minimum Java 11 required"
• Conflicting configuration (WAR + GraalVM) → error with alternatives

Tool Version Selection:

• Use latest stable LTS Java version (11, 17, 21)
• Pin test dependencies, use version ranges for compile deps (Maven)
• Use Gradle version catalog for multi-module projects

---

Output Contract

Schema (JSON):

{
  "project_name": "string",
  "project_type": "library | application | spring-boot | microservice",
  "java_version": "string",
  "build_tool": "maven | gradle",
  "structure": {
    "directories": ["string"],
    "files": {
      "path/to/file": "file content (string)"
    }
  },
  "commands": {
    "build": "string",
    "test": "string",
    "package": "string",
    "run": "string (optional)"
  },
  "next_steps": ["string"],
  "timestamp": "ISO-8601 string (NOW_ET)"
}

Required Fields:

• project_name, project_type, java_version, build_tool, structure, commands, next_steps, timestamp

File Contents:

• All generated files must be syntactically valid (XML, Gradle, Java)
• Include inline comments explaining non-obvious configuration
• Reference official documentation in comments

---

Examples

Quick Start: Java Library (30 lines)

// examples/LibraryExample.java
package com.example.utils;

import java.time.Instant;
import java.util.*;

public final class StringMetrics {
    public record Metrics(int length, int wordCount, Instant analyzed) {}

    private final List<String> history = new ArrayList<>();

    public Metrics analyze(String text) {
        if (text == null || text.isBlank()) {
            throw new IllegalArgumentException("Text cannot be null or blank");
        }
        history.add(text);
        int wordCount = text.split("\\s+").length;
        return new Metrics(text.length(), wordCount, Instant.now());
    }

    public List<String> getHistory() {
        return Collections.unmodifiableList(history);
    }
}

Additional Examples:

• CLI Tool: examples/CliExample.java (30 lines) - picocli, file I/O, exit codes
• Spring Boot API: examples/ApiExample.java (36 lines) - REST endpoints, records, concurrent storage

Template Resources (see resources/)

• Maven: pom-library.xml / pom-cli.xml / pom-springboot.xml
• Gradle: build-library.gradle / build-cli.gradle / build-springboot.gradle
• Testing: ExampleTest.java - JUnit 5 with modern assertions

---

Quality Gates

Token Budgets:

• T1: ≤2k tokens (basic structure + core build config)
• T2: ≤6k tokens (full tooling: testing, quality, Spring Boot)
• T3: ≤12k tokens (packaging, multi-module, native-image, CI/CD)

Safety:

• No hardcoded credentials or API keys
• .gitignore always includes sensitive file patterns
• Docker images use non-root users

Auditability:

• All tool configurations cite official documentation
• Version constraints are explicit (no floating versions)
• Generated files include generation timestamp and tool versions

Determinism:

• Same inputs → identical file structure and configuration
• Tool versions pinned to specific releases
• No randomness in file generation

Performance:

• T1 generation: <1 second
• T2 generation: <3 seconds (includes all configs)
• T3 generation: <5 seconds (includes Docker, CI/CD)

---

Resources

Official Documentation (accessed 2025-10-26):

1. Maven Documentation - Build tool and POM reference
2. Gradle User Guide - Build automation
3. JUnit 5 User Guide - Testing framework
4. Spring Boot Documentation - Framework reference
5. GraalVM Native Image - Native compilation
6. Checkstyle - Code style checking
7. SpotBugs - Static analysis
8. Testcontainers - Integration testing

Build Tools:

• Maven Central Repository - Dependency search
• Gradle Plugin Portal - Gradle plugins
• Maven Wrapper - Portable builds
• Gradle Wrapper - Version management

Best Practices:

• Google Java Style Guide - Code formatting
• Effective Java (3rd Edition) - Best practices
• Spring Boot Best Practices - Framework patterns