# GitHub Copilot Custom Instructions

## Project context

- Project: RolePlay
- Java: 21
- Build: Maven
- Framework: Quarkus (latest stable)
- GroupId: de.neitzel
- ArtifactId: roleplay
- Base package: de.neitzel.roleplay
- Sub-packages: business, common, data, fascade
- Startup code lives in base package.
- use liquidbase for database migrations, with migration scripts in `src/main/resources/db/migration`.

## Architecture and package rules

- Keep startup/bootstrap classes in `de.neitzel.roleplay`.
- Place business logic in `de.neitzel.roleplay.business`.
- Place shared utilities and cross-cutting types in `de.neitzel.roleplay.common`.
- Place persistence/data access in `de.neitzel.roleplay.data`.
- Place external-facing facades in `de.neitzel.roleplay.fascade`.
- Prefer clear package boundaries and avoid circular dependencies between packages.

## Coding standards

- Use Lombok to reduce boilerplate where appropriate.
- Favor immutability; prefer `final` fields and constructor injection.
- Use Quarkus idioms and avoid heavyweight frameworks.
- Keep methods small and focused; one responsibility per class.
- Use Java 21 language features when they improve clarity.
- Add concise comments only for non-obvious logic.
- All classes, fields, and methods (even private) should have JavaDoc comments, even if brief, to explain their purpose
  and usage.

## Testing requirements

- Create unit tests for new or changed logic.
- Use JUnit 5 and Mockito for unit tests.
- Follow Arrange-Act-Assert style and keep tests deterministic.
- Mock external dependencies; avoid integration tests unless asked.

## Maven and dependencies

- Target Java 21 toolchain in Maven.
- Use the latest stable Quarkus platform BOM.
- Keep dependencies minimal; do not add libraries without necessity.
- Keep versions of dependencies up to date, especially for security patches.
- Versions of plugins and dependencies should be stored inside the `properties` section of the `pom.xml` for easy
  management.
- Use the `quarkus-maven-plugin` for building and running the application, and ensure it is configured correctly in the
  `pom.xml`.
- Use the `maven-surefire-plugin` for running unit tests, and ensure it is configured to use JUnit 5.
- Use the `maven-compiler-plugin` to set the Java source and target versions to 21, and ensure it is configured
  correctly in the `pom.xml`.

## Output expectations for Copilot

- Provide complete, compilable code snippets.
- Include package declarations and imports.
- Prefer Quarkus-friendly APIs and annotations.
- When adding code, update or add unit tests.

## Do and don’t

- Do: keep code in the correct package.
- Do: add tests for business logic.
- Don’t: put startup code outside the base package.
- Don’t: introduce unnecessary abstraction layers.