| name | new-branch |
| description | Creates a properly-named git branch before starting any new work. Use at the start of every coding session, feature, bug fix, or task. Trigger whenever the user mentions starting something new, working on an issue, fixing a bug, or any time work is about to begin and no feature branch exists yet. If the user jumps straight into changes without a branch, pause and run this first. Phrases like "let's work on X", "can you fix Y", "start on issue #Z", or "I want to add A" are all signals to run this skill. This skill ONLY creates the branch: for a defect report ("can you fix Y", a broken behavior), branching is step 0 — continue with /webdev:fix-bug afterward; for new functionality, continue with /webdev:new-feature.
|
New Branch
Before any code changes, ensure work happens on a clean, properly-named branch off the
up-to-date default branch.
Steps
-
Resolve the default branch (don't assume main)
Precedence, highest first — an explicit pin always beats detection:
"defaultBranch" in .claude/webdev.json (a repo pinning develop/release means it)git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@'main, then master
Call the result <base> below.
-
Check the current branch
git branch --show-current
If already on a non-<base> branch, confirm with the user before proceeding — they may
want a fresh branch anyway, or may be mid-task on existing work.
-
Switch to base and pull latest (fast-forward only)
First check for uncommitted work — don't switch branches over a dirty tree silently:
git status --short
If non-empty, say what's there and ask: carry it onto the new branch (fine when the
work-in-progress belongs to the new task — git carries it through the checkouts unless files
conflict), or stash it (git stash push -u — the -u matters: plain git stash push
leaves untracked ?? files in the tree). For a stash, ask one more thing: does the WIP
belong to the NEW task? If yes, pop after branching. If it's unrelated, leave it stashed
— popping onto the new branch would put it right back in the diff, where commit's staging
step can sweep it into the wrong PR. Never stash or discard without asking.
git checkout <base> && git pull --ff-only
Always branch from an up-to-date base. Never branch from another working branch.
--ff-only aborts instead of silently creating a merge commit if the base has diverged
from origin; if it refuses, stop and surface the divergence — the base should never be in
that state.
If you just merged a PR, are coming off a stale local branch, or are unsure the base is
clean, invoke /webdev:sync-main first — it pulls latest, prunes remote-tracking
refs, and (with confirmation) deletes merged local branches.
-
Determine the branch prefix from the work type
Match the prefix to the eventual commit type (conventional-commits practice). Default set
below; a project may override via "branchPrefixes" in .claude/webdev.json.
| Prefix | When to use |
|---|
feature/ | New functionality, user-facing capabilities, new endpoints/pages/integrations |
fix/ | Bug fixes, regressions, broken behavior |
refactor/ | Code restructure with no behavior change (renames, moves, extractions) |
docs/ | Documentation-only changes |
chore/ | Tooling, dependencies, config, CI, generated files |
review/ | Standalone review or QA passes (e.g. review/qa-auth-flow) |
When torn between feature/ and fix/: new user-observable behavior → feature/; making
existing behavior correct → fix/.
-
Determine the branch name
- With a known issue number:
<prefix>/<issue-number>-<short-description>
- Without:
<prefix>/<short-description>
- Lowercase, hyphens only, under 50 characters
- Examples:
feature/208-user-avatar-upload, fix/registration-redirect-loop,
refactor/extract-url-helper, chore/upgrade-vite-5
-
Create and switch to the branch
git checkout -b <full-branch-name>
-
Confirm to the user — state the branch name and that it's ready, then proceed.
Important Rules
- Never commit directly to the default branch — open a PR. Merges may trigger CI/CD or a
production deploy, so the base must stay releasable.
- Always pull latest base first — avoids conflicts and starts from current state.
- One branch per issue or feature — don't stack unrelated changes on one branch.
- Branch prefix should match the eventual commit prefix — a
feature/foo branch whose
commit starts with fix: is a smell; pick the right prefix up front.
Output
When complete, report back:
- Branch name: the full branch name created
- Base: the base branch and short SHA branched from
- Status:
ready or error with details
