added codex structure

.codex/agents/architect.md

@@ -0,0 +1,27 @@
+# Architect agent
+
+The Architect agent is responsible for understanding the task and protecting the repository architecture.
+
+## Responsibilities
+
+- Read project documentation and enabled profiles.
+- Identify affected components.
+- Determine whether the change is architectural.
+- Require an ADR for architectural decisions.
+- Prefer simple, incremental designs.
+- Avoid unnecessary new dependencies or frameworks.
+
+## Architectural decisions
+
+An ADR is required for changes involving:
+
+- framework or runtime selection;
+- new dependencies with architectural impact;
+- data model changes;
+- deployment changes;
+- security model changes;
+- authentication or authorization changes;
+- logging or monitoring strategy changes;
+- container topology changes;
+- Ansible role/playbook structure changes;
+- persistence, backup, restore, or retention changes.

.codex/agents/developer.md

@@ -0,0 +1,25 @@
+# Developer agent
+
+The Developer agent implements the requested change.
+
+## Responsibilities
+
+- Implement the minimal necessary change.
+- Keep code readable and maintainable.
+- Avoid unrelated cleanups.
+- Avoid broad rewrites unless requested.
+- Preserve existing behavior unless the task requires a change.
+- Follow enabled project profiles.
+- Use English for comments.
+
+## Forbidden behavior
+
+The Developer MUST NOT:
+
+- introduce secrets;
+- introduce unnecessary dependencies;
+- change public behavior silently;
+- bypass tests;
+- modify deployment/security files casually;
+- use `latest` container tags;
+- add privileged containers without ADR justification.

.codex/agents/documentation-writer.md

@@ -0,0 +1,17 @@
+# Documentation Writer agent
+
+The Documentation Writer agent keeps repository documentation aligned with code and operational behavior.
+
+## Responsibilities
+
+- Update documentation in English.
+- Update `docs/architecture.md` for architectural changes.
+- Update `docs/deployment.md` for deployment changes.
+- Update `docs/operations.md` and `docs/runbook.md` for operational procedures.
+- Update `docs/security.md` for security behavior changes.
+- Update `docs/testing.md` for test strategy or test command changes.
+- Create or update ADRs for architectural decisions.
+
+## Style
+
+Documentation MUST be practical, concise, and operationally useful.

.codex/agents/reviewer.md

@@ -0,0 +1,23 @@
+# Reviewer agent
+
+The Reviewer agent challenges the completed work before final reporting.
+
+## Responsibilities
+
+- Check that the task was implemented as requested.
+- Check that the change is minimal and focused.
+- Check that tests were run inside Docker.
+- Check that documentation and ADRs were updated when needed.
+- Check that security rules were respected.
+- Identify residual risks.
+- Provide rollback notes.
+
+## Review questions
+
+- Did the implementation solve the actual request?
+- Were unrelated files changed?
+- Were tests added or updated when needed?
+- Were tests executed using the configured Docker-based command?
+- Is there any hidden architectural decision without an ADR?
+- Were secrets, weak permissions, or risky defaults introduced?
+- Is rollback clear?

.codex/agents/security-reviewer.md

@@ -0,0 +1,20 @@
+# Security Reviewer agent
+
+The Security Reviewer agent checks the change against the security baseline.
+
+## Responsibilities
+
+- Detect secrets or credential leaks.
+- Check authentication, authorization, TLS, network exposure, container, Ansible, and deployment changes.
+- Verify least-privilege assumptions.
+- Ensure sensitive data is not logged.
+- Ensure dependencies are justified.
+- Require ADRs for security-sensitive architectural changes.
+
+## Output
+
+The Security Reviewer MUST report:
+
+- security-sensitive files changed;
+- risks introduced or avoided;
+- whether additional manual review is recommended.

.codex/agents/test-engineer.md

@@ -0,0 +1,18 @@
+# Test Engineer agent
+
+The Test Engineer agent is responsible for verification.
+
+## Responsibilities
+
+- Apply pragmatic TDD.
+- Add or update tests before implementation when practical.
+- Ensure all tests run inside Docker containers.
+- Prefer deterministic tests.
+- Avoid tests that require external services unless explicitly configured.
+- Report test commands and results.
+
+## Required behavior
+
+Before completion, the Test Engineer MUST ensure that the configured Docker-based test command has been executed.
+
+If no test command exists, the Test Engineer MUST suggest one and report that the task is not fully verified.

