---
name: managing-branches
description: Git branching strategy expertise with flow-aware automation. Auto-invokes when branching strategies (gitflow, github flow, trunk-based), branch creation, branch naming, merging workflows, release branches, hotfixes, environment branches, or worktrees are mentioned. Integrates with existing commit, issue, and PR workflows.
version: 1.0.0
allowed-tools: Bash, Read, Grep, Glob, Write
---

# 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**:
```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**:
1. Check current branch and status
2. Determine base branch from strategy (develop for gitflow, main for github-flow)
3. Generate branch name from issue or description
4. Create branch from base
5. Link to issue if applicable
6. Optionally create worktree for parallel development
7. 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**:
1. Check current branch is a feature branch
2. Ensure working directory is clean
3. Update target branch (develop)
4. Merge feature branch
5. Push changes
6. Delete feature branch (local and remote)
7. Update linked issues
8. 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**:
1. Create hotfix branch from main
2. Optionally create worktree for isolation
3. Guide through fix
4. Merge to main AND develop
5. Create tag
6. 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**:
1. Create release branch from develop
2. Bump version numbers
3. Update changelog
4. Allow final fixes
5. Merge to main and develop
6. Create tag
7. 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**:
1. Analyze current repository state
2. Recommend strategy based on team size and workflow
3. Create configuration file
4. Set up branch protection
5. 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!