create-feature-branch · diff
git:20260711.9771000 to git:20260929.5a11e52
43 added, 9 removed. Audit A to A.
---
name: create-feature-branch
- description: Creates a new feature branch from main inside the intended repository after confirming the branch target and repository context. Use when the user wants to start a new feature branch, asks to create a branch for upcoming work, mentions a branch name such as feature/<name>, or another workflow has already resolved the target repository.
+ description: Creates a new work branch from main inside the intended repository after confirming the branch target and repository context, named <type>/<task-id>-<slug> unless the repository says otherwise. Use when the user wants to start a new branch, asks to create a branch for upcoming work, mentions a branch name such as feature/<name> or fix/<name>, or another workflow has already resolved the target repository.
argument-hint: "What feature or branch name should this use?"
---
# Create Feature Branch
- Create a new feature branch for the user's next task in the intended repository.
+ Create a new branch for the user's next task in the intended repository.
## Quick start
1. Confirm the target repository root unless the calling workflow already resolved it.
- 2. Ask what feature the branch should represent unless the user already gave a clear branch name.
- 3. Turn the answer into a short branch name such as `feature/<name>`.
+ 2. Ask what the branch should represent unless the user already gave a clear branch name.
+ 3. Name it by the rules in *Branch name* below — by default `<type>/<task-id>-<slug>`, such as `feature/t-0456-battle-core`.
4. Switch into the target repository root with `Push-Location` / `Pop-Location` or an equivalent directory stack.
5. Update the local `main` branch to the latest state and create the new branch there.
+ ## Branch name
+
+ Take the first of these that applies:
+
+ 1. **The repository's own convention** — CONTRIBUTING, CLAUDE.md, or a rule
+ file that names a branch format. Follow it as written.
+ 2. **The workflow's own convention** — a caller that fixes the name, such as
+ workhub's worktree mode, which works on `task/<task-id>`. Use that name.
+ 3. **The default below.**
+
+ The default is `<type>/<task-id>-<slug>`:
+
+ - `<type>` is one of four:
+ - `feature` — new behaviour
+ - `fix` — a bug fix
+ - `docs` — documentation only
+ - `chore` — dependency updates, configuration, cleanup
+
+ Never `feat`: the short Conventional Commits spelling belongs in commit
+ messages, not branch names. Pick the type from what the change is, not from
+ the word the user happened to use.
+ - `<task-id>` is the id of the task this work belongs to, lowercased
+ (`T-0456` → `t-0456`). Take it from the task being worked on — the launch
+ prompt or the task file. With no task, drop it and its hyphen.
+ - `<slug>` is two to four lowercase ASCII words joined by hyphens, saying what
+ the branch does.
+
+ Examples:
+
+ - `feature/t-0456-battle-core`
+ - `fix/t-0460-billboard-depth`
+ - `docs/t-0457-branch-naming`
+ - `chore/dependency-upgrade` — no task
+
## Workflow
1. Resolve the repository context.
- If a calling workflow already resolved a repository root or repository id, treat it as binding.
- If multiple repositories could apply, ask one narrow question before running any git command.
- Run `git rev-parse --show-toplevel` in the working directory and stop if it does not match the intended repository.
- Never rely on the shell's inherited current directory when the repository matters.
2. Confirm the branch target.
- - If the user gives a feature description, convert it to a concise kebab-case slug.
- - If the user gives an exact branch name, use it when it matches the repository convention.
- - If the repository uses a different prefix than `feature/`, follow that convention.
+ - If the user gives a description of the work, build the name from it by the rules in *Branch name*.
+ - If the user gives an exact branch name, use it when it matches the convention that applies; otherwise propose the conforming name and say why.
3. Sync `main` in the target repository.
- Use `Push-Location` / `Pop-Location` or an equivalent directory stack when switching into the target repository root.
- Switch to the local `main` branch in that repository.
- Update it from the default remote with a non-interactive command.
- 4. Create the feature branch.
+ 4. Create the branch.
- Create the branch from the updated `main` branch in the target repository.
- Switch to the new branch immediately.
5. Report the result.
- Tell the user the final branch name.
- Tell the user which repository root the branch was created in.
- Surface blockers such as repository mismatches, uncommitted changes, missing remotes, or pull failures instead of guessing.
## Notes
- Never run git against the workspace working directory (e.g. the workhub vault) unless it is intentionally the target.
- Use non-interactive git commands.
- - Do not invent a branch name when the requested feature is still ambiguous.
+ - Do not invent a branch name when the requested work is still ambiguous.
- Only perform the git steps when the user has explicitly asked for branch creation.
+