.codex/orchestration.md

@@ -0,0 +1,41 @@
+# Agent orchestration
+
+Codex operates as one implementation agent, but it MUST reason through the following logical roles for every task.
+
+## Standard orchestration
+
+1. Architect
+   - Understands the task.
+   - Identifies architectural impact.
+   - Decides whether an ADR is required.
+
+2. Test Engineer
+   - Defines the verification strategy.
+   - Adds or updates tests first when practical.
+   - Ensures tests run inside Docker.
+
+3. Developer
+   - Implements the minimal necessary change.
+   - Preserves existing behavior unless explicitly changed.
+
+4. Security Reviewer
+   - Reviews security-sensitive files and behavior.
+   - Ensures the security baseline is respected.
+
+5. Documentation Writer
+   - Updates documentation and ADRs when needed.
+
+6. Reviewer
+   - Challenges the result.
+   - Checks whether completion criteria are satisfied.
+   - Identifies residual risks and rollback notes.
+
+## When to simplify orchestration
+
+For trivial documentation-only changes, Codex may execute a shortened process, but it MUST still report:
+
+- what changed;
+- whether tests were applicable;
+- whether ADRs were needed;
+- residual risks;
+- rollback notes.

.codex/profiles/ansible.md

@@ -0,0 +1,40 @@
+# Ansible profile
+
+Enable this profile for repositories containing Ansible playbooks, roles, inventories, or automation scripts.
+
+## Rules
+
+Codex MUST:
+
+- prefer idempotent tasks;
+- use Ansible builtin modules instead of `shell` or `command` when possible;
+- use `service_facts` when checking service availability or service state;
+- use `become` explicitly when privilege escalation is needed;
+- avoid `ignore_errors` unless explicitly justified;
+- avoid `changed_when: false` unless semantically correct;
+- avoid storing secrets in plain YAML;
+- keep roles and tasks modular;
+- write comments in English;
+- preserve compatibility requirements stated in the repository.
+
+## Validation examples
+
+Use Docker-based validation commands configured for the project, for example:
+
+```bash
+docker compose run --rm ansible ansible-playbook --syntax-check playbook.yml
+```
+
+```bash
+docker compose run --rm ansible ansible-lint
+```
+
+## Shell and command usage
+
+`shell` and `command` are allowed only when there is no suitable module or when interacting with legacy tools.
+
+When using `shell` or `command`, Codex SHOULD:
+
+- make the task idempotent;
+- define `changed_when` and `failed_when` where needed;
+- explain why a module is not used.

.codex/profiles/docker.md

@@ -0,0 +1,40 @@
+# Docker profile
+
+Enable this profile for repositories containing Dockerfiles, Compose files, container entrypoints, reverse proxy configuration, or containerized deployment logic.
+
+## Rules
+
+Codex MUST:
+
+- avoid `latest` tags;
+- prefer pinned or explicit versions;
+- keep images small and reproducible;
+- avoid privileged containers unless explicitly justified in an ADR;
+- avoid unnecessary published ports;
+- use least-privilege users where practical;
+- avoid storing secrets in images or Compose files;
+- use healthchecks when useful and practical;
+- document exposed ports, volumes, networks, and runtime assumptions;
+- keep entrypoints simple and explicit.
+
+## Project mode behavior
+
+If `.codex/project.md` sets `project_mode: work`, Codex SHOULD prefer Red Hat UBI minimal images when possible and reasonable.
+
+If `.codex/project.md` sets `project_mode: personal`, Codex may use the most appropriate base image for the project, but it MUST still avoid `latest` tags and unsafe defaults.
+
+## Validation examples
+
+Use project-specific Docker-based commands, for example:
+
+```bash
+docker compose config
+```
+
+```bash
+docker compose build
+```
+
+```bash
+docker compose run --rm app pytest
+```

.codex/profiles/python.md

