feat: formalize branch naming convention {issue-num}-{kebab-slug} #179

Merged

forgejo_admin merged 1 commit from 129-enforce-branch-naming-convention into main

2026-03-28 00:21:12 +00:00

forgejo_admin commented

2026-03-28 00:18:35 +00:00

Contributor

Summary

Formalizes the {issue-number}-{kebab-case-purpose} branch naming convention that 6+ hooks already depend on. Adds documentation across agent profiles and a soft-validation PostToolUse hook that warns on non-compliant branch names without blocking.

Changes

hooks/validate-branch-name.sh -- new PostToolUse hook (soft warn, not block) that checks branch names from create_issue_and_branch match the {issue-num}-{kebab-slug} convention
settings.json -- registers validate-branch-name.sh alongside label-on-branch.sh on the create_issue_and_branch matcher
agents/dev.md -- adds "Branch Naming Convention" section documenting the format, examples, and the 6 hooks that depend on it; adds constraint bullet
agents/qa.md -- updates SOP compliance checklist from vague "Branch named after issue number?" to explicit convention reference
hooks/inject-subagent-context.sh -- adds branch naming convention to dev agent context injection
hooks/check-issue.sh -- updates comments to reference the formal convention and distinguish primary vs legacy patterns
schemas/agent-spawn-requirements.json -- adds convention reference to dev agent type description
tests/test_validate_branch_name.sh -- 14 test cases covering valid names, missing prefix, wrong number, empty slug, non-kebab-case, missing fields, and result text fallback

Test Plan

bash tests/test_validate_branch_name.sh -- 14/14 pass
bash tests/test_block_groupme_send.sh -- 21/21 pass (no regressions)
jq . settings.json and jq . schemas/agent-spawn-requirements.json -- valid JSON
Next agent dispatch should see branch naming guidance in context and produce compliant branch names

Review Checklist

Soft validation only (warn, not block) per issue constraint
Works across all repos (not repo-specific)
No existing branches renamed
Tests cover happy path + all error cases
No unrelated changes

Issue acceptance criteria note: pal-e-docs convention update is out of scope for this PR (Dev agent cannot write to pal-e-docs). Dottie should handle agent-spawn-conventions and convention-agent-design updates separately.

Forgejo issue: #129

Closes #129

## Summary Formalizes the `{issue-number}-{kebab-case-purpose}` branch naming convention that 6+ hooks already depend on. Adds documentation across agent profiles and a soft-validation PostToolUse hook that warns on non-compliant branch names without blocking. ## Changes - `hooks/validate-branch-name.sh` -- new PostToolUse hook (soft warn, not block) that checks branch names from `create_issue_and_branch` match the `{issue-num}-{kebab-slug}` convention - `settings.json` -- registers `validate-branch-name.sh` alongside `label-on-branch.sh` on the `create_issue_and_branch` matcher - `agents/dev.md` -- adds "Branch Naming Convention" section documenting the format, examples, and the 6 hooks that depend on it; adds constraint bullet - `agents/qa.md` -- updates SOP compliance checklist from vague "Branch named after issue number?" to explicit convention reference - `hooks/inject-subagent-context.sh` -- adds branch naming convention to dev agent context injection - `hooks/check-issue.sh` -- updates comments to reference the formal convention and distinguish primary vs legacy patterns - `schemas/agent-spawn-requirements.json` -- adds convention reference to dev agent type description - `tests/test_validate_branch_name.sh` -- 14 test cases covering valid names, missing prefix, wrong number, empty slug, non-kebab-case, missing fields, and result text fallback ## Test Plan - `bash tests/test_validate_branch_name.sh` -- 14/14 pass - `bash tests/test_block_groupme_send.sh` -- 21/21 pass (no regressions) - `jq . settings.json` and `jq . schemas/agent-spawn-requirements.json` -- valid JSON - Next agent dispatch should see branch naming guidance in context and produce compliant branch names ## Review Checklist - [x] Soft validation only (warn, not block) per issue constraint - [x] Works across all repos (not repo-specific) - [x] No existing branches renamed - [x] Tests cover happy path + all error cases - [x] No unrelated changes ## Related Notes - Issue acceptance criteria note: pal-e-docs convention update is out of scope for this PR (Dev agent cannot write to pal-e-docs). Dottie should handle `agent-spawn-conventions` and `convention-agent-design` updates separately. ## Related - Forgejo issue: #129 Closes #129

forgejo_admin added 1 commit

2026-03-28 00:18:35 +00:00

feat: document and validate {issue-number}-{kebab-case-purpose} branch naming convention fd8298a66a

Six hooks already depend on parsing issue numbers from branch names but the
convention was implicit. This formalizes it with documentation across agent
profiles and a soft-validation PostToolUse hook that warns (not blocks) on
non-compliant branch names from create_issue_and_branch.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>