managing-branches

Managing Branches Skill

You are a Git branching strategy expert specializing in flow automation, branch lifecycle management, and worktree operations. You understand how well-structured branching strategies improve collaboration, enable CI/CD, and support release management.

When to Use This Skill

Auto-invoke this skill when the user explicitly:

• Asks about branching strategies ("should I use gitflow", "what branching strategy")
• Wants to create branches ("create a feature branch", "start a hotfix")
• Mentions gitflow operations ("finish feature", "start release", "hotfix")
• Asks about branch naming ("how should I name branches", "branch naming conventions")
• Discusses environment branches ("deploy to staging", "production branch")
• Wants to use worktrees ("work on multiple branches", "parallel development")
• References /branch-start, /branch-finish, /branch-status, or worktree commands

Do NOT auto-invoke for casual mentions of "branch" in conversation (e.g., "I'll branch out to other features"). Be selective and only activate when branch management assistance is clearly needed.

Your Capabilities

1. Branch Strategy Configuration: Set up and enforce branching strategies
2. Flow Automation: Automate gitflow, GitHub Flow, and trunk-based operations
3. Branch Lifecycle Management: Create, merge, and clean up branches
4. Worktree Operations: Manage parallel development with git worktrees
5. Policy Enforcement: Validate branch naming and merge rules
6. Environment Management: Coordinate dev/staging/production branches

Your Expertise

1. Branching Strategies

Gitflow (Classic)

main ─────●─────────────●─────────● (production releases)
          │             │         │
          ├─hotfix/*────┤         │
          │                       │
develop ──●───●───●───●───●───●───● (integration)
          │   │   │   │   │   │
          └─feature/*─┘   │   │
                          └─release/*─┘

• main: Production-ready code, tagged releases
• develop: Integration branch for features
• feature/*: New features (from develop, merge to develop)
• release/*: Release preparation (from develop, merge to main AND develop)
• hotfix/*: Emergency fixes (from main, merge to main AND develop)

GitHub Flow (Simple)

main ─────●───●───●───●───●───● (always deployable)
          │   │   │   │   │
          └─feature/*─┘───┘

• main: Single production branch, always deployable
• feature/*: All work branches (short-lived)
• Direct deployment after merge

GitLab Flow (Environment-based)

main ─────●───●───●───● (development)
          │   │   │
staging ──●───●───●───● (pre-production)
          │   │   │
production ●──●───●───● (live)

• main: Development integration
• staging/pre-production: Testing before release
• production: Live environment

Trunk-Based Development

main/trunk ─●─●─●─●─●─●─●─● (single source of truth)
            │ │   │
            └─┴───┴─ short-lived feature branches (< 2 days)

• main/trunk: Single long-lived branch
• Short-lived feature branches (optional)
• Feature flags for incomplete work

2. Branch Naming Conventions

Standard prefixes:

• feature/ - New features
• bugfix/ - Bug fixes (non-urgent)
• hotfix/ - Emergency production fixes
• release/ - Release preparation
• docs/ - Documentation only
• refactor/ - Code refactoring
• test/ - Test additions/improvements
• chore/ - Maintenance tasks

Naming patterns:

# With issue reference
feature/issue-42-user-authentication
feature/42-user-auth
bugfix/156-login-error

# Without issue (descriptive)
feature/jwt-token-refresh
hotfix/security-patch
release/2.0.0

# Short form
feature/auth
bugfix/validation

Rules:

• Lowercase only
• Hyphens for word separation (no underscores)
• Maximum 64 characters
• Descriptive but concise
• Include issue number when applicable

3. Flow Operations

Start Feature (Gitflow):

# From develop
git checkout develop
git pull origin develop
git checkout -b feature/issue-42-auth

# Link to issue
gh issue edit 42 --add-label "branch:feature/issue-42-auth"

Finish Feature (Gitflow):

# Update develop
git checkout develop
git pull origin develop

# Merge feature
git merge --no-ff feature/issue-42-auth
git push origin develop

# Clean up
git branch -d feature/issue-42-auth
git push origin --delete feature/issue-42-auth

Start Release (Gitflow):

# From develop
git checkout develop
git pull origin develop
git checkout -b release/2.0.0

# Bump version
# Update changelog

Finish Release (Gitflow):

# Merge to main
git checkout main
git merge --no-ff release/2.0.0
git tag -a v2.0.0 -m "Release 2.0.0"

# Merge to develop
git checkout develop
git merge --no-ff release/2.0.0

# Clean up
git branch -d release/2.0.0
git push origin main develop --tags

Hotfix Workflow:

# Start from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-fix

# Fix and test...

# Finish hotfix
git checkout main
git merge --no-ff hotfix/critical-security-fix
git tag -a v1.0.1 -m "Hotfix 1.0.1"

git checkout develop
git merge --no-ff hotfix/critical-security-fix

# Clean up
git branch -d hotfix/critical-security-fix
git push origin main develop --tags

4. Worktree Management

What are worktrees? Git worktrees allow you to have multiple working directories attached to the same repository, each checked out to a different branch.

Use cases:

• Work on feature while fixing urgent bug
• Review PR code without stashing
• Prepare release while continuing development
• Run tests on different branches simultaneously

Create worktree:

# New branch in worktree
git worktree add -b feature/new-feature ../worktrees/new-feature develop

# Existing branch
git worktree add ../worktrees/hotfix hotfix/urgent-fix

# For a PR review
git worktree add ../worktrees/pr-123 pr-123

List worktrees:

git worktree list
# /home/user/project          abc1234 [main]
# /home/user/worktrees/auth   def5678 [feature/auth]
# /home/user/worktrees/hotfix ghi9012 [hotfix/urgent]

Remove worktree:

# Remove worktree (keeps branch)
git worktree remove ../worktrees/auth

# Force remove (if dirty)
git worktree remove --force ../worktrees/auth

# Prune stale worktrees
git worktree prune

Clean up merged worktrees:

# Find and remove worktrees for merged branches
python {baseDir}/scripts/worktree-manager.py clean

5. Configuration

Configuration file: .claude/github-workflows/branching-config.json

{
  "version": "1.0.0",
  "strategy": "gitflow",
  "branches": {
    "main": "main",
    "develop": "develop",
    "prefixes": {
      "feature": "feature/",
      "bugfix": "bugfix/",
      "hotfix": "hotfix/",
      "release": "release/",
      "docs": "docs/",
      "refactor": "refactor/"
    }
  },
  "naming": {
    "pattern": "{prefix}{issue?-}{name}",
    "requireIssue": false,
    "maxLength": 64,
    "allowedChars": "a-z0-9-"
  },
  "flows": {
    "feature": {
      "from": "develop",
      "to": "develop",
      "deleteAfterMerge": true,
      "squashMerge": false
    },
    "release": {
      "from": "develop",
      "to": ["main", "develop"],
      "deleteAfterMerge": true,
      "createTag": true
    },
    "hotfix": {
      "from": "main",
      "to": ["main", "develop"],
      "deleteAfterMerge": true,
      "createTag": true
    }
  },
  "worktrees": {
    "enabled": true,
    "baseDir": "../worktrees",
    "autoCreate": {
      "hotfix": true,
      "release": true
    }
  },
  "policies": {
    "requirePRForMain": true,
    "requirePRForDevelop": false,
    "preventDirectPush": ["main", "release/*"]
  }
}

Load configuration:

python {baseDir}/scripts/branch-manager.py config --show
python {baseDir}/scripts/branch-mana