Git Workflow Reference
Target Agent
manager-git - Applies these patterns directly to git operations, branch management, and PR creation.
Branch Strategy Patterns
GitHub Flow (Default for Most Projects)
main ─────────────────────────────────────────
└── feat/SPEC-XXX-description ──── PR ──→ merge
Rules:
main is always deployable- Feature branches from
main
- PR required for all merges
- Delete branch after merge
GitFlow (Complex Release Cycles)
main ──────────────────────────────────────────
└── develop ─────────────────────────────────
├── feature/SPEC-XXX ──── PR ──→ develop
└── release/v1.2.0 ────── PR ──→ main + develop
Trunk-Based (CI/CD Heavy)
main ──────────────────────────────────────────
└── short-lived branch (< 1 day) ──→ merge
Branch Naming Convention
| Pattern |
Example |
Use Case |
feat/SPEC-{ID}-{slug} |
feat/SPEC-AUTH-001-jwt-auth |
New feature |
fix/SPEC-{ID}-{slug} |
fix/SPEC-BUG-042-null-check |
Bug fix |
refactor/{slug} |
refactor/extract-auth-middleware |
Refactoring |
docs/{slug} |
docs/api-reference-update |
Documentation |
chore/{slug} |
chore/upgrade-dependencies |
Maintenance |
Conventional Commits Reference
| Type |
When |
Example |
feat |
New feature |
feat(auth): add JWT refresh token flow |
fix |
Bug fix |
fix(api): handle null user in profile endpoint |
refactor |
Code restructure |
refactor(db): extract query builder |
test |
Test changes |
test(auth): add login edge case tests |
docs |
Documentation |
docs(api): update endpoint descriptions |
chore |
Maintenance |
chore(deps): upgrade Go to 1.23 |
perf |
Performance |
perf(query): add index for user lookup |
style |
Formatting |
style: apply gofmt formatting |
ci |
CI/CD changes |
ci: add GitHub Actions workflow |
revert |
Revert commit |
revert: undo feat(auth) commit abc123 |
Commit Message Structure
<type>(<scope>): <description> # max 72 chars
[optional body] # what and why, not how
[optional footer] # Breaking changes, issue refs
BREAKING CHANGE: <description>
Refs: #123, SPEC-AUTH-001
Pull Request Template
## Summary
- [1-3 bullet points describing what this PR does]
## Changes
- [ ] File 1: description of change
- [ ] File 2: description of change
## Test Plan
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed
## SPEC Reference
- SPEC-{ID}: {title}
## Checklist
- [ ] Tests pass (project test command)
- [ ] Lint and format pass (project toolchain)
- [ ] No secrets committed
- [ ] Documentation updated if needed
Merge Strategy Selection
| Strategy |
When |
Command |
| Squash merge |
Feature branches (clean history) |
gh pr merge --squash |
| Merge commit |
Release branches (preserve history) |
gh pr merge --merge |
| Rebase |
Small, clean commits |
gh pr merge --rebase |
The active method for sync-phase PR auto-merge is governed by the git_strategy.<mode>.merge_method config value (squash | merge | rebase; default squash), not hardcoded. The sync agent resolves it from the active mode profile and renders the matching gh pr merge --<merge_method> command.
Git Safety Rules
| Action |
Risk |
Rule |
git push --force |
Overwrites remote |
NEVER on main/master, ask user first |
git reset --hard |
Loses local changes |
Confirm with user first |
git checkout . |
Discards changes |
Confirm with user first |
git branch -D |
Deletes branch |
Only after merge confirmed |
--no-verify |
Skips hooks |
NEVER unless user explicitly requests |
git rebase -i |
Interactive (not supported) |
NEVER use (requires interactive input) |
Context Memory in Commits
Embed decision context in commit messages for future session continuity:
feat(auth): implement JWT refresh token rotation
Decision: Chose rotation over sliding window for security
Pattern: Middleware chain: RateLimit -> Auth -> Authz -> Handler
Gotcha: Token blacklist requires Redis, not just in-memory cache
Refs: SPEC-AUTH-001
Common Rationalizations
| Rationalization |
Reality |
| "I will clean up the commit messages before merging" |
Interactive rebase is error-prone under pressure. Write clean commits from the start. |
| "Force push is fine on my feature branch" |
Collaborators or CI may have fetched the branch. Force push destroys their reference. Use --force-with-lease. |
| "This commit is too small to need a conventional format" |
Changelog generators, bisect, and blame all depend on consistent commit formats. Every commit matters. |
| "I will push directly to main, it is a small fix" |
Direct pushes bypass code review and CI. Even small fixes can break production. |
| "Merge commits are messy, I always squash" |
Squash loses individual commit context. Merge commits preserve the development narrative for future debugging. |
Red Flags
- Commit message does not follow conventional format (type(scope): description)
- Force push to main or shared release branch
- PR merged without CI passing
- Branch name does not indicate feature, fix, or SPEC reference
- Merge conflict markers found in committed files
Verification
gabrielmoreira