gh-bradleyboehmke-brads-marketplace-git-workflow/commands/create-branch.md

---
description: Interactive guidance for creating properly named Git branches following conventions
---

# Create Branch Command

You are helping a developer create a new Git branch following Personal naming conventions and workflow best practices.

## Objective

Provide **interactive, suggestive guidance** for branch creation that:
1. Analyzes current Git state
2. Suggests a properly formatted branch name
3. Gives the user control to accept, modify, or skip
4. Educates on conventions without blocking workflow

## Workflow

### Step 1: Analyze Current State

Check the current Git state:

```bash
# Current branch and status
git branch --show-current
git status

# Check if on main and if it's up-to-date
git fetch origin
git status
```

Identify:
- **Current branch**: What branch is the user on?
- **Uncommitted changes**: Are there staged or unstaged changes?
- **Base branch status**: Is main (or intended base) up-to-date with remote?

### Step 2: Generate Branch Name Suggestion

**Activate the `github-workflow-patterns` skill** to reference branch naming conventions.

Based on user's request, infer:
- **Branch type**: feature, fix, bugfix, hotfix, refactor, docs, experiment, chore
- **Description**: Short, kebab-case description of the work
- **Ticket number** (if mentioned): e.g., PROJ-123

**Format**: `<type>/<description>` or `<type>/<ticket>-<description>`

**Examples**:
- User says "add customer export feature" → `feature/add-customer-export`
- User says "fix auth timeout bug" → `fix/resolve-auth-timeout`
- User says "fix JIRA-456 data validation" → `fix/JIRA-456-data-validation`
- User says "refactor validation logic" → `refactor/extract-validation-logic`
- User says "urgent production fix" → `hotfix/patch-critical-error`

**Rules**:
- Use lowercase with hyphens (kebab-case)
- Be descriptive but concise (3-5 words)
- Avoid personal names, dates, or generic terms like "temp" or "dev"

### Step 3: Determine Base Branch

**Default**: Branch off `main` (or `master`)

**Special cases**:
- If user is on a feature branch and mentions "sub-feature" or related work → suggest branching from current
- If user explicitly says "from <branch>" → use that branch
- For hotfixes → always suggest `main` (or production branch)

### Step 4: Present Interactive Suggestion

Format your response as a clear, actionable suggestion with 3-4 options:

```
Based on your request, I suggest:

Current branch: <current-branch> [status indicators]
Branch off from: <base-branch> [status]
Suggested name: <type>/<description>

[Show rationale if helpful - e.g., "This follows convention: <type>/<short-description>"]

What would you like to do?
1. ✓ Create branch '<suggested-name>'
2. ✏️  Modify the branch name
3. ⏭️  Skip - continue working in current branch
[4. Additional option if relevant - see Special Cases below]
```

**Status indicators**:
- `(clean, up-to-date ✓)` - Clean state, synced with remote
- `(uncommitted changes ⚠️)` - Has uncommitted work
- `(behind origin ⚠️)` - Needs to pull latest
- `(feature branch)` - Currently on a feature branch

### Step 5: Handle User Response

**Option 1: Accept suggestion**
- User says: "yes", "1", "create it", "go ahead", "looks good"
- Action: Execute branch creation

```bash
# If base branch needs updating
git checkout <base-branch>
git pull origin <base-branch>

# Create and switch to new branch
git checkout -b <suggested-name>

# Optionally set up remote tracking (if pushing immediately)
git push -u origin <suggested-name>
```

- Confirm:
```
✓ Created and switched to: <branch-name>

Next steps:
1. Make your changes
2. Run /git-workflow:pre-commit-check to validate quality
3. Run /git-workflow:draft-commit to create commit
4. Run /git-workflow:draft-pr to create pull request
```

**Option 2: Modify branch name**
- User says: "call it <new-name>", "2", "use <new-name> instead", "change to <new-name>"
- Action: Parse new name, validate it follows conventions, create with modified name
- If name doesn't follow conventions, warn but allow (user choice)

```
✓ Created and switched to: <user-modified-name>

Note: This name doesn't follow standard convention (<type>/<description>).
Consider using: <suggested-alternative> for future branches.

Next steps:
1. Make your changes
2. Run /git-workflow:pre-commit-check to validate quality
3. Run /git-workflow:draft-commit to create commit
4. Run /git-workflow:draft-pr to create pull request
```

**Option 3: Skip**
- User says: "no", "3", "skip", "not now", "continue on current branch"
- Action: Do nothing, acknowledge

```
Understood. Continuing work on current branch: <current-branch>

Remember: You can run /git-workflow:create-branch anytime to create a properly named branch.
```

## Special Cases

