upstream-sync

Merges a newer Shattered Pixel Dungeon release tag into the Shatterfish fork with hook re-verification.

Updated Sep 3, 2026
One-click install
npx skills add https://github.com/watchthelight/shatterfish --skill upstream-sync-watchthelight
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: upstream-sync
Source: https://github.com/watchthelight/shatterfish/tree/main/.claude/skills/upstream-sync
Command: npx skills add https://github.com/watchthelight/shatterfish --skill upstream-sync-watchthelight

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Upgrading a permanent downstream fork to a new upstream release is risky: custom hooks can be silently lost, mirrored code can drift, and fairness guarantees can break. This Skill executes the documented upgrade procedure with mandatory checkpoints so every merge is verified and reproducible. ## Core Features & Use Cases - Human-approved tag selection: Fetches upstream tags, filters out beta/rc releases, shows the commit delta, and stops for explicit human approval before merging. - Hook and mirror re-verification: Re-applies every documented hook after conflict resolution, re-verifies mirrored upstream method bodies against digests, and records the verified tag. - Full validation pipeline: Runs the Gradle build, harness fairness and determinism tests, regenerates the Codex, runs the rig baseline, and updates all affected docs in the same PR. - Use Case: When Shattered Pixel Dungeon publishes a new stable release, invoke this Skill to produce a reviewed upgrade PR with green CI, published rig numbers, and updated documentation. ## Quick Start Ask the assistant to upgrade upstream to the latest stable Shattered Pixel Dungeon tag and follow the documented sync procedure.

Frequently Asked Questions about upstream-sync

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

FAQPage Schema
How do I upgrade a downstream fork to a new upstream release tag?

Fetch upstream tags, pick the newest stable tag, get human approval, then merge it on a dedicated branch. Re-apply every documented hook, rebuild, run the test suites, and open a PR listing all re-verified hooks.

How do I resolve merge conflicts in files with custom hooks?

Re-apply the hook minimally on top of upstream's changes rather than taking either side wholesale, then update the hook's row in the tracking table. For files that should never have been modified, investigate why they differ before resolving.

Can I merge upstream master instead of a release tag?

No. This procedure only merges stable release tags and explicitly forbids merging upstream/master or any non-tag ref. Tags provide a pinned, reviewable baseline for the fork.

What happens if fairness or determinism tests fail after an upstream merge?

A failure blocks the upgrade until it is understood. It usually means the Observer class must learn a new visibility rule introduced by the upstream change, and the fix is scoped to what the upgrade broke.

Why does the upgrade keep the old Codex folder until merge?

Keeping the previous tag's Codex folder makes the diff between tags reviewable in the PR. The old folder is deleted only after the upgrade PR is merged.