diff --git a/plugins/git/.apm/skills/git-branches/README.md b/plugins/git/.apm/skills/git-branches/README.md
index c31a1bd..b3626dd 100644
--- a/plugins/git/.apm/skills/git-branches/README.md
+++ b/plugins/git/.apm/skills/git-branches/README.md
@@ -1,6 +1,6 @@
 # git-branches
 
-Manage the full lifecycle of git branches — create, switch, delete, rename, and track feature/hotfix/release branches under GitHub Flow or Gitflow.
+Manage the full lifecycle of git branches — create, switch, delete, rename, track, merge, and compare feature/hotfix/release branches under GitHub Flow or Gitflow.
 
 ## What it does
 
@@ -12,11 +12,22 @@ This skill handles branch operations within the git workflow suite. It creates b
 /git-branches
 ```
 
-Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, or track. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
+Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, track, merge, or compare two branches. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
 
 ## Files
 
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
+| `references/branch-patterns.md` | Loaded when a branch's base, name prefix, or merge rule depends on GitHub Flow vs. Gitflow |
+| `references/branch-operations.md` | Loaded when running a create/switch/delete/rename/track/list action, or resolving `get-intent` |
+| `references/merging.md` | Loaded when merging one branch into another or resolving merge conflicts |
+| `references/comparing-branches.md` | Loaded when comparing two branches or finding where they diverged |
+| `references/orchestrator-contract.md` | Loaded when `git-orchestrate` or another calling agent supplies a structured request rather than prose |
 | `references/sources.md` | Research sources backing the branching/gitflow guidance |
+
+## Composition
+
+`git-orchestrate` calls this skill for the branch step of a multi-step workflow and parses its
+structured result. Cherry-pick and revert are `git-history`'s; commit authoring and rebase are
+`git-commits`'; branch operations against a Gitea-hosted remote are `gitea-branches`'.
diff --git a/plugins/git/.apm/skills/git-branches/SKILL.md b/plugins/git/.apm/skills/git-branches/SKILL.md
index cef3f0c..7a2e715 100644
--- a/plugins/git/.apm/skills/git-branches/SKILL.md
+++ b/plugins/git/.apm/skills/git-branches/SKILL.md
@@ -2,13 +2,11 @@
 name: git-branches
 
 description: >
-  Use when managing the full lifecycle of git branches: create feature/hotfix/release branches
-  (gitflow, GitHub Flow, or custom patterns from config), switch, delete, rename, and track branches,
-  or retrieve branch intent metadata. Handles branch protection safety checks and returns structured
-  results for agent composition. Use even if the user doesn't explicitly mention branch names — they
-  may be asking about "fixing something" or "shipping a feature", which implicitly requires branch
-  management. Do not use when the user needs only commit operations (use git-commits) or history
-  inspection (use git-history).
+  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`.
 
 metadata:
   category: git
@@ -21,92 +19,57 @@ metadata:
 
 ## Gotchas
 
-- **Branches are cheap; deletion is cheap but risky.** Deleting one requires checking if commits on it are reachable elsewhere; always confirm before deleting, as it may lose unmerged work.
-- **Uncommitted changes can block branch switches.** `git switch` aborts if local modifications conflict with the target branch. Offer to stash changes before switching when this happens, don't force a checkout.
-- **Tracking relationships matter for coordination.** Agents pushing on behalf of users should always set tracking (`-u origin <branch>`) so later pushes/pulls know the target. Without it, commands fail or target the wrong remote branch.
-- **Gitflow vs. GitHub Flow are not compatible.** Gitflow requires `develop` and `release/*` branches with `--no-ff` merges; GitHub Flow uses only `main` and feature branches with fast-forward. Read the repo's config or ask the orchestrator which pattern to use — don't guess.
-- **Naming collisions with tags.** A branch and tag can have the same name. Prefer `git switch` over `git checkout` for branch operations — verify which ref you're targeting with `git branch --list <name>` / `git tag --list <name>` if the name could be ambiguous, and disambiguate explicitly with `refs/heads/<name>` (branch) or `refs/tags/<name>` (tag) where a command accepts either.
-- **Never force-push `main` or `master`.** This is a hard refusal, not a confirmation gate — it applies even if the caller passes `confirm: true`. Deleting or renaming `main`/`master` in a way that would require a force-push to reconcile the remote (e.g. force-deleting and recreating it, or renaming it out from under in-flight work) must be rejected outright; explain why and suggest a non-destructive alternative (e.g. a new branch) instead of proceeding.
+- **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.
 
-## Branch Patterns
+## Step 1 — Determine the branching pattern
 
-Default to **GitHub Flow** (simpler, modern, CI/CD-friendly). Fall back to **Gitflow** only if the repo's config specifies it or the branch structure shows it in use (presence of `develop` or release branches).
+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.
 
