git.branch.manage

Purpose

This skill automates git branch management for Carbon ACX by:

• •Creating branches with proper naming conventions
• •Checking out existing branches safely
• •Managing branch state (tracking, upstream)
• •Performing rebases and merges
• •Detecting and reporting merge conflicts
• •Cleaning up stale branches
• •Ensuring proper branch hygiene

When to Use

Trigger Patterns:

• •"Create a branch for..."
• •"Switch to branch..."
• •"Rebase this branch"
• •"Update my branch from main"
• •"Delete old branches"
• •Before starting new work on a feature/fix

Do NOT Use When:

• •Making commits (use git.commit.smart)
• •Creating PRs (use git.pr.create)
• •Resolving complex merge conflicts (requires human judgment)

Allowed Tools

• •bash - Git commands
• •grep - Search branch lists, commit messages

Access Level: 2 (Git operations - can create/delete branches)

Tool Rationale:

• •bash: Required for all git branch operations
• •grep: Filter branch lists and search patterns

Explicitly Denied:

• •No force deleting branches without confirmation
• •No rebasing published branches without warning
• •No modifying main/master branches

Expected I/O

Input:

• •Type: Branch management request
• •Context: Current working state, branch name/description
• •Optional: Base branch (defaults to main/master)

Example:

"Create a feature branch for dark mode"
"Switch to the UX improvements branch"
"Rebase my branch on main"
"Delete merged branches"

Output:

• •Type: Branch operation completed
• •Format: Confirmation message with branch state
• •Includes:
  • •Branch name used
  • •Operation performed (create, checkout, rebase, delete)
  • •Current HEAD position
  • •Any conflicts or warnings

Validation:

• •Branch name follows conventions
• •No uncommitted changes (or properly handled)
• •Operations succeed without data loss
• •User informed of branch state changes

Dependencies

Required:

• •Git repository
• •Clean working directory (or stashing strategy)

Optional:

• •Remote repository configured for push/pull operations

Workflow

Branch Creation

Step 1: Determine Branch Name

Naming Convention:

<type>/<description>

Types:

• •feat/ or feature/ - New features
• •fix/ or bugfix/ - Bug fixes
• •chore/ - Maintenance, tooling, dependencies
• •docs/ - Documentation only
• •refactor/ - Code restructuring
• •test/ - Test additions/updates
• •perf/ - Performance improvements

Description:

• •Lowercase with hyphens (kebab-case)
• •Concise but descriptive (3-5 words)
• •No special characters except hyphens

Examples:

• •feat/dark-mode-toggle
• •fix/aviation-calculation-error
• •chore/update-react-dependencies
• •docs/update-api-documentation
• •refactor/component-structure

Alternative naming (also accepted):

• •feature/description
• •bugfix/description
• •User-specified names (if they follow convention)

Step 2: Check for Existing Branch

git branch --list "feat/dark-mode-toggle"
git branch -r --list "*/feat/dark-mode-toggle"

If exists: Ask user if they want to:

• •Checkout existing branch
• •Create with different name
• •Delete and recreate (dangerous!)

Step 3: Determine Base Branch

# Check if main exists
git rev-parse --verify main 2>/dev/null

# Otherwise check for master
git rev-parse --verify master 2>/dev/null

