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

Branch Strategy Configuration: Set up and enforce branching strategies
Flow Automation: Automate gitflow, GitHub Flow, and trunk-based operations
Branch Lifecycle Management: Create, merge, and clean up branches
Worktree Operations: Manage parallel development with git worktrees
Policy Enforcement: Validate branch naming and merge rules
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:

bash

# 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):

bash

# 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):

bash

# 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):

bash

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

# Bump version
# Update changelog

Finish Release (Gitflow):

bash

# 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:

bash

# 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:

bash

# 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:

bash

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

Remove worktree:

bash

# 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:

bash

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

5. Configuration

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

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:

bash

python {baseDir}/scripts/branch-manager.py config --show
python {baseDir}/scripts/branch-manager.py config --set strategy=github-flow

6. Branch Validation

Validate branch name:

bash

python {baseDir}/scripts/flow-validator.py validate-name "feature/auth"
# ✅ Valid: follows feature branch convention

python {baseDir}/scripts/flow-validator.py validate-name "my_feature"
# ❌ Invalid: must start with prefix, no underscores

Check flow compliance:

bash

python {baseDir}/scripts/flow-validator.py check-flow feature/auth
# ✅ Flow: feature → develop
# ✅ Base branch: develop
# ✅ Merge target: develop

Validate merge:

bash

python {baseDir}/scripts/flow-validator.py validate-merge feature/auth main
# ❌ Invalid: feature branches should merge to develop, not main

Workflow Patterns

Pattern 1: Start New Feature

Trigger: User wants to start working on a new feature

Workflow:

Check current branch and status
Determine base branch from strategy (develop for gitflow, main for github-flow)
Generate branch name from issue or description
Create branch from base
Link to issue if applicable
Optionally create worktree for parallel development
Update project board

Example:

markdown

User: "Start a feature for issue 42"

You:
Let me create a feature branch for issue #42...

Issue: #42 "Implement user authentication"
Strategy: gitflow
Base branch: develop

Creating branch: feature/issue-42-user-auth

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

✅ Branch created: feature/issue-42-user-auth
✅ Linked to issue #42
✅ Ready to start development

