AgentSkillsCN

Branch Orchestration

当用户希望“创建分支”、“重命名分支”、“智能命名分支”、“将分支关联到议题”,或管理分支生命周期时,可使用此技能。它能够依据 {issueNum}-{workType}/{kebab-name} 的命名规范,智能生成分支名称并自动关联相关议题。

SKILL.md
--- frontmatter
name: Branch Orchestration
description: Use this skill when the user wants to "create branch", "rename branch", "smart branch name", "link branch to issue", or manage branch lifecycle. Provides intelligent branch naming with automatic issue linking following the pattern {issueNum}-{workType}/{kebab-name}.
version: 0.1.0

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:

HookAutomatic BehaviorWhen to Use Skill
create-issue-on-promptRenames branch after issue creationRename before issue creation, custom naming
add-github-contextDiscovers issue from branch nameManual 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 ! gh issue view $ISSUE_NUM &>/dev/null; then
    echo "⚠️  Issue #$ISSUE_NUM referenced in branch name doesn't exist"
  fi
fi

Example 4: Bulk Branch Cleanup

bash
# Get all merged branches
MERGED=$(git branch --merged main | grep -v "^\*\|main\|master")

for branch in $MERGED; do
  # Parse branch name
  PARSED=$(parseBranchName "$branch")
  ISSUE_NUM=$(echo "$PARSED" | jq -r '.issueNumber // empty')

  # Check if issue is closed
  if [ -n "$ISSUE_NUM" ]; then
    STATE=$(gh issue view $ISSUE_NUM --json state -q .state 2>/dev/null || echo "")
    if [ "$STATE" = "CLOSED" ]; then
      echo "Deleting merged branch: $branch (issue #$ISSUE_NUM closed)"
      git branch -d "$branch"
      git push origin --delete "$branch" 2>/dev/null || true
    fi
  else
    echo "Deleting merged branch: $branch (no linked issue)"
    git branch -d "$branch"
  fi
done

Best Practices

  1. Follow naming convention - Always use {issueNum}-{workType}/{kebab-name}
  2. Link to issues - Create branches from issue numbers when possible
  3. Validate before push - Use validateBranchName() to check format
  4. Clean up regularly - Delete merged and stale branches
  5. Update state files - Keep .claude/logs/branch-issues.json synced
  6. Use work type detection - Automatically categorize with detectWorkType()
  7. Sync with remote - Always use -u flag when pushing new branches

Common Patterns

Pattern: Create Branch from Current Issue

bash
# Auto-detect issue from current context
ISSUE_NUM=$(cat .claude/logs/branch-issues.json | jq -r '.[] | .issueNumber' | head -1)

if [ -n "$ISSUE_NUM" ]; then
  ISSUE_DATA=$(gh issue view $ISSUE_NUM --json title,labels)
  TITLE=$(echo "$ISSUE_DATA" | jq -r '.title')
  WORK_TYPE=$(detectWorkType "$TITLE")
  BRANCH_NAME=$(generateBranchName $ISSUE_NUM "$WORK_TYPE" "$TITLE")

  git checkout -b "$BRANCH_NAME"
  git push -u origin "$BRANCH_NAME"
fi

Pattern: Switch Branch by Issue Number

bash
# Switch to branch for issue #42
ISSUE_NUM=42
BRANCH=$(git branch -a | grep -E "^[ *]*$ISSUE_NUM-" | sed 's/^[ *]*//' | head -1)

if [ -n "$BRANCH" ]; then
  git checkout "$BRANCH"
else
  echo "No branch found for issue #$ISSUE_NUM"
fi

Pattern: List Branches by Work Type

bash
# List all feature branches
git branch | grep -E "feature/" | sed 's/^[ *]*//'

# List all fix branches
git branch | grep -E "fix/" | sed 's/^[ *]*//'