Serially land a batch of green PRs through the forge's own merge API — migration-aware ordering, update-branch for stale PRs, wait for the post-merge workflows between merges, then run /worktree-cleanup. Invoke as `/merge-train` (discover all green PRs) or `/merge-train <PR#> [<PR#>…]` (explicit batch). Operator-invoked only; complements /pr-iterate, which never merges.
91%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Parallel worktree agents produce batches of pull requests that each go green in isolation. Landing them is where the manual toil and the risk concentrate: the operator clicks merge N times, each merge instantly makes the surviving PRs stale against the base branch, and — in most projects — a merge triggers deployment or migration workflows against a shared environment, so order matters.
This skill is the operator-side merge train: it merges a batch one PR at a time through the forge's own API, re-validating between merges.
It does not weaken shared invariant §7. That invariant says the merge action
is a human decision with a human's name on it, and /pr-iterate's hard rule
"you never merge" still stands unchanged. /merge-train is the human decision,
made explicitly, for a named batch, at a moment the operator chose — it is
delegation of the mechanics after the decision, not of the decision. An agent
never starts a train on its own initiative.
Everything stays inside branch protection: the merge and update-branch calls produce exactly what the UI button produces. Nothing is bypassed, rebased, or force-pushed.
constitution/local-workflow.md says it is,
and the reason it says so usually involves commit signing — read the article
before reaching for a different flag. If the operator explicitly asks for a
squash on a given PR, its title must satisfy Conventional Commits, because
the title becomes the commit subject.If the operator gave PR numbers, use exactly those (still verify each is green — refuse red ones with a one-line reason). Otherwise discover:
gh pr list --state open --json number,title,isDraft,reviewDecision,mergeable,mergeStateStatus,headRefName
gh pr checks <N> # per candidate — every required check green?Drop: drafts, reviewDecision == "CHANGES_REQUESTED", any red or pending
required check, mergeable == "CONFLICTING" (send those to /pr-iterate
instead).
gh pr view <N> --json files --jq '.files[].path'scripts/guards.config.sh's BEHAVIOR_DELTA_SURFACES is where this
repo lists its contract artifacts — the persistence and schema surfaces there
are the ones to look for. Landing them early means the siblings get updated
against the new state instead of colliding at the end.Before the first merge, show the ordered list (PR, title, why it's positioned there, which carry the ordered artifacts). In auto-discovery mode, wait for the operator's go-ahead. When the operator passed explicit PR numbers, that message is the go-ahead — proceed.
# a. Stale against the base branch? Update through the forge.
gh pr view "$PR" --json mergeStateStatus --jq .mergeStateStatus # BEHIND?
gh api -X PUT "repos/{owner}/{repo}/pulls/$PR/update-branch"
# b. Wait for checks to re-run and go green.
gh pr checks "$PR" --watch
# c. Merge, with the method the local workflow article mandates.
gh pr merge "$PR" --merge
# d. Wait for the post-merge workflows before the next merge — the train should
# observe each result, not outrun it, even when their concurrency groups
# would queue anyway.
gh run list --branch <base> --limit 5 --json name,status,conclusion,databaseId
gh run watch <databaseId>If checks go red after update-branch (4b): that is a real cross-PR
interaction surfaced early — skip the PR, record it as a /pr-iterate
candidate, continue the train.
If the merge itself is rejected: re-read state; if it is not a transient
(e.g. checks re-queued), stop and report.
If a post-merge workflow fails (4d): hard rule 6 — stop the train, escalate
with the run log.
Run /worktree-cleanup — the merged PRs' worktrees are now prunable, and
the root checkout's base branch should fast-forward to include the batch.
If the batch bumped VERSION, the train is not over at cleanup: cut and push
the release tag (git tag -a v<version> <merge sha> && git push origin v<version>) — an untagged bump is a release no consumer can reach, and a
repo whose CI enforces release integrity (the kit's own does, in its
self-host suite's F3) stays red on main by design until the tag exists.
Tagging is part of landing the bump, and it carries the operator's name
exactly like the merge did.
merge-train — <date>
Plan: #A (schema) -> #B -> #C
Landed: #A <merge sha> · #B <merge sha>
Skipped: #C — checks went red after update-branch (-> /pr-iterate #C)
base: <sha before> -> <sha after> · post-merge workflows ✅
Cleanup: <worktrees removed> removed · <kept> keptconstitution/local-workflow.md — the merge method, the rejected one and why,
and the required checks. That article is the authority for step 4c.docs/adr/INDEX.md — if the merge method was a recorded decision, cite its
number when you explain an ordering or a refusal./pr-iterate — drives a PR to green; never merges./worktree-cleanup — the final step of every train.agranado2k/tic-tac-toe-with-agentic-sdlc
931d5f3
Also appears in
since Nov 19, 2026
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.