# Upstream Sync

> Sync new changes from upstream.

- Skill: `mary-ext/upstream-sync` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mary-ext/upstream-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mary-ext/upstream-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mary-ext (https://skillmd.com/u/mary-ext)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mary-ext/upstream-sync

---


## 1. Establish the range

`git fetch upstream` — the remote is `https://github.com/bluesky-social/social-app`, and the clone
must be full, not shallow.

`README.md` under "upstream tracking" carries the marker:

> last reviewed upstream tip: `<hash>` (date)

The range is `<hash>..upstream/main`. Size it with `git rev-list --count` and `git log --oneline`.

## 2. Review every commit, oldest to newest

`git show <commit>`, then find the fork's counterpart with grepping the codebase and judge what a
port would actually cost.

- Read the diff, not the subject line. A commit that reads as an iOS/Android fix or a dependency
  bump still touches shared and web code often enough to be worth checking.
- Nothing applies cleanly — React Native is nearly gone here, so every port is a rewrite rather than
  a cherry-pick.
- Absent code is usually deliberate: a stripped feature, or something still beta or A/B gated.
  Determine which before calling it a gap. A good beta feature is still portable, and we may unflag
  it ahead of upstream.

**Chase the prerequisites.** A commit's diff is only half the story; keep digging until you can
state what porting it needs, and say what you checked.

- New or changed lexicons → do our `@atcute/*` packages cover them yet? Compare the installed
  version against `pnpm view @atcute/<pkg>`.
- New upstream dependency → does the same package work on web, is there an equivalent, or is it
  replaceable with what we already have?
- Builds on an earlier upstream commit outside the range, or on one you tiered as skip → surface
  that link.

**Large ranges:** hand chunks of hashes to subagents, asking each for per-commit files touched,
whether web or shared code changed, a one-line summary, and a preliminary tier. Re-run `git show`
yourself on the candidates they flag — a subagent returns a paraphrase, not the source.

## 3. Report, grouped by interest

A table of commit and rationale, in tiers:

- **Good to port** — clear web value, fits the fork cleanly.
- **Meh to port** — minor or marginal; fine to skip.
- **Bad but we can port anyway** — awkward fit or extra work, but defensible.
- **Ignore entirely** — native-only, A/B gated, or targets a stripped feature.

Attach the prerequisites from step 2 to each portable item. Then propose an order by dependency,
risk, and size, decomposed into commit-sized units of one logical change each. Stop here.

## 4. Get explicit agreement

Present the plan and wait for explicit sign-off before porting. Expect back-and-forth over what
belongs in or out; revise until the user agrees, then implement.

## Advancing the marker

The marker means "reviewed", not "ported" — advance it once the range is handled, deliberate skips
included. Write the resolved hash from `git rev-parse upstream/main` and today's date into
`README.md`.