### Case 1: Uncommitted Changes

If user has uncommitted changes, add a 4th option:

```
⚠️  Warning: You have uncommitted changes in current branch (<current-branch>)

Suggested name: <type>/<description>
Branch off from: <base-branch>

What would you like to do?
1. ✓ Stash changes, create branch, restore changes
2. ✏️  Modify the branch name
3. ⏭️  Skip - continue working in current branch
4. 💾 Commit changes first (run pre-commit-check → draft-commit)
```

**If user chooses Option 1** (stash):
```bash
git stash push -m "WIP: stashing for branch <new-branch>"
git checkout <base-branch>
git pull origin <base-branch>
git checkout -b <new-branch>
git stash pop
```

**If user chooses Option 4** (commit first):
- Switch to pre-commit-check workflow first
- Then draft-commit workflow
- After commit completes, return to branch creation suggestion

### Case 2: Currently on Feature Branch

If user is on a feature branch (not main/master):

```
Current branch: <feature-branch> (feature branch)
Suggested name: <type>/<description>
Branch off from: <feature-branch>

Note: Creating a sub-feature branch from your current branch.
If you want to start fresh from main instead, choose option 4.

What would you like to do?
1. ✓ Create branch '<suggested-name>' from current branch
2. ✏️  Modify the branch name
3. ⏭️  Skip - continue working in current branch
4. 🔄 Branch from main instead
```

**If user chooses Option 4**:
```bash
git checkout main
git pull origin main
git checkout -b <suggested-name>
```

### Case 3: Base Branch Behind Remote

If main (or base) is behind remote:

```
⚠️  Note: <base-branch> is behind origin/<base-branch>

Suggested name: <type>/<description>
Branch off from: <base-branch> (will pull latest first)

What would you like to do?
1. ✓ Pull latest <base-branch>, then create branch '<suggested-name>'
2. ✏️  Modify the branch name
3. ⏭️  Skip - continue working in current branch
```

### Case 4: Already on Target Branch

If a branch with the suggested name already exists:

```
⚠️  Branch '<suggested-name>' already exists

What would you like to do?
1. 🔄 Switch to existing branch '<suggested-name>'
2. ✏️  Use a different name (e.g., '<suggested-name>-v2')
3. ⏭️  Skip - continue working in current branch
```

## Parameters

This command accepts optional parameters (usually inferred by the agent):

- `--type=<type>` - Branch type (feature, fix, hotfix, refactor, docs, experiment, chore)
- `--description=<desc>` - Brief description of the work
- `--from=<branch>` - Base branch to branch from (default: auto-detect, usually main)
- `--ticket=<number>` - Optional ticket/issue number to include in branch name

**Example invocations**:
```bash
# Agent infers from user's natural language request
User: "Create a branch to add customer export"
Agent: /git-workflow:create-branch --type=feature --description="add customer export"

# Explicit invocation with parameters
/git-workflow:create-branch --type=fix --description="resolve auth timeout" --ticket=PROJ-123

# Minimal invocation (will prompt for details)
/git-workflow:create-branch
```

## Output Format

Always use **console format** (interactive only - markdown reports don't apply here).

Present information in a clear, scannable format:
- Use **emoji sparingly** for status indicators (✓, ⚠️, ✏️, ⏭️, 💾, 🔄)
- Use **numbered options** for user choices
- Show **concrete commands** when executing actions
- Provide **clear next steps** after completion

## Key Principles

1. **Suggestive, not prescriptive**: Offer guidance but give users control
2. **Educational**: Explain conventions so users learn, not just follow
3. **Context-aware**: Adapt to current Git state and user situation
4. **Non-blocking**: Never prevent users from proceeding if they choose to skip
5. **Integrated**: Flow naturally into draft-commit and draft-pr workflows

## Example Interaction

**User**: "Let's start working on adding a customer segmentation feature"

**Command Response**:
```
Based on your request, I suggest:

Current branch: main (clean, up-to-date ✓)
Branch off from: main
Suggested name: feature/add-customer-segmentation

This follows convention: <type>/<short-description>

What would you like to do?
1. ✓ Create branch 'feature/add-customer-segmentation'
2. ✏️  Modify the branch name
3. ⏭️  Skip - continue working in current branch
```

**User**: "1"

**Command Response**:
```
✓ Created and switched to: feature/add-customer-segmentation

Next steps:
1. Make your changes
2. Run /git-workflow:pre-commit-check to validate quality
3. Run /git-workflow:draft-commit to create commit
4. Run /git-workflow:draft-pr to create pull request
```

---

**Remember**: This command is about empowering developers with best practices while respecting their autonomy and workflow preferences.