@@ -0,0 +1,42 @@
+# Python profile
+
+Enable this profile for Python repositories.
+
+## Suggested standard
+
+Codex SHOULD prefer:
+
+- `pytest` for tests;
+- `ruff` for linting and formatting checks;
+- type hints for public functions and non-trivial logic;
+- `pathlib` for filesystem paths where practical;
+- explicit error handling;
+- small, focused functions;
+- simple modules over unnecessary class hierarchies.
+
+## Rules
+
+Codex MUST:
+
+- keep dependencies minimal;
+- avoid broad `except` clauses unless justified;
+- avoid hidden side effects at import time;
+- separate business logic from CLI, web, or framework glue;
+- avoid global mutable state unless justified;
+- write tests for behavior, not implementation details;
+- run tests inside Docker containers.
+
+## Validation examples
+
+Use project-specific Docker-based commands, for example:
+
+```bash
+docker compose run --rm app ruff check .
+docker compose run --rm app pytest
+```
+
+If formatting is configured:
+
+```bash
+docker compose run --rm app ruff format --check .
+```

.codex/project.md

@@ -0,0 +1,107 @@
+# Project configuration for Codex
+
+Edit this file for each repository.
+
+## Project identity
+
+Project name: `CHANGE_ME`
+Project description: `CHANGE_ME`
+Primary language/runtime: `CHANGE_ME`
+
+## Project mode
+
+Choose one:
+
+```text
+project_mode: personal
+project_mode: work
+```
+
+Rules:
+
+- `personal`: Docker base image policy is neutral.
+- `work`: prefer Red Hat UBI minimal images when possible.
+
+## Enabled profiles
+
+Enable only the profiles that apply to this repository:
+
+```text
+enabled_profiles:
+  - docker
+  - ansible
+  - python
+```
+
+## Branching model
+
+Codex MUST:
+
+- start from `develop`;
+- create one branch per task;
+- use one of these prefixes:
+  - `feature/`
+  - `fix/`
+  - `hotfix/`
+  - `chore/`
+  - `docs/`
+  - `refactor/`
+
+Examples:
+
+```text
+feature/add-healthcheck
+fix/selinux-authorized-keys
+hotfix/restore-container-startup
+```
+
+## Commit style
+
+Codex MUST use Conventional Commits.
+
+Examples:
+
+```text
+feat: add Docker healthcheck
+fix: correct Ansible SELinux handling
+docs: add ADR for deployment strategy
+test: add regression tests for parser
+refactor: simplify container startup logic
+chore: update Codex project metadata
+```
+
+## Test command
+
+All tests MUST be executed inside Docker containers.
+
+Configure the canonical test command for this repository:
+
+```bash
+CHANGE_ME
+```
+
+Examples:
+
+```bash
+docker compose run --rm app pytest
+```
+
+```bash
+docker compose run --rm app ruff check .
+docker compose run --rm app pytest
+```
+
+```bash
+docker compose run --rm ansible ansible-playbook --syntax-check playbook.yml
+```
+
+If no test command is configured, Codex MUST:
+
+1. report that tests are not configured;
+2. suggest the appropriate Docker-based test command;
+3. avoid claiming that the task is fully verified.
+
+## Documentation language
+
+Documentation language: English.
+Code comments language: English.

.codex/prompts/bugfix.md

@@ -0,0 +1,37 @@
+# Bugfix prompt
+
+```text
+You are working in this repository as Codex.
+
+Mandatory instructions:
+- Read AGENTS.md and all relevant files under .codex/ before making changes.
+- Start from develop.
+- Create a dedicated fix branch.
+- Reproduce the bug with a failing test before implementing the fix, when practical.
+- Implement the minimal fix.
+- Run the configured Docker-based test command from .codex/project.md.
+- Update documentation and ADRs if required.
+- Commit using Conventional Commits.
+
+Bug description:
+<DESCRIBE THE BUG HERE>
+
+Expected behavior:
+<DESCRIBE EXPECTED BEHAVIOR HERE>
+
+Observed behavior:
+<DESCRIBE OBSERVED BEHAVIOR HERE>
+
+Acceptance criteria:
+<LIST ACCEPTANCE CRITERIA HERE>
+
+Final response must include:
+- branch name;
+- commit hash;
+- root cause;
+- summary of changes;
+- tests executed and result;
+- documentation/ADR updates;
+- residual risks;
+- rollback notes.
+```

.codex/prompts/documentation.md

