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

.
├── 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

Copy this template into a new or existing repository.
Edit .codex/project.md and configure:
- project mode;
- enabled profiles;
- Docker-based test command;
- branch naming rules if needed.
Add project-specific details to the documentation under docs/.
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.