name: speckit-branch-convention-configure description: Set up branch and folder naming rules for the current project compatibility: Requires spec-kit project structure with .specify/ directory metadata: author: github-spec-kit source: branch-convention:commands/speckit.branch-convention.configure.md

Configure Branch Convention

Set up configurable naming rules for how /specify creates Git branches and spec folder names. Supports ticket IDs, GitFlow prefixes, date formats, and custom patterns.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty). The user may specify a preset (e.g., "gitflow", "ticket", "date") or provide custom patterns directly.

Prerequisites

1. Verify a spec-kit project exists by checking for .specify/ directory
2. Check if a convention config already exists at .specify/branch-convention.yml

Outline

1. Determine convention type: Based on user input or interactive selection:

   Preset	Branch Pattern	Folder Pattern	Example Branch	Example Folder
   default	{seq}-{kebab}	{seq}-{kebab}	003-user-auth	003-user-auth
   gitflow	{type}/{seq}-{kebab}	{seq}-{kebab}	feat/003-user-auth	003-user-auth
   ticket	{ticket}-{kebab}	{ticket}-{kebab}	PROJ-142-user-auth	PROJ-142-user-auth
   date	{date}-{kebab}	{date}-{kebab}	20260408-user-auth	20260408-user-auth
   custom	User-defined pattern	User-defined pattern	—	—

2. Collect configuration: Build the convention config with these fields:

   # .specify/branch-convention.yml
   convention:
     branch_pattern: '{type}/{seq}-{kebab}'
     folder_pattern: '{seq}-{kebab}'
     type_prefix:
       feature: 'feat'
       bugfix: 'fix'
       hotfix: 'hotfix'
       refactor: 'refactor'
       docs: 'docs'
     default_type: 'feat'
     seq_padding: 3
     seq_start: 1
     date_format: 'YYYYMMDD'
     ticket_pattern: '[A-Z]+-[0-9]+'
     max_length: 60
     separator: '-'
     lowercase: true
   

3. Available tokens: Document these template tokens for patterns:

   Token	Description	Example
   {seq}	Zero-padded sequence number	003
   {kebab}	Kebab-case feature summary (2-4 words)	user-auth-flow
   {ticket}	Ticket/issue ID (e.g., JIRA, Linear)	PROJ-142
   {date}	Date in configured format	20260408
   {type}	Branch type prefix from type_prefix map	feat
   {summary}	Raw feature summary (spaces allowed)	user auth flow

4. Write configuration: Save the convention to .specify/branch-convention.yml

5. Validate existing branches (optional): If branches already exist, check them against the new convention and report any non-compliant ones.

6. Report: Output a summary:

   • Convention type selected
   • Branch pattern and folder pattern configured
   • Example branch name using the new convention
   • Number of existing branches that comply / do not comply
   • Suggest next step: /speckit.branch-convention.validate to check compliance, or /speckit.specify to create a new feature using the convention

Rules

• Never overwrite without confirmation — if .specify/branch-convention.yml already exists, show current config and ask before replacing
• Branch and folder patterns are independent — branch may include type prefix (feat/) while folder stays flat
• Backward compatible — if no convention is configured, spec-kit default behavior ({seq}-{kebab}) applies
• Validate patterns — ensure configured patterns produce valid Git branch names (no spaces, no special chars except /, -, _)
• Preserve existing numbering — sequence numbers continue from the highest existing branch number