@@ -0,0 +1,30 @@
+# Documentation prompt
+
+```text
+You are working in this repository as Codex.
+
+Mandatory instructions:
+- Read AGENTS.md and all relevant files under .codex/ before making changes.
+- Start from develop.
+- Create a dedicated docs branch.
+- Write documentation in English.
+- Keep documentation practical, concise, and operationally useful.
+- Update ADRs if documenting an architectural decision.
+- Run tests only if documentation changes affect generated docs, examples, commands, or checked files.
+- Commit using Conventional Commits.
+
+Documentation task:
+<DESCRIBE DOCUMENTATION WORK HERE>
+
+Acceptance criteria:
+<LIST ACCEPTANCE CRITERIA HERE>
+
+Final response must include:
+- branch name;
+- commit hash;
+- summary of documentation changes;
+- tests/checks executed, if applicable;
+- ADR updates;
+- residual risks;
+- rollback notes.
+```

.codex/prompts/refactor.md

@@ -0,0 +1,36 @@
+# Refactor prompt
+
+```text
+You are working in this repository as Codex.
+
+Mandatory instructions:
+- Read AGENTS.md and all relevant files under .codex/ before making changes.
+- Start from develop.
+- Create a dedicated refactor branch.
+- Preserve existing behavior.
+- Do not introduce new features.
+- Do not perform unrelated cleanups.
+- Add tests only if coverage is missing for the behavior being preserved.
+- Run the configured Docker-based test command from .codex/project.md.
+- Update documentation and ADRs if required.
+- Commit using Conventional Commits.
+
+Refactor goal:
+<DESCRIBE THE REFACTOR HERE>
+
+Non-goals:
+<LIST WHAT MUST NOT CHANGE>
+
+Acceptance criteria:
+<LIST ACCEPTANCE CRITERIA HERE>
+
+Final response must include:
+- branch name;
+- commit hash;
+- summary of changes;
+- confirmation that behavior is preserved;
+- tests executed and result;
+- documentation/ADR updates;
+- residual risks;
+- rollback notes.
+```

.codex/prompts/security-review.md

@@ -0,0 +1,31 @@
+# Security review prompt
+
+```text
+You are working in this repository as Codex.
+
+Mandatory instructions:
+- Read AGENTS.md, .codex/security.md, and all enabled profiles before reviewing.
+- Do not make broad rewrites.
+- If fixes are requested, create a dedicated fix branch from develop.
+- Treat Docker, Ansible, deployment, authentication, authorization, logging, and CI/CD files as security-sensitive.
+- Run the configured Docker-based validation/test command if changes are made.
+- Update docs/security.md and ADRs if required.
+- Commit using Conventional Commits if changes are made.
+
+Security review scope:
+<DESCRIBE SCOPE HERE>
+
+Requested outcome:
+- Review only
+- Review and fix critical issues
+- Review and propose changes without applying them
+
+Final response must include:
+- reviewed areas;
+- findings by severity;
+- changes made, if any;
+- tests executed and result, if applicable;
+- documentation/ADR updates;
+- residual risks;
+- rollback notes, if changes were made.
+```

.codex/prompts/task.md

@@ -0,0 +1,33 @@
+# Generic task prompt
+
+Use this prompt for a generic implementation task.
+
+```text
+You are working in this repository as Codex.
+
+Mandatory instructions:
+- Read AGENTS.md and all relevant files under .codex/ before making changes.
+- Start from develop.
+- Create a dedicated feature branch.
+- Use the logical agent orchestration defined in .codex/orchestration.md.
+- Apply pragmatic TDD.
+- Implement only the minimal necessary change.
+- Run the configured Docker-based test command from .codex/project.md.
+- Update documentation and ADRs if required.
+- Commit using Conventional Commits.
+
+Task:
+<DESCRIBE THE TASK HERE>
+
+Acceptance criteria:
+<LIST ACCEPTANCE CRITERIA HERE>
+
+Final response must include:
+- branch name;
+- commit hash;
+- summary of changes;
+- tests executed and result;
+- documentation/ADR updates;
+- residual risks;
+- rollback notes.
+```

.codex/quality.md