Default: main (or master if main doesn't exist) User can override: "Create branch from develop"

Step 4: Fetch Latest

git fetch origin

Ensures base branch is up-to-date

Step 5: Create and Checkout

git checkout -b feat/dark-mode-toggle origin/main

Alternative (two-step):

git branch feat/dark-mode-toggle origin/main
git checkout feat/dark-mode-toggle

Step 6: Confirm

git status
git log -1 --oneline

Report to user:

✅ Branch created: feat/dark-mode-toggle
Base: origin/main (abc1234)
Current HEAD: abc1234 chore: prepare release v1.3.0
Status: No commits yet, ready for work

Branch Checkout

Step 1: Check Working Directory

git status --porcelain

If uncommitted changes:

• •Offer to stash: git stash push -m "WIP: auto-stashed by git.branch.manage"
• •Or require commit first

Step 2: Find Branch

Local branches:

git branch --list "*pattern*"

Remote branches:

git branch -r --list "origin/*pattern*"

If multiple matches: Present list to user for selection

If no matches: Suggest creating new branch

Step 3: Checkout

Local branch:

git checkout feat/dark-mode-toggle

Remote branch (first checkout):

git checkout -b feat/dark-mode-toggle origin/feat/dark-mode-toggle

Step 4: Confirm

git status

Report:

✅ Switched to branch: feat/dark-mode-toggle
Tracking: origin/feat/dark-mode-toggle
Status: Up to date with remote

Branch Rebase

Step 1: Verify Current Branch

git rev-parse --abbrev-ref HEAD

Safety check: Never rebase main/master directly

Step 2: Check Uncommitted Changes

git status --porcelain

If uncommitted: Require commit or stash first

Step 3: Fetch Latest

git fetch origin

Step 4: Rebase

git rebase origin/main

If conflicts:

⚠️ Rebase conflict detected

Conflicting files:
- apps/carbon-acx-web/src/components/Dashboard.tsx
- package.json

Options:
1. Resolve conflicts manually
2. Abort rebase: git rebase --abort

To continue after resolving:
- git add <resolved-files>
- git rebase --continue

Do NOT auto-resolve conflicts - require human judgment

Step 5: If Successful

git log --oneline -5

Report:

✅ Rebase successful

Your branch has been rebased on origin/main
Previous HEAD: abc1234
New HEAD: xyz9876

Commits on this branch: 3
- feat(web): add dark mode state management
- feat(web): create theme toggle component
- test(web): add theme switching tests

⚠️ Note: Branch history has been rewritten
If already pushed, you'll need to force-push: git push --force-with-lease

Branch Cleanup

Step 1: List Merged Branches

# Local branches merged to main
git branch --merged main | grep -v "main\|master\|\*"

# Remote merged branches
git branch -r --merged main | grep -v "main\|master"

Step 2: Present List

Show user:

Merged branches (safe to delete):
Local:
- feat/dark-mode-toggle
- fix/aviation-calculation

Remote:
- origin/chore/update-dependencies

Delete these branches? (yes/no)

Step 3: Delete (if approved)

Local:

git branch -d feat/dark-mode-toggle

Remote:

git push origin --delete feat/dark-mode-toggle

Report:

✅ Deleted 2 local branches
✅ Deleted 1 remote branch

Remaining branches: 5

Examples

Example 1: Create Feature Branch

User: "Create a branch for dark mode feature"

Claude Process:

1. •Parse intent: Feature branch
2. •Generate name: feat/dark-mode-toggle
3. •Check if exists: No
4. •Fetch origin
5. •Create from origin/main:
   bash

   git fetch origin
   git checkout -b feat/dark-mode-toggle origin/main
   

6. •Report:
   code

   ✅ Created branch: feat/dark-mode-toggle
   Base: origin/main (abc1234)
   Ready to start work on dark mode feature
   

Example 2: Switch to Existing Branch

User: "Switch to the UX improvements branch"

Claude Process:

1. •Search branches: git branch --list "*ux*"
2. •Find match: feat/ux-improvements
3. •Check working directory: Clean ✅
4. •Checkout:
   bash

   git checkout feat/ux-improvements
   

5. •Report:
   code

   ✅ Switched to: feat/ux-improvements
   Last commit: d4e5f6g refactor(web): improve dashboard layout
   Status: 2 commits ahead of origin/main
   

Example 3: Rebase on Main

User: "Rebase my branch on main"

Claude Process:

1. •Current branch: feat/dark-mode-toggle
2. •Check uncommitted: Clean ✅
3. •Fetch: git fetch origin
4. •Rebase:
   bash

   git rebase origin/main
   

5. •Success:
   code

   ✅ Rebase successful
   Your branch is now up-to-date with origin/main
   3 commits rebased
   

6. •Warn about force-push if already pushed

Example 4: Handle Rebase Conflict

User: "Update my branch from main"

Claude Process:

1. •Current branch: feat/emission-chart
2. •Rebase: git rebase origin/main
3. •Conflict detected:
   code

   ⚠️ Rebase stopped due to conflicts
   
   Conflicting files:
   - apps/carbon-acx-web/src/components/Chart.tsx
     (both modified)
   
   Conflict type: Content conflict
   Your changes: Added EmissionChart component
   Main changes: Refactored base Chart component
   
   Resolution needed:
   1. Open Chart.tsx and resolve conflict markers
   2. Keep both changes if compatible
   3. After fixing:
      git add Chart.tsx
      git rebase --continue
   
   To abort: git rebase --abort
   

4. •Wait for user to resolve
5. •Do NOT auto-resolve

Example 5: Clean Up Merged Branches

User: "Delete old branches"

Claude Process:

1. •List merged:
   bash

   git branch --merged main
   

2. •Found: feat/dark-mode-toggle, fix/typo-readme
3. •Present list:
   code

   Merged branches (safe to delete):
   - feat/dark-mode-toggle (merged in PR #42)
   - fix/typo-readme (merged in PR #38)
   
   Delete these? (yes/no)
   

4. •User confirms: yes
5. •Delete:
   bash

   git branch -d feat/dark-mode-toggle fix/typo-readme
   

6. •Report:
   code

   ✅ Deleted 2 local branches
   Remaining: 3 active branches
   

Example 6: Create Branch from Specific Base

User: "Create a hotfix branch from v1.2.3 tag"

Claude Process:

1. •Parse: Hotfix, base is tag v1.2.3
2. •Verify tag exists: git rev-parse v1.2.3
3. •Generate name: hotfix/urgent-security-fix (ask user for description)
4. •Create:
   bash

   git checkout -b hotfix/urgent-security-fix v1.2.3
   

5. •Report:
   code

   ✅ Created branch: hotfix/urgent-security-fix
   Base: v1.2.3 (tag)
   ⚠️ This branch is behind main - use for hotfix only
   

Limitations

Scope Limitations:

• •Cannot auto-resolve merge conflicts (requires human judgment)
• •Cannot rebase published/shared branches without warning
• •Cannot delete branches with unmerged changes (safety)
• •Cannot modify protected branches (main/master)

Known Edge Cases:

• •Detached HEAD state → Warn user, suggest creating branch from current state
• •Diverged branches (force-push needed) → Warn about risks
• •Stale remote branches → Suggest pruning with git remote prune
• •Branch name conflicts → Suggest alternative names

Performance Constraints:

• •Rebasing many commits (100+) may take time
• •Fetching from slow remotes may delay operations
• •Large conflicts difficult to present in text format

Security Boundaries:

• •Does not force-delete branches without confirmation
• •Does not auto-resolve conflicts (data loss risk)
• •Does not push to protected branches
• •Respects repository permissions

Validation Criteria

Success Metrics:

• •✅ Branch names follow conventions
• •✅ Operations complete without data loss
• •✅ User informed of branch state changes
• •✅ Conflicts detected and reported (not auto-resolved)
• •✅ Working directory state preserved (stash if needed)
• •✅ Remote tracking configured when appropriate

Failure Modes:

• •❌ Uncommitted changes → Suggest commit or stash
• •❌ Branch name invalid → Suggest corrected name
• •❌ Merge conflict → Report, provide resolution steps
• •❌ Remote unreachable → Suggest checking network
• •❌ Branch doesn't exist → Suggest creating or list similar names

Recovery:

• •If conflict during rebase: Provide clear resolution steps
• •If branch exists: Offer alternatives (checkout, rename, delete)
• •If uncommitted changes: Offer stash or commit options
• •If operation fails: Provide git status and suggest next action

Related Skills

Composes With:

• •git.commit.smart - Commit work before switching branches
• •git.pr.create - Create PR after branch work complete
• •git.release.prep - Create release branch

Dependencies:

• •None - foundational skill

Alternative Skills:

• •For commits: git.commit.smart
• •For PRs: git.pr.create

Maintenance

Owner: Workspace Team (shared skill) Review Cycle: Quarterly Last Updated: 2025-10-24 Version: 1.0.0

Maintenance Notes:

• •Update branch naming conventions if Carbon ACX changes standards
• •Review rebase strategies as git workflows evolve
• •Adjust conflict detection logic for better reporting
• •Keep stash/unstash behavior synchronized with user preferences