Java Scaffold

Java Scaffold Skill

Scaffolding for Java projects with Spring Boot or Quarkus – including AI support via LangChain4j.

Philosophy: Before every generation: check lessons-learned.md + query current versions from the internet – never use outdated versions from memory.

What This Skill Does

1. Queries project coordinates – groupId, artifactId, framework (Spring Boot / Quarkus)
2. Checks current versions – Verify Spring Boot, Quarkus, Taikai, LangChain4j online
3. Generates project structure – pom.xml, application.properties
4. Creates BCE layers – Entity, Repository, Service, Controller/Resource in BCE pattern
5. Creates AI layers (optional) – AI Service, Tools, RAG, Guardrails via LangChain4j
6. Creates Flyway migration – Initial SQL schema matching the entity
7. Creates Swagger UI + health check configuration
8. Creates architecture tests – Taikai-based ArchitectureTest (incl. AI layer rules)
9. Creates Renovate config – automatic dependency update PRs

Note: Dockerfiles, docker-compose, and other infrastructure are handled by the infrastructure.

How to Use

Create a new Quarkus project with PostgreSQL and AI support (LangChain4j)

Create a business application with chatbot and RAG (document search)

Create a new Spring Boot project with PostgreSQL and RabbitMQ

Create a new entity "Product" with name and price

Generate an AI service with tool integration for my Quarkus project

Instructions

Before every generation:

1. Check .claude/lessons-learned.md
2. Query current versions from the internet (Maven Central / GitHub Releases) – never use outdated versions from memory!

Step 1 – Required Query

Before every new application or module – if not already known – always ask all the following questions before generating code:

1a – Project Coordinates

1b – OpenAPI Spec Available? (optional)

Ask before scaffolding: Is there an OpenAPI specification for this project?

• Yes → run openapi first; then during scaffold do not regenerate boundary/rest/ and entity/dto/ – only the framework (pom.xml, docker-compose, application.properties, Flyway, architecture test, Dockerfile).
• No → proceed normally, generate all layers.

1c – Required Services

Explicitly ask which services are actually needed:

Only confirmed services are included in pom.xml, docker-compose.yml, and application.properties. Unneeded services are omitted entirely – no commented-out blocks.

Never guess or use defaults – always ask explicitly.

1d – AI Support (LangChain4j) – optional

Ask: Should the application include AI functionality (LLM integration)?

If Yes, query the following details:

AI Profile Overview (Quarkus):

Step 2 – Version Check

Outdated dependency versions lead to incompatibilities and security vulnerabilities. Therefore, check current versions online before every code generation:

Known versions (as of 2026-03-01 – always verify online!):

Quarkus 3.27 (LTS) technically runs with Java 25 but produces warnings. For Java 25, Quarkus 3.31+ is required.

Step 3 – Generate Code

Generation order:

1. pom.xml with all dependencies, versions-maven-plugin, Taikai
2. application.properties (DB, Flyway, health, optionally messaging, auth, AI)
3. Entity + Repository (entity/)
4. Service (control/)
5. Controller/Resource (boundary/rest/)
6. Consumer (boundary/messaging/) – only if RabbitMQ confirmed
7. Security config – only if Keycloak confirmed
8. AI Service (boundary/ai/) – only if AI support confirmed
9. AI Tools (control/ai/) – only if tools confirmed
10. RAG Components (control/ai/) – only if RAG confirmed
11. Guardrails (control/ai/) – only if guardrails confirmed
12. AI REST Endpoint (boundary/rest/) – if AI support confirmed
13. Flyway migration (db/migration/V1__create_<entity>_table.sql)
14. Architecture test (ArchitectureTest.java) – incl. AI layer rules if AI support
15. renovate.json

Next step: Run infrastructure to generate Dockerfile, docker-compose, and other infrastructure.

Step 3a – AI Dependencies (Quarkus + LangChain4j)

For AI support, include the following dependencies in pom.xml:

LLM Provider (choose exactly ONE):

RAG – Vector Store (only for RAG feature):

Agentic Workflows (only for agents feature):

Fault Tolerance (recommended for production):

Quarkiverse BOM – use the BOM instead of individual versions:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkiverse.langchain4j</groupId>
            <artifactId>quarkus-langchain4j-bom</artifactId>
            <version><!-- CHECK BEFORE GENERATION: https://mvnrepository.com/artifact/io.quarkiverse.langchain4j/quarkus-langchain4j-bom --></version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Step 3b – AI Package Structure (BCE)

AI components follow the BCE pattern with dedicated sub-packages:

src/main/java/{{GROUP_ID}}/
├── boundary/
│   ├── ai/              ← AI Services (@RegisterAiService interfaces)
│   ├── rest/            ← REST endpoints (incl. AI resource)
│   └── messaging/       ← RabbitMQ consumers (optional)
├── control/
│   ├── ai/              ← AI Tools, RAG, Guardrails
│   └── ...              ← Business services
└── entity/
    └── ...              ← JPA entities, DTOs