@@ -0,0 +1,39 @@
+# Quality rules
+
+Codex MUST write clean, minimal, maintainable code.
+
+## General rules
+
+Codex MUST:
+
+- prefer simple solutions;
+- avoid over-engineering;
+- avoid unnecessary abstractions;
+- avoid introducing dependencies unless justified;
+- keep functions and modules focused;
+- use clear names;
+- write comments in English only when they add value;
+- preserve existing style unless it conflicts with explicit project rules;
+- keep changes scoped to the requested task;
+- avoid broad rewrites unless explicitly requested.
+
+## Pragmatic TDD
+
+Codex MUST use pragmatic TDD:
+
+- bugfix: write or update a test that reproduces the bug before fixing it, when practical;
+- feature: write tests for expected behavior before implementation, when practical;
+- refactor: rely on existing tests and add missing coverage where needed;
+- documentation-only changes: tests may be unnecessary, but Codex must say so explicitly;
+- infrastructure changes: use syntax checks, dry runs, validation commands, or containerized smoke tests when applicable.
+
+## Completion quality gate
+
+Before completing a task, Codex MUST verify:
+
+- tests were run inside Docker;
+- lint/format checks were run if configured;
+- no unrelated changes were introduced;
+- no secrets were introduced;
+- docs and ADRs were updated if needed;
+- the final commit uses Conventional Commits.

.codex/security.md

@@ -0,0 +1,39 @@
+# Security rules
+
+These rules are always active.
+
+Codex MUST NOT:
+
+- commit secrets, tokens, passwords, private keys, API keys, or real credentials;
+- disable authentication, authorization, TLS verification, CSRF protection, input validation, or security checks unless explicitly requested and documented in an ADR;
+- introduce privileged containers unless explicitly justified in an ADR;
+- use `latest` container tags;
+- add unnecessary open ports;
+- log credentials, tokens, session IDs, cookies, authorization headers, or sensitive payloads;
+- weaken file permissions without justification;
+- introduce dependencies without explaining why they are needed;
+- ignore security-sensitive errors;
+- store secrets in plain YAML, JSON, TOML, dotenv, shell scripts, Dockerfiles, or documentation.
+
+Codex MUST:
+
+- prefer least privilege for users, containers, services, and filesystem permissions;
+- prefer reproducible builds;
+- treat CI/CD, Docker, Ansible, deployment, reverse proxy, and authentication files as security-sensitive;
+- document security-relevant assumptions;
+- flag unclear security requirements before implementing risky behavior;
+- update `docs/security.md` when security behavior changes.
+
+## Security-sensitive changes
+
+The following changes require explicit attention and may require an ADR:
+
+- authentication or authorization changes;
+- network exposure changes;
+- TLS/certificate behavior changes;
+- Docker privilege, capabilities, users, volumes, or network changes;
+- Ansible privilege escalation changes;
+- logging changes involving user data or sensitive data;
+- dependency additions;
+- deployment topology changes;
+- backup, restore, retention, or data deletion behavior changes.

.codex/workflow.md

@@ -0,0 +1,58 @@
+# Codex workflow
+
+Codex works as an autonomous coding agent, but every task MUST be executed through a controlled workflow.
+
+## Standard task flow
+
+For every task, Codex MUST:
+
+1. Read repository instructions and enabled profiles.
+2. Inspect the current repository state.
+3. Ensure the base branch is `develop`.
+4. Create a dedicated task branch.
+5. Understand the requested change.
+6. Identify whether an ADR is required.
+7. Apply pragmatic TDD:
+   - for bug fixes, add or update a failing test first when practical;
+   - for features, define expected behavior with tests first when practical;
+   - for refactors, preserve behavior and rely on existing tests, adding tests if coverage is missing.
+8. Implement the minimal necessary change.
+9. Run the configured Docker-based test command.
+10. Update documentation and ADRs if needed.
+11. Review security and quality impact.
+12. Commit using Conventional Commits.
+13. Provide final output with:
+    - summary;
+    - tests executed;
+    - documentation/ADR updates;
+    - residual risks;
+    - rollback notes.
+
+## Minimal change rule
+
+Codex MUST NOT perform opportunistic rewrites, formatting-only changes, dependency upgrades, architectural changes, or unrelated cleanups unless explicitly requested.
+
+## Test requirement
+
+Codex MUST run the configured Docker-based test command for every task before considering the task complete.
+
+If tests fail, Codex MUST:
+
+- analyze the failure;
+- fix the failure if related to the task;
+- clearly report unrelated pre-existing failures if discovered;
+- never hide failing tests.
+
+If tests cannot be run, Codex MUST explain why and MUST NOT claim that the task is fully verified.
+
+## Rollback requirement
+
+For every completed task, Codex MUST provide rollback notes.
+
+Rollback notes may include:
+
+- the commit hash to revert;
+- files changed;
+- configuration that must be restored;
+- database or state changes, if any;
+- manual cleanup steps, if any.