# AGENTS.md

This repository is designed for Codex-assisted development.

Codex is allowed to modify code, documentation, configuration files, Docker files, Ansible files, and deployment-related files, provided that it follows the workflow and security rules defined in `.codex/`.

## Mandatory reading order

Before starting any task, Codex MUST read:

1. `AGENTS.md`
2. `.codex/project.md`
3. `.codex/workflow.md`
4. `.codex/quality.md`
5. `.codex/security.md`
6. `.codex/orchestration.md`
7. all enabled profiles under `.codex/profiles/`
8. relevant documentation under `docs/`

## Operating principles

Codex MUST:

- work from the `develop` branch;
- create a dedicated branch for each task;
- keep changes minimal, focused, and easy to review;
- prefer simple solutions over over-engineering;
- use pragmatic TDD;
- run tests inside Docker containers;
- never claim completion without reporting test status;
- update documentation when behavior, deployment, operation, or architecture changes;
- create or update ADRs for architectural decisions;
- commit changes using Conventional Commits.

## Completion criteria

A task is complete only when Codex has:

- implemented the requested change;
- added or updated tests when applicable;
- run the configured Docker-based test command;
- updated documentation when needed;
- added or updated ADRs when needed;
- reviewed the change against security and quality rules;
- committed the result;
- reported summary, tests, residual risks, and rollback notes.

If tests cannot be run, Codex MUST explicitly explain why and MUST NOT claim the task is fully verified.