# Github Conventions

> GitHub conventions -- branch naming, commit format, issue/PR templates, and safe issue/PR referencing in comments.

- Skill: `jartan-llc/github-conventions` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jartan-llc/github-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jartan-llc/github-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Jartan-LLC (https://skillmd.com/u/jartan-llc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jartan-llc/github-conventions

---


# GitHub Conventions

CRITICAL: `#<number>` auto-links to issues/PRs on GitHub. Use `1.`/`2.`/`3.` for numbered lists and "Finding 1:"/"Item 1:" for labeled items -- never `#1`, `#2`, `#3` as markers.

## Authentication

**Never reconfigure auth transport to unblock a command.** Don't switch the remote
between SSH and HTTPS, add a credential helper, or push to an explicit URL. A
missing key or token scope is a missing credential, not a transport problem --
only the user can supply it, and working around it changes config they never asked
you to touch, often globally. Stop and ask.

## Branches

Feature branches: `feature/<description>` or `feature/issue-<number>`
Always check if a branch already exists for an issue before creating a new one.

For sub-issues of a larger feature, branch from the parent feature branch rather than main. Sub-issue work merges back into the parent feature branch, which eventually merges to main.

## Commits

Conventional commits format: `<type>: description`

Types: `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `test:`, `chore:`
Optional scope: `feat(frontend): description`

## Issues

Templates in `.github/ISSUE_TEMPLATE/` -- read them for section structure.

- **Bug reports**: must have label `bug`
- **Feature requests**: must have label `enhancement`

## Pull Requests

PR template at `.github/PULL_REQUEST_TEMPLATE.md` -- read it for section structure.
Use `Closes #<number>` to link PRs to issues.

## Code Reviews

Reviews are posted as PR comments. See [review-format.md](review-format.md) for the
recommended structure -- severity buckets and the `#N` footgun to avoid in the summary.

## Implementation Plans

Plans are posted as issue comments and saved to `.claude/workspace/`. See [plan-format.md](plan-format.md) for the recommended structure.