An opinionated Codex-native foundation for Python projects with a human-controlled development workflow, progressively loaded engineering standards, reproducible quality tooling, and selectable source-control hosting.
Create an independent repository rather than a fork unless you intend to contribute changes back to this boilerplate. Then follow the single linear Getting Started guide from repository creation through project setup and verification.
The customization reference explains the available setup fields and generated behavior. Consult it when choosing values; the executable sequence remains in Getting Started.
- Python 3.14 dependency and environment management with uv;
- Ruff, Pyright, pytest, coverage, Import Linter, and pre-commit;
- a root
AGENTS.mdworking agreement; - repository Skills and progressively loaded engineering standards;
- a project-scoped independent Codex reviewer;
- project-definition and Architecture Decision Record foundations;
- GitHub and GitLab automation plus provider-neutral output;
- deterministic, preview-first project customization.
The boilerplate intentionally does not select application architecture, framework dependencies, infrastructure, deployment, or product requirements.
Create the environment and install hooks:
uv sync --locked
uv run pre-commit install --hook-type pre-commit --hook-type pre-pushRun the complete local quality gate:
uv lock --check
uv run pre-commit run --all-files
uv run pre-commit run --all-files --hook-stage pre-push
uv buildRead Contributing before proposing changes. Usage questions belong in Support, and vulnerabilities must follow the private process in Security.
- Getting Started
- Customizing the Boilerplate
- Development Tooling
- Agent Configuration
- Project Definition
- Architecture Decisions
The boilerplate is distributed under the MIT License. Projects that choose another license must preserve the boilerplate notice as described in the customization guide.