| name | git-branch |
| description | You MUST use this for branch name requests and branch actions. Create, switch, or rename Git branches using repository-aware branch naming conventions. |
| license | Apache-2.0 |
| metadata | {"author":"Oleg Shulyakov","version":"1.0.0","source":"github.com/olegshulyakov/agent.md","catalog":"utility","category":"version-control","tags":["git","branch"]} |
Git Branching
Generate, switch, and apply clear Git branch names that follow repository and team conventions.
Workflow
- Classify the request as an output or action workflow.
- Inspect repository context when it can affect the branch name or action.
- Apply the naming rules below.
- Return only the requested branch name for pure generation requests.
- For actions, inspect the current branch and worktree before running Git.
Output Workflow
Use when the user asks to generate, suggest, improve, or review a branch name.
For pure generation requests, return only the branch name unless the user asks
for options or rationale. Reviews may include concise, actionable feedback.
Action Workflow
Use when the user asks to create, start, switch, check out, or rename a branch.
- Preserve user work. Never reset, discard, or overwrite changes.
- If the requested branch already exists, switch to it only when that clearly
matches the request; otherwise report the conflict.
- Report the command outcome or any blocker that prevents completion.
Branch Name Structure
<type>/<ticket-id>-<short-description>
| Part | Required | Notes |
|---|
type | Yes | Category prefix (see below) |
ticket-id | If available | Lowercase issue/ticket ID, e.g. proj-123 or 42 |
short-description | Yes | kebab-case summary of the work |
Examples:
- Feature:
feature/proj-42-user-authentication
- Bugfix:
bugfix/proj-101-fix-login-redirect
- Hotfix:
hotfix/payment-null-pointer-crash
- Chore:
chore/upgrade-node-18
- Release:
release/v2.4.0
Type Prefixes
| Prefix | When to Use |
|---|
feature/ | New functionality or user-facing capability |
bugfix/ | Non-urgent bug fixes going through normal workflow |
hotfix/ | Urgent fixes that go directly to production/main |
release/ | Release preparation branches (release/v1.2.0) |
chore/ | Maintenance, dependency updates, config changes, refactors |
docs/ | Documentation-only changes |
test/ | Adding or fixing tests with no production code change |
experiment/ | Exploratory work, spikes, or proof-of-concepts |
Action Words
Treat these user words as branch action intent:
| User wording | Git behavior |
|---|
create a branch | Create a new branch from the current HEAD |
start a branch | Create and switch to a new branch |
checkout a branch | Create/switch if clearly requested by the user |
switch to a branch | Switch to an existing branch, or create if asked |
rename this branch | Rename the current branch after checking context |
Prefer git switch -c <branch> for creating and switching to a new branch. Prefer git switch <branch> for switching to an existing branch.
Formatting Rules
-
kebab-case only — Use hyphens, never underscores or spaces.
- ✅
feature/user-profile-settings
- ❌
feature/user_profile_settings
- ❌
feature/User Profile Settings
-
Lowercase — All characters should be lowercase.
- ✅
bugfix/proj-99-fix-api-timeout
- ❌
BugFix/Proj-99-Fix-API-Timeout
-
Keep it short but descriptive — Aim for 3–6 words in the description segment. Max ~60 characters total.
- ✅
feature/add-dark-mode-toggle
- ❌
feature/add-a-new-dark-mode-toggle-setting-to-the-user-preferences-page
-
No special characters — Use one / between the type prefix and branch
description. Otherwise, avoid /, \, @, #, ~, ^, :, ?, *,
and spaces; hyphens are the only other allowed non-alphanumeric characters.
-
Include ticket ID when available — Makes branches traceable to issues.
- ✅
bugfix/gh-204-session-expiry-error
- ✅
feature/123-export-to-csv (if project uses numeric IDs only)
-
No trailing slashes or dots.
- ❌
feature/add-search.
- ❌
feature/
When the User Provides a Branch Name for Review
Check it against:
Give specific, actionable feedback. If the name is mostly fine, say so and suggest a small tweak. If it's unclear what the branch is for, ask what the task is before suggesting a name.
Verification
- Generated and reviewed names satisfy the formatting rules.
- Action workflows leave the repository on the requested branch.
- Existing user changes remain intact.