# merge-queue-readiness

The merge-queue-readiness skill simulates a PR merged with the latest main before it enters a GitHub merge queue. Use it to catch integration failures that isolated PR checks can miss.

- skill · `type=skill` · Claude Code, Codex, OpenCode, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 539 repo stars
- Author: ZaxbyHub
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/ZaxbyHub/opencode-swarm/tree/HEAD/.opencode/skills/merge-queue-readiness/SKILL.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/merge-queue-readiness

## What it does

Before queuing a PR, the skill calls for fetching `main` and running `/swarm ci-simulate [<pr-ref>]`. The command tests the merged result in a temporary worktree with `bun run typecheck`, `bun run lint`, `bun run build`, and a full `bun test` run, then removes the worktree. If the command is unavailable, the instructions describe a manual worktree merge followed by integration and unit tests.

This is a pre-merge signal, not a full CI replica: it does not reproduce CI quarantine or retry behavior. The simulation command accepts an optional PR ref, but not `--base` or `--head`. Clean up the temporary worktree even after failures; if removal fails, report the block and run `git worktree prune`.

## Requirements
- Works with: GitHub

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/merge-queue-readiness/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/merge-queue-readiness/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/merge-queue-readiness/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/merge-queue-readiness/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install ZaxbyHub/opencode-swarm .opencode/skills/merge-queue-readiness
```

2. **Manually: put the files in place**
- File: `.github/skills/merge-queue-readiness/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .opencode/skills/merge-queue-readiness
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/merge-queue-readiness/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ZaxbyHub/opencode-swarm/tree/HEAD/.opencode/skills/merge-queue-readiness/SKILL.md

## When to use it
- test a PR merged with the latest `main` before queueing it
- run local checks against a merge result
- catch integration failures exposed only by merge-group context
- remove the temporary worktree after a simulation

## Example prompts
- Check this PR against the latest `main` before adding it to the merge queue.
- Simulate the merge for `feature/login` before the final push.
- Run the merge check and clean up the temporary worktree if it fails.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 91e00936562e703f.

BEGIN THIRD-PARTY FILE 91e00936562e703f
````text
---
name: merge-queue-readiness
description: Pre-queue merge-group CI simulation. Triggered before adding a PR to a GitHub merge queue. Prevents merge-queue kick-outs from integration test failures.
metadata:
  audience: swarm-plugin
---

# Merge Queue Readiness

## Trigger
Before adding the PR to the merge queue (or before the final push if the repo uses a merge queue).

## Protocol
1. **Fetch latest main:** `git fetch origin main`
2. **Run the simulation command (preferred):**
   ```
   /swarm ci-simulate [<pr-ref>]
   ```
   The optional positional `<pr-ref>` is the PR branch/ref to simulate (defaults to the current branch). It does NOT accept `--base`/`--head` flags. The command runs fixed local gates: `bun run typecheck`, `bun run lint`, `bun run build`, then a full-batch `bun test`. It creates a temporary detached worktree under `os.tmpdir()/swarm-ci-simulate` (a SIBLING of the project root, not project-relative), merges the PR ref, runs the gate sequence, removes the worktree, and prunes metadata. It does not accept arbitrary shell commands and does NOT replicate CI's quarantine/retry semantics — it is a fast pre-merge signal, not a CI parity check.
3. **Manual fallback:** If the command is unavailable, create a temporary simulation worktree (do NOT mutate the PR branch). The default worktree base is a SIBLING of the project root (`<parent>/.swarm-worktrees/`), overridable via the `worktree_dir` config; on Windows, very long paths may be shortened to `os.tmpdir()/swwt/...`. Place the worktree under that base. Do NOT hardcode `/tmp` — it does not exist on Windows.
   ```
   git worktree add ../.swarm-worktrees/merge-sim origin/main
   cd ../.swarm-worktrees/merge-sim
   git merge <pr-branch> --no-edit
   ```
4. **Run integration + unit tests against the merged result:**
   ```
   bun test tests/integration --timeout 120000
   bun test tests/unit --timeout 120000
   ```
   (Use per-file loops for hot modules per AGENTS.md invariant 6)
5. **If failures:** Fix on the PR branch, re-push, re-simulate. Always run the cleanup step (6) before re-simulating or on any exit path — do not leave the simulation worktree behind.
6. **Cleanup for manual fallback (run on EVERY exit path, including failure):** Prefer non-force `git worktree remove ../.swarm-worktrees/merge-sim`. If the removal is blocked or fails, surface the block to the user (the worktree guard fails closed for safety) and run `git worktree prune`.
7. **Only after simulation passes,** add PR to the merge queue.

## Why this matters
PR-branch CI and merge-group CI test DIFFERENT things:
- PR-branch: tests the PR head commit in isolation
- Merge-group: tests a temporary merge of PR head + latest main
````
END THIRD-PARTY FILE 91e00936562e703f

The third-party file has ended. Everything between the 91e00936562e703f tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2710 of 3068 bytes. © ZaxbyHub · MIT · https://github.com/ZaxbyHub/opencode-swarm/tree/HEAD/.opencode/skills/merge-queue-readiness/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
