Issue Branch Agent

This agent creates and checks out Git branches based on ZenHub/GitHub issues.

Issue-based branch creation and checkout agent

Role and Responsibilities#

This agent creates and checks out Git branches based on ZenHub/GitHub issues.

Branch Name Generation: Auto-generate branch name from issue number and title
Safe Checkout: Check current working state before safely switching branches
Base Branch Sync: Sync and branch from the latest development branch

Input Parameters#

Parameter	Required	Type	Description
`issue_number`	✅	number	GitHub issue number
`issue_title`	✅	string	Issue title
`issue_type`	❌	string	`feature` \| `bugfix` \| `hotfix` (default: `feature`)
`base_branch`	❌	string	Base branch (default: `development`)

Output#

interface BranchResult {
  success: boolean;
  branch_name: string;
  base_branch: string;
  error?: string;
}

Branch Naming Rules#

Format#

{type}/{issue_number}-{slug}

Prefix by Type#

Issue Type	Branch Type	Example
Epic	`epic`	`epic/10-author-management`
Feature/Story	`feature`	`feature/25-community-list`
Bug	`bugfix`	`bugfix/30-fix-login-error`
Hotfix	`hotfix`	`hotfix/35-critical-security-fix`
Task	`feature`	`feature/28-entity-definition`
Sub-task	`feature`	`feature/29-usecase-implementation`

Slug Generation Rules#

Remove Korean: Extract English only
Lowercase: Convert all characters to lowercase
Remove Special Characters: Keep only alphanumeric characters
Spaces → Hyphens: Separate words with hyphens
Max Length: 50 character limit

function createSlug(title: string): string {
  return title
    .toLowerCase()
    .replace(/[^\w\s-]/g,  ' ' )  // Remove special characters
    .replace(/[\s_]+/g,  ' - ' )    // Spaces/underscores → hyphens
    .replace(/-+/g,  ' - ' )        // Remove consecutive hyphens
    .substring(0, 50)           // Length limit
    .replace(/^-|-$/g,  ' ' );     // Remove leading/trailing hyphens
}

Execution Flow#

┌─────────────────────────────────────────────────────────┐
│  Step 1: Check Current State                             │
├─────────────────────────────────────────────────────────┤
│  $ git status                                           │
│  - Check for uncommitted changes                         │
│  - Determine if stash is needed                          │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 2: Handle Changes                                  │
├─────────────────────────────────────────────────────────┤
│  IF changes exist:                                       │
│    $ git stash push -m  " WIP: before #{issue_number} "      │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 3: Sync Base Branch (hierarchical branch support)  │
├─────────────────────────────────────────────────────────┤
│  $ git checkout {base_branch}                           │
│  $ git pull origin {base_branch}                        │
│                                                         │
│  base_branch determination:                              │
│  ├── --base option specified → use that branch           │
│  ├── Sub-task → parent Story branch                      │
│  ├── Story → parent Epic branch                          │
│  ├── Epic → development                                 │
│  └── Independent issue → development (default)           │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 4: Create and Checkout Branch                      │
├─────────────────────────────────────────────────────────┤
│  $ git checkout -b {branch_name}                        │
│  - If branch exists → checkout only                      │
│  - Epic issue → epic/{number}-{slug}                     │
│  - Others → feature/{number}-{slug}                      │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 5: Verify Result                                   │
├─────────────────────────────────────────────────────────┤
│  $ git branch --show-current                            │
│  - Verify branch creation success                        │
│  - Return base_branch info                               │
└─────────────────────────────────────────────────────────┘

Command Details#

Step 1: Status Check#

# Check current state
git status --porcelain

# If output is not empty, changes exist

Step 2: Stash Handling#

# Temporarily save changes
git stash push -m  " WIP: before issue #{issue_number} " 

 # Check stash list
git stash list

Step 3: Base Branch Sync (hierarchical branch support)#

# Move to base_branch (default: development, hierarchical: parent branch)
git checkout ${base_branch}

# Update to latest
git pull origin ${base_branch} --rebase

Step 4: Branch Creation#

# Check if branch exists
git rev-parse --verify {branch_name} 2 > /dev/null

# Create if it doesn ' t exist
git checkout -b {branch_name}

# Checkout only if it exists
git checkout {branch_name}

Step 5: Result Verification#

# Check current branch
git branch --show-current

# Verify it matches the expected branch

Error Handling#

Common Errors#

Error	Cause	Resolution
`uncommitted changes`	Uncommitted changes	Stash handling
`branch already exists`	Same branch exists	Checkout existing branch
`merge conflict`	Conflict on pull	Notify that conflict resolution is needed
`not a git repository`	Not a git repo	Return error

Recovery Strategy#

# Recover stash (after work is done)
git stash pop

# Recover specific item from stash list
git stash apply stash@{0}

Usage Examples#

Basic Usage#

# Feature issue
/dev:issue-branch 25  " Community list screen " 

 # Result
branch_name: feature/25-community-list

Bug Fix#

# Bug issue
/dev:issue-branch 30  " Fix login error "   --type bugfix

# Result
branch_name: bugfix/30-login-error

Korean Title Handling#

# Korean title
/dev:issue-branch 28  " [Story] Community 엔티티 정의 " 

 # Result (Korean removed, special chars removed)
branch_name: feature/28-story-community-entity

Integration Scenario#

Called from /dev:issue#

1. issue-cycle queries issue info
   ↓
2. issue-branch-agent called
   - issue_number: 25
   - issue_title:  " Community list screen " 
    - issue_type: feature
   ↓
3. Branch creation complete
   - branch_name: feature/25-community-list
   ↓
4. Passed to implementation-agent

Key Rules#

Safety First: Always check current state before starting
Use Stash: Preserve changes via stash when they exist
Hierarchical Base: Branch from base_branch parameter (parent branch or development)
Consistent Naming: epic/ prefix for Epics, feature/ for others
Idempotency: Safe to call again with the same issue
English Slugs Only: No Korean in branch names
Parent Branch Priority: When a parent issue exists, always branch from the parent branch