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
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a claude-codeWhat 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
mainbefore 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
mainbefore adding it to the merge queue. - Simulate the merge for
feature/loginbefore 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-code2Manually: put the files in place
~/.claude/skills/merge-queue-readiness/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/merge-queue-readiness/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a codex2Manually: put the files in place
.agents/skills/merge-queue-readiness/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a cursor2Manually: put the files in place
.cursor/skills/merge-queue-readiness/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .opencode/skills/merge-queue-readiness2Manually: put the files in place
.github/skills/merge-queue-readiness/SKILL.md1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a gemini-cli2Platform CLI
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .opencode/skills/merge-queue-readinessManually: put the files in place
.devin/skills/merge-queue-readiness/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill merge-queue-readiness -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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