Skip to main content
skill CX Codex

merge-review — Claude Code skill: what it does, how to install

merge-review scans the fleet worktree merge queue, flags files touched by more than one branch, and suggests a merge order before anything lands in main.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What merge-review does

The skill reads .planning/telemetry/merge-check-queue.jsonl, the file worktree-remove.js populates once a fleet agent finishes a branch. For every entry it pulls git diff main..{branch} and compares the changed file lists across branches pairwise, sorting shared files into three buckets: both sides adding code, both sides touching the same section, or one side removing what the other added.

Each branch gets a risk label of low, medium or high plus a recommendation — merge, review-first, or resolve-conflict. If conflicts form a loop between three or more branches, the skill refuses to invent a merge order and hands the decision back to the user instead. It never runs the merge itself; the only write actions are updating queue statuses and, once a branch is confirmed merged, removing its worktree with git worktree remove.

Run it as /merge-review to process the whole queue, or /merge-review {branch} to check one branch. An empty merge-check-queue.jsonl just gets a note that there's nothing pending.

What it helps with

  • review a fleet merge queue before accepting branches into main
  • spot files edited by two branches at once
  • get a risk rating per pending branch
  • work out a safe merge order across dependent branches
  • clear out worktrees after a branch is merged

Example prompts for the agent

  • Check the merge queue before merging the fleet branches
  • Review branch fleet/task-abc for conflicts
  • Work out a merge order for everything pending in fleet

How to install merge-review

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill merge-review -a claude-code

3Manually: put the files in place

~/.claude/skills/merge-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/merge-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about merge-review

How do I install merge-review in Claude Code?

Through the marketplace: run /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local. Alternatively, install it alone with npx skills add SethGammon/Citadel --skill merge-review -a claude-code.

What does merge-review do?

It reads the fleet worktree merge queue, diffs each pending branch against main, and checks for files edited by more than one branch. It then rates each branch's risk and recommends a merge order.

What happens if branches conflict in a loop?

If branch A conflicts with B, B with C, and C with A, the skill lists every conflict pair but does not propose a merge order, leaving the call to the user.

Source text

SKILL.md · MIT
---
name: merge-review
license: MIT
description: >-
  Reviews pending fleet worktree merges before they're accepted. Reads the
  merge-check queue, detects file-level conflicts between branches, proposes a
  safe merge order, and surfaces reconciliation plans for overlapping changes.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - merge review
  - check merges
  - any conflicts
  - fleet conflicts
  - pending branches
  - safe to merge
last-updated: 2026-03-26
---

# /merge-review — Fleet Merge Arbitration

## Orientation

**Use when:** reviewing pending fleet worktree merges before accepting them into the main branch.
**Don't use when:** reviewing general code quality (use /review); checking CI status before merging (use /pr-watch).

## When to Route Here

- "check merges"
- "any conflicts"
- "what do the fleet agents want to merge"
- "review the pending branches"
- "is it safe to merge fleet output"
- "arbitrate the worktrees"
- worktree-remove.js has queued items and the user wants to process them

## Invocation Forms

```
/merge-review              # Process the full queue
/merge-review {branch}     # Review a specific branch only
```

## Protocol

### Step 1: Read the Queue

Read `.planning/telemetry/merge-check-queue.jsonl`. Each line is a JSON object:
```json
{"branch": "fleet/task-abc", "worktree": "/path/to/worktree", "queuedAt": "ISO"}
```

If the file doesn't exist or is empty:
> "No pending merge reviews. Fleet agents haven't completed any worktrees recently."
Stop here.

If invoked with a specific branch (`/merge-review {branch}`): filter to that branch only.

### Step 2: For Each Branch — Gather Diff Data

Run `git diff main..{branch} --name-only`, `--stat`, and `git branch --list {branch}`.

If the branch no longer exists: mark `status: "merged"`, note "likely already merged. Skipped.", continue.

### Step 3: Detect Overlapping Files

Compare changed file sets pairwise. For each pair sharing files, read `git diff main..{branch} -- {file}` for both and classify:
- **Additive**: both add to the file (low risk, likely auto-mergeable)
- **Overlapping edits**: both modify the same function/section (medium risk)
- **Contradictory**: one adds, the other removes the same code (high risk)

### Step 4: Assess Risk Per Branch

For each branch:
- **low** — no overlapping files with other branches
- **medium** — overlaps exist but changes appear additive or in different sections
- **high** — overlaps in the same function, class, or closely coupled section

### Step 5: Propose Merge Order

Order branches: fewest conflicts first, most conflicts last.

If circular dependencies exist (A conflicts with B, B conflicts with C, C conflicts
with A): escalate to the user — do not propose an impossible order.

### Step 6: Output the Report

