Enforces git branching strategy, PR process, and merge rules. Covers branch naming, commit conventions, PR creation, CI requirements, and the merge-to-main checklist. Use when creating branches, making commits, opening PRs, or merging code.

Git Workflow

Main is always deployable. No exceptions.

Branching Strategy (GitHub Flow)

main (protected - always deployable)
  ├── feature/user-auth
  ├── feature/search-api
  ├── fix/login-timeout
  └── chore/upgrade-deps

Branch Naming

Prefix	Use
`feature/`	New functionality
`fix/`	Bug fixes
`refactor/`	Code restructuring with no behavior change
`chore/`	Build config, dependencies, CI, docs

Rules:

Lowercase, hyphens only. No spaces, no underscores.
Short and descriptive: feature/user-search, not feature/implement-the-user-search-functionality-with-filters.
One concern per branch. Don't mix a feature with a refactor.

Creating a Branch

git checkout main
git pull origin main
git checkout -b feature/your-feature

Commit Conventions

Format: type: short description

feat: add user search endpoint
fix: correct pagination off-by-one
refactor: extract auth middleware into separate module
chore: upgrade dependencies to latest
test: add unit tests for rate limiting

Types: feat, fix, refactor, chore, test, docs

Rules:

Present tense, imperative mood ("add" not "added" or "adds").
First line under 72 characters.
Commit often. Small, atomic commits that each do one thing.
Never commit: .env, credentials, API keys, large binaries.

Pull Request Process

1. Before Opening PR

2. Open PR

gh pr create --title "feat: add user search" --body "$(cat <<'EOF'
## Summary
- Brief description of what changed and why

## Test plan
- [ ] Unit tests pass
- [ ] Manual verification of key flows
EOF
)"

3. CI Must Pass

Automated checks run on every PR. All must pass before merge.

4. Code Review

Run /review on the PR changes. Address all CRITICAL and WARNING items.

5. Merge to Main

gh pr merge --squash

Squash merge keeps main history clean. The PR title becomes the merge commit message.

6. Clean Up

git checkout main
git pull origin main
git branch -d feature/your-feature

What Goes Directly to Main (Never)

Nothing. Even a one-line fix gets a branch and PR. The CI gate and review step catch things humans miss.

Hotfix Process

Same as above but with urgency:

git checkout main && git pull
git checkout -b fix/critical-issue
# fix, commit, push, PR, CI passes, merge

workflow