Skip to main content
command CX Codex

speckit.git.validate — Claude Code command: branch naming validation

speckit.git.validate — a command that checks whether your current Git branch follows project naming conventions for feature branches. Install it if your team uses structured branch prefixes and wants to automate validation.

MIT ★ 110 updated 2026-10-19

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

What speckit.git.validate does

The command fetches the current branch name and verifies that its final path segment starts with one of two markers: a sequential number of three or more digits (for example, 001-feature-name or jdoe/web/042-fix-bug) or a timestamp in YYYYMMDD-HHMMSS format (for example, 20260319-143022-feature-name). When a branch matches the pattern, it outputs success and checks whether a specs directory with the matching prefix exists under specs/.

If the branch does not match either pattern, the command reports an error with naming suggestions. When Git is unavailable or the directory is not a repository, it falls back to the SPECIFY_FEATURE environment variable. Git must be in PATH for the command to run.

What it helps with

  • verify branch name against project standards
  • check that a specs directory exists for the current branch
  • validate branch naming through an environment variable when Git is inaccessible
  • display detailed error messages for naming violations

Example prompts for the agent

  • Run speckit.git.validate before committing to confirm the branch follows naming rules
  • Execute the command at the start of work to ensure the specs/ directory is in place
  • Use it in CI/CD to automatically validate branch names on pull requests

How to install speckit.git.validate

Manually: put the files in place

.claude/commands/speckit.git.validate.md

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

Questions about speckit.git.validate

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

Add the command file to .claude/commands/speckit.git.validate.md in your project root. It becomes available in Claude Code as soon as the project loads.

What does speckit.git.validate do?

It checks whether your branch name matches one of two formats: a sequential number (001-, 042-) or a timestamp (20260319-143022-). If the branch is valid, it verifies the specs directory exists.

Which branch name formats does the command accept?

The final path segment must start with a three-digit number and a hyphen (like 001-feature-name) or a timestamp in YYYYMMDD-HHMMSS format (like 20260319-143022-feature-name). Namespace prefixes such as jdoe/web/ are allowed.

Source text

speckit.git.validate.md · MIT
---
description: "Validate current branch follows feature branch naming conventions"
---

# Validate Feature Branch

Validate that the current Git branch follows the expected feature branch naming conventions.

## Prerequisites

- Check if Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
- If Git is not available, output a warning and skip validation:
  ```
  [specify] Warning: Git repository not detected; skipped branch validation
  ```

## Validation Rules

Get the current branch name:

```bash
git rev-parse --abbrev-ref HEAD
```

The branch name's final path segment must start with one of these feature markers:

1. **Sequential**: `[0-9]{3,}-` (e.g., `001-feature-name`, `042-fix-bug`, `1000-big-feature`, `jdoe/web/008-guided-tour`)
2. **Timestamp**: `[0-9]{8}-[0-9]{6}-` (e.g., `20260319-143022-feature-name`, `jdoe/web/20260319-143022-feature-name`)

## Execution

If on a feature branch (matches either pattern):
- Output: `✓ On feature branch: <branch-name>`
- Check if the corresponding spec directory exists under `specs/`:
  - For sequential branches, look for `specs/<prefix>-*` where prefix matches the numeric portion, regardless of branch namespace prefixes
  - For timestamp branches, look for `specs/<prefix>-*` where prefix matches the `YYYYMMDD-HHMMSS` portion, regardless of branch namespace prefixes
- If spec directory exists: `✓ Spec directory found: <path>`
- If spec directory missing: `⚠ No spec directory found for prefix <prefix>`

If NOT on a feature branch:
- Output: `✗ Not on a feature branch. Current branch: <branch-name>`
- Output: `Feature branches should be named like: 001-feature-name, 20260319-143022-feature-name, or <namespace>/001-feature-name`

## Graceful Degradation

If Git is not installed or the directory is not a Git repository:
- Check the `SPECIFY_FEATURE` environment variable as a fallback
- If set, validate that value against the naming patterns
- If not set, skip validation with a warning

© alfredoperez · MIT · alfredoperez/speckit-companion

Similar slash commands

All slash commands for Git and GitHub →

From the same set83

The whole set →
cleanup-reviewer cleanup-reviewer reviews a specified slice of a repository cleanup diff and reports findings only. Use it when the review should stay within named files. CX Codex ★ 110repo stars speckit.git.initialize The speckit.git.initialize command sets up a Git repository in your project and creates an initial commit if one doesn't exist. Use it when starting a new project or preparing a template. CX Codex +1 ★ 110repo stars speckit-git-remote speckit-git-remote detects the Git remote URL and verifies GitHub connectivity for tasks like issue creation in spec-kit workflows. Designed for repositories structured with a .specify/ directory. CX Codex +1 ★ 110repo stars speckit-git-initialize speckit-git-initialize creates a Git repository in the current project and makes its first commit. It fits spec-kit projects that need Git initialized. CX Codex +1 ★ 110repo stars cleanup-implementer cleanup-implementer executes a single repository cleanup work packet. It edits assigned files, runs target checks, and never touches git write operations. CX Codex ★ 110repo stars bench-prep bench-prep is a command for Claude Code and Codex that resets three test cells to baseline and assigns them one task size before an agent works through the SpecKit Companion workflow. CX Codex +1 ★ 110repo stars speckit.companion.before-converge speckit.companion.before-converge is a Claude Code command that records the start of converge in .spec-context.json for the Companion GUI. Run it from the repository root before that step. CX Codex +1 ★ 110repo stars speckit.companion.classify speckit.companion.classify evaluates task scope from spec.md to classify changes as simple, normal, or oversized. Companion workflows use this signal to adapt the execution pipeline. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open