Create Feature Branch

Purpose

Create a feature branch with proper naming convention, sync with remote development branch, and set up remote tracking for WescoBar workflows.

When to Use

• Conductor workflow Phase 2, Step 1 (Branch Setup)
• Before starting implementation of new feature
• When picking up GitHub issue
• As first step in feature development workflow

Naming Convention

feature/issue-<NUMBER>-<short-description>

Examples:

• feature/issue-137-dark-mode
• feature/issue-42-character-portraits
• feature/issue-89-gemini-caching

Rules:

• Always start with feature/
• Include issue-<NUMBER> for GitHub issue linking
• Use kebab-case for description
• Keep description under 40 characters
• Use descriptive but concise naming

Instructions

Step 1: Validate Inputs

bash
1ISSUE_NUMBER=$1
2ISSUE_TITLE=$2  # Optional: for auto-generating description
3
4if [ -z "$ISSUE_NUMBER" ]; then
5  echo "❌ Error: Issue number required"
6  exit 1
7fi
8
9# Validate issue number is numeric
10if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
11  echo "❌ Error: Issue number must be numeric"
12  exit 1
13fi

Step 2: Generate Branch Name

bash
1# Generate short description from issue title if provided
2if [ -n "$ISSUE_TITLE" ]; then
3  # Convert to lowercase, replace spaces with hyphens, remove special chars
4  SHORT_DESC=$(echo "$ISSUE_TITLE" | \
5    tr '[:upper:]' '[:lower:]' | \
6    sed 's/[^a-z0-9 ]//g' | \
7    tr -s ' ' '-' | \
8    cut -d'-' -f1-5)  # Keep first 5 words max
9else
10  # Manual description required
11  echo "Enter short description (kebab-case):"
12  read SHORT_DESC
13fi
14
15BRANCH_NAME="feature/issue-${ISSUE_NUMBER}-${SHORT_DESC}"
16
17echo "Branch name: $BRANCH_NAME"

Step 3: Check if Branch Already Exists

bash
1# Check local branches
2if git rev-parse --verify "$BRANCH_NAME" 2>/dev/null; then
3  echo "⚠️ Branch already exists locally: $BRANCH_NAME"
4  echo "Options:"
5  echo "  1. Checkout existing branch"
6  echo "  2. Create new branch with different name"
7  echo "  3. Delete and recreate"
8
9  read -p "Choose (1/2/3): " CHOICE
10
11  case $CHOICE in
12    1)
13      git checkout "$BRANCH_NAME"
14      echo "✅ Checked out existing branch"
15      exit 0
16      ;;
17    2)
18      echo "Enter new description:"
19      read NEW_DESC
20      BRANCH_NAME="feature/issue-${ISSUE_NUMBER}-${NEW_DESC}"
21      ;;
22    3)
23      git branch -D "$BRANCH_NAME"
24      echo "Deleted existing branch - will recreate"
25      ;;
26  esac
27fi
28
29# Check remote branches
30if git ls-remote --heads origin "$BRANCH_NAME" | grep -q "$BRANCH_NAME"; then
31  echo "⚠️ Branch exists on remote: $BRANCH_NAME"
32  echo "Fetching remote branch..."
33  git fetch origin "$BRANCH_NAME"
34  git checkout --track "origin/$BRANCH_NAME"
35  echo "✅ Checked out remote branch"
36  exit 0
37fi

Step 4: Sync with Development

bash
1echo "→ Syncing with development branch..."
2
3# Checkout development
4git checkout development
5
6# Pull latest changes
7if ! git pull origin development; then
8  echo "❌ Error: Failed to pull latest development"
9  echo "Resolve conflicts and try again"
10  exit 1
11fi
12
13echo "✅ Development branch up to date"

Step 5: Create Feature Branch

bash
1echo "→ Creating feature branch: $BRANCH_NAME"
2
3# Create and checkout new branch
4if ! git checkout -b "$BRANCH_NAME"; then
5  echo "❌ Error: Failed to create branch"
6  exit 1
7fi
8
9echo "✅ Feature branch created"

Step 6: Push to Remote with Tracking

