---
name: speckit-branch-convention-validate
description: Check all feature branches and spec folders against the configured naming
  convention
compatibility: Requires spec-kit project structure with .specify/ directory
metadata:
  author: github-spec-kit
  source: branch-convention:commands/speckit.branch-convention.validate.md
---

# Validate Branch Convention

Check all existing feature branches and spec folders against the configured naming convention. Reports compliance status and identifies violations.

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty). The user may specify a specific branch to validate (e.g., "003-user-auth") or "all" to check everything.

## Prerequisites

1. Verify a spec-kit project exists by checking for `.specify/` directory
2. Load convention config from `.specify/branch-convention.yml`
3. If no convention is configured, use the default pattern (`{seq}-{kebab}` for both branch and folder)

## Outline

1. **Load convention**: Read `.specify/branch-convention.yml` and extract:
   - `branch_pattern` — the expected branch naming pattern
   - `folder_pattern` — the expected spec folder naming pattern
   - Token definitions (seq_padding, separator, lowercase, etc.)

2. **Collect branches and folders**: Gather all feature-related items:
   - **Git branches**: List all local branches matching spec-kit patterns (exclude `main`, `master`, `develop`)
   - **Spec folders**: List all directories under `specs/`
   - **Match pairs**: Associate each branch with its corresponding spec folder

3. **Validate each item**: For every branch and folder, check:

   | Check              | Rule                                                              | Example Violation                                 |
   | ------------------ | ----------------------------------------------------------------- | ------------------------------------------------- |
   | Pattern match      | Branch matches `branch_pattern` structure                         | `user-auth` missing sequence number               |
   | Type prefix        | If pattern includes `{type}`, prefix must be in `type_prefix` map | `feature/003-auth` instead of `feat/003-auth`     |
   | Sequence format    | `{seq}` must be zero-padded to `seq_padding` digits               | `3-auth` instead of `003-auth`                    |
   | Length limit       | Branch name must not exceed `max_length` characters               | `003-very-long-branch-name-that-exceeds-limit...` |
   | Case rule          | If `lowercase: true`, no uppercase characters (except ticket IDs) | `003-User-Auth`                                   |
   | Separator          | Words must use configured `separator`                             | `003_user_auth` when separator is `-`             |
   | Branch-folder sync | Branch name and folder name must be derivable from same source    | Branch `feat/003-auth` but folder `004-auth`      |
   | Ticket format      | If pattern includes `{ticket}`, must match `ticket_pattern` regex | `proj-142` when pattern requires `[A-Z]+-[0-9]+`  |

4. **Output compliance report**:

   ```markdown
   # Branch Convention Compliance Report

   **Convention**: {preset name or "custom"}
   **Branch pattern**: {branch_pattern}
   **Folder pattern**: {folder_pattern}

   ## Results

   | Branch             | Folder          | Status           | Issues                   |
   | ------------------ | --------------- | ---------------- | ------------------------ |
   | feat/003-user-auth | 003-user-auth   | ✅ Compliant     | —                        |
   | 004-chat-system    | 004-chat-system | ⚠️ Non-compliant | Missing type prefix      |
   | feat/5-api         | 5-api           | ⚠️ Non-compliant | Sequence not zero-padded |

   ## Summary

   - **Total**: {N} branches
   - **Compliant**: {X} ✅
   - **Non-compliant**: {Y} ⚠️
   - **Orphaned folders** (no branch): {Z}

   ## Recommended Actions

   1. Run `/speckit.branch-convention.rename` to fix non-compliant items
   ```

5. **Report**: Output the compliance report. Do not modify any files — this command is read-only.

## Rules

- **Read-only** — this command never modifies any files or branches
- **Always show all items** — include compliant and non-compliant for full visibility
- **Be specific about violations** — explain exactly which rule was violated and what the correct name should be
- **Handle missing config gracefully** — if no convention is configured, validate against the default pattern and note that no custom convention has been set