familienarchiv/COLLABORATING.md

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)