Problem
Branch names across the repository are inconsistent — some use issue-NNNN, others feat/description, fix/NNNN-description, add-description (no number), pr-NNNN, etc. This makes it difficult to:
- Trace worktrees back to their corresponding issues/PRs
- Identify merged branches for cleanup (especially with squash merges where
git branch --merged doesn't work)
- Maintain a consistent contributor experience
Proposed Solution
Document a branch naming convention in:
AGENTS.md — as a requirement for AI coding agents (they will comply deterministically)
CONTRIBUTING.md — as a strong recommendation for human contributors
Convention
<type>/<number>-<short-slug>
Where <number> is either an issue number or a PR number — whichever is created first. This accommodates contributors who start with a PR rather than an issue.
| Prefix |
When to use |
feat/ |
New features |
fix/ |
Bug fixes |
docs/ |
Documentation changes |
community/ |
Community catalog additions |
chore/ |
Maintenance, tooling, CI |
Rules:
- Always include the issue or PR number immediately after the prefix
- Use kebab-case for the slug
- Keep the slug short — enough to identify the work without looking up the issue
Acceptance Criteria
Problem
Branch names across the repository are inconsistent — some use
issue-NNNN, othersfeat/description,fix/NNNN-description,add-description(no number),pr-NNNN, etc. This makes it difficult to:git branch --mergeddoesn't work)Proposed Solution
Document a branch naming convention in:
AGENTS.md— as a requirement for AI coding agents (they will comply deterministically)CONTRIBUTING.md— as a strong recommendation for human contributorsConvention
Where
<number>is either an issue number or a PR number — whichever is created first. This accommodates contributors who start with a PR rather than an issue.feat/fix/docs/community/chore/Rules:
Acceptance Criteria
AGENTS.mdhas a "Branch Naming Convention" section (requirement for agents)CONTRIBUTING.mdreferences the same convention in the "Submitting a pull request" section (recommendation for humans)