A Spec Kit extension that adds configurable branch and folder naming conventions — supports ticket IDs, GitFlow prefixes, date-based naming, and custom patterns.
Spec Kit's /specify command creates branches and spec folders using a fixed naming pattern (003-feature-name). Teams with existing Git conventions face adoption blockers:
- No support for GitFlow prefixes (
feat/,fix/,hotfix/) - No way to include ticket/issue IDs (JIRA, Linear, GitHub Issues)
- No date-based naming option beyond the built-in timestamp mode
- No validation to enforce naming consistency across a team
- No way to fix non-compliant branches after the fact
The Branch Convention extension adds three commands that make naming fully configurable:
| Command | Purpose | Modifies Files? |
|---|---|---|
/speckit.branch-convention.configure |
Set up naming rules with presets or custom patterns | Yes — .specify/branch-convention.yml |
/speckit.branch-convention.validate |
Check branches and folders against the convention | No — read-only |
/speckit.branch-convention.rename |
Fix non-compliant branches and folders | Yes — branches, folders, artifact references |
specify extension add --from https://github.com/Quratulain-bilal/spec-kit-branch-convention/archive/refs/tags/v1.0.0.zipChoose from built-in presets or define a custom pattern:
| Preset | Branch Pattern | Example |
|---|---|---|
default |
{seq}-{kebab} |
003-user-auth |
gitflow |
{type}/{seq}-{kebab} |
feat/003-user-auth |
ticket |
{ticket}-{kebab} |
PROJ-142-user-auth |
date |
{date}-{kebab} |
20260408-user-auth |
custom |
User-defined | — |
| Token | Description | Example |
|---|---|---|
{seq} |
Zero-padded sequence number | 003 |
{kebab} |
Kebab-case feature summary | user-auth-flow |
{ticket} |
Ticket/issue ID | PROJ-142 |
{date} |
Date in configured format | 20260408 |
{type} |
Branch type prefix | feat |
{summary} |
Raw feature summary (spaces allowed) | user auth flow |
/speckit.branch-convention.configure ← Set up naming rules (once per project)
│
▼
/speckit.specify ← Creates branch using your convention
│
▼
/speckit.branch-convention.validate ← Check compliance (anytime)
│
▼
/speckit.branch-convention.rename ← Fix non-compliant branches (if needed)
Interactive setup for naming rules. Choose a preset (default, gitflow, ticket, date) or define a custom pattern. Saves configuration to .specify/branch-convention.yml with options for:
- Branch and folder patterns (independent)
- Type prefixes (
feat,fix,hotfix,refactor,docs) - Sequence padding, separators, case rules
- Ticket ID format (regex pattern)
- Maximum branch name length
Read-only compliance check across all feature branches and spec folders. Reports:
- Pattern match violations
- Missing type prefixes
- Incorrect sequence padding
- Branch-folder sync mismatches
- Length limit violations
Safely renames non-compliant branches and folders:
- Shows a preview plan before making changes
- Requires explicit confirmation (destructive operation)
- Uses
git mvfor folders (preserves history) - Updates artifact references (spec.md, plan.md, tasks.md headers)
- Handles currently checked-out branch correctly
The extension registers an optional hook:
- before_specify: Validates naming convention compliance before creating a new feature branch
- Presets for common patterns — GitFlow, ticket-based, and date-based naming out of the box
- Branch and folder patterns are independent — branch may include
feat/prefix while folder stays flat - Backward compatible — without configuration, spec-kit default behavior is preserved
- Safe renaming — always preview before executing, requires clean working tree
- No remote operations — rename only affects local branches and folders, remote updates are manual
- Spec Kit >= 0.4.0
- Issue #407 — Configurable naming convention for /specify branch and specs/ folder (39+ upvotes)
MIT
