Agent-Java/AGENTS.md

Repository Guidelines

Project Structure & Modules

• src/main/java/com/clortox/agent: Spring Boot app code (AgentApplication, support classes).
• src/main/resources: Config (e.g., application.yml). SQLite DB path: ./data/agent.db.
• src/test/java/com/clortox/agent: JUnit 5 tests (Spring test support).
• target/: Build outputs. Not checked in.
• data/: Created at startup for local DB. Do not commit.

Build, Test, and Run

• Build: ./mvnw clean verify — compile, run tests, package the app.
• Package (skip tests): ./mvnw -DskipTests package — produces JAR in target/.
• Run locally: ./mvnw spring-boot:run — starts the API with SQLite.
• Run JAR: java -jar target/agent-0.0.1-SNAPSHOT.jar — same as above.
• Java version: JDK 21 is enforced by the build (enforcer plugin).

Coding Style & Naming

• Language: Java 21. Indentation: 4 spaces; 120-col soft wrap.
• Packages: com.clortox.agent.*. Class names are PascalCase; methods/fields camelCase.
• Spring components: annotate appropriately (@RestController, @Service, @Entity). Favor constructor injection.
• Lombok: allowed where present (e.g., @Getter, @RequiredArgsConstructor). Avoid overuse that obscures intent.

Testing Guidelines

• Frameworks: JUnit 5 with Spring Boot test starter; Modulith test starter is available.
• Naming: *Tests.java per class or feature (e.g., AgentApplicationTests).
• Run tests: ./mvnw test. Prefer slice tests where possible; use @SpringBootTest only when needed.
• Aim for meaningful coverage on domain logic; avoid brittle tests against logs or timing.

Commit & Pull Requests

• Commits: imperative, concise subject (≤72 chars). Example: Add SQLite dialect and datasource config.
• Include context in body: rationale, notable trade-offs, follow-up TODOs.
• PRs: clear description, linked issues (Fixes #123), test evidence (logs or screenshots), and manual run steps.
• Ensure: ./mvnw clean verify passes locally and no files added to data/ or target/.

Configuration Tips

• DB location: application.yml points to jdbc:sqlite:./data/agent.db. Override via CLI: ./mvnw spring-boot:run -Dspring-boot.run.arguments="--spring.datasource.url=jdbc:sqlite:/tmp/agent.db".
• The app creates ./data at startup; avoid hardcoding absolute paths.