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

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.