git-workflow-and-versioning

Use the format 'type: short description' with types like feat, fix, refactor, test, docs, or chore, followed by an optional body explaining why the change was made. The message should explain intent, not just restate what the diff shows.

Separate concerns first: keep formatting, refactoring, and feature changes in distinct commits. Each commit should do one logical thing, target roughly 100 lines, and pass tests independently before committing.

Trunk-based development keeps main always deployable with short-lived feature branches merged within 1-3 days. It is the recommended default because long-lived branches accumulate merge risk, though the commit discipline applies to any branching model.

Bump major for breaking changes, minor for backward-compatible features, and patch for backward-compatible fixes. When unsure whether a change is breaking, assume it is, since consumers may rely on behavior beyond the documented API.

Yes, use git worktrees to give each agent its own directory checked out to a separate branch. This avoids branch switching conflicts, and failed experiments can be discarded by removing the worktree.

Never commit environment files like .env, build output like dist/ or .next/, node_modules/, or secrets such as .pem keys. Set up a .gitignore immediately and scan staged diffs for passwords, tokens, and API keys before committing.