Contributing
Commits, branches, git hooks, and the AI tooling conventions every developer working in this repo needs to know.
This section documents the conventions every developer working in the ITU monorepo is expected to follow — how commits are formatted, how branches are named, which hooks run when, how the Turbo pipeline is wired, and the AI tooling (openspec, the .ai/ skill registry, surfaces inventory, and the AGENTS.md convention) that helps you scope and ship changes consistently.
Read this before you land your first commit in this repo. The rules here are enforced by hooks and CI, so a non-conforming commit, branch, or MDX page will be rejected before it leaves your machine. The good news: once you know the shape, it all stays out of your way.
Two sub-groups
AI tooling
Openspec workflow, the .ai/ skill registry, surfaces inventory, and the AGENTS.md / concepts convention.
Conventions
Commits, branches, git hooks, the Turbo pipeline, and the pre-push accessibility audit.
Where to start
If you're new to the repo, the shortest useful path is:
Get the repo running
Walk through the Quick Start to set up your local environment, install dependencies, and verify the dev servers come up. Nothing in this section assumes the repo is in a working state.
Learn the commit and branch rules
Before your first commit, read Commit messages and Branch naming. Both are enforced by hooks — a non-conforming commit or branch will be rejected before it leaves your machine.
Understand what runs on your push
Skim the Git hooks tour so you know which checks fire on commit vs push, and what to do when one fails. Most of the time the answer is "fix the underlying issue" — bypass flags like --no-verify are actively discouraged.
Adopt the openspec workflow for non-trivial changes
For anything bigger than a typo fix, read the Openspec workflow page and use opsx:propose to scope the change before you start coding. The proposal forces you to think about which surfaces you're touching before you touch them.
Why these conventions exist
Every rule in this section exists because it's been load-bearing in practice — a hook prevents a class of bug, a workflow forces a class of decision, an inventory prevents a class of oversight. None of it is decoration. If you find a convention that doesn't seem to be doing useful work, that's worth raising as an openspec proposal: either the rule needs better justification on the page, or it should be removed.