java-scaffold

name	java-scaffold
description	Scaffolding for Java projects with Spring Boot or Quarkus, PostgreSQL, RabbitMQ, and LangChain4j AI. Generates pom.xml, BCE package structure, Flyway migrations, architecture tests (Taikai), and application code. Supports AI business applications with LangChain4j (AI Services, Tools/Function Calling, RAG, Guardrails). Use this skill for new Java applications, new entities, architecture tests, AI services, or AI integrations – also for "create a new project", "scaffold", "new module", "new entity", "AI Service", "Chatbot", "RAG", "LangChain4j". For Dockerfiles, docker-compose, and infrastructure, use the infrastructure skill.
argument-hint	[framework] [description]

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

#	Field	Example
1	groupId	com.example.orders
2	artifactId	order-service
3	Framework	Spring Boot or Quarkus

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:

Service	Dependency (Spring)	Dependency (Quarkus)	Default
Database (PostgreSQL)	spring-boot-starter-data-jpa, postgresql, spring-boot-starter-flyway, flyway-database-postgresql	quarkus-hibernate-orm-panache, quarkus-jdbc-postgresql, Flyway	Yes
REST / Swagger UI	springdoc-openapi-starter-webmvc-ui	quarkus-smallrye-openapi	Yes (always for REST)
Messaging (RabbitMQ)	spring-boot-starter-amqp	quarkus-messaging-rabbitmq	No
Auth / IAM (Keycloak)	spring-boot-starter-oauth2-resource-server	quarkus-oidc	No

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:

#	Field	Options	Default
1	LLM Provider	OpenAI, Ollama (local), Anthropic (Claude)	OpenAI
2	AI Features	Chat (simple AI service), Tools (function calling), RAG (document search), Guardrails (input/output validation), Agents (agentic workflows)	Chat
3	RAG Vector Store (only for RAG)	PgVector (PostgreSQL), Chroma, Redis	PgVector
4	Fault Tolerance (production)	Yes / No	No

AI Profile Overview (Quarkus):

Profile	Description	Dependencies	Templates
Chat	Simple AI service with system/user prompt	quarkus-langchain4j-{provider}	AiService, AiResource
Chat + Tools	AI service with function calling (DB access, REST calls)	+ no extra dep (part of core)	+ AiTool
Chat + RAG	AI service with document search (vector database)	+ quarkus-langchain4j-pgvector	+ RagIngestion, RagRetriever
Chat + Guardrails	AI service with input/output validation	+ no extra dep (part of core)	+ AiGuardrail
Agentic	Autonomous agents with workflow orchestration	+ quarkus-langchain4j-agentic	Agent, AgentWorkflow
Fault Tolerant	Production-ready setup with retry/timeout/fallback	+ quarkus-smallrye-fault-tolerance	AiServiceWithFaultTolerance, AiServiceFallback
Complete	All features combined	All above	All templates

Step 2 – Version Check

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

Artifact	Where to check
Spring Boot Parent POM	https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-parent
Quarkus BOM	https://mvnrepository.com/artifact/io.quarkus.platform/quarkus-bom
Taikai	https://central.sonatype.com/artifact/com.enofex/taikai
versions-maven-plugin	https://mvnrepository.com/artifact/org.codehaus.mojo/versions-maven-plugin
quarkus-langchain4j	https://mvnrepository.com/artifact/io.quarkiverse.langchain4j/quarkus-langchain4j-openai

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

Artifact	Version	Java 25 compatible
Spring Boot	4.0.3	Yes (full Java 25 support)
Quarkus	3.31.4	Yes (full Java 25 support since 3.31)
Taikai	1.60.0	Yes
versions-maven-plugin	2.21.0	Yes
quarkus-langchain4j	1.8.0.CR1	Yes (check before generation!)

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

Provider	Dependency (groupId:artifactId)	Version
OpenAI (or compatible API)	io.quarkiverse.langchain4j:quarkus-langchain4j-openai	Part of Quarkiverse BOM
Ollama (local)	io.quarkiverse.langchain4j:quarkus-langchain4j-ollama	Part of Quarkiverse BOM
Anthropic (Claude)	io.quarkiverse.langchain4j:quarkus-langchain4j-anthropic	Part of Quarkiverse BOM

RAG – Vector Store (only for RAG feature):

Store	Dependency	Note
PgVector	io.quarkiverse.langchain4j:quarkus-langchain4j-pgvector	Uses existing PostgreSQL DB
Easy RAG	io.quarkiverse.langchain4j:quarkus-langchain4j-easy-rag	Simplest variant, auto-ingestion from directory
Chroma	io.quarkiverse.langchain4j:quarkus-langchain4j-chroma	External service needed
Redis	io.quarkiverse.langchain4j:quarkus-langchain4j-redis	External service needed

