About

Imported from jacob-balslev/skill-graph (marketplace/skills/merge-queue/SKILL.md). Install upstream with npx skills add jacob-balslev/skill-graph --skill merge-queue. Copyright stays with the author (MIT).

Merge Queue (Serialized Commit Control)

Name: merge-queue
Author: jacob-balslev

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

File	Purpose
`scripts/agent/merge-queue.sh`	The primary CLI for managing the queue.
`agent-orchestration/logs/events.jsonl`	Emits `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.

Phase	Action	Tool
Lock	Acquire `merge.lock`	`scripts/agent/merge-queue.sh` (merge subcommand)
Verify	Check branch state	Verify branch is up to date with master and passes tests.
Merge	Non-FF Merge	Merge with `--no-ff` to preserve task history.
Cleanup	Delete branch/worktree	Remove the git worktree and the remote task branch.
Release	Release `merge.lock`	Allow 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

File	Purpose
`scripts/agent/merge-queue.sh`	The primary CLI for managing the queue.
`.git/merge.lock`	(Virtual) The lock file preventing concurrent merges.
`agent-orchestration/logs/events.jsonl`	Emits `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 skill	Use	Why
Ordinary branching, rebasing, committing, or tag management	`version-control`	Version-control owns general git history shape; this skill owns only serialized agent-branch integration.
Reviewing whether a branch's code is correct before merge	`code-review`	Code-review owns behavioral approval; this skill owns the queue mechanics after a branch is ready.
Explaining what changed in a branch or patch	`diff-analysis`	Diff-analysis owns patch interpretation; this skill owns merge ordering, locks, and cleanup.
Investigating a failed test or production bug after merge	`debugging`	Debugging 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

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jacob-balslev-skill-graph-merge-queue/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jacob-balslev-skill-graph-merge-queue.ocm.jsonjson

{
  "ocm": "1",
  "id": "jacob-balslev-skill-graph-merge-queue",
  "kind": "skill",
  "name": "merge-queue",
  "description": "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`).",
  "publisher": "jacob-balslev",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "merge",
      "queue",
      "atomic",
      "lock",
      "idempotency",
      "no-ff",
      "worktree",
      "cleanup",
      "agent"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "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`)."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/jacob-balslev/skill-graph",
      "path": "marketplace/skills/merge-queue/SKILL.md",
      "ref": "ee6f58e2f4adb9a9ac8fb43556e4c5f633a8361c",
      "url": "https://github.com/jacob-balslev/skill-graph/blob/ee6f58e2f4adb9a9ac8fb43556e4c5f633a8361c/marketplace/skills/merge-queue/SKILL.md",
      "key": "jacob-balslev/skill-graph/marketplace/skills/merge-queue/SKILL.md"
    },
    "compatibility": "Markdown, Git, agent-skill runtimes",
    "allowed_tools": [
      "Read",
      "Grep",
      "Bash"
    ],
    "license": "MIT"
  },
  "instructions": "# Merge Queue (Serialized Commit Control)\n\n## Concept of the skill\n\nUse when serializing merges across multiple agent branches, resolving conflicts between agent outputs, or cleaning stale task branches.\n\n\n## Domain Context\n\n**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).\n\n## Co",
  "cost": {
    "context_tokens": 1496
  }
}

Fetch it by URL: GET /api/v1/registry/jacob-balslev-skill-graph-merge-queue/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.