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
