| name | branch-creation |
| description | How to name new feature branches and start them from a clean base. TRIGGER when: creating a new feature branch, picking a branch name, deciding whether to use a tracker-provided default branch name. DO NOT TRIGGER when: on an existing branch, syncing a branch with the default (use `git-feature-branch-sync` instead), or force-pushing.
|
| user-invocable | false |
Branch Creation
Naming
Branch names follow <TICKET-ID>/<topic-slug> when the project has a
ticket system (Linear, Jira, GitHub Issues, etc.). When there's no
ticket system, use <topic-slug> alone.
- Topic slug — lowercase, hyphen-separated, ≤50 chars. Describes
the change, not the motivation.
- Ticket ID — as the tracker emits it (e.g.,
GH-1234, T-42,
issue-99).
- Don't accept tracker defaults like the
<user>/<ticket>-<slug>
form some tools emit (Linear's gitBranchName field is a common
source). The user prefix signals branch ownership, not work type,
and isn't standard practice.
Examples:
- With ticket:
GH-1234/checkout-redesign, T-42/verify-jwt-hardening
- Without ticket:
verify-jwt-hardening, checkout-redesign
Why no <type>/ prefix?
Industry guides often recommend <type>/<ticket>-<topic> — e.g.,
feature/GH-1234-checkout (Conventional Branch).
That pattern adds signal when:
- The team uses branch-prefix-keyed automation (changelog generation,
CI gating by branch type, auto-deploy paths).
- Branches are scanned without opening the associated ticket.
When neither applies — the ticket system already carries the work
type as a label, and no automation keys off the branch prefix — the
type prefix duplicates the tracker metadata without adding signal.
Lullabot's ADR
documents the same tradeoff and the same conclusion: "For our
purposes we don't need the branch to indicate if it is a feature or
a fix... Instead we rely on the ticket's type."
If a specific project needs prefix-keyed automation, add the type
prefix at that project's CLAUDE.md level. The global default stays
prefix-free.
Branch from a fresh default
Create feature branches from the current tip of the default branch,
not from whatever happens to be checked out:
git checkout main && git pull --ff-only
git checkout -b <new-branch>
Branching off a stale or unrelated branch carries baggage (extra
commits, dirty state) that doesn't belong in the PR. Repos that route
branch creation through a worktree helper (EnterWorktree, custom
scripts) usually handle this automatically — verify once, then trust.
If the repo's default branch is master, trunk, develop, or
anything other than main, substitute accordingly. Check with
git symbolic-ref refs/remotes/origin/HEAD.
Plan files go on the implementation branch
If this branch is for work that has an associated plan file
(.claude/plans/<name>.md), commit the plan to this feature branch.
Don't open a standalone plan-only branch that can merge independently
of the implementation — plan and code ship as one PR. Reviewing the
plan as a PR diff on the feature branch is fine; merging it
separately from the implementation it plans isn't.