-**GitHub Flow:**
-- Base: `main`
-- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
-- Merge: fast-forward when possible (preserves linear history)
-- Delete after merge
+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`.
 
-**Gitflow:**
-- Base: `main` (production) + `develop` (integration)
-- Feature branches: `feature/<feature-name>` (from `develop`)
-- Release branches: `release/X.Y.Z` (from `develop`, merged to `main` + `develop`)
-- Hotfix branches: `hotfix/X.Y.Z` (from `main`, merged to `main` + `develop`)
-- Merge: always use `--no-ff` to preserve branch structure
+## Step 2 — Dispatch on the action
 
-## Workflow
+| 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` |
 
-- [ ] **Determine pattern:** Check git plugin config (`.claude/plugins/git/config.json`, if present — see `config.example.json` in the plugin root for the expected shape) for `branching_pattern` (default: `github-flow`). If not set, inspect repo for `develop` branch or `release/*` branches; if present, assume Gitflow.
-- [ ] **Create branch:** Use `git switch -c <branch> <base>`. Base defaults to config's `base_branch` (usually `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`).
-- [ ] **Track remote:** If pushing, always use `git push -u origin <branch>` to establish tracking.
-- [ ] **Safety checks before destructive ops:** Before delete/force-push/rebase with history loss, check: (1) Is this branch tracking a remote? Warn if yes. (2) Are there unpushed commits? Warn if yes. (3) Does the orchestrator call include `confirm: true`? Fail if not. For humans, prompt interactively.
-- [ ] **Return structured results:** Always return branch operations as JSON or structured text: `{ "action": "create", "branch": "feature/x", "base": "main", "tracking": "origin/feature/x", "intent": "implement feature X" }`. Agents need to parse this for subsequent operations.
-- [ ] **Retrieve intent (`get-intent`):** Git has no native field for free-text branch metadata — this skill doesn't persist it. On `create`, the `intent` value is only ever returned in the structured result; the caller (orchestrator or agent) is responsible for storing it if it needs to be looked up later. On `get-intent`, either parse it back out of the branch name convention (`feature/<intent-slug>`) or return `{ "intent": null }` if the caller never persisted the original create-time value — don't fabricate an intent.
+Load only the file the action needs. A destructive action still passes Step 3 first.
 
-### Command mapping for each action
+## Step 3 — Gate destructive operations
 
-- **delete:** `git branch -d <branch>` refuses if the branch has unmerged commits — prefer this by default. `git branch -D <branch>` forces deletion and discards unmerged work; only use it after the safety checks above pass and `confirm: true` is set. For a remote branch: `git push origin --delete <branch>`.
-- **rename:** `git branch -m <old> <new>`.
-- **list:** `git branch` (local only), `git branch -a` (all local + remote-tracking), `git branch -r` (remote-tracking only), `git branch --merged`/`--no-merged` (filter by merge status into current branch).
-- **get-intent:** No git command — see Workflow step "Retrieve intent" for how this is resolved.
-- **track (existing branch):** `git branch --set-upstream-to=origin/<branch>` sets tracking without a push; `git branch -vv` shows tracking state for all local branches.
-- **switch (existing branch):** `git switch <branch>` — switches to an existing local branch (aborts on conflicting local changes, see Gotchas). `git switch -` switches back to the previously checked-out branch.
+Before any delete or force-delete that loses history:
 
-## Merging
+- [ ] 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.
 
-Scope: fast-forward/merge-commit mechanics and conflict resolution only. Rebase, cherry-pick, and revert belong to `git-history`.
+These gates are passable. The `main`/`master` refusal in Gotchas is not.
 
-- **Fast-forward:** `git merge <branch>` — advances the pointer with no merge commit if the target hasn't diverged.
-- **True merge:** `git merge --no-ff <branch>` — forces a merge commit even when fast-forward is possible; required by Gitflow on all supporting-branch merges.
-- **Squash merge:** `git merge --squash <branch>` stages the combined diff without committing; follow with a manual `git commit`.
-- **Octopus merge:** `git merge branch-a branch-b branch-c` merges more than two branches at once; fails outright on any conflict, so use sequential two-way merges if conflicts are expected.
+## Step 4 — Set tracking
 
-**Conflict resolution:** when Git can't auto-merge, it inserts conflict markers and stops. Run `git status` to find conflicted files, edit them to resolve the markers, then `git add <file>` and `git merge --continue`. `git merge --abort` reverts to the pre-merge state. `git mergetool` opens the configured merge tool; `git diff --diff-filter=U` shows only conflicted files.
+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.
 
-## Comparing Branches
+## Step 5 — Return a structured result
 
-- `git log main..feature` — commits in `feature` not in `main`.
-- `git log feature..main` — commits in `main` not in `feature` (reverse direction).
-- `git log --left-right main...feature` — both diverging sets (symmetric diff).
-- `git diff main...feature` — diff from the common ancestor to `feature`'s tip.
-- `git merge-base main feature` — print the common ancestor commit.
+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.
 
