Skip to content

Engineering Standards

These documents are binding. Every contributor, human or AI agent, follows them. A change that breaks a rule is not merged.

Each rule has an ID (e.g. COV-2) so reviews and commit messages can cite it, and names what enforces it. review means a human checks it, and the rule is in the PR checklist.

# Document Covers
01 Repository layout Where things live
02 Commits, branches & versioning Conventional Commits, SemVer from tags, automatic releases
03 Code quality Python conventions, typing, linting, dependency injection
04 Architecture Layers, ports & adapters, import contracts
05 Testing Test types, 100 % coverage, mutation testing
06 Documentation Docs that cannot go stale, docstrings, ADRs
07 Security Generic application and supply-chain security
08 Git hooks What runs at commit, commit-msg and pre-push
09 CI/CD Workflows, required checks, releases
10 Definition of Done The checklist for every change
11 Keeping standards current How these rules evolve and reach every project
— Project-specific Rules that only apply to this project

Principles

  1. Shift left. Every rule has a gate, and every gate runs at the earliest stage that can run it: in the editor and at commit, then at push, then in CI, with only the slow or external checks left to nightly and weekly jobs. Each README shows this as a generated table, next to badges that report what the gates measured.
  2. Machines enforce, humans judge. Anything a tool can check is checked by a tool, locally and in CI.
  3. Local hooks are a convenience; CI is the authority. Hooks can be skipped with --no-verify; CI cannot. CI reruns every hook stage.
  4. No silent exceptions. Exclusions (coverage, lint, typing) are declared in configuration, with a reason, where review sees them. Inline exclusions are refused.
  5. The standards are code. They are versioned, released, tested (standards check-standards) and pulled into projects like any other dependency (11).