odoo-at-payroll/AGENTS.md

## Agent memory

Before starting work in a new agent conversation:

- read this `AGENTS.md`;
- read the `agent-memory/SKILL.md` skill;
- read `.agents/MEMORY.md` for the current project handoff.

Update `.agents/MEMORY.md` when the task produces significant state, blockers,
or decisions.

## Skills

Skills are task-specific instructions and must be read before planning work.

Before producing a plan, identify all skills applicable to the task and read
their `SKILL.md` files.

Skills are self-contained directories under `.agents/skills/`.

When a skill is selected, read its `SKILL.md` and consult any relevant
documentation under that skill's `references/` directory.

Skills are task-specific guidance, not a replacement for the mandatory
project workflow in this file. The agent must follow `AGENTS.md` even when
no skill applies.

### Skill selection

- Odoo/Python/module development:
  `odoo19-development/SKILL.md`
- Any payroll work (besoldung, Lohnsteuer, SV, Meldewesen, annual value
  updates, extending the modules in this repo):
  `payroll/SKILL.md`
- Any Wissensbasis work (batch intake, curation, `kb.json`, the sources
  `.lexis360/` and `.wiku/`):
  `wissensbasis/SKILL.md`

Multiple skills may apply. Read all applicable skills.

For example, implementing the Lohnsteuer core (AP3) normally requires:

1. `odoo19-development/SKILL.md`
2. `payroll/SKILL.md`

Work on the VRV bridge module (`l10n_at_gemeinde_payroll_vrv`) happens in
the gem360 repository; there, additionally consult the gem360 skills
(`odoo19-accounting`, `vrv2015`, `accounting-review`).

## Mandatory development workflow

All non-trivial implementation tasks follow this workflow:

### 1. Understand

Before changing anything:

- read `AGENTS.md`;
- read all applicable skills;
- inspect the existing implementation;
- search the Odoo 19 source for existing functionality;
- inspect relevant tests;
- inspect relevant legal source material under `personalverrechnung/`
  and `.firecrawl/` (local, not versioned);
- identify dependencies and integration points.

Do not modify files during this phase.

### 2. Plan

Produce a concise implementation plan containing:

- understanding of the requirement;
- relevant existing Odoo functionality;
- files/components likely to change;
- proposed implementation;
- data/model/report implications;
- tests to add or modify;
- relevant legal/accounting considerations;
- potential risks or unresolved questions.

### 3. Wait for approval

**STOP after presenting the plan.**

Do not create, modify, delete, or rename files until the user explicitly approves
the plan.

Questions and clarification are allowed during this phase.

### 4. Implement

After approval:

- implement the approved plan;
- prefer existing Odoo functionality over custom implementations;
- keep the change as small and upgrade-friendly as practical;
- do not introduce unrelated refactoring;
- follow Odoo 19 coding and Git guidelines.

If implementation reveals that the approved plan is materially wrong or
incomplete, stop and explain the discrepancy rather than silently expanding
scope.

### 5. Validate

Run appropriate tests and checks.

At minimum:

- relevant Odoo tests;
- module installation/update checks where appropriate;
- Python/XML validation;
- linting/static checks available in the repository.

Validate the legal semantics (Lohnsteuer/SV values against the verified
sources in `personalverrechnung/`) as well as technical correctness.

### 6. Review

Before considering the task complete, review the resulting changes for:

- correctness;
- Odoo framework integration;
- reuse of existing Odoo functionality;
- maintainability;
- security/access rights;
- multi-company behavior;
- unnecessary custom code;
- regression risk.

## Verify before assuming

Never invent or assume the existence of an API.

Before using a:

- Python package;
- Odoo module;
- Odoo model;
- field;
- method;
- XML ID;
- configuration key;
- external API;

verify that it exists in the current Odoo 19 Enterprise source,
installed environment, or declared project dependencies.

Do not infer existence from model naming conventions, previous Odoo versions,
documentation alone, training knowledge, or similarly named components.

If existence cannot be verified, stop and report the uncertainty.

In particular, never add a dependency merely because it would be a plausible
package name.

## Prefer framework functionality

Before implementing custom functionality, search the Odoo 19 Enterprise and
community source available to the project for an existing mechanism.

Prefer, in order:

1. existing Odoo functionality that already satisfies the requirement;
2. extending an existing Odoo mechanism;
3. composing existing Odoo mechanisms;
4. a small project-specific implementation only when the above are insufficient.

Do not duplicate functionality merely because implementing it locally appears
simpler.

When choosing a custom implementation over an existing Odoo mechanism, explain
the reason in the plan.

## Git

Follow the Odoo 19 Git guidelines.

When working with Git:

- Keep commits focused and logically coherent.
- Prefer one module per commit where practical.
- Do not mix unrelated changes.
- Review the staged diff before committing.
- Never commit secrets, credentials, client data, local configuration, or
  unrelated generated files.
- Do not create a commit unless the user explicitly asks for one or the task
  explicitly requires it.
- When committing, use the Odoo commit-message conventions configured in
  Zed's `agent.commit_message_instructions`.