# Collaboration Rules

How we work together on this project.

## Honesty and Objectivity

Evaluate all suggestions on their technical merits. No sycophancy — if something doesn't make sense, doesn't align with best practices, or could be improved, say so directly and constructively. Technical accuracy and project quality take precedence over being agreeable.

## Core Workflow: Research → Plan → Implement → Validate

Every non-trivial feature or bug fix follows this sequence:

1. **Research** — Read the relevant code. Understand existing patterns before touching anything.
2. **Plan** — Write a plan to `/.agent/current-plan.md` and align with the user before writing code. Update the plan as work progresses.
3. **Implement** — Use Red/Green TDD (see below).
4. **Validate** — Run formatters, linters, and tests after every implementation step.

Never start writing code without having read the relevant files first.

## Red/Green TDD

All new behavior is driven by tests written **before** the implementation. The cycle is:

1. **Red** — Write a test that captures the requirement. Run it and confirm it fails. A test that passes before the implementation is written is not testing anything real.
2. **Green** — Write the minimum production code needed to make the test pass. No more.
3. **Refactor** — Clean up the implementation (names, structure, duplication) while keeping the test green.
4. **Commit** — The test and implementation ship together in a single logical commit.

Repeat for each new behavior.

### What level of test to write

| Scenario | Test type |
|---|---|
| Business logic, calculations, service rules | Unit test (`DocumentServiceTest`, etc.) |
| HTTP contract, request validation, error codes | Controller slice test (`@WebMvcTest`) |
| Full user-facing behavior, navigation, forms | E2E Playwright spec |

### Rules

- Never write production code without a failing test that requires it.
- Keep the Green step minimal — resist adding "obvious" extras that have no test yet.
- The Refactor step must not change behavior — if a test breaks, the refactor introduced a bug.
- If a bug is reported with no test, write the failing test first, then fix it.

## Issue Tracking (Gitea)

All work is tracked in **Gitea** at `http://192.168.178.71:3005` (repo `marcel/familienarchiv`). Never use todo files or CLAUDE.md notes as a substitute.

Create an issue whenever work is identified that isn't being done in the current session.

### Issue title formats

**`feature` label** — user story format:
```
As a [role] I want [capability] so/because [reason]
```
Examples:
- "As a user I want to search documents so I can find a specific document faster"
- "As an admin I want to add a new user so I don't have to restart the server"

**`bug` label** — user-facing impact, not the technical cause:
```
[What breaks] when [trigger]
```
Examples:
- "Document list shows blank page when no results found"
- "Upload fails silently when file exceeds 50MB"

**`devops` label** — infrastructure, CI/CD, deployment, tooling:
- "Fix CI checkout failing due to unresolvable hostname"
- "Add E2E test seed data for runner"

### Priority labels

- `priority: high` — blocking or urgent
- `priority: medium` — normal
- `priority: low` — nice to have

### Other labels

- `needs-discussion` — decision needed before work starts
- `wontfix` — acknowledged, not addressing

## Branching and Pull Requests

All changes go through a branch and a pull request — never commit directly to `main`.

### Branch naming

```
<type>/<short-description>
```

Examples:
- `feat/received-documents-person-page`
- `fix/tag-filter-url-sync`
- `devops/docker-compose-v2`

### Workflow

1. Create a branch from `main` before writing any code.
2. Commit work to that branch.
3. Open a pull request on Gitea targeting `main` for review.
4. Wait for approval before merging.

The PR description should reference the related issue (`Closes #n` or `Refs #n`).

## Commit Messages

Every commit must reference the relevant Gitea issue.

- `Closes #12` — commit fully resolves the issue (Gitea auto-closes it)
- `Refs #12` — commit is related but doesn't fully close the issue

Place the reference at the end of the commit body:

```
feat: add person typeahead to document edit form

Closes #7
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
```

### Atomic commits

Each commit must do exactly one logical thing. Never bundle multiple unrelated changes into a single commit, even if they are small.

**Wrong** — three changes in one commit:
```
fix(e2e+i18n): add missing DE translation, fix test selectors, fix lang switching
```

**Right** — three separate commits:
```
fix(i18n): add missing person_btn_conversations DE translation
fix(e2e): exclude /persons/new from person link selector
fix(e2e): clear locale cookie when switching back to base language
```

When in doubt, commit more often rather than less.

## Code Style

See [CODESTYLE.md](./CODESTYLE.md) for the full guide: Clean Code (Uncle Bob), DRY/KISS trade-offs, and SOLID principles applied to this stack.

Quick reminders:
- Pure functions over stateful helpers where possible
- No premature abstractions — KISS beats DRY
- No backwards-compatibility shims for code that has no callers
- Validate at system boundaries only (user input, external APIs)