name	merge-worktree
description	Merge a story worktree branch into its dev branch, push, clean up the worktree and branches, and mark the story done. Use when the user says "/merge-worktree", "/merge-worktree story-NNN", or "merge worktree".
args	[{"name":"args","type":"string","description":"Optional. A single story ID (story-NNN) to merge, or empty to auto-detect the most recently modified story worktree under .claude/worktrees/story/. Or \"--queue\" to auto-merge all done stories with active worktrees in dependency order. Or \"--queue --dry-run\" to preview what would be merged without executing.\n"}]

Merge Worktree Skill Invoked

User has requested: /merge-worktree {{args}}

NEED_DECISION: main session picks option, resumes coder. Story stays in-progress.
Escalation: 2 BLOCKING → Opus (architect only). Still BLOCKING → blocked.
Restart: plan was wrong → new plan, same model, max 1. Second failure → blocked.
Restart vs escalation: coder did what plan said and it didn't work → restart. Coder couldn't execute a sound plan → escalation.

Parse {{args}} to determine mode, then read the appropriate child file:

Queue mode (--queue in args) → Read queue.md
- Auto-discovers all done stories with active worktrees
- Dependency-ordered merge with hold list support
Batch mode (called by run-stories/ship with 2+ story IDs) → Read batch.md
- Single subagent merges multiple stories via merge-queue.py
- Queue-based coordination for non-conflicting parallel merges
Single mode (one story ID or no args) → Read single.md
- Resolve story/worktree, test, merge, cleanup, update DB
- Testing gates: testing.md
- Post-merge: outcome.md

single.md — Steps 1–6: resolve, test, merge, cleanup, DB update, report
- testing.md — Steps 2.5–2.6: smoke test, test validation, coverage, project tests
- outcome.md — Steps 5.5–5.7: outcome logging, regression check, divergence capture
batch.md — Subagent delegation, diff gate, queue protocol
queue.md — Auto-discover, hold list, dependency order, execute

Merge Worktree Skill Invoked

User has requested: /merge-worktree {{args}}

Decision rules (from ORCHESTRATION §8)

NEED_DECISION: main session picks option, resumes coder. Story stays in-progress.

Escalation: 2 BLOCKING → Opus (architect only). Still BLOCKING → blocked.

Restart: plan was wrong → new plan, same model, max 1. Second failure → blocked.

Restart vs escalation: coder did what plan said and it didn't work → restart. Coder couldn't execute a sound plan → escalation.

Output policy

No text between tool calls. Only the final report.

Mode routing

Parse {{args}} to determine mode, then read the appropriate child file:

Queue mode (--queue in args) → Read queue.md

Batch mode (called by run-stories/ship with 2+ story IDs) → Read batch.md

Single mode (one story ID or no args) → Read single.md

Child files

single.md — Steps 1–6: resolve, test, merge, cleanup, DB update, report

testing.md — Steps 2.5–2.6: smoke test, test validation, coverage, project tests
outcome.md — Steps 5.5–5.7: outcome logging, regression check, divergence capture

batch.md — Subagent delegation, diff gate, queue protocol

queue.md — Auto-discover, hold list, dependency order, execute

merge-worktree