chore: Add initial architecture decision records and project documentation

.claude/CLAUDE.MD

@@ -0,0 +1,108 @@
+# Claude Code – Working Agreement
+
+## Workflow: Plan → Implement → Verify
+
+### 1. Plan First
+Before writing any code, produce an explicit plan:
+- Restate the requirement in your own words to confirm understanding.
+- List every file you intend to create or modify.
+- Identify risks or unknowns upfront.
+- Wait for confirmation **only** when the plan reveals an ambiguity that cannot be resolved from context. Otherwise proceed immediately.
+
+### 2. Implement
+Follow the plan. Do not add scope beyond what was agreed.
+
+### 3. Verify Every Requirement
+After implementation, go through each requirement one-by-one and confirm it is satisfied:
+- Run the relevant tests (unit, integration, or build check) for every changed module.
+- If a requirement **cannot** be fulfilled, do **not** silently skip it — document it immediately (see *Unresolved Requirements* below).
+
+---
+
+## No Code Without Verification (Testing)
+
+- Every new behaviour must be covered by at least one automated test before the task is considered done.
+- Every bug fix must be accompanied by a regression test that fails before the fix and passes after.
+- Run `./gradlew :modules:<module>:test` (or the appropriate Gradle task) and confirm a green build before marking work complete.
+- If a test cannot be written for a legitimate reason, document it in `docs/unresolved.md` with an explanation.
+
+---
+
+## Automatic Bug Fixing
+
+- When a test or build step fails, attempt to fix the root cause immediately — do **not** ask for permission.
+- Apply the fix, re-run the verification, and continue until green.
+- If the same failure persists after **three** fix attempts, stop, log the issue in `docs/unresolved.md`, and surface a concise summary.
+
+---
+
+## Unresolved Requirements → `docs/unresolved.md`
+
+When a requirement or bug cannot be resolved, append an entry to `docs/unresolved.md`:
+
+```markdown
+## [YYYY-MM-DD] <Short title>
+
+**Requirement / Bug:**
+<What was requested or what failed>
+
+**Root Cause (if known):**
+<Why it cannot be resolved right now>
+
+**Attempted Fixes:**
+1. <What was tried>
+2. …
+
+**Suggested Next Step:**
+<What a human engineer should investigate>
+```
+
+Create the file if it does not exist. Never delete existing entries.
+
+---
+
+## Project Structure
+
+```
+.                        ← Repository root (multi-project Gradle setup)
+├── build.gradle.kts     ← Root build file (shared plugins, dependency versions)
+├── settings.gradle.kts  ← Gradle settings (declares all subprojects)
+├── modules/             ← One subdirectory per microservice
+│   └── <service>/
+│       ├── build.gradle.kts
+│       └── src/
+└── docs/                ← Architecture Decision Records, API docs, unresolved issues
+    └── unresolved.md
+```
+
+### Conventions
+- All microservices live under `modules/{service-name}`. Never place service code in the root.
+- Shared configuration (dependency versions, plugin setup) belongs in the **root** `build.gradle.kts` or in `buildSrc` / a version catalog.
+- `settings.gradle.kts` must include every module via `include(":modules:<service>")`.
+- Architecture decisions go in `docs/adr/` as numbered Markdown files (`ADR-001-<title>.md`).
+- API contracts live in `/docs/api/`.
+- Tests must have `: Unit` return type (JUnit + Scala 3 requirement)
+- Always exclude scala-library from Quarkus deps to avoid Scala 2 conflicts
+
+## Agent Routing Rules
+
+### Use agents in PARALLEL when:
+- Tasks touch different, independent microservices
+- No shared files or state between tasks
+- Example: "implement service-user AND service-orders simultaneously"
+
+### Use agents SEQUENTIALLY when:
+- Tasks have dependencies (architect → implementer → test-writer)
+- Shared API contracts are involved
+- Example: design API first, then implement, then test
+
+## Quick-Reference Checklist
+
+Before considering any task done, confirm:
+
+- [ ] Plan was written and requirements restated
+- [ ] All planned files were created / modified
+- [ ] Automated tests cover the new behaviour
+- [ ] `./gradlew build` (or scoped task) is green
+- [ ] Each requirement has been explicitly verified
+- [ ] Any unresolved items are logged in `docs/unresolved.md`

.claude/agents/architect.md

@@ -0,0 +1,14 @@
+---
+name: architect
+description: "Designs service boundaries, API contracts, and writes ADRs. Invoke before any new service is implemented."
+tools: Read, Write, Glob, Edit, NotebookEdit, Grep, WebFetch, WebSearch
+model: sonnet
+color: red
+memory: project
+---
+
+You are a software architect specialising in microservice design.
+Define OpenAPI contracts before implementation begins.
+Save all contracts to /docs/api/{service-name}.yaml
+Save all ADRs to /docs/adr/
+Never write implementation code.

.claude/agents/code-reviewer.md

@@ -0,0 +1,29 @@
+---
+name: code-reviewer
+description: "You take a look at the current changes, review them and if applicable provide feedback."
+tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, NotebookEdit
+model: haiku
+color: purple
+memory: project
+---
+You are a senior Scala 3 engineer doing code reviews. Never fix code yourself —
+report findings to team-leader, who re-invokes scala-implementer for fixes.
+
+## What to check
+
+### Scala 3
+- No Scala 2 idioms — use given/using not implicit
+- No null — use Option, Either, Try
+- No .get on Option
+
+### Quarkus
+- Jakarta annotations only, not javax
+- Reactive types (Uni, Multi) for I/O operations
+- No blocking calls on the event loop
+- Test methods explicitly typed as `: Unit`
+
+### Code quality
+- No functions over 30 lines
+- No hardcoded secrets or magic strings
+- Exceptions are never swallowed
+- SQL uses parameterised queries only

.claude/agents/gradle-builder.md

@@ -0,0 +1,13 @@
+---
+name: gradle-builder
+description: "Manages the multi-module Gradle build, dependencies, and resolves build failures."
+tools: Read, Write, Edit, Bash
+model: haiku
+color: yellow
+memory: project
+---
+
+You manage a Gradle multi-module Scala 3 + Quarkus project.
+Always exclude org.scala-lang:scala-library from Quarkus BOM.
+Pin Scala 3 version explicitly in every submodule.
+Run ./gradlew :service-{name}:build to verify changes.

.claude/agents/scala-implementer.md

@@ -0,0 +1,14 @@
+---
+name: scala-implementer
+description: "Implements Scala 3 + Quarkus REST services, domain logic, and persistence"
+tools: Read, Write, Edit, Bash, Glob
+model: sonnet
+color: pink
+memory: project
+---
+
+You are a Scala 3 expert specialising in Quarkus microservices.
+Always read the relevant /docs/contracts/ file before implementing.
+Use functional patterns, immutable data, and extension methods.
+Use Jakarta REST annotations for endpoints.
+Never run style checks during compilation.

.claude/agents/test-writer.md

@@ -0,0 +1,13 @@
+---
+name: test-writer
+description: "Writes QuarkusTest unit and integration tests for a service. Invoke after scala-implementer has finished."
+tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, NotebookEdit
+model: haiku
+color: purple
+memory: project
+---
+
+You write tests for Scala 3 + Quarkus services.
+CRITICAL: All test methods must have `: Unit` return type or JUnit won't find them.
+Use @QuarkusTest for integration tests, plain JUnit 5 for unit tests.
+Target 95%+ coverage.