```
## Merge Review: {N} branch(es) pending

### Branch: {name}
Files changed: {N}
Overlap with other branches: {branch-X} ({file-list}) | none
Risk: low | medium | high
Recommendation: merge | review-first | resolve-conflict

---
[repeat for each branch]
---

### Conflicts Detected

{branch-A} and {branch-B} both modified:
  - {file}: {brief description — e.g., "A adds export, B removes same export"}
Recommended resolution: {which change to keep, or how to combine them}

[repeat for each conflict pair]

### Proposed Merge Order

1. {branch} — no conflicts, safe to merge first
2. {branch} — depends on #1; review {file} after merging #1
3. {branch} — manual conflict resolution needed in {file} before merging

### Summary
Branches ready to merge: {N}
Branches needing review: {N}
Branches with hard conflicts: {N}
```

If all branches are conflict-free:
```
## Merge Review: {N} branch(es) pending — No conflicts detected

All branches can be merged in any order. Recommended order (by change size, smallest first):
1. {branch} — {N} files
2. {branch} — {N} files
```

### Step 7: Update the Queue

After producing the report, mark reviewed items in the queue:
- Branches still needing work: `status: "reviewed"`, add `reviewedAt` timestamp
- Branches no longer existing: `status: "merged"` (already handled in Step 2)

Write the updated queue back to `.planning/telemetry/merge-check-queue.jsonl`.

### Step 8: Cleanup Merged Worktrees

Run `git worktree list --porcelain`. For each non-main worktree: check `git branch --merged HEAD`. If merged and clean: run `git worktree remove "{path}" --force` and `git branch -d "{branch}"`. No user confirmation needed. Report count: "Cleaned up {N} merged worktree(s): {branch-names}".

---

## Fringe Cases

**Queue empty:** Output "No pending merge reviews." and stop.

**Branch no longer exists:** Remove from queue, note, continue.

**Branch not in queue:** Note "not in the merge queue" and suggest `/merge-review` to see all.

**All branches conflict (circular):** List all conflicts; do not propose an order; escalate to user.

**One branch pending:** Skip conflict detection; output single-branch review (files, stat, recommendation).

**Large diff (>500 lines):** Summarize changed areas; link to `git diff` command for details.

**Worktree path missing but branch exists:** Proceed with git diff using branch name; worktree existence not required.

---

## Integration Points

- **worktree-remove.js** — queues items to `.planning/telemetry/merge-check-queue.jsonl` when a fleet worktree completes
- **fleet skill** — run `/merge-review` after fleet agents complete, before merging to main
- **session-end.js** — may surface a reminder if the merge queue has items at session end

## Contextual Gates

**Disclosure:** "Reviewing pending fleet worktree merges. Read-only — no changes applied."
**Reversibility:** green — read-only review; no files merged or modified
**Trust gates:**
- Any: view merge review report and recommendations

## Quality Gates

- Never merge branches — only analyze and recommend
- Always update the queue after processing (mark reviewed/merged)
- Always provide a concrete recommendation for each branch (merge / review-first / resolve-conflict)
- If a branch was already merged, clean it from the queue without error
- If all conflicts are circular/unresolvable, escalate clearly rather than proposing an impossible order

## Exit Protocol

/merge-review does not produce a HANDOFF block. It outputs the merge report (Step 6) and then
waits for the next user command.

After the report, suggest next actions based on what was found:
- If all branches are safe: "All clear. Merge in the order above."
- If conflicts exist: "Resolve the flagged conflicts before merging. Run `/merge-review` again after resolving."
- If queue is empty: "Queue is empty. Nothing to review."

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Git and GitHub →

From the same set55

The whole set →
design This skill builds a design manifest from a project’s styles or your preferences. A post-edit hook flags mismatches in edited files. CX Codex +1 ★ 937repo stars live-preview live-preview takes screenshots of components during construction, not after completion. Catches layout regressions and invisible blocks before they propagate. CX Codex +1 ★ 937repo stars architect architect turns a PRD or task outline into an implementation plan with file trees, data models, and phased build steps. CX Codex +1 ★ 937repo stars cost See token usage and costs for sessions, campaigns, and time periods. Use it to check where spend is going and how quickly it is rising. CX Codex +1 ★ 937repo stars deploy-steward deploy-steward serializes PR merges into main, tracks CI gates, triggers deploys, and files repair tasks when checks fail. CX Codex +1 ★ 937repo stars prd prd turns an app idea into a structured product requirements document, asking about decisions that affect its shape. Use it before handing a project plan to Archon. CX Codex +1 ★ 937repo stars organize organize — a skill that audits and corrects project structure: checks file placement, moves files to match conventions, updates imports. Leaves code inside files untouched. CX Codex +1 ★ 937repo stars create-app create-app — a skill for Claude Code and Codex that builds applications from a single prompt. It routes work across five distinct tiers, passing through PRD, architecture, and verified execution phases. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open