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