Instruction to manage forked repositories.

fork-reorg.md

description	Use when migrating an existing forked repository into a clean upstream-vs-custom workflow while preserving non-conforming local work and existing divergence.
name	Fork Reorg
argument-hint	Fork URL, upstream URL, and any known local-only files or branches
agent	agent

Reorganize This Fork For Clean Upstream vs Custom Work

You are working inside an already-active forked repository.

The repository may already contain some non-conforming history, mixed customizations, local deployment files, direct commits on main, or partial remote/branch setup. Your job is to reorganize it into a durable fork workflow without losing existing work.

Objective

Set up this repository so that:

• origin points to the user's fork
• upstream points to the source repository
• local main tracks upstream/main and remains upstream-clean going forward
• custom/main becomes the long-lived branch for fork-only divergence
• upstream PR work happens on contrib/<topic> branches
• fork-only work happens on custom/<topic> branches
• fork-only files and policies are clearly mapped and documented for future agent sessions

Non-Negotiable Constraints

• Do not lose, reset, overwrite, or silently discard existing user work.
• Do not use destructive git commands unless the user explicitly approves them.
• If the current repository state is messy or mixed, preserve it first and then reorganize around it.
• Prefer the smallest viable restructuring that creates a clean operating model.
• If repo-specific conventions exist, preserve them rather than imposing unrelated structure.
• If helper scripts are added, match the platform and tooling that the repository already uses.

First Steps

1. Inspect the current git state:
   • git remote -v
   • git status --short --branch
   • git branch -vv
   • check whether key local files are ignored by repo or global ignore rules
2. Classify the current state before changing anything:
   • upstream-safe work
   • fork-only customizations
   • mixed or ambiguous changes
3. If the repo already contains mixed or non-conforming work, preserve it before reorganizing:
   • create a safety branch if needed
   • do not force-reset history
   • do not assume main is clean

Target Structure

Implement a workflow equivalent to this model, adapted to the repository:

• origin = user's fork
• upstream = source repo
• main = upstream-clean branch that tracks upstream/main
• custom/main = long-lived branch for divergence
• contrib/<topic> = upstream PR branches
• custom/<topic> = fork-only branches

Required Repo Changes

Create or update the minimal set of files needed so future agent sessions follow the same model:

1. A fork mapping document such as FORK-MAPPING.md that explains:
   • remote mapping
   • branch roles
   • fork-only files and directories
   • rules for upstream-safe vs fork-only work
   • daily sync workflow
2. Agent instructions such as AGENTS.md or equivalent workspace instructions that state:
   • which remote is origin
   • which remote is upstream
   • that main stays upstream-clean
   • that custom/main is the long-lived divergent branch
   • that upstream PRs must not include fork-only files
   • that mixed requests should be split into separate branches
3. Helper scripts for routine fork workflows when appropriate, for example:
   • syncing from upstream
   • creating upstream PR branches
   • creating custom branches
4. Optional but recommended:
   • fork-only automation only if it does not pollute an upstream-clean main
   • if scheduled automation is needed, place it on a fork-only default branch such as custom/main, or run it from an external controller repository instead of storing it on main

Handling Existing Non-Conforming State

If the repo is already partially divergent or not following this structure:

• identify what should remain on main versus move to custom/main
• preserve user work before reshaping branches
• prefer additive migration over risky history surgery
• if history cleanup is required, stop and explain the tradeoff before proceeding
• if local deployment files, secrets paths, org-specific prompts, or environment-specific compose files exist, classify them as fork-only by default

Verification

Before finishing, verify all of the following:

• remotes are correctly mapped
• branch tracking is correct
• fork-only files are not accidentally hidden by ignore rules if they are meant to be tracked
• helper scripts have no obvious syntax errors
• any new workflow files are syntactically valid
• fork-only automation is not stored on an upstream-clean main
• the resulting policy is documented clearly enough that a future agent can continue without rediscovering intent

Output Requirements

When done, provide:

1. a short summary of what was changed
2. the final remote and branch model
3. any files created or updated for fork governance
4. whether existing non-conforming work was preserved, moved, or left in place
5. exact commands the user can run next
6. any residual risk, especially if the repo started in a mixed or messy state

Important Decision Rule

When in doubt, optimize for:

1. preserving existing work
2. separating upstream-safe changes from fork-only divergence
3. making future agent behavior predictable
4. avoiding hidden policy that lives only in chat instead of in repo files

Proceed with concrete repo changes when safe. If a destructive or ambiguous step is required, pause and ask only for that missing decision.