Skip to main content
skill CX Codex

merge-queue-readiness — Claude Code skill for merge queue checks

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.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a claude-code
Open on GitHub

What merge-queue-readiness 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.

What it helps with

  • 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 for the agent

  • 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.

How to install merge-queue-readiness

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a claude-code

2Manually: put the files in place

~/.claude/skills/merge-queue-readiness/SKILL.md

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

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

Questions about merge-queue-readiness

How do I install merge-queue-readiness in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a claude-code. The skill file is placed at ~/.claude/skills/merge-queue-readiness/SKILL.md.

What does merge-queue-readiness do?

It checks a PR together with the latest main before the PR enters a GitHub merge queue. Its preferred path uses /swarm ci-simulate; the instructions also cover a manual worktree flow.

Does the simulation reproduce all merge-group CI behavior?

No. It runs local checks and the full bun test suite, but does not reproduce CI quarantine or retry behavior. Treat it as a pre-merge signal, not a CI parity check.

Source text

SKILL.md · MIT
---
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

Integration tests that pass on the PR branch may fail in merge-group context due to test interactions exposed by the merged result.

## Automation
`/swarm ci-simulate` automates the merge-result worktree, merge, command run,
worktree removal, and metadata prune. Use the manual protocol only when the
command is unavailable or the repo needs bespoke setup.

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

SKILL.md skills catalog →

From the same set121

The whole set →
swarm-resume swarm-resume is a Claude Code skill that restores swarm plan state and clears stale git branches to resume work on an approved plan. CX Codex +1 ★ 539repo stars ci-failure-batching ci-failure-batching collects failed PR checks before planning fixes. Use it to group related CI problems and avoid a separate push cycle for each one. CX Codex +1 ★ 539repo stars mock-to-internals-migration mock-to-internals-migration is a Claude Code skill for moving mocks from Vitest to Bun and checking the _internals seam. It activates for mock migrations and related test-structure changes. CX Codex +1 ★ 539repo stars gate-attribution gate-attribution assigns reviewer and test engineer verdicts to individual plan tasks during swarm batch runs. Activates when dispatches return multi-task rows. CX Codex +1 ★ 539repo stars issue-tracer issue-tracer — a subagent that carries a GitHub issue from report to fix plan. It collects evidence, pinpoints the root cause, and touches no code until you approve the plan. CX Codex +1 ★ 539repo stars qa-reviewer The qa-reviewer subagent reviews pull requests before merge, checking logic, security, error handling, style, and test coverage without changing code. CX Codex +1 ★ 539repo stars durable-session-state The durable-session-state skill keeps task plans, decisions, validation results, and review verdicts in project files. Use it to pick up long-running work after context compaction or a handoff. CX Codex +1 ★ 539repo stars swarm-pr-feedback swarm-pr-feedback — a skill that works through PR feedback you already have: review notes, GitHub threads, failing checks, conflicts. Everything is verified against the code before a single edit lands. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open