From a09caab9fc5691935b119f1a454a99a38d97b6cd Mon Sep 17 00:00:00 2001
From: Sunny Singh <sunny.singh@alloy.com>
Date: Thu, 3 Sep 2026 15:24:13 -0400
Subject: [PATCH] Add branch-validate skill

---
 .agents/skills/branch-validate            |  1 +
 .claude/skills/branch-validate            |  1 +
 README.md                                 | 10 ++++
 skills/branch-validate/SKILL.md           | 63 +++++++++++++++++++++++
 skills/branch-validate/validate-branch.sh | 32 ++++++++++++
 skills/pr-create/SKILL.md                 | 12 +++--
 6 files changed, 116 insertions(+), 3 deletions(-)
 create mode 120000 .agents/skills/branch-validate
 create mode 120000 .claude/skills/branch-validate
 create mode 100644 skills/branch-validate/SKILL.md
 create mode 100755 skills/branch-validate/validate-branch.sh

diff --git a/.agents/skills/branch-validate b/.agents/skills/branch-validate
new file mode 120000
index 0000000..0027f89
--- /dev/null
+++ b/.agents/skills/branch-validate
@@ -0,0 +1 @@
+../../skills/branch-validate
\ No newline at end of file
diff --git a/.claude/skills/branch-validate b/.claude/skills/branch-validate
new file mode 120000
index 0000000..0027f89
--- /dev/null
+++ b/.claude/skills/branch-validate
@@ -0,0 +1 @@
+../../skills/branch-validate
\ No newline at end of file
diff --git a/README.md b/README.md
index 0d04f76..455c047 100644
--- a/README.md
+++ b/README.md
@@ -37,3 +37,13 @@ You can then ask an AI agent to create a PR, or call the skill directly in the p
 ```
 
 The skill drafts a PR summary from the branch's diff (title, overview, test instructions, risks) and offers to create a new PR or update an existing one.
+
+### Validate branch names
+
+A skill is available to ensure git branch names conform to the Alloy organization standard.
+
+```sh
+gh skill install UseAlloy/.github branch-validate
+```
+
+It ships with a `validate-branch.sh` script to validate branch names.
diff --git a/skills/branch-validate/SKILL.md b/skills/branch-validate/SKILL.md
new file mode 100644
index 0000000..9691369
--- /dev/null
+++ b/skills/branch-validate/SKILL.md
@@ -0,0 +1,63 @@
+---
+name: branch-validate
+description: Ensure a git branch name is validated against standard naming conventions.
+---
+
+## Goal
+
+Ensure git branches are created with our standard organize-wide convention.
+
+In the case where a branch or PR is already created and is incorrect, recreate it until it's valid.
+
+## Validating the branch
+
+The current branch name can be validated with the script inside of this skill:
+
+```bash
+./validate-branch.sh
+```
+
+If the branch is not yet created, pass it to the script:
+
+```bash
+./validate-branch.sh 'feature/TICKET-123/example-branch-name'
+```
+
+If a PR was created for the existing, incorrectly-named branch, close that PR. Create a new PR for the new correctly-named branch.
+
+Use this fallback format when the ticket ID is not known at all: `task/<label>`
+
+If using the Cursor Cloud `ManagePullRequest` tool to create the branch and PR, enable the `skip_branch_prefix_check` parameter to bypass Cursor's pre-existing branch naming checks.
+
+## Git branch naming
+
+IMPORTANT: Follow the branch naming convention below when creating or renaming branches, regardless of whether a branch or PR already exists.
+
+Branch name must match format: `<type>/<ticket>/<label>'
+
+- `<type>` - a work type in all lowercase, e.g. feature, task, sub-task
+- `<ticket>` - a ticket ID in all uppercase, e.g. MYTEAM-123
+- `<label>` - a short description lowercase letters, numbers, and dashes
+
+Example: feature/TICKET-123/example-branch-name
+
+The ticket ID is known when:
+
+- You've been @mentioned from a Jira ticket.
+- The user provides a Jira ticket URL or ID in the prompt.
+- The prompt, current branch, base branch, PR branch, or issue context contains a Jira-style ticket ID such as `TEAM-123` or `team-123`.
+
+Extract the ticket ID with this precedence:
+
+1. Explicit Jira ticket in the user prompt.
+2. Jira ticket in the requested/current/base branch name.
+3. Jira ticket in linked issue or PR context.
+
+If a ticket ID is found, do not use `task/<label>`. Use `task/<TICKET>/<label>`.
+
+If Cursor Cloud or Claude Managed Agents provides a run-specific suffix, append it to `<label>` while keeping the ticket:
+
+- Correct: `task/TEAM-123/descriptive-label-suffix456`
+- Incorrect: `task/descriptive-label-suffix456`
+
+If a branch was already created or if a PR was already created, then create a new branch, following this section's conventions on git branch names.
diff --git a/skills/branch-validate/validate-branch.sh b/skills/branch-validate/validate-branch.sh
new file mode 100755
index 0000000..32a03af
--- /dev/null
+++ b/skills/branch-validate/validate-branch.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+# This script validates a git branch, passed in as $1 otherwise defaults to the current branch.
+
+set -euo pipefail
+
+WORK_TYPE_PATTERN='[a-z]+(-[a-z]+)*'
+TICKET_ID_PATTERN='[A-Z][A-Z0-9]+-[0-9]+'
+BRANCH_LABEL_PATTERN='[a-z0-9-]+'
+BRANCH_NAME_PATTERN="^${WORK_TYPE_PATTERN}/${TICKET_ID_PATTERN}/${BRANCH_LABEL_PATTERN}$"
+
+branch_name="${1:-$(git rev-parse --abbrev-ref HEAD)}"
+
+if [[ ! "$branch_name" =~ $BRANCH_NAME_PATTERN ]]; then
+  echo 'Branch name must match format: <type>/<ticket>/<label>'
+
+  printf '\n'
+
+  echo '<type>   - a work type in all lowercase, e.g. feature, task, sub-task'
+  echo '<ticket> - a ticket ID in all uppercase, e.g. MYTEAM-123'
+  echo '<label>  - a short description lowercase letters, numbers, and dashes'
+
+  printf '\n'
+
+  echo 'Example: feature/TICKET-123/example-branch-name'
+
+  printf '\n'
+
+  echo "Rename your branch: git branch --move '${branch_name}' <new-branch>"
+
+  exit 1
+fi
diff --git a/skills/pr-create/SKILL.md b/skills/pr-create/SKILL.md
index 7ede36f..abbfc7f 100644
--- a/skills/pr-create/SKILL.md
+++ b/skills/pr-create/SKILL.md
@@ -35,6 +35,10 @@ Right size:
 
 The trimmed version drops field lists, quantitative details, and extra justifying clauses — all derivable from the diff or obvious from context. The "why" survives as a single short clause.
 
+## Branch creation
+
+If a branch is needed to be created or validated, refer to the `branch-validate` skill.
+
 ## PR Template
 
 The canonical pull request template lives in this public `UseAlloy/.github` repository:
@@ -58,11 +62,13 @@ Fill in this template — do not invent or reorder sections. The per-section aut
 This is the single source of truth, not conversation history.
 
 ```sh
-git log origin/master..HEAD --oneline
-git diff origin/master...HEAD --stat
-git diff origin/master...HEAD
+git log origin/main..HEAD --oneline
+git diff origin/main...HEAD --stat
+git diff origin/main...HEAD
 ```
 
+Replace `main` with the default branch, which is `main` by default but in some cases may be `master`.
+
 Read the full diff carefully. Every claim in the summary must be backed by something in the diff. Do not describe changes that were discussed but not committed, or changes that were made and then reverted.
 
 ### Conversation context is secondary