Git and PR Operations

Prerequisites: gh CLI installed + authenticated. gh: command not found or auth error → stop and surface, no workarounds.

• Resolve repo per Repo Derivation — codebases resolve independently.
• Run Confirmation Protocol before mutating ops.
• Multi-codebase ops → per codebase → aggregate into one report.

Operation Index

Placeholders

• {N} — issue number (#42 → 42). In feature/sprint-{N}, the sprint number.
• {short-description} — derived per Branch Naming.
• {branch} / {branch_name} — full branch name from the caller or context.
• {message} — commit message, provided by the caller.
• {files} — file paths to stage, provided by the caller.
• {body} — PR or review body, rendered via the github-templates skill.

Repo Derivation

owner/repo derived at runtime, never hardcoded. Run from inside the codebase directory (path from the Codebases table, never cwd); derive once per codebase and cache.

gh repo view --json owner,name --jq '[.owner.login,.name]|join("/")'

Confirmation Protocol

Before any mutating op: summarise all planned mutations in one block, ask once "Proceed? (y/n)", proceed only if confirmed.

Branch Naming

Base fixed by caller, never inferred — caller names which Branch Naming row applies. Standalone bug/refactor → base off main; in-sprint bug/refactor → base off sprint branch.

short-description derivation:

1. Strip leading [Tag] prefix (e.g. [Story], [Bug]).
2. Lowercase; replace spaces and special chars with hyphens.
3. Remove stop words: a, an, the, and, or, for, to, of, in, on, at, by, with, when, then.
4. Keep first 4 remaining words; trim trailing hyphens.

Collision: if the derived name exists on remote (check via Check Branch Exists), append -2, -3, etc. until unique.

Operations

Create Branch

git checkout {base_branch} && git pull
git checkout -b {new_branch}
git push -u origin {new_branch}

Story branches: confirm the sprint branch exists via Check Branch Exists first; absent → stop and surface, never auto-create. Run the collision check before creating.

Checkout

git checkout {branch_name}
git pull

"Checkout sprint branch" → feature/sprint-{N} for the current sprint.

Check Branch Exists

git ls-remote --exit-code --heads origin {branch_name} — exit 0 = exists (true), exit 2 = not found (false).

Commit and Push

git add {files}
git commit -m "{message}"
git push origin {branch_name}

{message} is caller-provided. Asked to author it → stop and surface: "Commit message authoring is out of scope — provide a message or use a commit-message skill."

Delete Branch

git push origin --delete {branch}

remote ref does not exist → treat as success, skip silently. Any other error surfaces.

Delete All Story Branches

• gh api --paginate repos/{owner}/{repo}/branches --jq '.[].name'
• Filter for feature/issue-{N}-*, fix/issue-{N}-*, or revert/issue-{N}-*.
• Confirm the full delete list, then delete each via git push origin --delete {branch} (skip silently on "remote ref does not exist").
• Report: count deleted, count skipped, failures.

Create PR

• gh pr create --repo {owner}/{repo} --title "{title}" --body "{body}" --head {head} --base {base} — returns PR URL.
• body rendered via github-templates (e.g. pr-story, pr-bug) — never freeform.
• Resolve the number from the URL or gh pr view {url} --json number,url. Report both number and URL.

Fetch PR

• gh pr view {id} --repo {owner}/{repo} --json title,body,headRefName,baseRefName,files,merged,closingIssuesReferences
• Also gh pr diff {id} for file list and diff content.

List PRs

• gh pr list --repo {owner}/{repo} --state {state} --json number,title,url,headRefName,state,merged
• state: open | closed | merged | all. "Merged only" → --state merged.

Submit Review

• Approve: gh pr review {pr_id} --approve --body "{body}"
• Request changes: gh pr review {pr_id} --request-changes --body "{body}"
• {body} for structured reviews rendered via github-templates.

Merge PR

• gh pr merge {pr_id} --repo {owner}/{repo} --squash

Diff Branch Files

• gh api repos/{owner}/{repo}/compare/{base}...{head} --jq '[.files[].filename]' — array of changed file paths.

Multi-codebase Operations

Resolve owner/repo per codebase → build full mutation plan across all → run Confirmation Protocol once with combined list → execute per codebase sequentially (parallel pushes can race) → aggregate per-codebase success/skip/error into one summary.

Constraints

• Never hardcode owner/repo — always derive via gh repo view from the codebase directory.
• Never write commit message content — the caller provides {message}.
• Never write PR or review body content from scratch — render via github-templates.
• Never auto-create missing base branches — stop and surface.
• Never run mutating ops without confirmation, even from a higher-level orchestrator.
• Never silently swallow errors other than remote ref does not exist on delete.
• Never operate on a codebase whose path isn't in the Codebases table.
• Force pushes require explicit caller request plus confirmation — never inferred.