Git Workflow Agent Rules
Project Context
You are working within a team git workflow. All changes are reviewed via pull requests, the main branch is always deployable, and commit history is clean and meaningful.
Branching Strategy
- Use trunk-based development for small, fast-moving teams: short-lived feature branches, merge within 1–2 days.
- Use Gitflow for teams with scheduled releases: `main`, `develop`, `feature/*`, `release/*`, `hotfix/*`.
- Name branches with type and ticket reference: `feature/AGE-123-add-oauth`, `fix/AGE-456-memory-leak`, `hotfix/AGE-789-security-patch`.
- Keep feature branches short-lived — branches open longer than 3 days accumulate merge conflicts.
- Delete branches immediately after merging — stale branches cause confusion about active work.
- Protect `main` and `develop` with branch protection rules: require PRs, status checks, and up-to-date branches.
Conventional Commits
- Use the Conventional Commits specification for all commit messages: `<type>(<scope>): <subject>`.
- Types: `feat` (new feature), `fix` (bug fix), `docs` (docs only), `style` (formatting), `refactor` (no feature/fix), `perf` (performance), `test` (tests), `chore` (build/tooling), `ci` (CI config), `revert`.
- Subject line: imperative mood, under 72 characters, no trailing period: `feat(auth): add OAuth2 login with Google`.
- Body: wrap at 80 characters, explain what changed and why, not how.
- Footer: `Closes #123`, `Fixes #456`, `BREAKING CHANGE: removed deprecated API`.
- Each commit should represent one logical change — avoid commits that mix feature work with unrelated refactors.
- Never commit generated files, build artifacts, secrets, or `node_modules/`.
Rebase & History
- Rebase feature branches onto `main` before opening a pull request: `git fetch origin && git rebase origin/main`.
- Use `git rebase -i HEAD~<n>` to squash fixup commits before a PR: `WIP`, `fix typo`, and `address review` commits should be squashed.
- Use `git commit --fixup <sha>` during review and `git rebase -i --autosquash` to fold fixes into the original commits.
- Never rebase shared branches — only rebase local commits before they are pushed to the remote.
- Use `git cherry-pick` to port specific fixes to release or hotfix branches.
- Use `git bisect start` / `git bisect good` / `git bisect bad` to binary search for regression-introducing commits.
Pull Requests
- Keep PRs under 400 lines of diff — smaller PRs receive faster, more thorough reviews.
- Write a clear PR description: what changed, why, how to test, screenshots if UI changed.
- Link to the issue or ticket with `Closes #<number>` in the description body.
- Request review from at least one team member before merging.
- Address all reviewer comments — respond to every thread even if only to acknowledge.
- Prefer squash merges for feature branches to keep `main` history clean.
- Use regular merges for long-running branches (release, hotfix) to preserve context.
- Never merge a PR until CI passes — fix failing tests before merging.
Git Hooks
- Use `pre-commit` hooks to run linting and formatting: fail fast before the commit is recorded.
- Use `commit-msg` hooks to validate commit message format against Conventional Commits regex.
- Use `pre-push` hooks to run the test suite before pushing to the remote.
- Use `husky` + `lint-staged` for Node.js projects to run hooks on staged files only — keeps hooks fast.
- Keep hooks fast (under 5 seconds) — slow hooks get disabled by developers.
Tags & Releases
- Tag releases with semantic version tags: `v1.2.3` — annotated tags with `git tag -a v1.2.3 -m "Release 1.2.3"`.
- Push tags explicitly: `git push origin v1.2.3` — they are not pushed by default with `git push`.
- Use `git describe --tags` in build scripts to embed the version into the binary or artifact.
- Sign releases with GPG: `git config user.signingkey <keyid>` and `git tag -s v1.2.3`.
Gitignore & Hygiene
- Add IDE files (`.idea/`, `.vscode/`), OS metadata (`.DS_Store`, `Thumbs.db`), build artifacts (`dist/`, `build/`), and environment files (`.env`, `.env.local`) to `.gitignore`.
- Use `.gitattributes` to normalize line endings: `* text=auto` to prevent CRLF/LF conflicts on mixed OS teams.
- Use `git lfs track "*.psd" "*.mp4"` for large binary files — never commit binaries directly to git.
- Use `git blame -w -C -C -C` to trace the history of a line ignoring whitespace and moves.
Git
