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.