release-sync

Create a merge PR reconciling main into dev after squash releases.

Updated Apr 15, 2026
One-click install
npx skills add https://github.com/AAbdulghany/fms --skill release-sync-aabdulghany
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: release-sync
Source: https://github.com/AAbdulghany/fms/tree/main/.claude/skills/release-sync
Command: npx skills add https://github.com/AAbdulghany/fms --skill release-sync-aabdulghany

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

After squash-merge releases, history divergence between main and dev creates conflicts for subsequent PRs. This skill automates reconciliation by creating a framework-guided merge PR that makes the release squash commit an ancestor of dev, preserving history and simplifying future release flows.

Core Features & Use Cases

  • Pre-flight checks to verify repository identity, tag presence, and required branches.
  • Creates a sync branch from upstream/dev, merges upstream/main with -X ours to preserve dev content, and opens a merge PR against dev.
  • Carries forward CHANGELOG.md from main when needed as a separate commit to maintain release notes history.
  • Idempotent: detects already-synced repos and performs no-op, ensuring safe re-runs.
  • Enforces safety and governance: framework-only, true merge PR flow, audit-friendly commits.

Quick Start

Invoke the release-sync operation with a version tag to create the sync PR that reconciles main into dev after the release.

Frequently Asked Questions about release-sync

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does git history diverge after a squash-merge release from dev to main?

Squash-merging a release from dev to main creates a new single commit on main, causing history divergence because dev lacks that squash commit as an ancestor, leading to conflicts in subsequent release PRs.

How do I sync main into dev after a squash-merge release to prevent future merge conflicts?

To sync main into dev, create a sync branch from upstream/dev and merge upstream/main using the -X ours strategy to preserve dev content, then open a merge PR against dev to make the release commit an ancestor.

What's the best way to automate release reconciliation between main and dev branches?

Automating release reconciliation involves running pre-flight checks to verify tags and branches, creating a true merge PR with an -X ours merge strategy, and optionally carrying forward CHANGELOG.md to maintain release notes history.

Does this main to dev synchronization workflow work with any git repository?

This workflow applies specifically to ApexYard framework repositories where releases are squash-merged from dev to main, enforcing framework-only governance and pre-flight checks to verify repository identity before proceeding.

What happens if I run the main to dev sync operation on a repository that is already synced?

The sync operation is idempotent, meaning it detects already-synced repositories and performs a no-op, ensuring safe re-runs without creating duplicate merge PRs or altering git history unnecessarily.

How is the CHANGELOG.md handled during the main to dev merge reconciliation?

The CHANGELOG.md is optionally carried forward from main as a separate commit during the merge reconciliation, ensuring release notes history is maintained independently of the -X ours merge strategy preserving dev content.