-## Integration with Orchestrator
-
-When invoked by `git-orchestrate`, accept requests in the form:
-```json
-{
-  "action": "create|switch|delete|rename|track|list|get-intent",
-  "branch": "<branch-name>",
-  "base": "<base-branch (optional, defaults to config)>",
-  "intent": "<human-readable intent (optional)>",
-  "confirm": "<true for destructive ops, omit for read ops>"
-}
-```
-
-Return results as:
 ```json
 {
   "success": true,
-  "action": "create|switch|...",
+  "action": "create|switch|delete|rename|track|list|get-intent",
   "branch": "<name>",
   "message": "descriptive message",
   "intent": "<intent if tracked>",
-  "tracking": "origin/<branch (if set)>",
+  "tracking": "origin/<branch, if set>",
   "error": "<error message if success=false>",
   "suggestion": "<recovery suggestion if applicable>"
 }
 ```
 
-If error is due to uncommitted changes, include `{ "suggestion": "stash changes and retry" }` so the orchestrator can offer automatic recovery.
+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.
diff --git a/plugins/git/.apm/skills/git-branches/references/branch-operations.md b/plugins/git/.apm/skills/git-branches/references/branch-operations.md
new file mode 100644
index 0000000..8c428cc
--- /dev/null
+++ b/plugins/git/.apm/skills/git-branches/references/branch-operations.md
@@ -0,0 +1,34 @@
+---
+source_keys:
+  - context7-git-htmldocs
+---
+
+# Per-action command mapping
+
+One command per action. Where two forms exist, the first is the default and the second the escape
+hatch.
+
+- **create** — `git switch -c <branch> <base>`. Base comes from the config's `base_branch`
+  (`main` under GitHub Flow, usually `develop` under Gitflow).
+- **switch** — `git switch <branch>` moves to an existing local branch; it aborts rather than
+  clobbering conflicting local changes. `git switch -` returns to the previous branch.
+- **delete (local)** — `git branch -d <branch>` refuses when the branch holds unmerged commits,
+  which is why it is the default. `git branch -D <branch>` forces the deletion and discards that
+  work — only after the destructive-operation gates pass and `confirm: true` is set.
+- **delete (remote)** — `git push origin --delete <branch>`.
+- **rename** — `git branch -m <old> <new>`.
+- **list** — `git branch` (local), `-a` (local plus remote-tracking), `-r` (remote-tracking only),
+  `--merged` / `--no-merged` (filter by merge status into the current branch).
+- **track** — `git branch --set-upstream-to=origin/<branch>` sets an upstream without pushing.
+  `git branch -vv` shows the tracking state of every local branch.
+
+## get-intent
+
+Git has no native field for free-text branch metadata, and this skill does not persist any. On
+`create`, the `intent` value is only returned in the structured result — the caller decides
+whether to store it.
+
+On `get-intent`, either parse the intent back out of the branch-name convention
+(`feature/<intent-slug>`) or return `{ "intent": null }` when the caller never persisted the
+create-time value. Never fabricate an intent: a downstream commit message built on a guessed
+intent is worse than one built on none.
diff --git a/plugins/git/.apm/skills/git-branches/references/branch-patterns.md b/plugins/git/.apm/skills/git-branches/references/branch-patterns.md
new file mode 100644
index 0000000..84e6680
--- /dev/null
+++ b/plugins/git/.apm/skills/git-branches/references/branch-patterns.md
@@ -0,0 +1,31 @@
+---
+source_keys:
+  - nvie-gitflow-post
+  - atlassian-gitflow-tutorial
+  - gitflow-cheatsheet
+---
+
+# Branch patterns
+
+Which pattern is in play decides the base branch, the branch name prefix, and whether merges are
+allowed to fast-forward. Default to GitHub Flow — simpler, and what CI/CD-oriented repos expect.
+Fall back to Gitflow only when the config says so or the repo already carries `develop` or
+`release/*` branches.
+
+## GitHub Flow
+
+- Base: `main`
+- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
+- Merge: fast-forward where possible, to keep history linear
+- Delete the branch after merge
+
+## Gitflow
+
+- Base: `main` (production) plus `develop` (integration)
+- Feature branches: `feature/<feature-name>`, cut from `develop`
+- Release branches: `release/X.Y.Z`, cut from `develop`, merged to both `main` and `develop`
+- Hotfix branches: `hotfix/X.Y.Z`, cut from `main`, merged to both `main` and `develop`
+- Merge: always `--no-ff`, so the branch structure survives in the history
+
+The two are not mixable. A `--no-ff` merge into a GitHub Flow repo leaves merge commits nobody
+expects; a fast-forward merge of a Gitflow release branch erases the release boundary.
diff --git a/plugins/git/.apm/skills/git-branches/references/comparing-branches.md b/plugins/git/.apm/skills/git-branches/references/comparing-branches.md
new file mode 100644
index 0000000..24c3214
--- /dev/null
+++ b/plugins/git/.apm/skills/git-branches/references/comparing-branches.md
@@ -0,0 +1,16 @@
+---
+source_keys:
+  - context7-git-htmldocs
+---
+
+# Comparing two branches
+
+The two-dot and three-dot forms mean different things and are easy to swap by accident — check the
+direction before reporting a result.
+
+- `git log main..feature` — commits on `feature` that are not on `main`.
+- `git log feature..main` — the reverse direction: commits on `main` not on `feature`.
+- `git log --left-right main...feature` — both diverging sets at once (symmetric difference).
+- `git diff main...feature` — the diff from the common ancestor to `feature`'s tip, which is what
+  a reviewer sees, rather than the diff between the two tips.
+- `git merge-base main feature` — print the common ancestor commit.
diff --git a/plugins/git/.apm/skills/git-branches/references/merging.md b/plugins/git/.apm/skills/git-branches/references/merging.md
new file mode 100644
index 0000000..0c8f245
--- /dev/null
+++ b/plugins/git/.apm/skills/git-branches/references/merging.md
@@ -0,0 +1,29 @@
+---
+source_keys:
+  - context7-git-htmldocs
+---
+
+# Merging one branch into another
+
+Scope is fast-forward and merge-commit mechanics plus conflict resolution. Rebase belongs to
+`git-commits`; cherry-pick and revert to `git-history`.
+
+- **Fast-forward** — `git merge <branch>` advances the pointer with no merge commit when the
+  target has not diverged.
+- **True merge** — `git merge --no-ff <branch>` forces a merge commit even when a fast-forward is
+  possible. Gitflow requires it on every supporting-branch merge.
+- **Squash merge** — `git merge --squash <branch>` stages the combined diff without committing.
+  Follow it with a `git commit`.
+- **Octopus merge** — `git merge branch-a branch-b branch-c` merges more than two branches at
+  once, but fails outright on any conflict. Use sequential two-way merges when conflicts are
+  likely.
+
+## Conflict resolution
+
+When Git cannot auto-merge it writes conflict markers and stops mid-merge. Run `git status` to
+list the conflicted files, edit each to resolve its markers, then `git add <file>` and
+`git merge --continue`.
+
+- `git merge --abort` restores the pre-merge state.
+- `git mergetool` opens the configured merge tool.
+- `git diff --diff-filter=U` shows only the still-conflicted files.
diff --git a/plugins/git/.apm/skills/git-branches/references/orchestrator-contract.md b/plugins/git/.apm/skills/git-branches/references/orchestrator-contract.md
new file mode 100644
index 0000000..7fceb33
--- /dev/null
+++ b/plugins/git/.apm/skills/git-branches/references/orchestrator-contract.md
@@ -0,0 +1,16 @@
+# Orchestrator request contract
+
+`git-orchestrate` and other calling agents send this shape. The result shape they parse back is in
+`SKILL.md` Step 5, because every run emits one.
+
+Request:
+
+```json
+{
+  "action": "create|switch|delete|rename|track|list|get-intent",
+  "branch": "<branch-name>",
+  "base": "<base branch, optional, defaults to config>",
+  "intent": "<human-readable intent, optional>",
+  "confirm": "<true for destructive ops, omit for read ops>"
+}
+```
diff --git a/plugins/git/.apm/skills/git-branches/references/sources.md b/plugins/git/.apm/skills/git-branches/references/sources.md
index d65c617..506756c 100644
--- a/plugins/git/.apm/skills/git-branches/references/sources.md
+++ b/plugins/git/.apm/skills/git-branches/references/sources.md
@@ -12,7 +12,8 @@
 - **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Branch Patterns — Gitflow vs. GitHub Flow structure and defaults)
+- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
+- references/branch-patterns.md (Gitflow vs. GitHub Flow structure, defaults, and why the two are not mixable)
 
 ## atlassian-gitflow-tutorial
 
@@ -23,7 +24,9 @@
 - **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Branch Patterns — Gitflow branch types, base/merge targets, `--no-ff` requirement)
+- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
+- references/branch-patterns.md (Gitflow branch types, base/merge targets, `--no-ff` requirement)
+- references/merging.md (`--no-ff` requirement on Gitflow supporting-branch merges)
 
 ## gitflow-cheatsheet
 
@@ -34,7 +37,7 @@
 - **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Branch Patterns — feature/release/hotfix naming conventions)
+- references/branch-patterns.md (feature/release/hotfix naming conventions)
 
 ## context7-git-htmldocs
 
@@ -45,4 +48,7 @@
 - **Research doc:** plugins/git/docs/research/docs/git/branching-merging.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Command mapping, Merging, Comparing Branches — `git switch`/`git branch`/`git merge`/`git log`/`git diff`/`git merge-base` command vocabulary and flags)
+- SKILL.md (Gotchas — `git switch` abort-on-conflict behaviour, branch/tag name ambiguity)
+- references/branch-operations.md (`git switch`/`git branch` command vocabulary and flags)
+- references/merging.md (`git merge` strategies and conflict-resolution commands)
+- references/comparing-branches.md (`git log`/`git diff`/`git merge-base` range syntax)
diff --git a/plugins/git/skills/git-branches/README.md b/plugins/git/skills/git-branches/README.md
index c31a1bd..b3626dd 100644
--- a/plugins/git/skills/git-branches/README.md
+++ b/plugins/git/skills/git-branches/README.md
@@ -1,6 +1,6 @@
 # git-branches
 
