> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jacobpevans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Cross-repo writing standards — commit shape, branch shape, PR shape, transport, scripts, diagrams.

> 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

<CardGroup cols={2}>
  <Card title="Commit conventions" icon="code-commit" href="/conventions/commit-conventions">
    No emoji in commit subjects, Conventional Commits, the autonomy rules that decide when to ship vs ask.
  </Card>

  <Card title="Branch conventions" icon="code-branch" href="/conventions/branch-conventions">
    Conventional Branch — short-form types only. `feat/<name>`, never `feature/<name>`.
  </Card>

  <Card title="PR conventions" icon="code-pull-request" href="/conventions/pr-conventions">
    PR title = the squash commit subject. Body leads with the why, ends with the test plan. Squash-merge default.
  </Card>

  <Card title="Git transport" icon="lock" href="/conventions/git-transport">
    SSH for public repos, HTTPS for private repos. Visibility decides — not owner, not org.
  </Card>

  <Card title="README conventions" icon="book-open" href="/conventions/readme-conventions">
    One standalone README shape per repo. Cross-repo context lives on this site, linked once.
  </Card>
</CardGroup>

### Writing & structure

<CardGroup cols={2}>
  <Card title="No scripts in non-script files" icon="ban" href="/conventions/no-scripts">
    Scripts live in dedicated files. YAML, Markdown, and heredocs never carry control flow.
  </Card>

  <Card title="Diagramming" icon="diagram-project" href="/conventions/diagramming">
    Every repo with non-trivial architecture ships diagrams. Inline Mermaid where GitHub renders, standalone `.mmd` + SVG otherwise.
  </Card>
</CardGroup>

## Related standards elsewhere in the site

* [Golden laws](/security/golden-laws) — the 15 non-negotiable security rules
* [Repo boundaries](/ai-development/repo-boundaries) — how rules, plugins, and docs split across the three AI repos
* [CI/CD policy](/infrastructure/cicd/policy) — release-please, dependency pinning, runner choice
* [Dependency automation](/infrastructure/cicd/dependency-automation) — Renovate trust tiers, scheduling, and automerge across every repo
* [OpenTofu check placement](/infrastructure/tofu-check-placement) — static checks in pre-commit, credentialed ops in CI

Standards that are AI-runtime only (tool routing, skill execution semantics, Bifrost routing) stay in [`ai-assistant-instructions`](/ai-development/ai-assistant-instructions) and are loaded as agent context. Anything humans need to read lives here.