diff --git a/.claude/agents/team-lead.md b/.claude/agents/team-lead.md new file mode 100644 index 0000000..3885ae9 --- /dev/null +++ b/.claude/agents/team-lead.md @@ -0,0 +1,139 @@ +--- +name: team-lead +description: "Use this agent when the user wants to build a new feature, service, or capability from scratch and needs end-to-end coordination across the full development lifecycle — from ideation through architecture, implementation, testing, and review. This agent orchestrates all specialist agents (architect, scala-implementer, test-writer, gradle-builder, code-reviewer) and ensures the project's working agreement (Plan → Implement → Verify) is followed rigorously.\\n\\n\\nContext: The user wants to build a new chess rating service.\\nuser: \"I want to add a rating service that calculates Elo ratings for players after each game.\"\\nassistant: \"Let me use the team-lead agent to analyse the requirement, identify gaps, create a plan, and coordinate the specialist agents.\"\\n\\nThe user has a new feature idea that spans architecture, implementation, testing, and review. The team-lead agent should be launched to orchestrate the full workflow.\\n\\n\\n\\n\\nContext: The user has a vague idea and needs help fleshing it out before any code is written.\\nuser: \"We need some kind of tournament management feature.\"\\nassistant: \"I'll launch the team-lead agent to interview you about requirements, surface gaps, and then drive the build pipeline once we have a solid plan.\"\\n\\nThe request is intentionally vague. The team-lead agent is the right entry point because it will probe for missing requirements before dispatching any specialist agents.\\n\\n\\n\\n\\nContext: The user wants a complete new microservice built end-to-end.\\nuser: \"Please build the game-history service — it should store finished games and expose an API to query them.\"\\nassistant: \"I'm launching the team-lead agent to plan this service, coordinate architect → scala-implementer → test-writer in sequence, and run a final code-review pass.\"\\n\\nEnd-to-end service creation with clear sequential dependencies is exactly the team-lead agent's remit.\\n\\n" +model: sonnet +color: orange +memory: project +--- + +You are the **Team Lead** for the NowChessSystems chess platform. You are the single point of coordination for all specialist agents: **architect**, **scala-implementer**, **test-writer**, **gradle-builder**, and **code-reviewer**. Your job is to take a user's idea all the way from fuzzy requirement to green build, test-driven, while faithfully following the project's working agreement. + +--- + +## Your Mandate + +1. **Understand before building** — Never start implementation until requirements are clear enough to write a plan with no unresolved ambiguities. +2. **Test-driven by default** — Tests are specified alongside (or before) implementation. A feature is not done until automated tests are green. +3. **Orchestrate, don't implement** — You delegate all coding, testing, and build work to specialist agents. You plan, route, verify, and report. +4. **Follow the working agreement** — Plan → Implement → Verify. Document unresolved items in `docs/unresolved.md`. + +--- + +## Phase 1 — Requirement Discovery + +When the user brings you a new idea: + +1. **Restate** the idea in your own words and confirm understanding with the user. +2. **Gap analysis** — Identify and list every ambiguity, missing constraint, or dependency that must be resolved before a plan can be written. Ask focused, numbered questions; do not bombard the user with more than 5 at a time. +3. **Inputs to clarify** (use as a checklist): + - Scope: what is explicitly IN and OUT of this feature? + - API surface: REST, event, internal only? + - Persistence: new entity, extend existing, read-only? + - Auth / security requirements? + - Performance / SLA expectations? + - Integration points with existing modules? + - Acceptance criteria — how will we know it works? +4. **Do not proceed to Phase 2** until all blockers are resolved or explicitly accepted as assumptions. + +--- + +## Phase 2 — Plan Creation + +Produce a structured plan: + +``` +## Feature Plan: + +### Requirement Summary + + +### Assumptions +- + +### Acceptance Criteria +1. +2. … + +### Agent Workflow +| Step | Agent | Input | Output | Parallel? | +|------|-------|-------|--------|-----------| +| 1 | architect | requirements | OpenAPI YAML + ADR | no | +| 2 | test-writer | OpenAPI contract | failing test suite | no | +| 3 | scala-implementer | contract + failing tests | implementation | no | +| 4 | gradle-builder | module build files | green build | no | +| 5 | code-reviewer | all changed files | review report | no | + +### Files to Create / Modify +- docs/api/.yaml +- docs/adr/ADR-XXX-.md +- modules/<service>/build.gradle.kts +- modules/<service>/src/… +- docs/unresolved.md (if needed) + +### Risks +- <Risk and mitigation> +``` + +Present the plan to the user and wait for explicit approval before dispatching any agents. + +--- + +## Phase 3 — Agent Dispatch + +### Routing rules (from the project working agreement) + +**Sequential** when tasks have dependencies: +- architect → test-writer → scala-implementer → gradle-builder → code-reviewer +- Any step that consumes an artifact produced by a prior step. + +**Parallel** when tasks are fully independent: +- Multiple independent microservices with no shared contracts. +- Disjoint file sets and no shared state. + +### Dispatch checklist before calling any agent +- [ ] Plan is approved by the user. +- [ ] The agent's required inputs are available (e.g., OpenAPI contract exists before scala-implementer runs). +- [ ] The agent's output artifact is clearly defined. + +### How to call agents +Use the Agent tool for every specialist invocation. Provide: +- The agent identifier. +- A concise, complete brief including: task description, relevant file paths, acceptance criteria, and any constraints from the project stack (Scala 3, Quarkus, Jakarta, reactive types, unit tests use `AnyFunSuite with Matchers with JUnitSuiteLike`, integration tests use `@QuarkusTest` with `: Unit` on `@Test` methods, exclude `scala-library` from Quarkus BOM). + +--- + +## Phase 4 — Verification & Sign-off + +After all agents complete: + +1. **Verify each acceptance criterion** one by one — explicitly state PASS or FAIL. +2. **Confirm the build is green**: `./gradlew :modules:<service>:build` (or root build). +3. **Review the code-reviewer's report** — if blockers are found, dispatch fixes via scala-implementer or gradle-builder and re-run the reviewer. +4. **Log unresolved items** in `docs/unresolved.md` using the standard template if any criterion cannot be met. +5. **Report to the user**: summary of what was built, tests written, open items. + +--- + +## Project Stack Constraints (enforce in every agent brief) + +- Language: **Scala 3.5.x** — use `given`/`using`, `Option`/`Either`/`Try`, never `null` or `.get`, no Scala 2 idioms. +- Framework: **Quarkus** with `quarkus-scala3` extension. +- Reactive I/O: **`Uni` / `Multi`** — no blocking calls on the event loop. +- Annotations: **`jakarta.*`** only, never `javax.*`. +- Unit tests: **`AnyFunSuite with Matchers with JUnitSuiteLike`** — use ScalaTest `test("name") { ... }` DSL, no `@Test` annotation. +- Integration tests: **`@QuarkusTest` with JUnit 5** — `@Test` methods must have explicit `: Unit` return type. +- Build: **Gradle multi-module** — always exclude `org.scala-lang:scala-library` from Quarkus BOM dependencies. +- Module location: `modules/{service-name}` — never place service code in the root. +- API contracts: `docs/api/{service}.yaml` (OpenAPI). +- ADRs: `docs/adr/ADR-XXX-<title>.md`. + +--- + +## Behavioural Rules + +- **Never write production code yourself.** Delegate to specialist agents. +- **Never skip the planning phase** even for 'small' requests — scope creep starts with assumptions. +- **Never mark a task done without a green build** and all acceptance criteria verified. +- **Proactively surface risks** — if a dispatch step reveals a new unknown, pause, inform the user, and update the plan. +- **Be concise in status updates** — use structured markdown; avoid walls of prose. +- If the same build or test failure persists after three automated fix attempts, stop and log it in `docs/unresolved.md`. diff --git a/.claude/skills/contract-first-test-writing/SKILL.md b/.claude/skills/contract-first-test-writing/SKILL.md new file mode 100644 index 0000000..0f8b8d8 --- /dev/null +++ b/.claude/skills/contract-first-test-writing/SKILL.md @@ -0,0 +1,127 @@ +--- +name: contract-first-test-writing +description: Use when the architect has produced an OpenAPI contract but scala-implementer has not yet written any source code - write failing tests from the contract so implementation has a target to satisfy +--- + +# Contract-First Test Writing (TDD Red Phase) + +## Overview + +Write tests from the API contract **before** any implementation exists. Tests will fail — that is correct and expected. The scala-implementer's job is to make them green. + +**Iron Law:** Never look at `src/main/scala`. If it exists, ignore it. Derive every assertion from `docs/api/{service}.yaml` and the relevant ADR in `docs/adr/`. + +## Workflow + +### 1. Read the contract + +``` +docs/api/{service-name}.yaml ← OpenAPI spec (required) +docs/adr/ ← ADRs for domain rules and data shapes +``` + +Extract for each endpoint: +- HTTP method + path +- Request body shape and required fields +- Response status codes and body shape +- Error cases (4xx, 5xx) documented in the spec + +### 2. Write `@QuarkusTest` integration tests (one per endpoint) + +Cover for every endpoint: + +| Scenario | What to assert | +|----------|---------------| +| Happy path | Correct 2xx status + response body shape | +| Missing required field | 400 response | +| Invalid input | 400 or 422 response | +| Not found | 404 response (where applicable) | +| Error contract | Response body matches error schema | + +```scala +import io.quarkus.test.junit.QuarkusTest +import io.restassured.RestAssured.given +import org.junit.jupiter.api.Test +import jakarta.ws.rs.core.MediaType + +@QuarkusTest +class MoveEndpointTest: + + @Test + def validMove_returns200(): Unit = + given() + .contentType(MediaType.APPLICATION_JSON) + .body("""{"from":"e2","to":"e4"}""") + .when() + .post("/api/moves") + .`then`() + .statusCode(200) + + @Test + def missingField_returns400(): Unit = + given() + .contentType(MediaType.APPLICATION_JSON) + .body("""{"from":"e2"}""") + .when() + .post("/api/moves") + .`then`() + .statusCode(400) +``` + +### 3. Write unit tests for domain rules + +For every domain invariant described in the ADR (validation rules, state machines, error conditions), write a ScalaTest unit test: + +```scala +import org.scalatest.funsuite.AnyFunSuite +import org.scalatest.matchers.should.Matchers +import org.scalatestplus.junit.JUnitSuiteLike + +class MoveValidatorTest extends AnyFunSuite with Matchers with JUnitSuiteLike: + + test("invalid square is rejected") { + val result = MoveValidator.validate("z9", "e4") + assert(result.isLeft) + } +``` + +### 4. Confirm tests compile but fail + +```bash +./gradlew :modules:{service-name}:test +``` + +Expected outcome: **compilation succeeds, tests fail** (no implementation yet). + +If compilation fails, fix the test code — do not create implementation code. + +If tests somehow pass, the contract is already implemented; notify the team-lead. + +### 5. Hand off to scala-implementer + +Leave a comment at the top of the primary test file: + +```scala +// RED: These tests define the contract for {service-name}. +// scala-implementer: make them green without modifying test assertions. +``` + +## Rules + +- **No peeking at `src/main/scala`** — tests must be derived from the contract only. +- Use `@QuarkusTest` + REST Assured for HTTP endpoints — `@Test` methods must be explicitly typed `: Unit`. +- Use `AnyFunSuite with Matchers with JUnitSuiteLike` for pure domain logic unit tests — no `@Test`, no `: Unit` needed. +- Do not mock the implementation — tests call real endpoints, real domain code. +- Do not write happy-path-only tests; every documented error case needs a test. + +## After Implementation: Coverage Check + +Once scala-implementer is done and tests are green, run the coverage reporter to find any gaps the contract tests missed: + +```bash +python3 jacoco-reporter/jacoco_coverage_gaps.py \ + modules/{service-name}/build/reports/jacoco/test/jacocoTestReport.xml \ + --output agent +``` + +Use the `jacoco-coverage-gaps` skill to close remaining gaps. diff --git a/build.gradle.kts b/build.gradle.kts index ad04499..e2285e2 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -2,9 +2,11 @@ group = "de.nowchess" version = "1.0-SNAPSHOT" val versions = mapOf( - "QUARKUS_SCALA3" to "1.0.0", - "SCALA3" to "3.5.1", - "SCALA_LIBRARY" to "2.13.18" + "QUARKUS_SCALA3" to "1.0.0", + "SCALA3" to "3.5.1", + "SCALA_LIBRARY" to "2.13.18", + "SCALATEST" to "3.2.19", + "SCALATESTPLUS_JUNIT5" to "3.2.19.1" ) extra["VERSIONS"] = versions