holocron/plugins/git/.apm/skills/git-branches/SKILL.md at 0fde892f2080ae55e1f19763e0f2d1e65c06f2ae

Files

Defame1297 0fde892f20 refactor(git-branches): retrofit to the ADR-0020 context contract

Description 612 -> 273 chars, body 1124 -> 457 words. Branch patterns,
operations, merging, comparison, and the orchestrator contract move to
references/.

Corrects rebase routing in four places: this skill sent rebase to
git-history, which carries no rebase content and disclaims it. Rebase is
git-commits'; cherry-pick and revert stay git-history's. Drops a Step 3
gate on a rebase flow this skill does not have.

2026-08-30 13:10:53 +00:00

3.5 KiB

Raw Blame History

name, description, metadata

name

description

metadata

git-branches

Use when creating, switching, deleting, renaming, tracking, merging, or comparing local git branches under GitHub Flow or Gitflow. Not writing or rewriting commits -> `git-commits`. Not history inspection -> `git-history`. Not a Gitea remote's branches -> `gitea-branches`.

Gotchas

Uncommitted changes abort a switch. git switch refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears.
A branch and a tag can carry the same name. Prefer git switch over git checkout, and where a command accepts either ref, disambiguate with refs/heads/<name> or refs/tags/<name>.
main and master are a refusal, not a gate. Force-pushing, force-deleting, or renaming them is rejected even when the caller passes confirm: true — no flag makes the remote's history recoverable. Offer a new branch instead.

Step 1 — Determine the branching pattern

Read branching_pattern from the git plugin config (.claude/plugins/git/config.json; the plugin root's config.example.json shows the shape). Default: github-flow. With no config, infer Gitflow from the presence of a develop or release/* branch, and GitHub Flow otherwise.

The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read references/branch-patterns.md.

Step 2 — Dispatch on the action

Action	Reference
create, switch, delete, rename, track, list, get-intent	`references/branch-operations.md`
merge a branch, resolve merge conflicts	`references/merging.md`
compare two branches, find their divergence	`references/comparing-branches.md`

Load only the file the action needs. A destructive action still passes Step 3 first.

Step 3 — Gate destructive operations

Before any delete or force-delete that loses history:

Does the branch track a remote? Warn if so.
Are there unpushed commits on it? Warn if so.
Did the caller pass confirm: true? Fail if not — for a human caller, prompt interactively instead of failing.

These gates are passable. The main/master refusal in Gotchas is not.

Step 4 — Set tracking

When pushing a branch for the first time, always git push -u origin <branch>. Without an upstream, later pushes and pulls either fail or silently target the wrong remote branch, and the caller has no way to tell which happened.

Step 5 — Return a structured result

Return every operation in this shape rather than prose, including failures — a calling agent chains its next operation on the result and cannot parse a sentence.

{
  "success": true,
  "action": "create|switch|delete|rename|track|list|get-intent",
  "branch": "<name>",
  "message": "descriptive message",
  "intent": "<intent if tracked>",
  "tracking": "origin/<branch, if set>",
  "error": "<error message if success=false>",
  "suggestion": "<recovery suggestion if applicable>"
}

When the failure is uncommitted local changes, set "suggestion": "stash changes and retry" so the caller can offer recovery rather than surfacing a dead end.

When a calling agent supplies a structured request rather than prose, read references/orchestrator-contract.md for the request schema.

3.5 KiB Raw Blame History