By default, follow <type>/<short-english-description> convention to infer the new branch name; a name explicitly specified by the user takes precedence.
Branch type
| type | Applicable scenario |
|---|---|
feature |
New feature, new module |
fix |
Fix a known bug |
hotfix |
Urgent production fix |
refactor |
Refactor without changing external behavior |
chore |
Chores such as build, CI, dependency updates |
docs |
Documentation addition or modification |
Default naming constraints
The following format is used for the agent to infer the name. When the user explicitly gives a name, that name takes precedence, but it must pass git check-ref-format --branch <name> validation and must not overwrite an existing branch; do not ask the user to rename again just to conform to the default format.
- Format:
<type>/<kebab-case-description> - description uses English, kebab-case, at most 5 words
- Total length (including type/) must not exceed 50 characters
Workflow
Step 1: Check the environment
Run git status and git branch --show-current, and confirm:
- Current branch name
- Whether there are uncommitted changes
For the baseline, use the branch or commit specified by the user first; otherwise default to the current HEAD and inform the user; do not ask whether to switch back to main just because the current branch is not main. First verify that the baseline is resolvable and that the target branch name is valid and does not exist. If the baseline cannot be determined, the name conflicts, or a Git operation is in progress, ask only about the specific gap, and do not overwrite or reset the existing branch.
Step 2: Infer the branch name
Choose a mode based on the input source:
Mode A — The user provides a description: Infer type and description from the user's requirement description.
Mode B — Analyze uncommitted changes: If the user has not provided a description and there are uncommitted changes, run git diff and git diff --cached to analyze the changes and infer type and description.
If there is not enough information to infer, proactively ask the user what they want to do.
Step 3: Reuse authorization or confirm the inferred name
When the user has already given a valid branch name and asked to create it, use it directly without confirming again. When the agent infers the name, show the baseline and suggested name and request confirmation once; if explicit confirmation already exists, continue directly. No response is not considered approval.
Will create
<base>fromfeature/user-export-module, please confirm the name or provide adjustments.
Step 4: Create the branch
- When the baseline resolves to the current HEAD, directly executing
git switch -c <branch-name>;git checkout -b <branch-name>is equivalently usable; there is no need to clear the working tree first. This operation only switches the branch reference and does not change file contents or the staging area. - Preserve staged changes, unstaged changes, untracked files, and the existing stash. Do not run
stash/stash popjust because the working tree has changes, and do not additionally runstash push --include-untracked。 - When other baselines may change a workspace with uncommitted changes, check the impact first; only proceed if existing content and staged state can be preserved and it matches the user's intent. Otherwise, prepare a reviewable isolated plan and ask; do not automatically stash, force switch, overwrite files, or rewrite history.
- When specifying another baseline, use
git switch -c <branch-name> <base>. After creation, verify the current branch, HEAD, and Git status to confirm that the original content and staged state are preserved. This task does not automatically commit or push.
After creation is complete, output a confirmation message.
Example
User: Create from the current branch fix/cache-timeout(with staged changes, unstaged changes, and untracked files)
Directly execute
git switch -c fix/cache-timeoutorgit checkout -b fix/cache-timeout, without repeated confirmation and without stashing; after creation, verify the branch and the original Git status.
User: Create a branch, I want to add an export feature to the user module
Inference:
feature/user-export
User: Switch to a hotfix branch, the online payment callback is reporting an error
Inference:
hotfix/payment-callback-error
User: Help me create a branch (there are uncommitted changes: modified README.md and files under docs/)
Inference:
docs/update-readme
User: Create a branch to refactor the authentication middleware
Inference:
refactor/auth-middleware