git-workflow
Standardized patterns for Git branching, worktrees, and lifecycle management.
When & Why to Use This Skill
This Claude skill provides a standardized framework for Git operations, focusing on efficient branching strategies, worktree management, and rigorous lifecycle closure. It enhances developer productivity by promoting isolated work environments and ensuring repository health through automated cleanup and consistent merge protocols, making it an essential tool for maintaining clean and scalable codebases.
Use Cases
- Isolated Feature Development: Use Git worktrees to handle complex features in parallel without the need for stashing or disrupting the state of the main branch.
- Efficient PR Reviews: Quickly spin up dedicated environments for reviewing Pull Requests using automated scripts, allowing for testing and validation without affecting the primary workspace.
- Automated Repository Cleanup: Enforce mandatory branch closure patterns to ensure that merged or abandoned branches are systematically removed from both local and remote environments.
- Standardized Workflow Integration: Implement consistent Git patterns across AI agent workflows to prevent merge conflicts and maintain a predictable development lifecycle.
| name | git-workflow |
|---|---|
| description | Standardized patterns for Git branching, worktrees, and lifecycle management. |
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
Instrumentation
./scripts/log-skill.sh "git-workflow" "workflow" "{calling_workflow_name}"