# Avaje — AI Agent & LLM Instructions

> Avaje is a suite of compile-time Java libraries: avaje-nima (web framework), avaje-inject (DI), avaje-config (configuration), avaje-jsonb (JSON), and avaje-simple-logger (logging).

## Agent Skills (recommended)

For installation, usage, and skill selection see:
**https://avaje.io/agent-skills/**

Source repository:
**https://github.com/avaje/skills**

Install with:
```bash
git clone https://github.com/avaje/skills.git ~/.agents/avaje-skills
mkdir -p ~/.agents/skills
ln -sf ~/.agents/avaje-skills/avaje-nima ~/.agents/skills/avaje-nima
ln -sf ~/.agents/avaje-skills/avaje-inject ~/.agents/skills/avaje-inject
ln -sf ~/.agents/avaje-skills/avaje-config ~/.agents/skills/avaje-config
ln -sf ~/.agents/avaje-skills/avaje-jsonb ~/.agents/skills/avaje-jsonb
ln -sf ~/.agents/avaje-skills/avaje-simple-logger ~/.agents/skills/avaje-simple-logger
```

Works with [pi](https://github.com/mariozechner/pi-coding-agent), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), and any [Agent Skills](https://agentskills.io) compatible harness.

---

## avaje-nima — Helidon SE web framework
- [Multi-module architecture](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/multi-module-architecture.md)
- [JVM Docker build (Jib)](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/add-jvm-docker-jib.md)
- [Native image Docker build (Jib)](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/add-native-docker-jib.md)
- [Global exception handler](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/add-global-exception-handler.md)
- [Controller testing](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/add-controller-test.md)
- [Exception handling](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/exception-handling.md)
- [Dependency injection](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/dependency-injection.md)
- [Filters](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/filters.md)
- [Controller basics](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/controller-basics.md)
- [Validation](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/validation.md)
- [Deployment](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/deployment.md)
- [Testing](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/testing.md)
- [Native image](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/native-image.md)
- [Troubleshooting](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/troubleshooting.md)

## Always check AGENTS.md and the guide index before automating or generating code for avaje-nima projects.

## Full Guide Index

- [Guide index](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/README.md): Full index of avaje-nima guides, including setup, controllers, testing, Docker, native image, and troubleshooting.
- [Archetype scaffolding](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/archetype-getting-started.md)
- [Multi-module architecture](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/multi-module-architecture.md)
- [JVM Docker build (Jib)](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/add-jvm-docker-jib.md)
- [Native image Docker build (Jib)](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/add-native-docker-jib.md)
- [Global exception handler](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/add-global-exception-handler.md)
- [Controller testing](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/add-controller-test.md)
- [Exception handling](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/exception-handling.md)
- [Dependency injection](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/dependency-injection.md)
- [Filters](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/filters.md)
- [Controller basics](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/controller-basics.md)
- [Validation](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/validation.md)
- [Deployment](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/deployment.md)
- [Testing](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/testing.md)
- [Native image](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/native-image.md)
- [Troubleshooting](https://raw.githubusercontent.com/avaje/avaje-nima/HEAD/docs/guides/troubleshooting.md)

---

## avaje-nima — Helidon SE web framework

**AI Agent Guide:**
- **Best for**: REST APIs, microservices, cloud-native applications, GraalVM native images, high-performance web services
- **Not for**: GraphQL APIs, heavy ORM workloads, traditional Servlet applications
- **Minimum Java**: 11+ | **Current**: 2.2.2
- **Key annotations**: @Controller, @Get/@Post/@Put/@Delete, @Path, @ExceptionHandler, @Filter, @Inject
- **Copilot instructions**: [avaje-nima Copilot guide](https://raw.githubusercontent.com/avaje/avaje-nima/main/docs/guides/README.md)

**Common AI Tasks:**
- Create REST controller: [overview](https://avaje.io/nima/#first-controller)
- Add exception handler: [guide](https://raw.githubusercontent.com/avaje/avaje-nima/main/docs/guides/add-global-exception-handler.md)
- Test with @InjectTest: [testing](https://avaje.io/nima/#testing)
- Build native image: [guide](https://raw.githubusercontent.com/avaje/avaje-nima/main/docs/guides/add-native-docker-jib.md)
- Add filters: [documentation](https://avaje.io/nima/#filters)

**Reference:

**Reference:**
- [avaje-nima overview](https://avaje.io/nima/): Getting started — dependencies, first controller, the Nima bootstrap class, testing, GraalVM native image
- [avaje-nima archetypes](https://avaje.io/nima/archetypes): Maven archetype to bootstrap a new avaje-nima project with one command
- [avaje-nima guides](https://avaje.io/nima/guides): Index of step-by-step guides for common tasks
- [avaje-nima error handlers](https://avaje.io/nima/#error-handlers): How to add a global exception handler using @Controller + @ExceptionHandler
- [avaje-nima filters](https://avaje.io/nima/#filters): Request/response filters with @Filter
- [avaje-nima testing](https://avaje.io/nima/#testing): Integration testing controllers with avaje-nima-test and @InjectTest
- [avaje-nima GraalVM native image](https://avaje.io/nima/#graalvm): native-maven-plugin and Jib configuration for native Docker images
- [Guide: avaje-nima archetype scaffolding](https://raw.githubusercontent.com/avaje/avaje-nima/main/docs/guides/archetype-getting-started.md): Step-by-step — generate a new avaje-nima project with Maven archetype, understanding project structure, compilation, and customization patterns
- [Guide: avaje-nima global exception handler](https://raw.githubusercontent.com/avaje/avaje-nima/main/docs/guides/add-global-exception-handler.md): Step-by-step — add a centralised @ExceptionHandler controller that maps exceptions to structured JSON error responses
- [Guide: avaje-nima controller testing](https://raw.githubusercontent.com/avaje/avaje-nima/main/docs/guides/add-controller-test.md): Step-by-step — write integration tests with @InjectTest, generated typed test clients, and raw HttpClient
- [Guide: avaje-nima JVM Docker image with Jib](https://raw.githubusercontent.com/avaje/avaje-nima/main/docs/guides/add-jvm-docker-jib.md): Step-by-step — add jib-maven-plugin to build a JVM Docker image without a Dockerfile
- [Guide: avaje-nima GraalVM native image with Jib](https://raw.githubusercontent.com/avaje/avaje-nima/main/docs/guides/add-native-docker-jib.md): Step-by-step — add a native Maven profile to compile a GraalVM native executable and package it as a Docker image

## avaje-inject — Dependency injection

**AI Agent Guide:**
- **Best for**: Compile-time DI, microservices, frameworks requiring zero-reflection, GraalVM native images
- **Not for**: Runtime bean discovery, reflection-heavy workloads
- **Minimum Java**: 11+ | **Key feature**: Compile-time code generation, @Singleton, @Component, @Inject, @Aspect, @Observes

**Common AI Tasks:**
- Create a singleton bean: [overview](https://avaje.io/inject/)
- Conditional beans with @RequiresBean: [documentation](https://avaje.io/inject/#conditional)
- AOP with @Aspect: [documentation](https://avaje.io/inject/#aop)
- Publish/observe events: [documentation](https://avaje.io/inject/#events)
- Test with @InjectTest: [documentation](https://avaje.io/inject/#testing)

**Reference:**
- [avaje-inject overview](https://avaje.io/inject/): Compile-time dependency injection — @Singleton, @Component, @Inject, constructor/field/method injection
- [avaje-inject conditional beans](https://avaje.io/inject/#conditional): @RequiresBean, @RequiresProperty, @Profile
- [avaje-inject AOP](https://avaje.io/inject/#aop): Aspect-oriented programming with @Aspect
- [avaje-inject events](https://avaje.io/inject/#events): Event publishing/observing with @Observes
- [avaje-inject testing](https://avaje.io/inject/#testing): Component testing with @InjectTest and @TestScope

## avaje-http — JAX-RS style HTTP controller generation

**AI Agent Guide:**
- **Best for**: REST APIs, annotation-driven controller generation, JAX-RS compatible code
- **Supports**: Helidon SE, Javalin, Jex, Nima
- **Not for**: GraphQL, non-REST protocols
- **Minimum Java**: 11+ | **Key annotations**: @Controller, @Get/@Post/@Put/@Delete, @Path, @Produces, @ExceptionHandler, @Filter, @Valid

**Common AI Tasks:**
- Generate controllers with @Controller: [overview](https://avaje.io/http/)
- Handle exceptions with @ExceptionHandler: [documentation](https://avaje.io/http/#exceptions)
- Validate requests with @Valid: [documentation](https://avaje.io/http/#bean-validation)
- Add request filters: [documentation](https://avaje.io/http/#filter)
- Generate OpenAPI/Swagger: [documentation](https://avaje.io/http/#openapi)

**Reference:**
- [avaje-http overview](https://avaje.io/http/): Annotation-processor-driven controller generation for Helidon SE, Javalin, and Jex — @Controller, @Get, @Post, @Path, @Produces
- [avaje-http exception handlers](https://avaje.io/http/#exceptions): @ExceptionHandler — mapping exceptions to HTTP responses
- [avaje-http bean validation](https://avaje.io/http/#bean-validation): @Valid on controllers and request payloads
- [avaje-http filters](https://avaje.io/http/#filter): @Filter for Helidon/Jex request filtering
- [avaje-http OpenAPI](https://avaje.io/http/#openapi): Auto-generated OpenAPI/Swagger definitions from controllers
- [avaje-http context](https://avaje.io/http/#context): Accessing raw ServerRequest/ServerResponse (Helidon) or Context (Javalin/Jex)

## avaje-jsonb — JSON serialisation

**AI Agent Guide:**
- **Best for**: JSON serialization, reflection-free performance, GraalVM native images
- **Use with**: REST APIs, microservices, any JSON workload
- **Not for**: GraphQL, complex type hierarchies without @Json.SubTypes
- **Minimum Java**: 11+ | **Key feature**: Compile-time JSON adapter generation, @Json, @Json.SubTypes

**Common AI Tasks:**
- Generate JSON adapters with @Json: [overview](https://avaje.io/jsonb/)
- Handle polymorphic JSON with @Json.SubTypes: [documentation](https://avaje.io/jsonb/#subtype)
- Write custom adapters: [documentation](https://avaje.io/jsonb/#custom)

**Reference:**
- [avaje-jsonb overview](https://avaje.io/jsonb/): Reflection-free JSON adapter generation with @Json — one of the fastest Java JSON libraries
- [avaje-jsonb subtypes](https://avaje.io/jsonb/#subtype): Polymorphic JSON with @Json.SubTypes
- [avaje-jsonb custom adapters](https://avaje.io/jsonb/#custom): Writing custom JsonAdapter implementations

## avaje-validator — Bean validation

**AI Agent Guide:**
- **Best for**: Compile-time bean validation, form validation, request payload validation
- **Not for**: Runtime schema validation without generated validators
- **Minimum Java**: 11+ | **Key annotations**: @Valid, @NotNull, @Size, @Min, @Max, custom constraints

**Common AI Tasks:**
- Validate beans with @Valid: [overview](https://avaje.io/validator/)
- Custom constraints: [documentation](https://avaje.io/validator/#custom)
- Validation groups: [documentation](https://avaje.io/validator/#groups)

**Reference:**
- [avaje-validator overview](https://avaje.io/validator/): Compile-time bean validation — @Valid, @NotNull, @Size, constraint annotations
- [avaje-validator custom constraints](https://avaje.io/validator/#custom): Defining custom validation constraints
- [avaje-validator groups](https://avaje.io/validator/#groups): Validation groups for conditional validation

## avaje-http-client — HTTP client

**AI Agent Guide:**
- **Best for**: Making HTTP calls in microservices, JVM httpClient wrapper, fluent API
- **Not for**: Async frameworks (though async support included)
- **Minimum Java**: 11+ | **Built on**: JDK HttpClient

**Common AI Tasks:**
- Make HTTP requests: [overview](https://avaje.io/http-client/)
- JSON marshalling: [overview](https://avaje.io/http-client/)
- Auth, logging, interception: [overview](https://avaje.io/http-client/)

**Reference:**
- [avaje-http-client overview](https://avaje.io/http-client/): Lightweight fluent wrapper over JDK HttpClient — sync/async, JSON marshalling, auth, logging, interception

## avaje-jex — Lightweight HTTP server

**AI Agent Guide:**
- **Best for**: Lightweight HTTP servers, WebSocket support, Javalin-inspired routing
- **Not for**: Full enterprise web frameworks
- **Minimum Java**: 11+ | **Built on**: JDK Http Server | **Key features**: JSON, SSE, WebSocket, static files, SSL

**Common AI Tasks:**
- Create HTTP handlers: [overview](https://avaje.io/jex/)
- Use with avaje-http controllers: [documentation](https://avaje.io/jex/#avaje-http)
- WebSocket support: [overview](https://avaje.io/jex/)

**Reference:**
- [avaje-jex overview](https://avaje.io/jex/): Javalin-inspired lightweight HTTP server that uses the JDK Http Server — handlers, JSON, SSE, WebSocket, static files, SSL
- [avaje-jex with avaje-http](https://avaje.io/jex/#avaje-http): Using avaje-http annotation-generated controllers with Jex

## avaje-config — External configuration

**AI Agent Guide:**
- **Best for**: External application configuration, YAML/properties, AWS AppConfig integration
- **Minimum Java**: 11+ | **Key features**: Config.get(), onChange listeners, file watching, AWS AppConfig
- **See also**: [avaje-config AI instructions](https://raw.githubusercontent.com/avaje/avaje-config/main/llms.txt)

**Common AI Tasks:**
- Add config to project: [guide](https://raw.githubusercontent.com/avaje/avaje-config/main/docs/guides/adding-avaje-config.md)
- AWS AppConfig: [guide](https://raw.githubusercontent.com/avaje/avaje-config/main/docs/guides/aws-appconfig-setup.md)

**Reference:**
- [avaje-config AI instructions](https://raw.githubusercontent.com/avaje/avaje-config/main/llms.txt): Dedicated AI guidance with core concepts, common patterns, and troubleshooting for avaje-config projects
- [Step-by-step guides index for avaje-config projects](https://raw.githubusercontent.com/avaje/avaje-config/main/docs/guides/README.md): Guide index with quick reference table and links to all step-by-step guides for common configuration tasks
- [avaje-config overview](https://avaje.io/config/): YAML/properties external configuration — Config.get(), onChange listeners, file watching, AWS AppConfig
- [Guide: Adding avaje-config to Your Project](https://raw.githubusercontent.com/avaje/avaje-config/main/docs/guides/adding-avaje-config.md): Step-by-step — create application.yaml/properties, use Config API, access Configuration object, implement change listeners
- [Guide: Adding AWS AppConfig Support](https://raw.githubusercontent.com/avaje/avaje-config/main/docs/guides/aws-appconfig-setup.md): Step-by-step — enable AWS AppConfig plugin, configure polling/refresh, implement dynamic feature flags, build native images

## avaje-simple-logger — SLF4J logger

**AI Agent Guide:**
- **Best for**: Lightweight logging for microservices, GraalVM native images
- **Perfect with**: avaje-nima
- **Minimum Java**: 11+

**Reference:**
- [avaje-simple-logger overview](https://avaje.io/simple-logger/): Lightweight SLF4J implementation suitable for use with avaje-nima and GraalVM native image



## GraalVM native image

- [GraalVM native image guide](https://avaje.io/graalvm/): Guidance and comparisons for building GraalVM native executables with avaje libraries