# 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** — Build with tests and error handling. Use pure functions where possible.
4. **Validate** — Run formatters, linters, and tests after every implementation step.

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

## 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>
```

## Code Style Reminders

- Pure functions over stateful helpers where possible
- No premature abstractions — solve the problem in front of you
- No backwards-compatibility shims for code that has no callers
- Validate at system boundaries only (user input, external APIs)