git-workflow

Git Workflow Patterns

Overview

Ensures consistent Git practices across all agent workflows, favoring isolated work environments (worktrees) and clean lifecycle closure.

Branch Setup

Option A: Standard Branching

Use for quick, single-task fixes where isolated environments are not required.

git checkout main && git pull origin main
git checkout -b feature/{feature-name}

Option B: Isolated Worktree (RECOMMENDED)

Use for complex features or PR reviews to keep the main workspace clean.

# Use automated script for features
./scripts/worktree-feature.sh {feature-name}
cd ../.worktrees/feature-{feature-name}

# OR for PR reviews
./scripts/worktree-review.sh {pr-number}
cd ../.worktrees/pr-{pr-number}

Why worktrees?

• Parallel work without stashing.
• Isolated dependencies.
• No interruption of main branch state.

Branch Lifecycle Closure (MANDATORY)

[!CAUTION] BLOCKING STEP. Never proceed to task completion with an open, unmerged feature branch unless explicitly documented.

Option A: Work Merged via PR (Recommended)

If the PR was merged via GitHub:

# Switch to main and clean up
git checkout main
git pull origin main
git branch -d feature/{name}      # Delete local

Option B: Local-Only Work (Direct Merge)

If work was small and doesn't need a PR:

# Merge locally and clean up
git checkout main
git merge feature/{name} --no-ff -m "merge: {feature}"
git branch -d feature/{name}      # Delete local
git push origin main

Option C: Abandon Work

git checkout main
git branch -D feature/{name}      # Force delete local
git push origin --delete feature/{name}  # Delete remote (if exists)

Option D: Keep WIP (Escape Hatch)

If the branch must stay open (e.g., waiting for review):

export SKIP_BRANCH_CHECK=1
git push

Option E: Worktree Cleanup

# From main workspace
git worktree remove ../.worktrees/{name}
./scripts/worktree-cleanup.sh  # Prune metadata