Branch Orchestration

What this skill does

# Branch Orchestration

Intelligent Git branch management with automated naming, issue linking, and lifecycle operations.

## Purpose

Branch Orchestration provides systematic branch naming and management following the convention `{issueNum}-{workType}/{kebab-name}`. Automatically links branches to GitHub issues, detects work types, and manages branch lifecycle including creation, renaming, remote sync, and cleanup.

## When to Use

- Creating branches with smart naming from issue context
- Renaming branches to follow project conventions
- Linking branches to GitHub issues
- Cleaning up merged or stale branches
- When hooks don't provide enough control over naming

## Core Capabilities

### Branch Naming Convention

Format: `{issueNumber}-{workType}/{kebab-case-title}`

**Examples:**
- `42-feature/add-dark-mode`
- `123-fix/safari-auth-bug`
- `7-docs/update-readme`
- `99-refactor/simplify-api`

### Branch Creation

Create branches with intelligent naming:

```bash
# Manual creation with naming utilities
ISSUE_NUM=42
WORK_TYPE="feature"
TITLE="Add dark mode support"

# Generate branch name
BRANCH_NAME=$(generateBranchName $ISSUE_NUM "$WORK_TYPE" "$TITLE")
# Result: "42-feature/add-dark-mode-support"

# Create and checkout branch
git checkout -b "$BRANCH_NAME"

# Push to remote with tracking
git push -u origin "$BRANCH_NAME"
```

**Utilities:**
- `generateBranchName(issueNumber, workType, title)` - Generate formatted name
- `toKebabCase(title)` - Convert title to kebab-case (max 40 chars)
- `validateBranchName(branchName)` - Check naming conventions

### Branch Renaming

Rename branches with remote sync:

```bash
# Get current branch
OLD_BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Generate new name
NEW_BRANCH="42-feature/add-dark-mode"

# Rename local branch
git branch -m "$OLD_BRANCH" "$NEW_BRANCH"

# Check if old branch exists on remote
if git ls-remote --heads origin "$OLD_BRANCH" | grep -q "$OLD_BRANCH"; then
  # Push new branch and delete old remote
  git push -u origin "$NEW_BRANCH"
  git push origin --delete "$OLD_BRANCH"
else
  # Just set upstream for new branch
  git push -u origin "$NEW_BRANCH"
fi
```

