Branch

Create and switch to a new, conventionally named branch. Works in two common scenarios:

1. In-progress work — you have uncommitted local changes and want to move them to a properly named branch. All local changes (staged, unstaged, and untracked files) are preserved exactly as they are.
2. Starting fresh — you are on a clean main/master/develop branch and want to create a new branch before starting work (e.g.,

   /optimus:branch "add user authentication"

   ).

The branch name is derived from the first available context: an inline description, conversation history, or local git diffs. Never commits, pushes, stages, or modifies anything — purely a local branch operation.

Workflow

1. Multi-repo Detection

Read

$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md

for workspace detection. If a multi-repo workspace is detected:

• Run the git commands below inside each child repo (the workspace root has no

  .git/

  , so git commands must target individual repos)
• Identify which repos have local changes (

  git status --short

  is non-empty)
• If one repo has changes, target it silently
• If multiple repos have changes, use

  AskUserQuestion

  — header "Target repo", question "Multiple repos have local changes. Which repo should get the new branch?": list each repo as an option
• If no repos have changes: the user may be starting fresh. If an inline description or conversation context identifies a target repo, use it. If ambiguous, ask which repo to target. If no context at all, inform the user and stop

2. Gather Context

Record the current branch:

git rev-parse --abbrev-ref HEAD

Determine a meaningful description for the branch from the first source that provides enough signal (check in this priority order):

1. Inline description — if the user provided text with the invocation (e.g.,

   /optimus:branch "fix login timeout"

   ), use it directly
2. Conversation context — scan the current conversation for the user's task intent, problem description, or feature request. Extract the core action and subject.
3. Git diff analysis (only if sources 1 and 2 were insufficient) — check for local changes first:

git status --short

If there are local changes, analyze them to infer intent:

# File-level overview
git diff --stat
git diff --cached --stat

# Content details (for deeper analysis if file names alone are ambiguous)
git diff
git diff --cached

When analyzing diffs, look for:

• File paths that reveal the domain (e.g.,

  src/auth/

  → authentication,

  tests/

  → testing)
• Test-only changes, documentation-only changes, config-only changes — these map directly to branch types in the shared reference

If no source provides enough signal to generate a meaningful name (no inline description, no conversation context, and either no local changes or changes too ambiguous to interpret), inform the user:

Could not determine a meaningful branch name from the conversation or local changes.
Provide a description, e.g., `/optimus:branch "add user authentication"`

Then stop — do not create a branch with a generic or meaningless name.

3. Derive Branch Name

Read

$CLAUDE_PLUGIN_ROOT/skills/commit/references/branch-naming.md

for the naming convention. Use the Type Detection Keywords section to determine

<type>

from context, and apply the Slug Rules to generate

<slug>

.

Handle collisions: if

git show-ref --verify --quiet refs/heads/<branch-name>

succeeds (branch exists), append

-2

to the slug. If that also exists, try

-3

, and so on up to

-9

. If all collide, inform the user and stop.

4. Create Branch

git checkout -b <branch-name>

Report (adapt based on whether local changes exist):

## Branch

Created `<branch-name>` from `<original-branch>`.
Local changes preserved (nothing committed or pushed).

If the working tree was clean (no local changes), omit the "Local changes preserved" line:

## Branch

Created `<branch-name>` from `<original-branch>`.

5. Next Step

Recommend the next step based on context:

• If the user seems to be starting new work →

  /optimus:tdd

  to build the feature test-first
• If changes look ready to commit →

  /optimus:commit

  to stage, commit, and optionally push
• If parallel work is needed →

  /optimus:worktree

  for an isolated workspace
• Default →

  /optimus:commit

  when ready

Tell the user: Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.

Important

• Preserve all local changes —

  git checkout -b

  carries staged, unstaged, and untracked files to the new branch untouched. Do not run

  git stash

  ,

  git add

  ,

  git reset

  , or any command that alters the working tree or index
• Never commit or push
• Never modify any files
• This skill is a fast local operation — avoid unnecessary commands or questions
• Only use

  AskUserQuestion

  when multiple repos have changes or when context is truly insufficient