# Speckit Branch Convention Configure

> Set up branch and folder naming rules for the current project Use when this capability is needed.

- Skill: `tomevault-io/speckit-branch-convention-configure` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/speckit-branch-convention-configure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/speckit-branch-convention-configure/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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

```text
$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:

   ```yaml
   # .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

---
> Source: [brunodsazevedo/react-native-pagseguro-plugpag](https://github.com/brunodsazevedo/react-native-pagseguro-plugpag) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-24 -->