pradeepmouli/speckit-branch-convention-configure

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