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

{type}/{issue_number}-{slug}

// IMPORTANT: if `title` contains non-ASCII (e.g. Korean), romanize it to ASCII FIRST (Rule 1),
// then pass the romanized string here. createSlug NEVER returns an empty string.
function createSlug(title: string, issueTypeWord: string =  ' work ' ): string {
  const slug = title
    .toLowerCase()
    .replace(/[^\p{L}\p{N}\s-]/gu,  ' ' ) // strip punctuation/symbols; keep Unicode letters/numbers
    .replace(/[\s_]+/g,  ' - ' )           // spaces/underscores → hyphens
    .replace(/-+/g,  ' - ' )               // collapse consecutive hyphens
    .substring(0, 50)                  // length limit
    .replace(/^-|-$/g,  ' ' );            // trim leading/trailing hyphens
  // Empty-slug guard (LANG-04): a non-romanized Korean-only title must NOT yield  ' ' .
  return slug || issueTypeWord;
}

┌─────────────────────────────────────────────────────────┐
│  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                               │
└─────────────────────────────────────────────────────────┘

# Check current state
git status --porcelain

# If output is not empty, changes exist

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

 # Check stash list
git stash list

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

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

# 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}

# Check current branch
git branch --show-current

# Verify it matches the expected branch

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

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

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

 # Result
branch_name: feature/25-community-list

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

# Result
branch_name: bugfix/30-login-error

# Mixed Korean/English title — Korean romanized, special chars removed
/dev:issue-branch 28  " [Story] Community 엔티티 정의 " 
 # Result
branch_name: feature/28-story-community-entity

# Korean-ONLY title — romanized to ASCII, NEVER empty (was the LANG-04 bug:  " feature/25- " )
/dev:issue-branch 25  " 커뮤니티 목록 " 
 # Result
branch_name: feature/25-keomyuniti-moklog

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