Skip to content

jacob-balslev/skill-graph / marketplace/skills/merge-queue

merge-queue

Unverified

Use when serializing merges across multiple agent branches, resolving conflicts between agent outputs, or cleaning stale task branches. Covers atomic locking, idempotency checks, non-fast-forward handling, and worktree cleanup. Do NOT use for ordinary git operations outside an agent merge queue (use `version-control`).

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

FilePurpose
scripts/agent/merge-queue.shThe primary CLI for managing the queue.
agent-orchestration/logs/events.jsonlEmits merge_started and merge_completed events.

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.

PhaseActionTool
LockAcquire merge.lockscripts/agent/merge-queue.sh (merge subcommand)
VerifyCheck branch stateVerify branch is up to date with master and passes tests.
MergeNon-FF MergeMerge with --no-ff to preserve task history.
CleanupDelete branch/worktreeRemove the git worktree and the remote task branch.
ReleaseRelease merge.lockAllow the next agent in the queue to proceed.

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

FilePurpose
scripts/agent/merge-queue.shThe primary CLI for managing the queue.
.git/merge.lock(Virtual) The lock file preventing concurrent merges.
agent-orchestration/logs/events.jsonlEmits merge_started and merge_completed events.

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

Instead of this skillUseWhy
Ordinary branching, rebasing, committing, or tag managementversion-controlVersion-control owns general git history shape; this skill owns only serialized agent-branch integration.
Reviewing whether a branch's code is correct before mergecode-reviewCode-review owns behavioral approval; this skill owns the queue mechanics after a branch is ready.
Explaining what changed in a branch or patchdiff-analysisDiff-analysis owns patch interpretation; this skill owns merge ordering, locks, and cleanup.
Investigating a failed test or production bug after mergedebuggingDebugging owns failure localization; this skill only preserves merge order and records queue state.

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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 318kUpdated Claude CodeCodexUnverifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 318kUpdated Claude CodeCodexUnverifiedInstall