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
git-flow-next types (
feature/<issue>-slug, release/*, hotfix/*) on develop-based repos; Conventional Branch short types (feat/<name>) on trunk-flow repos.PR conventions
PR title = the squash commit subject. Squash-merge into
develop (or main on trunk-flow repos); develop → main promotion is merge-commit only.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
Documentation standards
How this site is organized and written — IA, page naming, frontmatter, and the sources the rules derive from.
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
- Verifying the instrument — never let a name resolve to something it does not identify, and mutation-test every new check
ai-assistant-instructions and are loaded as agent context. Anything humans need to read lives here.