From ad0e29cf699ea29a44deb2c6977a141f2b417680 Mon Sep 17 00:00:00 2001 From: bisco Date: Tue, 28 Apr 2026 10:14:33 +0200 Subject: [PATCH] added codex structure --- .codex/agents/architect.md | 27 +++++++ .codex/agents/developer.md | 25 ++++++ .codex/agents/documentation-writer.md | 17 ++++ .codex/agents/reviewer.md | 23 ++++++ .codex/agents/security-reviewer.md | 20 +++++ .codex/agents/test-engineer.md | 18 +++++ .codex/orchestration.md | 41 ++++++++++ .codex/profiles/ansible.md | 40 ++++++++++ .codex/profiles/docker.md | 40 ++++++++++ .codex/profiles/python.md | 42 ++++++++++ .codex/project.md | 107 ++++++++++++++++++++++++++ .codex/prompts/bugfix.md | 37 +++++++++ .codex/prompts/documentation.md | 30 ++++++++ .codex/prompts/refactor.md | 36 +++++++++ .codex/prompts/security-review.md | 31 ++++++++ .codex/prompts/task.md | 33 ++++++++ .codex/quality.md | 39 ++++++++++ .codex/security.md | 39 ++++++++++ .codex/workflow.md | 58 ++++++++++++++ AGENTS.md | 48 ++++++++++++ README.md | 71 +++++++++++++++++ docs/adr/0000-template.md | 33 ++++++++ docs/architecture.md | 13 ++++ docs/deployment.md | 15 ++++ docs/operations.md | 13 ++++ docs/runbook.md | 19 +++++ docs/security.md | 16 ++++ docs/testing.md | 23 ++++++ 28 files changed, 954 insertions(+) create mode 100644 .codex/agents/architect.md create mode 100644 .codex/agents/developer.md create mode 100644 .codex/agents/documentation-writer.md create mode 100644 .codex/agents/reviewer.md create mode 100644 .codex/agents/security-reviewer.md create mode 100644 .codex/agents/test-engineer.md create mode 100644 .codex/orchestration.md create mode 100644 .codex/profiles/ansible.md create mode 100644 .codex/profiles/docker.md create mode 100644 .codex/profiles/python.md create mode 100644 .codex/project.md create mode 100644 .codex/prompts/bugfix.md create mode 100644 .codex/prompts/documentation.md create mode 100644 .codex/prompts/refactor.md create mode 100644 .codex/prompts/security-review.md create mode 100644 .codex/prompts/task.md create mode 100644 .codex/quality.md create mode 100644 .codex/security.md create mode 100644 .codex/workflow.md create mode 100644 AGENTS.md create mode 100644 docs/adr/0000-template.md create mode 100644 docs/architecture.md create mode 100644 docs/deployment.md create mode 100644 docs/operations.md create mode 100644 docs/runbook.md create mode 100644 docs/security.md create mode 100644 docs/testing.md diff --git a/.codex/agents/architect.md b/.codex/agents/architect.md new file mode 100644 index 0000000..1dd860c --- /dev/null +++ b/.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. diff --git a/.codex/agents/developer.md b/.codex/agents/developer.md new file mode 100644 index 0000000..f9356ea --- /dev/null +++ b/.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. diff --git a/.codex/agents/documentation-writer.md b/.codex/agents/documentation-writer.md new file mode 100644 index 0000000..99db6d2 --- /dev/null +++ b/.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. diff --git a/.codex/agents/reviewer.md b/.codex/agents/reviewer.md new file mode 100644 index 0000000..66413fd --- /dev/null +++ b/.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? diff --git a/.codex/agents/security-reviewer.md b/.codex/agents/security-reviewer.md new file mode 100644 index 0000000..5fa7df2 --- /dev/null +++ b/.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. diff --git a/.codex/agents/test-engineer.md b/.codex/agents/test-engineer.md new file mode 100644 index 0000000..fb6868a --- /dev/null +++ b/.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. diff --git a/.codex/orchestration.md b/.codex/orchestration.md new file mode 100644 index 0000000..69721a9 --- /dev/null +++ b/.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. diff --git a/.codex/profiles/ansible.md b/.codex/profiles/ansible.md new file mode 100644 index 0000000..9e57d8e --- /dev/null +++ b/.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. diff --git a/.codex/profiles/docker.md b/.codex/profiles/docker.md new file mode 100644 index 0000000..0f267fb --- /dev/null +++ b/.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 +``` diff --git a/.codex/profiles/python.md b/.codex/profiles/python.md new file mode 100644 index 0000000..b73c338 --- /dev/null +++ b/.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 . +``` diff --git a/.codex/project.md b/.codex/project.md new file mode 100644 index 0000000..8b6341e --- /dev/null +++ b/.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. diff --git a/.codex/prompts/bugfix.md b/.codex/prompts/bugfix.md new file mode 100644 index 0000000..20fc664 --- /dev/null +++ b/.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: + + +Expected behavior: + + +Observed behavior: + + +Acceptance criteria: + + +Final response must include: +- branch name; +- commit hash; +- root cause; +- summary of changes; +- tests executed and result; +- documentation/ADR updates; +- residual risks; +- rollback notes. +``` diff --git a/.codex/prompts/documentation.md b/.codex/prompts/documentation.md new file mode 100644 index 0000000..771235c --- /dev/null +++ b/.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: + + +Acceptance criteria: + + +Final response must include: +- branch name; +- commit hash; +- summary of documentation changes; +- tests/checks executed, if applicable; +- ADR updates; +- residual risks; +- rollback notes. +``` diff --git a/.codex/prompts/refactor.md b/.codex/prompts/refactor.md new file mode 100644 index 0000000..c240f7d --- /dev/null +++ b/.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: + + +Non-goals: + + +Acceptance criteria: + + +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. +``` diff --git a/.codex/prompts/security-review.md b/.codex/prompts/security-review.md new file mode 100644 index 0000000..7ebe314 --- /dev/null +++ b/.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: + + +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. +``` diff --git a/.codex/prompts/task.md b/.codex/prompts/task.md new file mode 100644 index 0000000..ff1d5d6 --- /dev/null +++ b/.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: + + +Acceptance criteria: + + +Final response must include: +- branch name; +- commit hash; +- summary of changes; +- tests executed and result; +- documentation/ADR updates; +- residual risks; +- rollback notes. +``` diff --git a/.codex/quality.md b/.codex/quality.md new file mode 100644 index 0000000..981d4fb --- /dev/null +++ b/.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. diff --git a/.codex/security.md b/.codex/security.md new file mode 100644 index 0000000..19b6725 --- /dev/null +++ b/.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. diff --git a/.codex/workflow.md b/.codex/workflow.md new file mode 100644 index 0000000..775bb6a --- /dev/null +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2292609 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 11ca552..bfc04f4 100644 --- a/README.md +++ b/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. diff --git a/docs/adr/0000-template.md b/docs/adr/0000-template.md new file mode 100644 index 0000000..beebd45 --- /dev/null +++ b/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. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..5e50cc6 --- /dev/null +++ b/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. diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..24755d5 --- /dev/null +++ b/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. diff --git a/docs/operations.md b/docs/operations.md new file mode 100644 index 0000000..86223df --- /dev/null +++ b/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. diff --git a/docs/runbook.md b/docs/runbook.md new file mode 100644 index 0000000..dea74d2 --- /dev/null +++ b/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. diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..0e855fa --- /dev/null +++ b/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. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..928ca48 --- /dev/null +++ b/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.