ldraney/claude-custom

Fork 0

Enforce branch naming convention: {ticket_number}-{purpose} #129

New issue

Closed

opened 2026-03-18 18:10:57 +00:00 by forgejo_admin · 3 comments

forgejo_admin commented

2026-03-18 18:10:57 +00:00

Contributor

Lineage

plan-pal-e-agency → Process enforcement

Type

Task

Repo

forgejo_admin/claude-custom

User Story

As a platform operator
I want branches named {ticket_number}-{purpose} (e.g., 189-fix-westside-harbor-auth)
So that I can trace any branch or PR back to its board ticket at a glance

Context

Currently branch names are ad-hoc — some use issue numbers, some use descriptions, some use both inconsistently. With the new ticket-first workflow (board item → review → Forgejo issue → agent dispatch), every branch should trace back to its board ticket number. This makes it trivial to verify process compliance: see a branch, see its ticket, see its review.

The convention: {board_item_id}-{kebab-case-purpose} or {forgejo_issue_number}-{kebab-case-purpose}.

Examples:

189-fix-westside-harbor-auth
111-keycloak-probe-networkpolicy
115-remove-capacitor-dev

File Targets

~/claude-custom/hooks/ — possible validation hook on branch creation (label-on-branch.sh already fires on branch events)
skill-create-issue in pal-e-docs — update to include branch naming in the issue spec
agent-spawn-conventions in pal-e-docs — update to mandate branch naming when agents are dispatched
convention-agent-design in pal-e-docs — add branch naming to agent workflow conventions

Files NOT to touch:

Existing branches — don't rename retroactively

Acceptance Criteria

Convention documented in pal-e-docs (agent-spawn-conventions or new convention note)
Agent dispatch prompts include branch name instruction
Branch name traceable to board item or Forgejo issue number

Test Expectations

Next agent dispatched creates a branch matching the convention
git branch -a on any repo shows convention-compliant names for new branches

Constraints

Don't enforce via blocking hook initially — document first, enforce later
Must work across all repos (not repo-specific)
Board item IDs and Forgejo issue numbers may differ — convention should accept either

Checklist

Convention note created or updated in pal-e-docs
agent-spawn-conventions updated
PR opened
No unrelated changes

pal-e-agency — project
agent-spawn-conventions — agent dispatch SOP
sop-board-workflow — board workflow that produces the ticket numbers
template-ticket — ticket template (traceability triangle)

### Lineage `plan-pal-e-agency` → Process enforcement ### Type Task ### Repo `forgejo_admin/claude-custom` ### User Story As a platform operator I want branches named `{ticket_number}-{purpose}` (e.g., `189-fix-westside-harbor-auth`) So that I can trace any branch or PR back to its board ticket at a glance ### Context Currently branch names are ad-hoc — some use issue numbers, some use descriptions, some use both inconsistently. With the new ticket-first workflow (board item → review → Forgejo issue → agent dispatch), every branch should trace back to its board ticket number. This makes it trivial to verify process compliance: see a branch, see its ticket, see its review. The convention: `{board_item_id}-{kebab-case-purpose}` or `{forgejo_issue_number}-{kebab-case-purpose}`. Examples: - `189-fix-westside-harbor-auth` - `111-keycloak-probe-networkpolicy` - `115-remove-capacitor-dev` ### File Targets - `~/claude-custom/hooks/` — possible validation hook on branch creation (label-on-branch.sh already fires on branch events) - `skill-create-issue` in pal-e-docs — update to include branch naming in the issue spec - `agent-spawn-conventions` in pal-e-docs — update to mandate branch naming when agents are dispatched - `convention-agent-design` in pal-e-docs — add branch naming to agent workflow conventions Files NOT to touch: - Existing branches — don't rename retroactively ### Acceptance Criteria - [ ] Convention documented in pal-e-docs (agent-spawn-conventions or new convention note) - [ ] Agent dispatch prompts include branch name instruction - [ ] Branch name traceable to board item or Forgejo issue number ### Test Expectations - [ ] Next agent dispatched creates a branch matching the convention - [ ] `git branch -a` on any repo shows convention-compliant names for new branches ### Constraints - Don't enforce via blocking hook initially — document first, enforce later - Must work across all repos (not repo-specific) - Board item IDs and Forgejo issue numbers may differ — convention should accept either ### Checklist - [ ] Convention note created or updated in pal-e-docs - [ ] agent-spawn-conventions updated - [ ] PR opened - [ ] No unrelated changes ### Related - `pal-e-agency` — project - `agent-spawn-conventions` — agent dispatch SOP - `sop-board-workflow` — board workflow that produces the ticket numbers - `template-ticket` — ticket template (traceability triangle)

forgejo_admin commented

2026-03-27 21:08:42 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-198-2026-03-27
Ticket is well-scoped and nearly ready — two fixable gaps in template compliance and traceability.

Missing ### Type header — Should be "Task" per template-issue (convention documentation work, no code).
Missing arch: label on board item #198 — Recommend arch:conventions to complete the traceability triangle.

Key finding: The branch naming convention already exists in practice across 6+ hooks and skills (forgejo-helper.sh, board-item-on-merge.sh, check-issue.sh, label-on-pr.sh, skill-implement-phase, skill-review-pr). The work here is consolidation and formalization into agent-spawn-conventions and skill-create-issue, not invention. All file targets verified and valid.

Optional: Clarify whether deliverable is a new convention-branch-naming note or updates to existing notes only.

## Scope Review: NEEDS_REFINEMENT Review note: `review-198-2026-03-27` Ticket is well-scoped and nearly ready — two fixable gaps in template compliance and traceability. - **Missing `### Type` header** — Should be "Task" per template-issue (convention documentation work, no code). - **Missing `arch:` label on board item #198** — Recommend `arch:conventions` to complete the traceability triangle. **Key finding:** The branch naming convention already exists in practice across 6+ hooks and skills (`forgejo-helper.sh`, `board-item-on-merge.sh`, `check-issue.sh`, `label-on-pr.sh`, `skill-implement-phase`, `skill-review-pr`). The work here is consolidation and formalization into `agent-spawn-conventions` and `skill-create-issue`, not invention. All file targets verified and valid. Optional: Clarify whether deliverable is a new `convention-branch-naming` note or updates to existing notes only.

forgejo_admin commented

2026-03-27 21:24:57 +00:00

Author

Contributor

Scope Review Corrections Needed

From review-198-2026-03-27:

Fix 1: Add ### Type header — should be Task (documentation/convention work, no code file targets).

Fix 2: Board label corrected: added arch:conventions (done).

Research finding: The {issue-num}-{description} convention already exists in practice across 6+ hooks (forgejo-helper.sh:219, board-item-on-merge.sh:8, check-issue.sh:133-145, label-on-pr.sh:45, skill-implement-phase step 5). This is consolidation work, not invention.

Once fixed → READY for next_up.

## Scope Review Corrections Needed From `review-198-2026-03-27`: **Fix 1:** Add `### Type` header — should be `Task` (documentation/convention work, no code file targets). **Fix 2:** Board label corrected: added `arch:conventions` (done). **Research finding:** The `{issue-num}-{description}` convention already exists in practice across 6+ hooks (`forgejo-helper.sh:219`, `board-item-on-merge.sh:8`, `check-issue.sh:133-145`, `label-on-pr.sh:45`, `skill-implement-phase` step 5). This is consolidation work, not invention. Once fixed → READY for next_up.

forgejo_admin commented

2026-03-27 21:48:36 +00:00

Author

Contributor

Issue body updated per scope review corrections.