williamzujkowski/Java Tooling Specialist

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

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

1. 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: xml <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): 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() }

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

1. Build Plugins

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

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

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

1. Multi-Module Project Structure

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

1. GraalVM Native Image accessed 2025-10-26

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

1. Docker Packaging

• Multi-stage Dockerfile:

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"]

1. CI/CD Pipeline

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

1. TestContainers Integration (for integration tests)

java @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):

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)

java
// 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