downstream-fork-maintain

Maintains downstream Git forks as continuously rebuilt, upstream-tracking patch sets.

Updated Jul 26, 2026
One-click install
npx skills add https://github.com/xz-dev/downstream-fork-maintain-skill --skill downstream-fork-maintain-xz-dev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: downstream-fork-maintain
Source: https://github.com/xz-dev/downstream-fork-maintain-skill/tree/main/skills/downstream-fork-maintain
Command: npx skills add https://github.com/xz-dev/downstream-fork-maintain-skill --skill downstream-fork-maintain-xz-dev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Downstream forks often drift into unmaintainable hard forks whose patches rot as upstream moves forward. This Skill keeps every change as an independently buildable, testable, PR-quality patch branch that follows upstream, while a regenerated main or release branch always provides usable integrated code and artifacts. ## Core Features & Use Cases - Structured Branch Model: Separates concerns across patch branches, temporary compatibility branches (tmp/patch/<name>), a ci maintenance branch, and a generated release branch, with a fixed integration order. - Continuous Rebuild & Validation: Rebuilds the release branch from a specific upstream commit, applies upstream PRs and patches in order, runs source and projected-package checks, and pushes safely with --force-with-lease. - Patch Lifecycle Management: Covers adding, maintaining, and retiring patches, including checking upstream issues and PRs before coding and retiring patches once merged upstream. - Use Case: A team maintains a fork of an open-source CLI tool with five unmerged features. The Skill keeps each feature on its own PR-ready branch, rebuilds the release branch nightly via GitHub Actions, and detects conflicts the day upstream changes break a patch. ## Quick Start Ask the agent to maintain this downstream fork against its upstream repository, keep each patch independently reviewable, and rebuild the integrated release branch.

Frequently Asked Questions about downstream-fork-maintain

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

FAQPage Schema
How do I maintain a downstream Git fork without it becoming a hard fork?

Keep every change on its own patch branch based on upstream, maintain a ci branch for automation and integration order, and rebuild the release branch from a specific upstream commit. Never commit fixes only to the release branch, since they would be lost on the next rebuild.

How to keep downstream patches mergeable as upstream changes?

Update each patch branch promptly onto the latest upstream, resolve conflicts on that branch, and run its tests there. Automated sync rebuilds the integrated branch from the newest upstream head so conflicts surface early instead of letting patches rot.

What is a temporary compatibility patch branch in fork maintenance?

A tmp/patch/<name> branch holds fixes for conflicts that only appear when otherwise independent patches are combined. It declares its dependencies, integration position, validation scope, and retirement condition, and is removed once the combination no longer exists.

Does the sync workflow support force pushing the release branch safely?

Yes, the workflow uses git push --force-with-lease so the push fails if unknown remote commits appeared since the fetch. It also uses concurrency controls to prevent two sync jobs from updating the same branch simultaneously.

When should a downstream patch branch be retired?

Retire a patch after upstream merges it or provides equivalent behavior, confirmed by running existing regression tests. Remove it from the integration configuration and documentation, rebuild and validate the release branch, and only then delete the branch.