Standards that apply to every repo, public or private, regardless of language or tool.These conventions are the human-readable form of policies that AI assistants enforce automatically. Every contributor — human or model — works inside the same envelope, so PRs land consistently no matter who authored them.
What this section covers
Git & GitHub
Commit conventions
No emoji in commit subjects, Conventional Commits, the autonomy rules that decide when to ship vs ask.
Branch conventions
Conventional Branch — short-form types only.
feat/<name>, never feature/<name>.PR conventions
PR title = the squash commit subject. Body leads with the why, ends with the test plan. Squash-merge default.
Git transport
SSH for public repos, HTTPS for private repos. Visibility decides — not owner, not org.
README conventions
One standalone README shape per repo. Cross-repo context lives on this site, linked once.
Writing & structure
No scripts in non-script files
Scripts live in dedicated files. YAML, Markdown, and heredocs never carry control flow.
Diagramming
Every repo with non-trivial architecture ships diagrams. Inline Mermaid where GitHub renders, standalone
.mmd + SVG otherwise.Related standards elsewhere in the site
- Golden laws — the 15 non-negotiable security rules
- Repo boundaries — how rules, plugins, and docs split across the three AI repos
- CI/CD policy — release-please, dependency pinning, runner choice
- Dependency automation — Renovate trust tiers, scheduling, and automerge across every repo
- OpenTofu check placement — static checks in pre-commit, credentialed ops in CI
ai-assistant-instructions and are loaded as agent context. Anything humans need to read lives here.