-Manage the full lifecycle of git branches — create, switch, delete, rename, and track feature/hotfix/release branches under GitHub Flow or Gitflow.
+Manage the full lifecycle of git branches — create, switch, delete, rename, track, merge, and compare feature/hotfix/release branches under GitHub Flow or Gitflow.
 
 ## What it does
 
@@ -12,11 +12,22 @@ This skill handles branch operations within the git workflow suite. It creates b
 /git-branches
 ```
 
-Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, or track. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
+Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, track, merge, or compare two branches. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
 
 ## Files
 
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
+| `references/branch-patterns.md` | Loaded when a branch's base, name prefix, or merge rule depends on GitHub Flow vs. Gitflow |
+| `references/branch-operations.md` | Loaded when running a create/switch/delete/rename/track/list action, or resolving `get-intent` |
+| `references/merging.md` | Loaded when merging one branch into another or resolving merge conflicts |
+| `references/comparing-branches.md` | Loaded when comparing two branches or finding where they diverged |
+| `references/orchestrator-contract.md` | Loaded when `git-orchestrate` or another calling agent supplies a structured request rather than prose |
 | `references/sources.md` | Research sources backing the branching/gitflow guidance |
+
+## Composition
+
+`git-orchestrate` calls this skill for the branch step of a multi-step workflow and parses its
+structured result. Cherry-pick and revert are `git-history`'s; commit authoring and rebase are
+`git-commits`'; branch operations against a Gitea-hosted remote are `gitea-branches`'.
diff --git a/plugins/git/skills/git-branches/SKILL.md b/plugins/git/skills/git-branches/SKILL.md
index cef3f0c..7a2e715 100644
--- a/plugins/git/skills/git-branches/SKILL.md
+++ b/plugins/git/skills/git-branches/SKILL.md
@@ -2,13 +2,11 @@
 name: git-branches
 
 description: >
-  Use when managing the full lifecycle of git branches: create feature/hotfix/release branches
-  (gitflow, GitHub Flow, or custom patterns from config), switch, delete, rename, and track branches,
-  or retrieve branch intent metadata. Handles branch protection safety checks and returns structured
-  results for agent composition. Use even if the user doesn't explicitly mention branch names — they
-  may be asking about "fixing something" or "shipping a feature", which implicitly requires branch
-  management. Do not use when the user needs only commit operations (use git-commits) or history
-  inspection (use git-history).
+  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`.
 
 metadata:
   category: git
@@ -21,92 +19,57 @@ metadata:
 
 ## Gotchas
 
-- **Branches are cheap; deletion is cheap but risky.** Deleting one requires checking if commits on it are reachable elsewhere; always confirm before deleting, as it may lose unmerged work.
-- **Uncommitted changes can block branch switches.** `git switch` aborts if local modifications conflict with the target branch. Offer to stash changes before switching when this happens, don't force a checkout.
-- **Tracking relationships matter for coordination.** Agents pushing on behalf of users should always set tracking (`-u origin <branch>`) so later pushes/pulls know the target. Without it, commands fail or target the wrong remote branch.
-- **Gitflow vs. GitHub Flow are not compatible.** Gitflow requires `develop` and `release/*` branches with `--no-ff` merges; GitHub Flow uses only `main` and feature branches with fast-forward. Read the repo's config or ask the orchestrator which pattern to use — don't guess.
-- **Naming collisions with tags.** A branch and tag can have the same name. Prefer `git switch` over `git checkout` for branch operations — verify which ref you're targeting with `git branch --list <name>` / `git tag --list <name>` if the name could be ambiguous, and disambiguate explicitly with `refs/heads/<name>` (branch) or `refs/tags/<name>` (tag) where a command accepts either.
-- **Never force-push `main` or `master`.** This is a hard refusal, not a confirmation gate — it applies even if the caller passes `confirm: true`. Deleting or renaming `main`/`master` in a way that would require a force-push to reconcile the remote (e.g. force-deleting and recreating it, or renaming it out from under in-flight work) must be rejected outright; explain why and suggest a non-destructive alternative (e.g. a new branch) instead of proceeding.
+- **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.
 
-## Branch Patterns
+## Step 1 — Determine the branching pattern
 
-Default to **GitHub Flow** (simpler, modern, CI/CD-friendly). Fall back to **Gitflow** only if the repo's config specifies it or the branch structure shows it in use (presence of `develop` or release branches).
+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.
 