Architecture rules for AI layers:

• @RegisterAiService interfaces → boundary/ai/
• @Tool classes → control/ai/
• RAG components (ingestion, retriever) → control/ai/
• Guardrails → control/ai/
• AI REST endpoints → boundary/rest/

Step 3c – AI application.properties

Use AI-specific properties from template templates/quarkus/ai/application-ai.properties as reference. When generating, only include the chosen provider – the template contains all three providers as reference, but only the chosen provider is included in the generated application.properties (without commented-out alternatives).

Important configuration per provider:

Disable AI Dev Services (real services via Docker Compose):

quarkus.langchain4j.ollama.devservices.enabled=false

Step 4 – Swagger UI

Every application with REST endpoints gets a Swagger UI:

Check versions before generation:

• Spring Boot: https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui
• Quarkus: Part of the Quarkus BOM – no separate version needed

Important with Security (Spring Boot): The SecurityConfig must explicitly permit Swagger UI paths (already included in template):

.requestMatchers("/swagger-ui/**", "/swagger-ui.html", "/v3/api-docs/**").permitAll()

Important for Quarkus: Enable quarkus.swagger-ui.always-include=true so the Swagger UI remains available in production mode (not just quarkus:dev).

Step 5 – Health Checks

Health endpoints are the foundation for Docker health checks and Kubernetes probes. Without them, neither Docker nor an orchestrator can check the application's state:

Health checks are used in:

• HEALTHCHECK in Dockerfile
• healthcheck in docker-compose.yml

Step 6 – Architecture Tests

Architecture tests with Taikai ensure that BCE layer separation is maintained even as the project grows. Template: templates/arch/ArchitectureTest.java.template

For AI projects, the ArchitectureTest contains additional rules:

• @RegisterAiService interfaces must reside in boundary.ai
• @Tool classes must reside in control.ai

<dependency>
    <groupId>com.enofex</groupId>
    <artifactId>taikai</artifactId>
    <version><!-- CHECK CURRENT VERSION BEFORE GENERATION: https://central.sonatype.com/artifact/com.enofex/taikai --></version>
    <scope>test</scope>
</dependency>

Step 7 – versions-maven-plugin

The versions-maven-plugin enables developers to detect outdated dependencies locally – complementing Renovate for the CI/CD workflow. Configure in every pom.xml in the <build><pluginManagement> block:

<build>
  <pluginManagement>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version><!-- CURRENT VERSION: https://mvnrepository.com/artifact/org.codehaus.mojo/versions-maven-plugin --></version>
        <configuration>
          <generateBackupPoms>false</generateBackupPoms>
        </configuration>
      </plugin>
    </plugins>
  </pluginManagement>
</build>

Useful commands for developers:

./mvnw versions:display-dependency-updates
./mvnw versions:display-plugin-updates
./mvnw versions:display-parent-updates

Step 8 – Renovate

Renovate automatically creates pull requests for dependency updates and keeps the project current. Every generated project receives renovate.json from templates/renovate.json.

References

AI Templates (Quarkus + LangChain4j)

Placeholders

Conventions

• Stack: Java 25 · Spring Boot 4.x or Quarkus 3.31+ · PostgreSQL 17 · RabbitMQ 4 · Keycloak 26.x · Maven 3.9 · Docker
• AI Stack: Quarkus LangChain4j · OpenAI / Ollama / Anthropic · PgVector (RAG)
• Architecture: BCE pattern strict (Boundary / Control / Entity)
• AI Architecture: AI Services in boundary/ai/, Tools + RAG + Guardrails in control/ai/
• Entities: Lombok @Data + @Builder – maven-compiler-plugin must configure Lombok as annotationProcessorPath
• Persistence: Flyway for all migrations – no ddl-auto=create
• Messaging: RabbitMQ consumers always in boundary/messaging/; Quarkus: @Blocking + @Transactional for DB access in consumers
• AI Tools: @Blocking + @Transactional for database access in tools
• Examples: Domain-neutral (order, product, event, item)
• Language: English in comments/docs and code
• Commits: Conventional Commits (feat:, fix:, docs:, chore:)
• Co-Author: @author Co-Author: Claude (claude-sonnet-4-6, Anthropic) – generated via java-scaffold

Position in Workflow

[spec-feature]      optional – business requirements
        |
[openapi]           if OpenAPI spec available
        |
[java-scaffold]     application: pom.xml, BCE, AI, Flyway
        |
[infrastructure]    Dockerfile, docker-compose, Helm
        |
[review]            code review
        |
[doc]               project documentation