**Utilities:**
- `parseBranchName(branchName)` - Extract components (issue#, work type, title)
- `extractIssueNumber(branchName)` - Get issue number from branch name

### Branch Linking

Link branches to GitHub issues:

```bash
# Add branch reference to issue body
ISSUE_NUM=42
BRANCH_NAME="42-feature/add-dark-mode"

CURRENT_BODY=$(gh issue view $ISSUE_NUM --json body -q .body)
UPDATED_BODY="$CURRENT_BODY

---

**Branch:** \`$BRANCH_NAME\`"

echo "$UPDATED_BODY" | gh issue edit $ISSUE_NUM --body-file -

# Save to state file
STATE_FILE=".claude/logs/branch-issues.json"
jq --arg branch "$BRANCH_NAME" --arg issue "$ISSUE_NUM" \
  '.[$branch] = {issueNumber: ($issue | tonumber)}' \
  "$STATE_FILE" > tmp.json && mv tmp.json "$STATE_FILE"
```

**State File:**
- `.claude/logs/branch-issues.json` - Maps branch names to issue numbers

### Branch Cleanup

Clean up merged or stale branches:

```bash
# Delete merged local branches
git branch --merged main | grep -v "^\*\|main\|master" | xargs -n 1 git branch -d

# Delete merged remote branches
gh pr list --state merged --json headRefName -q '.[].headRefName' | \
  xargs -I {} git push origin --delete {}

# Delete stale branches (no commits in 30 days)
git for-each-ref --sort=-committerdate refs/heads/ \
  --format='%(refname:short) %(committerdate:relative)' | \
  awk '$2 ~ /months/ && $3 >= 1 {print $1}' | \
  xargs -n 1 git branch -D
```

### Work Type Detection

Automatically detect work type from context:

```typescript
import { detectWorkType } from '../shared/hooks/utils/work-type-detector.js';

// From prompt
const workType = detectWorkType('fix the authentication bug');
// Returns: 'fix'

// From issue labels
const workType = detectWorkType(
  'Update authentication system',
  ['bug', 'priority:high']
);
// Returns: 'fix' (detected from 'bug' label)
```

**Work Types:**
- `feature` - New functionality
- `fix` - Bug fixes
- `chore` - Maintenance tasks
- `docs` - Documentation
- `refactor` - Code improvements

## Integration with Hooks

This skill complements the automatic hooks:

| Hook | Automatic Behavior | When to Use Skill |
|------|-------------------|------------------|
| create-issue-on-prompt | Renames branch after issue creation | Rename before issue creation, custom naming |
| add-github-context | Discovers issue from branch name | Manual branch-issue linking |

**State Files:**
- `.claude/logs/branch-issues.json` - Branch → Issue mapping

## Naming Utilities

### generateBranchName

```typescript
generateBranchName(issueNumber: number, workType: WorkType, title: string): string
```

Generates formatted branch name.

**Example:**
```typescript
generateBranchName(42, 'feature', 'Add Dark Mode')
// Returns: "42-feature/add-dark-mode"
```

### parseBranchName

```typescript
parseBranchName(branchName: string): ParsedBranchName
```

Parses branch name into components.

**Example:**
```typescript
parseBranchName('42-feature/add-dark-mode')
// Returns: { issueNumber: 42, workType: 'feature', title: 'add-dark-mode' }

parseBranchName('123-fix-auth-bug')
// Returns: { issueNumber: 123, title: 'fix-auth-bug' }
```

### validateBranchName

```typescript
validateBranchName(branchName: string): BranchValidation
```

Validates branch name against conventions.

**Example:**
```typescript
validateBranchName('42-feature/add-dark-mode')
// Returns: { valid: true }

validateBranchName('invalid name with spaces')
// Returns: { valid: false, reason: 'Branch name cannot contain spaces' }
```

### extractIssueNumber

```typescript
extractIssueNumber(branchName: string): number | null
```

Extracts issue number from branch name.

**Example:**
```typescript
extractIssueNumber('42-feature/add-dark-mode')
// Returns: 42

extractIssueNumber('main')
// Returns: null
```

## Examples

### Example 1: Create Branch for Issue

```bash
# Get issue details
ISSUE_NUM=42
ISSUE_DATA=$(gh issue view $ISSUE_NUM --json title,labels)
TITLE=$(echo "$ISSUE_DATA" | jq -r '.title')
LABELS=$(echo "$ISSUE_DATA" | jq -r '.labels[].name' | tr '\n' ',')

# Detect work type
WORK_TYPE=$(detectWorkType "$TITLE" "$LABELS")
# Returns: 'feature' or 'fix' or 'chore', etc.

# Generate branch name
BRANCH_NAME=$(generateBranchName $ISSUE_NUM "$WORK_TYPE" "$TITLE")
# Returns: "42-feature/add-dark-mode-support"

# Create and checkout
git checkout -b "$BRANCH_NAME"
git push -u origin "$BRANCH_NAME"

# Link to issue
echo "Branch \`$BRANCH_NAME\` created" | gh issue comment $ISSUE_NUM --body-file -
```

### Example 2: Rename Branch to Convention

```bash
# Current branch doesn't follow convention
CURRENT=$(git rev-parse --abbrev-ref HEAD)
# e.g., "claude-agile-narwhal-x7h3k"

# Get linked issue (if exists)
ISSUE_NUM=$(parseIssueFromBranch "$CURRENT")

if [ -z "$ISSUE_NUM" ]; then
  echo "No issue linked to this branch"
  exit 1
fi

# Get issue details
ISSUE_DATA=$(gh issue view $ISSUE_NUM --json title,labels)
TITLE=$(echo "$ISSUE_DATA" | jq -r '.title')
LABELS=$(echo "$ISSUE_DATA" | jq -r '.labels[].name' | tr '\n' ',')

# Generate new name
WORK_TYPE=$(detectWorkType "$TITLE" "$LABELS")
NEW_BRANCH=$(generateBranchName $ISSUE_NUM "$WORK_TYPE" "$TITLE")

# Rename with remote sync
git branch -m "$CURRENT" "$NEW_BRANCH"
git push -u origin "$NEW_BRANCH"
git push origin --delete "$CURRENT" 2>/dev/null || true
```

### Example 3: Validate Branch Names in CI

```bash
# Get current branch
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Skip validation for protected branches
if [[ "$BRANCH" =~ ^(main|master|develop)$ ]]; then
  exit 0
fi

# Validate format
if ! validateBranchName "$BRANCH"; then
  echo "❌ Branch name '$BRANCH' doesn't follow convention: {issueNum}-{workType}/{kebab-name}"
  echo "Examples: 42-feature/add-dark-mode, 123-fix/safari-bug"
  exit 1
fi

# Check if issue exists
ISSUE_NUM=$(extractIssueNumber "$BRANCH")
if [ -n "$ISSUE_NUM" ]; then
  if !