managing-branches

What this skill does

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