# Merge

> Close out a feature branch or cs task worktree - run the repo's gates, merge --no-ff, re-run gates on the merged result, clean up. Invoke when the user asks to merge a branch or worktree, or to close out a finished feature.

- Skill: `hex/merge` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hex/merge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hex/merge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: hex (https://skillmd.com/u/hex)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hex/merge

---


Merging is a ritual, not a git command: gates before, merge, gates after,
cleanup only when everything is green. This skill closes out work that is
already reviewed to the user's standard — it is the mechanical closer, not
a quality gate or a review.

## Prerequisites

- A clean tree. If `git status --porcelain` shows uncommitted changes,
  offer to commit them first; if the user declines, stop. Never merge
  over an uncommitted tree.
- A context (below). If neither applies — already on the default branch
  with nothing to merge — say so and stop.

## Detect the context

1. **cs task worktree**: the workspace is a cs session named
   `<base>@<task>`, or `git rev-parse --git-dir` differs from
   `git rev-parse --git-common-dir` inside a cs-managed worktree
   session. The merge verb here is `cs <base> --merge <task>` — it
   fuses the session records, merges the branch, and removes the
   worktree. This skill wraps it with gates.
2. **Feature branch**: an ordinary checkout on a non-default branch.
   The target is the branch it forked from — usually the repo's
   default branch (`git merge-base` confirms ancestry); ask the user
   when the target is ambiguous.
3. **Base session closing out a named feature**: the workspace is the
   base session and the invocation named a feature (`/merge fix-auth`),
   which is what `cs <base> -finish <feature>` arms from the picker.
   The target is `<base>@<feature>`; run the preflight gates inside
   that worktree, then `cs <base> --merge <feature>` from here, then
   the post-merge gates in this checkout. Do not change directory into
   the feature session to merge — it cannot remove its own working
   directory.

When this skill is invoked with an argument, the argument is the
feature name and context 3 applies. With no argument, detect the
context from the workspace.

## Discover the gates

Project instructions govern absolutely. Read the project's instruction
files — CLAUDE.md and anything it imports, CONTRIBUTING.md, and the
README's development section — for build steps, test commands,
generated artifacts, and deploy steps. A repo that generates a file
from source fragments needs its build run BEFORE tests and the
generated file committed with the branch, exactly as its instructions
say.

Without instructions, use the first conventional entry point that
exists: `tests/run_all.sh`, a `Makefile` test target, `package.json`
scripts.test, `cargo test`, `go test ./...`, `pytest`. If none exists,
ask the user once for the gate command and use it for the rest of the
conversation.

## The ritual

1. **Preflight gates** on the branch (worktree context: inside the
   worktree): the build step first if the repo has one, then the full
   test gate. Everything green before anything merges.
2. **Merge.**
   - Feature branch: `git checkout <target>`, then
     `git merge --no-ff <branch>` with a merge message summarizing the
     feature.
   - Task worktree: `cs <base> --merge <task>` merges the branch, fuses
     the session records, and removes the worktree. Once the feature
     session is closed, run the verb from the base session — it merges
     while holding its own live lock, so no hand-off is needed. It still
     refuses two ways: running from inside the feature session, which
     cannot remove its own live working directory (close it and run from
     the base); and any other live base or feature lock. Run the
     post-merge gates in the base session afterward.
3. **Gates again on the merged result** (worktree context: in the base
   session checkout). A merge that was green on the branch can still
   break the target.
4. **Cleanup**: delete the merged feature branch with `git branch -d` —
   but not until the post-merge gates are green. The worktree verb
   already cleaned up its own.

## When a gate fails

Diagnose it — that is why this is a skill and not a script. Find the
root cause per the project's debugging rules, fix forward on the
branch, and re-run the ritual from the top. A post-merge failure leaves
the merge commit in place: report it with the failing output and let
the user decide between fix-forward and revert. Never bypass, skip, or
weaken a gate to make a merge pass.

## After a green merge — offers, not actions

- If the project instructions document a deploy step, offer to run it
  (one question). Never deploy unprompted.
- In a cs session, offer `/checkpoint <feature>-merged`.

## Never

- Never push, to any remote — publishing is the user's decision, made
  separately.
- Never merge over uncommitted changes.
- Never delete a branch until the post-merge gates are green, and never
  use `git branch -D` on unmerged work.
- Never bypass a failing gate or force a merge.