Agentic Workflows (only for agents feature):

Feature	Dependency	Note
Agentic	io.quarkiverse.langchain4j:quarkus-langchain4j-agentic	@Agent, workflow patterns
MCP Client	io.quarkiverse.langchain4j:quarkus-langchain4j-mcp	Remote tools via Model Context Protocol

Fault Tolerance (recommended for production):

Feature	Dependency	Note
Fault Tolerance	io.quarkus:quarkus-smallrye-fault-tolerance	@Timeout, @Retry, @Fallback

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:

Provider	API Key Property	Model Property
OpenAI	quarkus.langchain4j.openai.api-key	quarkus.langchain4j.openai.chat-model.model-name
Ollama	(no key needed)	quarkus.langchain4j.ollama.chat-model.model-id
Anthropic	quarkus.langchain4j.anthropic.api-key	quarkus.langchain4j.anthropic.chat-model.model-name

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:

Framework	Dependency (groupId:artifactId)	Swagger UI URL	OpenAPI JSON URL
Spring Boot	org.springdoc:springdoc-openapi-starter-webmvc-ui	/swagger-ui.html	/v3/api-docs
Quarkus	io.quarkus:quarkus-smallrye-openapi	/q/swagger-ui	/q/openapi

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:

Framework	Endpoint	Dependency
Spring Boot	/actuator/health	spring-boot-starter-actuator
Quarkus	/q/health/live, /q/health/ready	quarkus-smallrye-health

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

File	Description
.claude/lessons-learned.md	Findings and corrections – check before every generation
templates/spring/	Spring Boot templates (Entity, Controller, Service, Consumer, Security, Dockerfile, Properties, docker-compose)
templates/quarkus/	Quarkus templates (Entity, Resource, Service) + src-main-docker/ for Dockerfiles
templates/quarkus/ai/	Quarkus AI templates (AI Service, Tools, RAG, Guardrails, Properties, docker-compose)
templates/arch/ArchitectureTest.java.template	Taikai-based architecture test (incl. AI layer rules)
templates/db/V1__create_table.sql.template	Initial Flyway migration
templates/renovate.json	Renovate configuration for automatic dependency updates

AI Templates (Quarkus + LangChain4j)

Template	Package	Description
AiService.java.template	boundary.ai	Simple declarative AI service (@RegisterAiService)
AiServiceWithTools.java.template	boundary.ai	AI service with @ToolBox integration
AiServiceWithRag.java.template	boundary.ai	AI service with RAG (RetrievalAugmentor)
AiTool.java.template	control.ai	Tool class with @Tool annotation for function calling
RagIngestion.java.template	control.ai	Document ingestion at startup (EmbeddingStore)
RagRetriever.java.template	control.ai	RetrievalAugmentor supplier for PgVector
AiGuardrail.java.template	control.ai	Input/output guardrails for validation
Agent.java.template	boundary.ai	Autonomous agent with @Agent and @ToolBox
AgentWorkflow.java.template	boundary.ai	Workflow orchestration (Sequence, Parallel, Loop, Supervisor)
AiServiceWithFaultTolerance.java.template	boundary.ai	AI service with @Timeout, @Retry, @Fallback
AiServiceFallback.java.template	control.ai	Fallback handler for LLM failures
AiResource.java.template	boundary.rest	REST endpoint /ai/chat for the AI service
application-ai.properties	–	AI-specific properties (provider, RAG, guardrails)
docker-compose-ai.yml	–	Docker Compose with PgVector and optional Ollama

Placeholders

Placeholder	Example
{{GROUP_ID}}	com.example.orders
{{ARTIFACT_ID}}	order-service
{{PACKAGE_PATH}}	com/example/orders
{{ENTITY_NAME}}	Order
{{ENTITY_NAME_LOWER}}	order
{{CHANNEL_IN}}	orders-in
{{CHANNEL_OUT}}	orders-out
{{AI_SERVICE_NAME}}	OrderAssistant
{{TOOL_CLASS_NAME}}	OrderTools
{{TOOL_METHOD_NAME}}	findOrderById
{{RAG_INGESTION_CLASS}}	DocumentIngestion
{{RAG_RETRIEVER_CLASS}}	DocumentRetriever
{{INPUT_GUARDRAIL_NAME}}	InputValidator
{{AI_RESOURCE_NAME}}	AiResource
{{AGENT_NAME}}	OrderAgent
{{AGENT_DESCRIPTION}}	Order specialist
{{AGENT_TASK_DESCRIPTION}}	Process the following order request
{{WORKFLOW_NAME}}	OrderWorkflow
{{DOMAIN_DESCRIPTION}}	Order management

---

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