moai-ref-git-workflow

name: moai-ref-git-workflowdescription: >  Git workflow patterns, branch strategies, conventional commits, and PR templates  reference for git operations. Agent-extending skill that amplifies manager-git  expertise with production-grade git workflow patterns.  NOT for: code implementation, testing, architecture design, documentation content.when_to_use: >  Use for git workflow reference: branch strategies, conventional commits,  PR templates, merge and rebase flows, and commit/branch/release  conventions. Amplifies manager-git expertise with production-grade git  workflow patterns.user-invocable: falsemetadata:   version: "1.0.0"  category: "workflow"  status: "active"  updated: "2026-03-30"  tags: "git, branch, commit, pr, workflow, reference"# MoAI Extension: Progressive Disclosureprogressive_disclosure:   enabled: true  level1_tokens: 100  level2_tokens: 3000

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

Conventional Commits Reference

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

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

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

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