codex-bootstrap/AGENTS.md

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.