Git Workflow Reference Skill

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

Agentic-Trunk (Local Batch Landing)

git_strategy.manual.workflow: agentic-trunk names the model MoAI-ADK's own factory runs on:

main ──────────────────────────────────────────
  └── WT-card-slug ── integration-worktree merge ──→ batch PR (release/main-batch-YYYYMMDD) ──→ tagged release

Rules:

One standing trunk main; card worktrees branch from it
Two delivery routes, decided by which tree holds main: when a dedicated integration worktree holds it, cards land serially there (--no-ff, no per-card pull request); when only the primary checkout holds it, moai factory complete opens the card's pull request and the leader merges it
With the dedicated integration worktree, the leader opens one batch pull request per lead_push_threshold landings
Lanes take no per-version release branch and run no lane push

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

[ ] All commit messages follow conventional format (show git log --oneline)
[ ] Branch name follows convention (feat/, fix/, refactor/, docs/, chore/ prefix)
[ ] No force pushes to main or protected branches (check reflog or CI)
[ ] PR has passing CI checks before merge
[ ] No merge conflict markers in committed files (grep for <<<<<<<)
[ ] SPEC-ID referenced in commit message or PR description when applicable

Agent Skills: Git Workflow Reference

Install this agent skill to your local

Skill Files