diff --git a/.claude/CLAUDE.MD b/.claude/CLAUDE.MD new file mode 100644 index 0000000..cefe0fd --- /dev/null +++ b/.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::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] + +**Requirement / Bug:** + + +**Root Cause (if known):** + + +**Attempted Fixes:** +1. +2. … + +**Suggested Next Step:** + +``` + +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 +│ └── / +│ ├── 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:")`. +- Architecture decisions go in `docs/adr/` as numbered Markdown files (`ADR-001-.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` \ No newline at end of file diff --git a/.claude/agents/architect.md b/.claude/agents/architect.md new file mode 100644 index 0000000..39cade9 --- /dev/null +++ b/.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. diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md new file mode 100644 index 0000000..fcd9c51 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.claude/agents/gradle-builder.md b/.claude/agents/gradle-builder.md new file mode 100644 index 0000000..d6bd77b --- /dev/null +++ b/.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. diff --git a/.claude/agents/scala-implementer.md b/.claude/agents/scala-implementer.md new file mode 100644 index 0000000..c7e8e70 --- /dev/null +++ b/.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. diff --git a/.claude/agents/test-writer.md b/.claude/agents/test-writer.md new file mode 100644 index 0000000..2d88c2d --- /dev/null +++ b/.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. diff --git a/docs/adr/ADR-001-Stack.md b/docs/adr/ADR-001-Stack.md new file mode 100644 index 0000000..e6f01ae --- /dev/null +++ b/docs/adr/ADR-001-Stack.md @@ -0,0 +1,43 @@ +# ADR-001: Technology Stack Selection + +## Status +Accepted + +## Context +The "NowChessSystems" project requires a modern, scalable, +and maintainable technology stack to support web-based interfaces. +The system is designed as a microservice architecture to allow for independent scaling and development of various components (e.g., engine, matchmaking, user management). + +## Decision +We have decided to use the following technologies for the core system: + +### Backend +- **Language:** [Scala 3](https://scala-lang.org/) for its powerful type system, functional programming capabilities, and seamless JVM integration. +- **Framework:** [Quarkus](https://quarkus.io/) with the `io.quarkiverse.scala:quarkus-scala3` extension to leverage GraalVM native compilation and fast startup times. +- **Persistence:** [Hibernate](https://hibernate.org/) and [Jakarta Persistence](https://jakarta.ee/specifications/persistence/) for standard-based ORM. + +### Frontend +- **Build Tool:** [Vite](https://vitejs.dev/) for a fast development experience. +- **Framework:** TBD (Evaluation between React, Angular, and Vue). +- **Terminal UI:** [Lanterna](https://github.com/mabe02/lanterna) for a text-based user interface (TUI). + +### DevOps & Infrastructure +- **Orchestration:** [Kubernetes](https://kubernetes.io/) for container orchestration. +- **GitOps & Delivery:** [ArgoCD](https://argoproj.github.io/cd/) for continuous delivery and [Kargo](https://kargo.io/) for multi-stage lifecycle management. + +### AI-Assisted Development +- [Claude Code Pro](https://claude.ai/) and [Claude Agent Teams](https://claude.ai/team) for coding and reviews. +- [Google Stitch](https://stitch.google.com/) (Free) for UI design and prototyping. + +## Consequences + +### Positive +- **High Performance:** Quarkus and GraalVM enable low memory footprint and fast startup. +- **Developer Productivity:** Scala 3 and AI tools provide a high-level, expressive environment. +- **Robustness:** Kubernetes and ArgoCD ensure reliable deployment and scaling. +- **Accessibility:** Offering both a TUI and a web interface caters to different user preferences. + +### Negative / Risks +- **Complexity:** Managing a microservices architecture with Kubernetes adds operational overhead. +- **Learning Curve:** Scala 3 and the specific Quarkus-Scala integration may require training for new developers. +- **Consistency:** Maintaining parity between the TUI and Web frontend functionality. \ No newline at end of file