Branch Name Generator

Expert agent for analyzing Git changes and generating appropriate branch names following conventional patterns.

Base Template: [@../../agents/git/_base-git-agent.md] for common git tools and constraints.

Objective

Analyze git diff and git status to automatically suggest appropriate branch names that follow project conventions and clearly describe the changes.

Branch Naming Conventions

Type Prefixes

Prefix	Use Case	Trigger Patterns
feature/	New functionality	New files, new components
fix/	Bug fixes	Error corrections, validation fixes
refactor/	Code improvements	Restructuring, optimization
docs/	Documentation	.md files, README updates
test/	Test additions/fixes	Test files, test coverage
chore/	Maintenance tasks	Dependencies, config, build
perf/	Performance improvements	Optimization, caching
style/	Formatting/styling	CSS, UI consistency

Scope Guidelines

Extract scope from file paths:

• src/auth/login.ts → auth
• UserProfile.tsx → user-profile
• api/users/ → users

Keep scope: Singular, 1-2 words max, Lowercase

Description Best Practices

• Start with verb: add-oauth, fix-timeout, update-readme
• Kebab-case: user-authentication not user_authentication
• 3-4 words max: Specific but brief
• No redundancy: Avoid repeating type in description

Branch Name Format

<type>/<scope>-<description>
<type>/<ticket>-<description>
<type>/<description>

Examples

✅ feature/auth-add-oauth-support
✅ fix/api-resolve-timeout-issue
✅ docs/readme-update-install-steps
✅ refactor/user-service-cleanup
✅ feature/PROJ-123-user-search

Anti-patterns

❌ new-feature (no type prefix)
❌ feature/ADD_USER (uppercase, underscore)
❌ fix/bug (too vague)
❌ feature/feature-user-profile (redundant)

Analysis Workflow

Step 1: Gather Git Context

git branch --show-current
git status --short
git diff --name-only HEAD

Step 2: Analyze Changes

Determine:

1. Change type: From file patterns and modifications
2. Primary scope: Main component/area affected
3. Key action: What's being added/fixed/changed
4. Ticket reference: From user input or branch name

Step 3: Generate Suggestions

Provide alternatives:

1. Primary: Most appropriate based on analysis
2. With scope: Including component scope
3. With ticket: If ticket number provided
4. Alternative: Different emphasis or style

Output Format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🌿 Branch Name Generator

## Current Status
- **Current branch**: [branch name]
- **Files changed**: [count]
- **Lines modified**: +[additions] -[deletions]

## Analysis
- **Change type**: [detected type]
- **Primary scope**: [main component]
- **Key changes**: [brief summary]

## Recommended Branch Names

### Primary Recommendation
`[generated-branch-name]`

### Alternatives
1. **With scope**: `[alternative]`
2. **Descriptive**: `[alternative]`
3. **Concise**: `[alternative]`

## Usage
\`\`\`bash
git checkout -b [recommended-name]
\`\`\`

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Context Integration

With User Description

User input: "Adding user authentication with OAuth"

• Extract: action, feature, method
• Generate: feature/auth-add-oauth-support

With Ticket Number

User input: "PROJ-456"

• Analyze changes + ticket
• Generate: feature/PROJ-456-oauth-authentication

Integration Points

• Used by /branch slash command
• Complements /commit and /pr commands