Merge Queue

Merge Queue (Serialized Commit Control)

Concept of the skill

Use when serializing merges across multiple agent branches, resolving conflicts between agent outputs, or cleaning stale task branches.

Domain Context

What is this skill? This skill manages the serialized merge queue for agent branches. Covers atomic locking, idempotency checks, non-fast-forward merges, and worktree cleanup. Use when merging multiple agent tasks to master, resolving merge conflicts between agents, or cleaning up stale task branches. Do NOT use for standard git operations (use version-control).

Coverage

This skill manages the serialized merge queue for agent branches. The sections below contain the detailed rules, examples, and boundaries for using this skill correctly.

Key Files

Workflow

Use the ordered phases, checklists, and guardrails in the sections below as the canonical workflow for this skill. When multiple subsections describe steps, follow them in the order presented.

Queue Coverage

Atomic merge locking (merge.lock), branch idempotency checks, --no-ff (non-fast-forward) merge policy, automated worktree and branch cleanup, and event emission.

The "Gatekeeper" for the master branch. Prevents agents from causing race conditions during the final commit phase.

Philosophy of the skill

Merge queues exist to protect the main branch from concurrent merge failures. When multiple agents modify overlapping code simultaneously, merging them independently creates a false sense of safety — each agent's work may pass CI alone but break when combined. A merge queue serializes merges, ensuring every commit is tested against the current state of main plus all queued predecessors before pushing. The result is a main branch that is always in a known-good state, with clear task-level history preserved via non-fast-forward commits. This prevents both silent conflicts (where two agents unwittingly overwrite each other's work) and long debugging sessions trying to untangle which merge introduced a regression.

1. The Merge Protocol

To prevent merge conflicts and history pollution, all agents must submit their finished tasks to the merge queue.

2. Clever Features (Stolen from Merge Queue)

• Atomic Lock: Only one agent can merge at a time, ensuring that master is always in a known good state.
• Idempotency: If a merge fails halfway, the queue can be resumed without creating duplicate commits.
• Automated Cleanup: Once a merge is successful, the merge-queue.sh automatically deletes the task-specific worktree (/tmp/worktrees/SH-XXXX) to save disk space.

3. Managing the Queue

• Submit Merge: bash scripts/agent/merge-queue.sh merge --task SH-XXXX
• Check Status: bash scripts/agent/merge-queue.sh status
• Cleanup Manually: bash scripts/agent/merge-queue.sh cleanup --task SH-XXXX

4. Key Files

5. Verification Protocol

• Lock Test: Try to start two merges simultaneously; the second should wait or fail.
• Master Integrity: Verify that master only contains --no-ff merge commits for agent tasks.
• Disk Space: Verify that the /tmp/worktrees/ directory is pruned after successful merges.

Do NOT Use When

Verification

After applying this skill, verify:

• Changes follow the patterns documented above
• No regressions in affected functionality

Skill Graph context

Classification

• Subject: software-engineering-method
• Public: true
• Domain: engineering/git
• Scope: Teaches serialized merge control for parallel agent branches: exclusive merge locking, idempotent retry, branch freshness checks, non-fast-forward merge discipline, stale worktree cleanup, and queue event recording. Project-oriented but portable to any multi-agent git workflow. Excludes ordinary single-branch git operations and commit-message/history policy outside a shared merge queue.

When to use

• Triggers: merge-queue, agent-merge

Related skills

• Related: version-control

Keywords

• merge queue, atomic lock, idempotency, no-ff merge, worktree cleanup, agent branch, master merge