Git Conventions

---
name: git-conventions
description: Apply when committing, branching, or opening a pull request. Conventional commit format, branch naming, PR scope.
license: MIT
version: 1.0.0
tokens_target: 650
triggers:
  - git commit
  - branch
  - pull request
loads_after: []
supersedes: []
---

# Sub-Skill: Git & Workflow Conventions
<!-- target: ~650 tokens (real tiktoken count) | 15 rules -->

**Purpose:** Consistent commit history, clean branches, no merge conflicts through discipline.
Rules that work in teams of 2–20 developers.

---

## Rules

### Commit Messages (Conventional Commits)

1. **Format:** `<type>(<scope>): <description>` — always lowercase, no period at the end.
   - Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`
   - Example: `feat(auth): add JWT refresh token rotation`
2. **Description in imperative mood.** `add feature` not `added feature` or `adds feature`.
3. **Scope is the affected module name.** `fix(user-service): handle null email` — not `fix(backend)`.
4. **Mark breaking changes with `!`.** `feat(api)!: remove deprecated v1 endpoints`
5. **Body for non-obvious changes.** Explains the *why*, not the *what*.

### Branching

6. **Branch names:** `<type>/<ticket-id>-<short-description>` — e.g. `feat/PROJ-123-user-export`.
7. **Feature branches live max. 2 days.** Longer → rebase daily onto `main`.
8. **No direct push to `main` or `develop`.** Always through a pull request.
9. **Delete branch before PR merge.** Clean up merged branches from remote.

### Pull Requests

10. **PR title = commit message of the squash commit.** Consistency between PR and git log.
11. **Max. 400 lines diff per PR.** Larger → split. Reviewers cannot meaningfully review more than 400 lines.
12. **Self-review before opening a PR.** Read through once yourself, fix obvious mistakes.

### Merge Strategy

13. **Squash-merge for feature branches.** Clean linear history on `main`.
14. **Merge commit for release branches.** So release points remain visible.
15. **`git rebase -i` before PR for clean commits.** Squash WIP commits together.

---

## Why This Sub-Skill Earns Stars

The agent automatically creates correct commit messages and branch names.
No manual corrections, no discussions in review about formatting.