Next steps:
1. Implement the feature
2. Commit with: feat(auth): description (Refs #42)
3. When done: /branch-finish or merge to develop

Pattern 2: Finish Feature Branch

Trigger: User is done with feature and wants to merge

Workflow:

Check current branch is a feature branch
Ensure working directory is clean
Update target branch (develop)
Merge feature branch
Push changes
Delete feature branch (local and remote)
Update linked issues
Suggest PR creation if required

Example:

markdown

User: "Finish this feature branch"

You:
Let me complete the feature branch...

Current branch: feature/issue-42-user-auth
Target: develop (per gitflow strategy)

Steps:
1. ✅ Working directory clean
2. ✅ Updated develop from origin
3. ✅ Merged feature/issue-42-user-auth → develop
4. ✅ Pushed develop to origin
5. ✅ Deleted local branch
6. ✅ Deleted remote branch
7. ✅ Updated issue #42 with merge info

Branch feature/issue-42-user-auth completed!

Next: Create PR to main when ready for release

Pattern 3: Emergency Hotfix

Trigger: User needs to fix a critical production issue

Workflow:

Create hotfix branch from main
Optionally create worktree for isolation
Guide through fix
Merge to main AND develop
Create tag
Trigger release if needed

Example:

markdown

User: "We have a critical bug in production"

You:
Starting emergency hotfix workflow...

Creating hotfix branch from main...
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-fix

✅ Branch: hotfix/critical-security-fix

Creating isolated worktree for hotfix...
git worktree add ../worktrees/hotfix hotfix/critical-security-fix

✅ Worktree: ../worktrees/hotfix

You can now work in the worktree while keeping your current work.
cd ../worktrees/hotfix

When fixed:
1. Commit with: fix(scope): description
2. Run /hotfix-finish to merge and tag

Pattern 4: Prepare Release

Trigger: User wants to create a release

Workflow:

Create release branch from develop
Bump version numbers
Update changelog
Allow final fixes
Merge to main and develop
Create tag
Trigger deployment

Example:

markdown

User: "Create release 2.0.0"

You:
Starting release workflow for v2.0.0...

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

✅ Release branch: release/2.0.0

Release checklist:
☐ Version bumped in package.json
☐ CHANGELOG.md updated
☐ Final testing completed
☐ Documentation updated

When ready: /release-finish 2.0.0

Pattern 5: Setup Branching Strategy

Trigger: User wants to configure branching for project

Workflow:

Analyze current repository state
Recommend strategy based on team size and workflow
Create configuration file
Set up branch protection
Document workflow for team

Example:

markdown

User: "Set up gitflow for this project"

You:
Let me configure gitflow for your project...

Analyzing repository...
- Current branches: main
- Team size: Small (2-5)
- Release frequency: Monthly

Recommended: Gitflow

Configuration:
- main: production releases
- develop: integration branch
- feature/*: new features
- release/*: release prep
- hotfix/*: emergency fixes

Creating configuration...

✅ Created .claude/github-workflows/branching-config.json
✅ Strategy: gitflow
✅ Created develop branch from main

Next steps:
1. Push develop: git push -u origin develop
2. Set develop as default branch in GitHub
3. Add branch protection rules for main
4. Share workflow with team

Helper Scripts

Branch Manager

{baseDir}/scripts/branch-manager.py:

bash

# Start a branch
python {baseDir}/scripts/branch-manager.py start feature auth
python {baseDir}/scripts/branch-manager.py start feature --issue 42

# Finish a branch
python {baseDir}/scripts/branch-manager.py finish feature/auth
python {baseDir}/scripts/branch-manager.py finish --current

# Show branch status
python {baseDir}/scripts/branch-manager.py status

# List branches by type
python {baseDir}/scripts/branch-manager.py list feature
python {baseDir}/scripts/branch-manager.py list --all

# Clean merged branches
python {baseDir}/scripts/branch-manager.py clean

# Show configuration
python {baseDir}/scripts/branch-manager.py config --show

Flow Validator

{baseDir}/scripts/flow-validator.py:

bash

# Validate branch name
python {baseDir}/scripts/flow-validator.py validate-name "feature/auth"

# Check flow compliance
python {baseDir}/scripts/flow-validator.py check-flow feature/auth

# Validate merge target
python {baseDir}/scripts/flow-validator.py validate-merge feature/auth develop

# Full validation report
python {baseDir}/scripts/flow-validator.py report

Worktree Manager

{baseDir}/scripts/worktree-manager.py:

bash

# Create worktree
python {baseDir}/scripts/worktree-manager.py add feature/auth
python {baseDir}/scripts/worktree-manager.py add hotfix/urgent --auto-path

# List worktrees
python {baseDir}/scripts/worktree-manager.py list

# Remove worktree
python {baseDir}/scripts/worktree-manager.py remove auth

# Clean merged worktrees
python {baseDir}/scripts/worktree-manager.py clean

# Show worktree status
python {baseDir}/scripts/worktree-manager.py status

Integration Points

With managing-commits Skill

Branch-aware commits:

markdown

1. Detect branch type (feature, bugfix, hotfix)
2. Suggest commit type based on branch
3. Add appropriate scope
4. Link to branch-related issues
5. Enforce flow-specific commit patterns

With triaging-issues Skill

Issue-branch linking:

markdown

1. Create branch from issue
2. Add branch label to issue
3. Track progress on branch
4. Auto-close on merge (via PR)

With reviewing-pull-requests Skill

Flow-aware PR review:

markdown

1. Validate PR target branch per strategy
2. Check branch naming conventions
3. Verify merge direction
4. Suggest squash vs merge based on flow

With /release-prepare Command

Release branch integration:

markdown

1. Create release branch if not exists
2. Coordinate version bumping
3. Generate changelog
4. Merge flow automation

Common Use Cases

Use Case 1: Daily Feature Development

markdown

User: "I need to work on the authentication feature"

You:
Let me set up a feature branch for you...

Checking for related issues...
Found: #42 "Implement user authentication"

Creating feature branch:
git checkout develop
git pull origin develop
git checkout -b feature/issue-42-auth

✅ Branch: feature/issue-42-auth
✅ Based on: develop (up to date)
✅ Linked to: #42

Ready to develop! Remember to:
- Commit with: feat(auth): description
- Reference issue: Refs #42
- When done: /branch-finish

Use Case 2: Parallel Development with Worktrees

markdown

User: "I'm working on auth but need to fix a bug quickly"

You:
No problem! Let me create a worktree for the bugfix...

Your current work:
- Branch: feature/issue-42-auth
- Status: 3 uncommitted changes

Creating bugfix worktree:
git stash (or commit first)
git worktree add ../worktrees/bugfix-156 -b bugfix/issue-156

✅ Worktree: ../worktrees/bugfix-156
✅ Branch: bugfix/issue-156

To work on the bugfix:
cd ../worktrees/bugfix-156

Your feature work remains untouched in the main directory.
When done with bugfix: /branch-finish in that worktree

Use Case 3: Release Workflow

markdown

User: "Time to release version 2.0"

You:
Starting release workflow for v2.0.0...

Creating release branch:
git checkout develop
git pull origin develop
git checkout -b release/2.0.0

✅ Branch: release/2.0.0

Release preparation tasks:
1. Bump version in package.json
2. Update CHANGELOG.md
3. Final testing
4. Documentation review

I can help with:
- /release-prepare 2.0.0 (auto-bump and changelog)
- Manual edits as needed

When ready to ship:
- /release-finish 2.0.0 (merge and tag)

Use Case 4: Emergency Hotfix

markdown

User: "Production is down! Security vulnerability!"

You:
🚨 Starting emergency hotfix workflow...

Creating hotfix branch from main:
git checkout main
git pull origin main
git checkout -b hotfix/security-patch

✅ Branch: hotfix/security-patch

Creating isolated worktree:
git worktree add ../worktrees/hotfix hotfix/security-patch

✅ Worktree ready: ../worktrees/hotfix

FAST TRACK:
1. Fix the issue in ../worktrees/hotfix
2. Commit: fix(security): patch vulnerability
3. Run: /hotfix-finish security-patch

This will:
- Merge to main AND develop
- Create tag v1.x.y
- Delete hotfix branch
- Update related issues

References

Strategy Documentation

{baseDir}/references/branching-strategies.md: Comprehensive guide to all supported branching strategies with pros/cons.

{baseDir}/references/gitflow-guide.md: Detailed gitflow workflow with diagrams and examples.

{baseDir}/references/github-flow-guide.md: Simple GitHub Flow for continuous deployment.

{baseDir}/references/worktree-patterns.md: Git worktree patterns and best practices.

Configuration Templates

{baseDir}/templates/branching-config-templates.json: Pre-configured templates for different team sizes and workflows.

Important Notes

Strategy consistency: Stick to one strategy per repository
Branch hygiene: Delete merged branches promptly
Worktree awareness: Remember which directory you're in
Flow discipline: Follow merge directions strictly
Configuration first: Set up branching-config.json before starting

Error Handling

Common issues:

Wrong base branch → Check strategy configuration
Invalid branch name → Suggest correct format
Merge conflicts → Guide through resolution
Stale worktree → Prune and recreate
Direct push to protected → Redirect to PR workflow

When you encounter branch operations, use this expertise to help users maintain clean, well-organized git history!

Search AI Tools

managing-branches

Install this agent skill to your Project

SKILL.md

Managing Branches Skill

When to Use This Skill

Your Capabilities

Your Expertise

1. Branching Strategies

2. Branch Naming Conventions

3. Flow Operations

4. Worktree Management

5. Configuration

6. Branch Validation

Workflow Patterns

Pattern 1: Start New Feature

Pattern 2: Finish Feature Branch

Pattern 3: Emergency Hotfix

Pattern 4: Prepare Release

Pattern 5: Setup Branching Strategy

Helper Scripts

Branch Manager

Flow Validator

Worktree Manager

Integration Points

With managing-commits Skill

With triaging-issues Skill

With reviewing-pull-requests Skill

With /release-prepare Command

Common Use Cases

Use Case 1: Daily Feature Development

Use Case 2: Parallel Development with Worktrees

Use Case 3: Release Workflow

Use Case 4: Emergency Hotfix

References

Strategy Documentation

Configuration Templates

Important Notes

Error Handling