-**GitHub Flow:**
-- Base: `main`
-- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
-- Merge: fast-forward when possible (preserves linear history)
-- Delete after merge
+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`.
 
-**Gitflow:**
-- Base: `main` (production) + `develop` (integration)
-- Feature branches: `feature/<feature-name>` (from `develop`)
-- Release branches: `release/X.Y.Z` (from `develop`, merged to `main` + `develop`)
-- Hotfix branches: `hotfix/X.Y.Z` (from `main`, merged to `main` + `develop`)
-- Merge: always use `--no-ff` to preserve branch structure
+## Step 2 — Dispatch on the action
 
-## Workflow
+| 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` |
 
-- [ ] **Determine pattern:** Check git plugin config (`.claude/plugins/git/config.json`, if present — see `config.example.json` in the plugin root for the expected shape) for `branching_pattern` (default: `github-flow`). If not set, inspect repo for `develop` branch or `release/*` branches; if present, assume Gitflow.
-- [ ] **Create branch:** Use `git switch -c <branch> <base>`. Base defaults to config's `base_branch` (usually `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`).
-- [ ] **Track remote:** If pushing, always use `git push -u origin <branch>` to establish tracking.
-- [ ] **Safety checks before destructive ops:** Before delete/force-push/rebase with history loss, check: (1) Is this branch tracking a remote? Warn if yes. (2) Are there unpushed commits? Warn if yes. (3) Does the orchestrator call include `confirm: true`? Fail if not. For humans, prompt interactively.
-- [ ] **Return structured results:** Always return branch operations as JSON or structured text: `{ "action": "create", "branch": "feature/x", "base": "main", "tracking": "origin/feature/x", "intent": "implement feature X" }`. Agents need to parse this for subsequent operations.
-- [ ] **Retrieve intent (`get-intent`):** Git has no native field for free-text branch metadata — this skill doesn't persist it. On `create`, the `intent` value is only ever returned in the structured result; the caller (orchestrator or agent) is responsible for storing it if it needs to be looked up later. On `get-intent`, either parse it back out of the branch name convention (`feature/<intent-slug>`) or return `{ "intent": null }` if the caller never persisted the original create-time value — don't fabricate an intent.
+Load only the file the action needs. A destructive action still passes Step 3 first.
 
-### Command mapping for each action
+## Step 3 — Gate destructive operations
 
-- **delete:** `git branch -d <branch>` refuses if the branch has unmerged commits — prefer this by default. `git branch -D <branch>` forces deletion and discards unmerged work; only use it after the safety checks above pass and `confirm: true` is set. For a remote branch: `git push origin --delete <branch>`.
-- **rename:** `git branch -m <old> <new>`.
-- **list:** `git branch` (local only), `git branch -a` (all local + remote-tracking), `git branch -r` (remote-tracking only), `git branch --merged`/`--no-merged` (filter by merge status into current branch).
-- **get-intent:** No git command — see Workflow step "Retrieve intent" for how this is resolved.
-- **track (existing branch):** `git branch --set-upstream-to=origin/<branch>` sets tracking without a push; `git branch -vv` shows tracking state for all local branches.
-- **switch (existing branch):** `git switch <branch>` — switches to an existing local branch (aborts on conflicting local changes, see Gotchas). `git switch -` switches back to the previously checked-out branch.
+Before any delete or force-delete that loses history:
 
-## Merging
+- [ ] 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.
 
-Scope: fast-forward/merge-commit mechanics and conflict resolution only. Rebase, cherry-pick, and revert belong to `git-history`.
+These gates are passable. The `main`/`master` refusal in Gotchas is not.
 
-- **Fast-forward:** `git merge <branch>` — advances the pointer with no merge commit if the target hasn't diverged.
-- **True merge:** `git merge --no-ff <branch>` — forces a merge commit even when fast-forward is possible; required by Gitflow on all supporting-branch merges.
-- **Squash merge:** `git merge --squash <branch>` stages the combined diff without committing; follow with a manual `git commit`.
-- **Octopus merge:** `git merge branch-a branch-b branch-c` merges more than two branches at once; fails outright on any conflict, so use sequential two-way merges if conflicts are expected.
+## Step 4 — Set tracking
 
-**Conflict resolution:** when Git can't auto-merge, it inserts conflict markers and stops. Run `git status` to find conflicted files, edit them to resolve the markers, then `git add <file>` and `git merge --continue`. `git merge --abort` reverts to the pre-merge state. `git mergetool` opens the configured merge tool; `git diff --diff-filter=U` shows only conflicted files.
+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.
 
-## Comparing Branches
+## Step 5 — Return a structured result
 
-- `git log main..feature` — commits in `feature` not in `main`.
-- `git log feature..main` — commits in `main` not in `feature` (reverse direction).
-- `git log --left-right main...feature` — both diverging sets (symmetric diff).
-- `git diff main...feature` — diff from the common ancestor to `feature`'s tip.
-- `git merge-base main feature` — print the common ancestor commit.
+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.
 