bash
1echo "→ Pushing to remote with tracking..."
2
3# Push with upstream tracking
4if ! git push -u origin "$BRANCH_NAME"; then
5  echo "❌ Error: Failed to push to remote"
6  echo "Branch created locally but not on remote"
7  exit 1
8fi
9
10echo "✅ Branch pushed to remote with tracking"

Step 7: Verify Setup

bash
1# Verify current branch
2CURRENT_BRANCH=$(git branch --show-current)
3
4if [ "$CURRENT_BRANCH" = "$BRANCH_NAME" ]; then
5  echo ""
6  echo "✅ Feature Branch Setup Complete"
7  echo "   Branch: $BRANCH_NAME"
8  echo "   Tracking: origin/$BRANCH_NAME"
9  echo "   Base: development"
10  echo ""
11  echo "Ready for implementation!"
12else
13  echo "⚠️ Warning: Not on expected branch"
14  echo "   Expected: $BRANCH_NAME"
15  echo "   Actual: $CURRENT_BRANCH"
16fi

Output Format

Success

json
1{
2  "status": "success",
3  "branch": {
4    "name": "feature/issue-137-dark-mode",
5    "issue": 137,
6    "base": "development",
7    "remote": "origin/feature/issue-137-dark-mode",
8    "tracking": true
9  },
10  "message": "Feature branch created and pushed to remote"
11}

Branch Already Exists

json
1{
2  "status": "success",
3  "branch": {
4    "name": "feature/issue-137-dark-mode",
5    "existed": true,
6    "action": "checked_out"
7  },
8  "message": "Existing branch checked out"
9}

Integration with Conductor

Used in conductor Phase 2, Step 1:

markdown
1### Phase 2: Branch Setup and Implementation
2
3**Step 1: Create Feature Branch**
4
5**RESUMPTION CHECK**: If feature branch already exists, SKIP this step.
6
7Use `create-feature-branch` skill:
8- Input: issue_number, issue_title (from Phase 1)
9- Output: branch_name, tracking status
10
11Expected result:
12- Branch created: `feature/issue-137-dark-mode`
13- Checked out and ready
14- Remote tracking set up
15- Base: development (latest)
16
17Record branch name for PR creation in Phase 4.

Error Handling

Development Branch Pull Fails

bash
1if ! git pull origin development; then
2  echo "❌ Merge conflicts in development branch"
3  echo "Action required:"
4  echo "  1. Resolve conflicts manually"
5  echo "  2. Run: git merge --continue"
6  echo "  3. Re-run create-feature-branch"
7  exit 1
8fi

Remote Push Fails (Network)

bash
1# Retry with exponential backoff (from CLAUDE.md)
2for i in {1..4}; do
3  if git push -u origin "$BRANCH_NAME"; then
4    break
5  else
6    if [ $i -lt 4 ]; then
7      DELAY=$((2 ** i))
8      echo "⏳ Push failed, retrying in ${DELAY}s..."
9      sleep $DELAY
10    else
11      echo "❌ Push failed after 4 attempts"
12      exit 1
13    fi
14  fi
15done

Branch Name Too Long

bash
1if [ ${#BRANCH_NAME} -gt 80 ]; then
2  echo "⚠️ Branch name too long: ${#BRANCH_NAME} characters"
3  echo "Truncating description..."
4  SHORT_DESC=$(echo "$SHORT_DESC" | cut -c1-40)
5  BRANCH_NAME="feature/issue-${ISSUE_NUMBER}-${SHORT_DESC}"
6fi

Related Skills

• check-resume-branch - Check if branch exists for resumption
• push-with-retry - Retry logic for network failures
• commit-with-validation - Atomic commit before PR

Best Practices

1. Always sync development first - Ensures latest base
2. Use descriptive names - But keep under 80 chars
3. Set up remote tracking - Enables git push without args
4. Verify branch created - Check git branch --show-current
5. Handle existing branches - Don't overwrite without confirmation
6. Retry on network failures - Use exponential backoff

Notes

• Branch naming follows WescoBar convention
• Remote tracking simplifies push workflow
• Development is the base branch (not main/master)
• Branch name includes issue number for PR auto-linking
• Supports resumption by checking for existing branches