| name | main-sync |
| description | Sync a long-lived feature branch with its repo's advancing main — bring main's commits into the branch under the repository's sync strategy, judge the rule-set and capability deltas, and re-run the combined Definition of Done. Use when main gains commits under a goal or review-fixes feature branch, before syncing a feature branch with origin/main, or when deciding whether a feature landed on main must be mirrored on the branch. |
Main sync
A long-lived feature branch decays as its repo's main advances: new rules bind work the branch already did, new capabilities land that the branch's own promises may cover, and evidence measured before the sync no longer describes the synced tree. A sync is not a mechanical operation — it is a scoped review of everything main brought in.
How the branch syncs
This repository squash-merges pull requests, so a pushed branch syncs by merging main into it, and pushed commits are never rewritten — the branch's intermediate history vanishes at the squash, so merge commits cost nothing.
Whatever the mode, rebasing a branch nothing else references yet — never pushed, backing no pull request, feeding no other lane — is legitimate, and every rebase begins with the pre-rebase conflict-surface check: surface the conflict set before any history is rewritten (git merge-tree, or a throwaway merge in a scratch worktree), so a conflict-heavy rebase is chosen deliberately, never discovered midway.
With main in, work the four obligations below before the sync lands.
1. Rule-set delta — both directions
Three rule-set sources govern the branch, and a sync can move all of them:
- The workspace's own instructions and skills (
CLAUDE.md, .claude/skills/).
- The repo's contracts: its
AGENTS.md and the binding process docs it commits.
- The branch's own contracts: its design docs, decision records, and the rulings made during its effort.
