branch-pr

name	branch-pr
description	Team-aware GitHub branch and PR creation workflow. Uses username/description branch naming, squash merge, conventional commits encouraged. Reads .agents/team-conventions.md from the repo if it exists; falls back to relaxed defaults otherwise. Trigger: When creating a pull request, opening a PR, preparing a branch for review, or pushing changes upstream.
license	Apache-2.0
metadata	{"author":"FullFran","version":"1.0","inspired_by":"gentleman-programming/agent-teams-lite"}

When to Use

Use this skill when the user asks to create a branch, push changes, open a PR, mark a PR ready, or merge a PR. For creating issues, use the sibling skill issue-creation. For exhaustive gh command coverage, see the gh-cli skill.

Critical Rules

1. Always read .agents/team-conventions.md first if it exists at the repo root. It overrides every default in this file.
2. Branch naming is <github-username>/<kebab-description> by default — NOT type/description. Example: fullfran/dark-mode, not feat/dark-mode.
3. Never force-push to the default branch. Confirm before any destructive gh command.
4. Squash and merge is the default strategy. The squashed message becomes the PR title, so the PR title MUST follow conventional commits even when individual commit messages are free-form.
5. Use the PR template that already exists in the repo (.github/PULL_REQUEST_TEMPLATE.md). Fill all mandatory sections (Summary, Changes, Test plan); fill optional sections only when they apply; DELETE optional sections that do not apply.
6. Never invent PR labels. Use only labels that exist in the repo (gh label list).

Workflow

1. Read .agents/team-conventions.md (if exists)
2. Verify the working tree is clean and on the right base
3. Create branch: <github-username>/<kebab-description>
4. Implement the change with conventional commits when possible
5. Run any required local checks (lint, tests, shellcheck)
6. Push the branch
7. Open the PR using the repo's PULL_REQUEST_TEMPLATE.md
8. Add the matching type:* label and any other relevant labels
9. Mark as draft if the change is not ready for review
10. Wait for CI checks to pass before suggesting merge

Reading team conventions

The conventions file lives at <repo>/.agents/team-conventions.md. Sections you care about:

Section	What to do with it
## Branch naming	Use the documented format. The default is <github-username>/<description>.
## Issue-first enforcement	If required: true, the PR body MUST contain Closes/Fixes/Resolves #N. Reject the PR creation otherwise.
## Conventional commits	If required: true, validate commit messages against the regex. Otherwise just suggest the format.
## Merge strategy	Default is squash. If the conventions say otherwise, use that.
## Labels	Use only the labels documented here.
## CI required checks	List of check names that must be green before merge is suggested.

If the file does not exist, fall back to the defaults below.

Defaults (when no .agents/team-conventions.md)

• Branch naming: <github-username>/<kebab-description>. Lowercase, kebab-case, max ~40 chars.
• Issue-first: NOT required. Linking is encouraged in the PR body but not enforced.
• Conventional commits: encouraged in commits, REQUIRED in the PR title (because squash merge propagates the PR title to main).
• Merge strategy: squash and merge, delete remote branch after merge.
• CI required checks: none (trust the user to verify locally).
• Labels: same set as issue-creation skill — type:*, priority:*, status:*, plus specials.

Branch naming

Default format:

<github-username>/<description>

• <github-username> is the GitHub login of the author, lowercase. Get it via gh api user --jq .login.
• <description> is short, kebab-case, no spaces, only [a-z0-9._-]. Aim for ~30-40 characters.

Examples:

✅ good	❌ bad
fullfran/dark-mode	feat/dark-mode (uses old type prefix)
fullfran/fix-zsh-glob	Fran/fix zsh glob (uppercase, spaces)
fullfran/migrate-auth-v2	feature_dark_mode (snake_case, no slash)

The agent should NOT hard-reject names that violate this. It warns the user with a suggestion and proceeds if the user insists.

PR title

Even when conventional commits are not enforced for individual commits, the PR title MUST be conventional because the squash-merge collapses everything into a single commit using the PR title as the subject.

^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9._-]+\))?!?: .+

Type	Use for	Maps to label
feat	new capability	type:feature
fix	bug fix	type:bug
docs	docs only	type:docs
refactor	code change with no behavior change	type:tech-debt
chore	tooling, deps, CI	type:chore
style	formatting, whitespace	type:chore
perf	performance improvement	type:enhancement
test	test additions/changes	type:chore
build	build system	type:chore
ci	CI config	type:chore
revert	revert a previous commit	type:bug
feat! / fix!	breaking change	breaking-change

PR body

Use the repo's .github/PULL_REQUEST_TEMPLATE.md. The template has these sections (mandatory marked with ★):

• ★ Summary — 1-3 bullets
• Linked issue — Closes #N (encouraged, may become required)
• ★ Type — tick exactly one and add the matching label
• ★ Changes — file/area table
• Architecture diagram — Mermaid, architecture-blueprint style, for any change touching multiple components. Highlight new/changed nodes.
• ★ Test plan — checkbox list of how this was verified
• Screenshots — for any user-visible UI change
• Notes for other developers — what frontend/mobile/infra/data teams need to know
• Deployment notes — feature flags, secrets, env vars, restart order
• Migration steps — schema migrations, backfills, manual cleanups
• Rollback plan — how to revert if it breaks prod
• Breaking changes — what breaks and how consumers adapt
• ★ Checklist — tests, docs, no Co-Authored-By, conventional commits, draft state, squash-friendly

The agent should DELETE the optional sections that do not apply when generating the PR body — leaving empty placeholders is noise.

Architecture diagram in PR body

When the change touches more than one component, include a Mermaid diagram in the "Architecture diagram" section showing the affected pieces AFTER the change. Highlight new or changed nodes with a different color.

flowchart LR
    user([User])
    feature[New thing this PR adds]
    existing[Existing component]

    user --> feature
    feature --> existing

    style feature fill:#7aa2f7,color:#1a1b26

For multi-step interactions use a sequenceDiagram. For state machines use stateDiagram-v2. The mermaid-diagrams skill has detailed guidance.

Commands

# 1. read conventions if they exist
[[ -f .agents/team-conventions.md ]] && cat .agents/team-conventions.md

# 2. get github username for branch name
username=$(gh api user --jq .login | tr '[:upper:]' '[:lower:]')

# 3. create branch
git checkout -b "${username}/<description>" main

# 4. implement, commit (conventional commits encouraged)
git add <files>
git commit -m "feat(scope): description"

# 5. push
git push -u origin HEAD

# 6. create PR using the repo template
gh pr create --title "feat(scope): description" --body "$(cat <<'EOF'
## Summary
- ...

## Changes
| File | Change |
|------|--------|
| ... | ... |

## Test plan
- [x] ...
EOF
)"

# 7. add type label
gh pr edit <pr-number> --add-label "type:feature"

# 8. mark as draft if not ready
gh pr ready <pr-number> --undo

# 9. check CI status
gh pr checks <pr-number>

For multi-line PR bodies always use the heredoc pattern (see gh-cli skill, "Heredoc Bodies for Multi-line Text").

Merge

Default strategy is squash and merge with branch deletion:

gh pr merge <pr-number> --squash --delete-branch

Confirm with the user before merging. NEVER merge a PR that has failing checks unless the user explicitly tells you to.

Bootstrap a new repo

If the target repo does not have a PR template, run:

~/dotfiles/scripts/team-bootstrap.sh .

This installs .github/PULL_REQUEST_TEMPLATE.md, the issue templates, the labels, and the .agents/team-conventions.md defaults file in one shot.