Skip to main content

Branching, repo & commit conventions

One page, enforced by tooling. The theme: at agent speed, divergence is the enemy — keep changes small, integrated continuously, and attributable.

Branching​

  • Trunk-based development with short-lived branches. A branch lives hours to a day, not weeks.
  • Long-lived branches are treated as a hazard. Agents generate change fast; a branch that lingers diverges faster than a human's would and becomes painful to merge. If work is too big for a short branch, it's too big for one task — decompose it.
  • Feature flags, not long branches, carry incomplete work into trunk safely.

Commits​

  • Conventional Commits (feat:, fix:, chore:, …) so changelogs and release notes generate automatically.
  • Commit messages end with the agent-provenance co-authorship line so history records what built each change.

Repo shape​

  • CODEOWNERS routes review to the accountable people/squads automatically.
  • Monorepo vs polyrepo: pick a default per product with explicit criteria for exceptions, recorded as an ADR. Don't mix models by accident.

Why it's enforced by tooling, not culture​

Conventions that rely on everyone remembering fail under volume. Branch-protection rules, commit linting and CODEOWNERS make the convention the path of least resistance — the only path the merge gate accepts.