Create Branch

## Language Conventions

**Infer language style from the project:**
- Analyze existing branches, commit messages, and documentation to detect the project's language variant (US English, UK English, etc.)
- Match the spelling conventions found in the project (e.g., "synchronize" vs "synchronise", "center" vs "centre")
- Maintain consistency with the project's established language style throughout branch names and command outputs

---

# Create Branch Command

This command creates and checks out a new git branch with intelligent validation and GitHub issue integration.

## Priority: GitHub Issue Integration

**IMPORTANT**: If the user provides an issue number (e.g., "#123", "123", or "issue 123"), ALWAYS prioritise using GitHub CLI's issue development workflow:

1. **Check for GitHub CLI availability**:
   ```bash
   gh --version
   ```
   If not available, inform the user and fall back to manual branch creation.

2. **Verify the issue exists**:
   ```bash
   gh issue view <issue-number>
   ```
   Display issue title and status to confirm.

3. **Create branch linked to issue**:
   ```bash
   gh issue develop <issue-number> -c
   ```
   - The `-c` flag automatically checks out the newly created branch
   - GitHub automatically generates an appropriate branch name from the issue title
   - The branch is linked to the issue for better project tracking

4. **Skip to remote push step** (step 8 below)

## Manual Branch Creation Workflow

If no issue number is provided, follow this workflow:

### 1. Check Repository Status

```bash
git status
```

Verify:
- Clean working directory or acceptable uncommitted changes
- Current branch information
- Whether we're in a git repository

### 2. Get Branch Name Input

Ask the user for the desired branch name. Accept input in any format - the command will handle formatting and validation.

### 3. Auto-Detect and Apply Prefix

Analyse the branch name input for keywords and automatically add appropriate prefixes:

- **feature/** - Keywords: "add", "implement", "create", "new", "feature"
- **bugfix/** - Keywords: "fix", "bug", "resolve", "patch", "repair"
- **hotfix/** - Keywords: "hotfix", "urgent", "critical", "emergency"
- **chore/** - Keywords: "chore", "refactor", "update", "upgrade", "maintain"
- **docs/** - Keywords: "docs", "documentation", "readme", "guide"

If the user's input already starts with a recognised prefix (feature/, bugfix/, etc.), keep it as-is.

### 4. Validate Branch Name

Apply comprehensive validation:

#### Kebab-Case Enforcement
- Convert to lowercase
- Replace spaces and underscores with hyphens
- Ensure format is: `prefix/kebab-case-name`

#### Character Validation
Reject branch names containing:
- Spaces (convert to hyphens)
- Special characters: `~`, `^`, `:`, `?`, `*`, `[`, `]`, `\`, `@{`, `..`
- Control characters or non-ASCII (except hyphens and slashes)
- Leading or trailing slashes or hyphens

#### Length Validation
- Minimum: 3 characters (excluding prefix)
- Maximum: 100 characters (total)

### 5. Check for Duplicates

Check both local and remote branches:

```bash
# Check local branches
git branch --list "<branch-name>"

# Check remote branches
git ls-remote --heads origin "<branch-name>"
```

If branch exists:
- **Locally**: Offer to checkout existing branch instead
- **Remotely**: Warn user and suggest alternative name
- **Both**: Inform user and ask if they want to checkout or choose different name

### 6. Determine Base Branch

Use smart defaulting:

1. Check if `main` exists:
   ```bash
   git rev-parse --verify main
   ```

2. If not, check if `master` exists:
   ```bash
   git rev-parse --verify master
   ```

3. If n