Create Branch

1---2name: create-branch3description: Create and checkout a new git branch with smart validation and GitHub issue integration4allowed-tools: Bash(git status) Bash(git branch) Bash(git checkout) Bash(git push) Bash(git rev-parse) Bash(git ls-remote) Bash(gh issue develop) Bash(gh issue list) Bash(gh issue view)5metadata:6  model: sonnet7---8 9## Language Conventions10 11**Infer language style from the project:**12- Analyze existing branches, commit messages, and documentation to detect the project's language variant (US English, UK English, etc.)13- Match the spelling conventions found in the project (e.g., "synchronize" vs "synchronise", "center" vs "centre")14- Maintain consistency with the project's established language style throughout branch names and command outputs15 16---17 18# Create Branch Command19 20This command creates and checks out a new git branch with intelligent validation and GitHub issue integration.21 22## Priority: GitHub Issue Integration23 24**IMPORTANT**: If the user provides an issue number (e.g., "#123", "123", or "issue 123"), ALWAYS prioritise using GitHub CLI's issue development workflow:25 261. **Check for GitHub CLI availability**:27   ```bash28   gh --version29   ```30   If not available, inform the user and fall back to manual branch creation.31 322. **Verify the issue exists**:33   ```bash34   gh issue view <issue-number>35   ```36   Display issue title and status to confirm.37 383. **Create branch linked to issue**:39   ```bash40   gh issue develop <issue-number> -c41   ```42   - The `-c` flag automatically checks out the newly created branch43   - GitHub automatically generates an appropriate branch name from the issue title44   - The branch is linked to the issue for better project tracking45 464. **Skip to remote push step** (step 8 below)47 48## Manual Branch Creation Workflow49 50If no issue number is provided, follow this workflow:51 52### 1. Check Repository Status53 54```bash55git status56```57 58Verify:59- Clean working directory or acceptable uncommitted changes60- Current branch information61- Whether we're in a git repository62 63### 2. Get Branch Name Input64 65Ask the user for the desired branch name. Accept input in any format - the command will handle formatting and validation.66 67### 3. Auto-Detect and Apply Prefix68 69Analyse the branch name input for keywords and automatically add appropriate prefixes:70 71- **feature/** - Keywords: "add", "implement", "create", "new", "feature"72- **bugfix/** - Keywords: "fix", "bug", "resolve", "patch", "repair"73- **hotfix/** - Keywords: "hotfix", "urgent", "critical", "emergency"74- **chore/** - Keywords: "chore", "refactor", "update", "upgrade", "maintain"75- **docs/** - Keywords: "docs", "documentation", "readme", "guide"76 77If the user's input already starts with a recognised prefix (feature/, bugfix/, etc.), keep it as-is.78 79### 4. Validate Branch Name80 81Apply comprehensive validation:82 83#### Kebab-Case Enforcement84- Convert to lowercase85- Replace spaces and underscores with hyphens86- Ensure format is: `prefix/kebab-case-name`87 88#### Character Validation89Reject branch names containing:90- Spaces (convert to hyphens)91- Special characters: `~`, `^`, `:`, `?`, `*`, `[`, `]`, `\`, `@{`, `..`92- Control characters or non-ASCII (except hyphens and slashes)93- Leading or trailing slashes or hyphens94 95#### Length Validation96- Minimum: 3 characters (excluding prefix)97- Maximum: 100 characters (total)98 99### 5. Check for Duplicates100 101Check both local and remote branches:102 103```bash104# Check local branches105git branch --list "<branch-name>"106 107# Check remote branches108git ls-remote --heads origin "<branch-name>"109```110 111If branch exists:112- **Locally**: Offer to checkout existing branch instead113- **Remotely**: Warn user and suggest alternative name114- **Both**: Inform user and ask if they want to checkout or choose different name115 116### 6. Determine Base Branch117 118Use smart defaulting:119 1201. Check if `main` exists:121   ```bash122   git rev-parse --verify main123   ```124 1252. If not, check if `master` exists:126   ```bash127   git rev-parse --verify master128   ```129 1303. If neither exists, use current HEAD131 1324. Allow user to specify different base branch if needed (ask before creating)133 134### 7. Create and Checkout Branch135 136```bash137git checkout -b <validated-branch-name> <base-branch>138```139 140Confirm successful creation with a message showing:141- Branch name142- Base branch used143- Current status144 145### 8. Remote Push Recommendation146 147Ask the user: "Would you like to push this branch to remote and set up tracking?"148 149If yes:150```bash151git push -u origin <branch-name>152```153 154This enables:155- Remote backup of the branch156- Collaboration with team members157- GitHub PR creation workflow158- Branch visibility in GitHub UI159 160## Error Handling161 162Provide clear, actionable error messages:163 164- **Not a git repository**: "This directory is not a git repository. Initialise one with `git init` or navigate to a repository."165- **GitHub CLI not available**: "GitHub CLI (`gh`) is not installed. Install it from https://cli.github.com or use manual branch creation."166- **Issue not found**: "Issue #123 not found. Check the issue number or create a branch manually."167- **Invalid branch name**: "Branch name contains invalid characters. Suggested: `feature/valid-branch-name`"168- **Branch exists**: "Branch `feature/existing` already exists. Switch to it with `git checkout feature/existing` or choose a different name."169- **Network issues**: "Unable to check remote branches. Proceeding with local creation only."170 171## Examples172 173### Example 1: GitHub Issue Integration174```175User: "Create a branch for issue #456"176Command: gh issue view 456177Output: #456 - Add user authentication (open)178Command: gh issue develop 456 -c179Output: Created and checked out branch: feature/456-add-user-authentication180```181 182### Example 2: Manual with Auto-Prefix183```184User: "Create branch: fix login bug"185Analysis: Contains "fix" → apply "bugfix/" prefix186Validated: "bugfix/login-bug"187Command: git checkout -b bugfix/login-bug main188```189 190### Example 3: Custom Prefix191```192User: "Create branch: docs/update readme"193Analysis: Already has "docs/" prefix → keep as-is194Validated: "docs/update-readme"195Command: git checkout -b docs/update-readme main196```197 198## Best Practises199 2001. **Always prioritise GitHub issue workflow** when issue numbers are mentioned2012. **Validate thoroughly** before creating branches to avoid git errors2023. **Use descriptive names** that clearly indicate the purpose2034. **Follow team conventions** - check existing branch names for patterns2045. **Push to remote early** for backup and collaboration2056. **Link branches to issues** whenever possible for better project tracking