Skip to main content
command CX Codex

speckit.git.feature — Claude Code command: Git branches

The speckit.git.feature command creates and checks out a Git feature branch from a specification. Configure sequential or timestamp numbering and shape branch names with a template.

MIT ★ 110 updated 2026-10-19

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/speckit.git.feature.md
Open on GitHub

What speckit.git.feature does

The command turns a feature description into a short branch slug, then runs the Bash or PowerShell script to create the branch. The script returns JSON containing BRANCH_NAME and FEATURE_NUM. A separate __SPECKIT_COMMAND_SPECIFY__ workflow creates the specification directory and files.

Numbering is read from .specify/extensions/git/git-config.yml, then from .specify/init-options.json; the fallback is sequential numbering. A branch template can include the author and app name, which separates feature branches by project in a monorepo. Git must be available and the current directory must be a repository. Otherwise branch creation is skipped with a warning. Run the script once per feature; do not pass --number, since the script selects the next value itself.

What it helps with

  • create a Git branch for a specified feature
  • check out a branch with a short name derived from its description
  • choose sequential or timestamp-based branch numbering
  • separate monorepo branches by author and app

Example prompts for the agent

  • Create a Git branch for OAuth2 sign-in with /speckit.git.feature.
  • Make a branch for the payment bug fix and use timestamp numbering: /speckit.git.feature.
  • Create a branch following the project template with /speckit.git.feature.

How to install speckit.git.feature

Manually: put the files in place

.claude/commands/speckit.git.feature.md

Call it with /speckit.git.feature. For all projects use ~/.claude/commands/

Questions about speckit.git.feature

How do I install speckit.git.feature in Claude Code?

Save the command file at .claude/commands/speckit.git.feature.md.

What does speckit.git.feature do?

It creates and checks out a Git branch from a feature description, then returns the branch name and feature number as JSON. It leaves specification files to a separate workflow.

How are branch numbering and names configured?

Set branch_numbering and, optionally, branch_template in .specify/extensions/git/git-config.yml. Without a template, the branch uses {number}-{slug}; {author} and {app} can distinguish projects in a monorepo.

Source text

speckit.git.feature.md · MIT
---
description: "Create a feature branch with sequential or timestamp numbering"
---

# Create Feature Branch

Create and switch to a new git feature branch for the given specification. This command handles **branch creation only** — the spec directory and files are created by the core `__SPECKIT_COMMAND_SPECIFY__` workflow.

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Environment Variable Override

If the user explicitly provided `GIT_BRANCH_NAME` (e.g., via environment variable, argument, or in their request), pass it through to the script by setting the `GIT_BRANCH_NAME` environment variable before invoking the script. When `GIT_BRANCH_NAME` is set:
- The script uses the exact value as the branch name, bypassing all prefix/suffix generation
- `--short-name`, `--number`, and `--timestamp` flags are ignored
- `FEATURE_NUM` is extracted when the final path segment starts with a numeric or timestamp feature marker (for example `042-name`, `feat/042-name`, or `jdoe/app/042-name`), otherwise set to the full branch name

## Prerequisites

- Verify Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
- If Git is not available, warn the user and skip branch creation

## Branch Numbering Mode

Determine the branch numbering strategy by checking configuration in this order:

1. Check `.specify/extensions/git/git-config.yml` for `branch_numbering` value
2. Check `.specify/init-options.json` for `feature_numbering` value (inherit from core)
3. Check `.specify/init-options.json` for `branch_numbering` value (deprecated, backward compatibility — will be removed in a future release)
4. Default to `sequential` if none of the above exist

## Branch Name Template

Check `.specify/extensions/git/git-config.yml` for an optional `branch_template` value. If it is empty or missing, use the default branch shape `{number}-{slug}`. If it is set, `{slug}` must not appear before `{number}`, its final path segment must start with `{number}-`, and the script expands these tokens:

- `{author}`: sanitized Git config author (`user.name`, falling back to the email local part)
- `{app}`: sanitized Spec Kit init directory name
- `{number}`: sequential number or timestamp
- `{slug}`: generated short branch slug

For monorepos, a template such as `{author}/{app}/{number}-{slug}` creates names like `jdoe/web/008-guided-tour` while preserving per-project feature numbering.

The script also accepts `branch_prefix` as a shorthand for simple namespaces; it expands to `<branch_prefix>/{number}-{slug}`.

## Execution

Generate a concise short name (2-4 words) for the branch:
- Analyze the feature description and extract the most meaningful keywords
- Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
- Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)

Run the appropriate script based on your platform:

- **Bash**: `.specify/extensions/git/scripts/bash/create-new-feature-branch.sh --json --short-name "<short-name>" "<feature description>"`
- **Bash (timestamp)**: `.specify/extensions/git/scripts/bash/create-new-feature-branch.sh --json --timestamp --short-name "<short-name>" "<feature description>"`
- **PowerShell**: `.specify/extensions/git/scripts/powershell/create-new-feature-branch.ps1 -Json -ShortName "<short-name>" "<feature description>"`
- **PowerShell (timestamp)**: `.specify/extensions/git/scripts/powershell/create-new-feature-branch.ps1 -Json -Timestamp -ShortName "<short-name>" "<feature description>"`

**IMPORTANT**:
- Do NOT pass `--number` — the script determines the correct next number automatically
- Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
- You must only ever run this script once per feature
- The JSON output will contain `BRANCH_NAME` and `FEATURE_NUM`
- Do not manually expand `branch_template`; the script reads the git extension config and applies it consistently

## Graceful Degradation

If Git is not installed or the current directory is not a Git repository:
- Branch creation is skipped with a warning: `[specify] Warning: Git repository not detected; skipped branch creation`
- The script still outputs `BRANCH_NAME` and `FEATURE_NUM` so the caller can reference them

## Output

The script outputs JSON with:
- `BRANCH_NAME`: The branch name (e.g., `003-user-auth`, `20260319-143022-user-auth`, or `jdoe/web/003-user-auth`)
- `FEATURE_NUM`: The numeric or timestamp prefix used

© alfredoperez · MIT · alfredoperez/speckit-companion

Similar slash commands

All slash commands for Git and GitHub →

From the same set83

The whole set →
speckit.companion.living-validate speckit.companion.living-validate is a command for Claude Code that checks living specs and feature deltas without editing files. It flags missing scenarios, unlinked headings, and syntax issues. CX Codex +1 ★ 110repo stars publish The publish command guides a VS Code extension release, from QA checks and changelog updates to versioning and pushing a tagged commit. A separate file is available for Codex. CX Codex +1 ★ 110repo stars release-loop release-loop is a command for Claude Code and Codex that moves a batch of changes through fixes, QA, and release. It prepares a report and waits for approval before publishing. CX Codex +1 ★ 110repo stars bench-wave bench-wave runs an end-to-end benchmark round for a pipeline-diet wave across two Companion cells and logs the metrics into a markdown plan. Useful for measuring speed, token counts, and driver feedback. CX Codex +1 ★ 110repo stars speckit-git-feature speckit-git-feature is a Claude Code skill that creates a Git branch from a task description within a Spec Kit project and reads its configuration. CX Codex +1 ★ 110repo stars speckit.companion.living-move speckit.companion.living-move relocates Speckit living specs between central storage and colocated code folders while updating the project registry. CX Codex +1 ★ 110repo stars publish-mod publish-mod releases the Claude Code mod through the repository marketplace and prepares the Anthropic directory handoff for the user. CX Codex +1 ★ 110repo stars speckit.companion.mark-complete speckit.companion.mark-complete marks the active spec as completed via write-context.py. Handy when you want to close a spec by hand instead of running a full converge. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open