-## Integration with Orchestrator
-
-When invoked by `git-orchestrate`, accept requests in the form:
-```json
-{
-  "action": "create|switch|delete|rename|track|list|get-intent",
-  "branch": "<branch-name>",
-  "base": "<base-branch (optional, defaults to config)>",
-  "intent": "<human-readable intent (optional)>",
-  "confirm": "<true for destructive ops, omit for read ops>"
-}
-```
-
-Return results as:
 ```json
 {
   "success": true,
-  "action": "create|switch|...",
+  "action": "create|switch|delete|rename|track|list|get-intent",
   "branch": "<name>",
   "message": "descriptive message",
   "intent": "<intent if tracked>",
-  "tracking": "origin/<branch (if set)>",
+  "tracking": "origin/<branch, if set>",
   "error": "<error message if success=false>",
   "suggestion": "<recovery suggestion if applicable>"
 }
 ```
 
-If error is due to uncommitted changes, include `{ "suggestion": "stash changes and retry" }` so the orchestrator can offer automatic recovery.
+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.
diff --git a/plugins/git/skills/git-branches/references/branch-operations.md b/plugins/git/skills/git-branches/references/branch-operations.md
new file mode 100644
index 0000000..8c428cc
--- /dev/null
+++ b/plugins/git/skills/git-branches/references/branch-operations.md
@@ -0,0 +1,34 @@
+---
+source_keys:
+  - context7-git-htmldocs
+---
+
+# Per-action command mapping
+
+One command per action. Where two forms exist, the first is the default and the second the escape
+hatch.
+
+- **create** — `git switch -c <branch> <base>`. Base comes from the config's `base_branch`
+  (`main` under GitHub Flow, usually `develop` under Gitflow).
+- **switch** — `git switch <branch>` moves to an existing local branch; it aborts rather than
+  clobbering conflicting local changes. `git switch -` returns to the previous branch.
+- **delete (local)** — `git branch -d <branch>` refuses when the branch holds unmerged commits,
+  which is why it is the default. `git branch -D <branch>` forces the deletion and discards that
+  work — only after the destructive-operation gates pass and `confirm: true` is set.
+- **delete (remote)** — `git push origin --delete <branch>`.
+- **rename** — `git branch -m <old> <new>`.
+- **list** — `git branch` (local), `-a` (local plus remote-tracking), `-r` (remote-tracking only),
+  `--merged` / `--no-merged` (filter by merge status into the current branch).
+- **track** — `git branch --set-upstream-to=origin/<branch>` sets an upstream without pushing.
+  `git branch -vv` shows the tracking state of every local branch.
+
+## get-intent
+
+Git has no native field for free-text branch metadata, and this skill does not persist any. On
+`create`, the `intent` value is only returned in the structured result — the caller decides
+whether to store it.
+
+On `get-intent`, either parse the intent back out of the branch-name convention
+(`feature/<intent-slug>`) or return `{ "intent": null }` when the caller never persisted the
+create-time value. Never fabricate an intent: a downstream commit message built on a guessed
+intent is worse than one built on none.
diff --git a/plugins/git/skills/git-branches/references/branch-patterns.md b/plugins/git/skills/git-branches/references/branch-patterns.md
new file mode 100644
index 0000000..84e6680
--- /dev/null
+++ b/plugins/git/skills/git-branches/references/branch-patterns.md
@@ -0,0 +1,31 @@
+---
+source_keys:
+  - nvie-gitflow-post
+  - atlassian-gitflow-tutorial
+  - gitflow-cheatsheet
+---
+
+# Branch patterns
+
+Which pattern is in play decides the base branch, the branch name prefix, and whether merges are
+allowed to fast-forward. Default to GitHub Flow — simpler, and what CI/CD-oriented repos expect.
+Fall back to Gitflow only when the config says so or the repo already carries `develop` or
+`release/*` branches.
+
+## GitHub Flow
+
+- Base: `main`
+- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
+- Merge: fast-forward where possible, to keep history linear
+- Delete the branch after merge
+
+## Gitflow
+
+- Base: `main` (production) plus `develop` (integration)
+- Feature branches: `feature/<feature-name>`, cut from `develop`
+- Release branches: `release/X.Y.Z`, cut from `develop`, merged to both `main` and `develop`
+- Hotfix branches: `hotfix/X.Y.Z`, cut from `main`, merged to both `main` and `develop`
+- Merge: always `--no-ff`, so the branch structure survives in the history
+
+The two are not mixable. A `--no-ff` merge into a GitHub Flow repo leaves merge commits nobody
+expects; a fast-forward merge of a Gitflow release branch erases the release boundary.
diff --git a/plugins/git/skills/git-branches/references/comparing-branches.md b/plugins/git/skills/git-branches/references/comparing-branches.md
new file mode 100644
index 0000000..24c3214
--- /dev/null
+++ b/plugins/git/skills/git-branches/references/comparing-branches.md
@@ -0,0 +1,16 @@
+---
+source_keys:
+  - context7-git-htmldocs
+---
+
+# Comparing two branches
+
+The two-dot and three-dot forms mean different things and are easy to swap by accident — check the
+direction before reporting a result.
+
+- `git log main..feature` — commits on `feature` that are not on `main`.
+- `git log feature..main` — the reverse direction: commits on `main` not on `feature`.
+- `git log --left-right main...feature` — both diverging sets at once (symmetric difference).
+- `git diff main...feature` — the diff from the common ancestor to `feature`'s tip, which is what
+  a reviewer sees, rather than the diff between the two tips.
+- `git merge-base main feature` — print the common ancestor commit.
diff --git a/plugins/git/skills/git-branches/references/merging.md b/plugins/git/skills/git-branches/references/merging.md
new file mode 100644
index 0000000..0c8f245
--- /dev/null
+++ b/plugins/git/skills/git-branches/references/merging.md
@@ -0,0 +1,29 @@
+---
+source_keys:
+  - context7-git-htmldocs
+---
+
+# Merging one branch into another
+
+Scope is fast-forward and merge-commit mechanics plus conflict resolution. Rebase belongs to
+`git-commits`; cherry-pick and revert to `git-history`.
+
+- **Fast-forward** — `git merge <branch>` advances the pointer with no merge commit when the
+  target has not diverged.
+- **True merge** — `git merge --no-ff <branch>` forces a merge commit even when a fast-forward is
+  possible. Gitflow requires it on every supporting-branch merge.
+- **Squash merge** — `git merge --squash <branch>` stages the combined diff without committing.
+  Follow it with a `git commit`.
+- **Octopus merge** — `git merge branch-a branch-b branch-c` merges more than two branches at
+  once, but fails outright on any conflict. Use sequential two-way merges when conflicts are
+  likely.
+
+## Conflict resolution
+
+When Git cannot auto-merge it writes conflict markers and stops mid-merge. Run `git status` to
+list the conflicted files, edit each to resolve its markers, then `git add <file>` and
+`git merge --continue`.
+
+- `git merge --abort` restores the pre-merge state.
+- `git mergetool` opens the configured merge tool.
+- `git diff --diff-filter=U` shows only the still-conflicted files.
diff --git a/plugins/git/skills/git-branches/references/orchestrator-contract.md b/plugins/git/skills/git-branches/references/orchestrator-contract.md
new file mode 100644
index 0000000..7fceb33
--- /dev/null
+++ b/plugins/git/skills/git-branches/references/orchestrator-contract.md
@@ -0,0 +1,16 @@
+# Orchestrator request contract
+
+`git-orchestrate` and other calling agents send this shape. The result shape they parse back is in
+`SKILL.md` Step 5, because every run emits one.
+
+Request:
+
+```json
+{
+  "action": "create|switch|delete|rename|track|list|get-intent",
+  "branch": "<branch-name>",
+  "base": "<base branch, optional, defaults to config>",
+  "intent": "<human-readable intent, optional>",
+  "confirm": "<true for destructive ops, omit for read ops>"
+}
+```
diff --git a/plugins/git/skills/git-branches/references/sources.md b/plugins/git/skills/git-branches/references/sources.md
index d65c617..506756c 100644
--- a/plugins/git/skills/git-branches/references/sources.md
+++ b/plugins/git/skills/git-branches/references/sources.md
@@ -12,7 +12,8 @@
 - **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Branch Patterns — Gitflow vs. GitHub Flow structure and defaults)
+- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
+- references/branch-patterns.md (Gitflow vs. GitHub Flow structure, defaults, and why the two are not mixable)
 
 ## atlassian-gitflow-tutorial
 
@@ -23,7 +24,9 @@
 - **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Branch Patterns — Gitflow branch types, base/merge targets, `--no-ff` requirement)
+- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
+- references/branch-patterns.md (Gitflow branch types, base/merge targets, `--no-ff` requirement)
+- references/merging.md (`--no-ff` requirement on Gitflow supporting-branch merges)
 
 ## gitflow-cheatsheet
 
@@ -34,7 +37,7 @@
 - **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Branch Patterns — feature/release/hotfix naming conventions)
+- references/branch-patterns.md (feature/release/hotfix naming conventions)
 
 ## context7-git-htmldocs
 
@@ -45,4 +48,7 @@
 - **Research doc:** plugins/git/docs/research/docs/git/branching-merging.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Command mapping, Merging, Comparing Branches — `git switch`/`git branch`/`git merge`/`git log`/`git diff`/`git merge-base` command vocabulary and flags)
+- SKILL.md (Gotchas — `git switch` abort-on-conflict behaviour, branch/tag name ambiguity)
+- references/branch-operations.md (`git switch`/`git branch` command vocabulary and flags)
+- references/merging.md (`git merge` strategies and conflict-resolution commands)
+- references/comparing-branches.md (`git log`/`git diff`/`git merge-base` range syntax)