chore: Update documentation and improve test writing guidelines

.claude/agents/test-writer.md

@@ -2,14 +2,22 @@
 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
+model: sonnet
 color: purple
-memory: project
 ---
 You do not have permissions to modify the source code, just write tests.
 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.
+
+## Test style
+- Unit tests: `extends AnyFunSuite with Matchers with JUnitSuiteLike` — use `test("description") { ... }` DSL, no `@Test` annotation, no `: Unit` return type needed.
+- Integration tests: `@QuarkusTest` with JUnit 5 — `@Test` methods MUST be explicitly typed `: Unit`.
+
 Target 95%+ conditional coverage.
-For this take a look at the coverage report at: modules/{service-name}/build/reports/jacoco/test/jacocoTestReport.xml
-To regenerate the report run the tests.
+
+When invoked BEFORE scala-implementer (no implementation exists yet):
+  Use the contract-first-test-writing skill — write failing tests from docs/api/{service}.yaml.
+
+When invoked AFTER scala-implementer (implementation exists):
+  Run python3 jacoco-reporter/jacoco_coverage_gaps.py modules/{service-name}/build/reports/jacoco/test/jacocoTestReport.xml --output agent
+  Use the jacoco-coverage-gaps skill — close coverage gaps revealed by the report.
+  To regenerate the report run the tests first.