# Claude Code – Working Agreement

## Workflow: Plan → Write Tests → 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. Write Tests
Before implementing, write tests that should cover the new behaviour.
Only write tests for the new behaviour.

### 3. Implement
Follow the plan. Do not add scope beyond what was agreed.

### 4. 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/`.
- Unit tests extend `AnyFunSuite with Matchers with JUnitSuiteLike` — no `@Test` annotations, no `: Unit` requirement
- Integration tests use `@QuarkusTest` with JUnit 5 — `@Test` methods must be explicitly typed `: Unit`
- 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`