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.

AGENTS.md

@@ -0,0 +1,48 @@
+# 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.

README.md

@@ -1,2 +1,73 @@
 # codex-bootstrap
 
+A repository template for AI-assisted development with Codex.
+
+This template defines a repeatable workflow for using Codex as an autonomous coding agent that can create branches, modify code, run Docker-based tests, update documentation, write ADRs, and commit changes using Conventional Commits.
+
+## Purpose
+
+Use this template to bootstrap repositories where Codex must operate with clear rules, minimal changes, pragmatic TDD, security guardrails, and explicit documentation requirements.
+
+## Repository structure
+
+```text
+.
+├── AGENTS.md
+├── README.md
+├── .codex/
+│   ├── project.md
+│   ├── workflow.md
+│   ├── security.md
+│   ├── quality.md
+│   ├── orchestration.md
+│   ├── prompts/
+│   │   ├── task.md
+│   │   ├── bugfix.md
+│   │   ├── refactor.md
+│   │   ├── security-review.md
+│   │   └── documentation.md
+│   ├── agents/
+│   │   ├── architect.md
+│   │   ├── developer.md
+│   │   ├── reviewer.md
+│   │   ├── security-reviewer.md
+│   │   ├── test-engineer.md
+│   │   └── documentation-writer.md
+│   └── profiles/
+│       ├── docker.md
+│       ├── ansible.md
+│       └── python.md
+└── docs/
+    ├── adr/
+    │   └── 0000-template.md
+    ├── architecture.md
+    ├── deployment.md
+    ├── operations.md
+    ├── security.md
+    ├── testing.md
+    └── runbook.md
+```
+
+## How to use
+
+1. Copy this template into a new or existing repository.
+2. Edit `.codex/project.md` and configure:
+   - project mode;
+   - enabled profiles;
+   - Docker-based test command;
+   - branch naming rules if needed.
+3. Add project-specific details to the documentation under `docs/`.
+4. When asking Codex to work on a task, use one of the prompt templates under `.codex/prompts/`.
+
+## Core rules
+
+Codex must:
+
+- start work from `develop`;
+- create a dedicated `feature/`, `fix/`, or `hotfix/` branch;
+- use pragmatic TDD;
+- keep changes minimal and focused;
+- run the configured Docker-based test command before completion;
+- update documentation and ADRs when needed;
+- produce a final report with summary, tests, risks, and rollback notes;
+- commit using Conventional Commits.

docs/adr/0000-template.md

@@ -0,0 +1,33 @@
+# ADR-0000: Title
+
+Date: YYYY-MM-DD
+
+Status: Proposed | Accepted | Superseded | Deprecated
+
+## Context
+
+Describe the problem, constraints, assumptions, and relevant background.
+
+## Decision
+
+Describe the decision that has been made.
+
+## Consequences
+
+Describe positive, negative, and neutral consequences.
+
+## Alternatives considered
+
+Describe alternatives and why they were not selected.
+
+## Security impact
+
+Describe security implications, if any.
+
+## Operational impact
+
+Describe deployment, monitoring, rollback, backup, restore, or operational implications, if any.
+
+## Rollback
+
+Describe whether and how this decision can be reverted.

docs/architecture.md

@@ -0,0 +1,13 @@
+# Architecture
+
+Describe the project architecture here.
+
+Include:
+
+- main components;
+- runtime dependencies;
+- data flow;
+- persistence;
+- external integrations;
+- deployment topology;
+- relevant ADRs.

docs/deployment.md

@@ -0,0 +1,15 @@
+# Deployment
+
+Describe how this project is deployed.
+
+Include:
+
+- environments;
+- Docker/Compose usage;
+- required configuration;
+- secrets handling;
+- exposed ports;
+- volumes;
+- networks;
+- deployment commands;
+- rollback procedure.

docs/operations.md

@@ -0,0 +1,13 @@
+# Operations
+
+Describe operational procedures.
+
+Include:
+
+- startup and shutdown;
+- health checks;
+- logs;
+- monitoring;
+- backup and restore;
+- routine maintenance;
+- known operational risks.

docs/runbook.md

@@ -0,0 +1,19 @@
+# Runbook
+
+Operational runbook for this project.
+
+## Common tasks
+
+Document routine operational tasks here.
+
+## Troubleshooting
+
+Document known issues, symptoms, checks, and remediation steps.
+
+## Rollback
+
+Document rollback procedures here.
+
+## Emergency contacts
+
+Document project-specific escalation paths if appropriate.

docs/security.md

@@ -0,0 +1,16 @@
+# Security
+
+Describe security assumptions and controls.
+
+Include:
+
+- authentication;
+- authorization;
+- network exposure;
+- TLS/certificates;
+- secrets management;
+- logging of sensitive data;
+- container privileges;
+- filesystem permissions;
+- dependency management;
+- relevant ADRs.

docs/testing.md

@@ -0,0 +1,23 @@
+# Testing
+
+Describe how tests are executed.
+
+All tests should run inside Docker containers.
+
+## Canonical test command
+
+```bash
+CHANGE_ME
+```
+
+## Test categories
+
+Describe applicable categories:
+
+- unit tests;
+- integration tests;
+- linting;
+- formatting checks;
+- Ansible syntax checks;
+- Docker/Compose validation;
+- smoke tests.