How to Sync a Forked Version with Upstream Updates from the Original Repository

Keep your fork of ayghri/i-have-adhd in perfect sync by adding an upstream remote, fetching updates, merging or rebasing, and reconciling the duplicated skill files.

The i-have-adhd repository is a coding assistant plugin with a unique dual-file structure that requires special attention during synchronization. When you fork the repository, your copy points to a static snapshot. To benefit from bug fixes, feature updates, and skill improvements in the original project, you must actively sync your fork with upstream changes.

Understanding the Repository Structure

The i-have-adhd plugin organizes its core logic in two locations that must stay identical:

• skills/i-have-adhd/SKILL.md — The canonical skill definition
• .cursor/skills/i-have-adhd/SKILL.md — A duplicated copy for IDE integration

The GitHub Actions workflow in .github/workflows/cursor-skill-sync.yml enforces this synchronization. If these files diverge, your pull requests and pushes will fail CI checks, blocking your contribution workflow.

Step-by-Step: Syncing Forked Versions with Upstream Updates

1. Add the Upstream Remote

First, configure Git to recognize the original repository as a source of truth.

# Navigate to your local fork

cd i-have-adhd

# Add the upstream remote

git remote add upstream https://github.com/ayghri/i-have-adhd.git

# Verify the remotes are configured

git remote -v

# origin    https://github.com/<your-username>/i-have-adhd.git (fetch)

# origin    https://github.com/<your-username>/i-have-adhd.git (push)

# upstream  https://github.com/ayghri/i-have-adhd.git (fetch)

# upstream  https://github.com/ayghri/i-have-adhd.git (push)

2. Fetch Upstream Changes

Download the latest commits without modifying your working directory.

git fetch upstream

This retrieves all branches from ayghri/i-have-adhd into remote-tracking references.

3. Integrate Upstream Updates

Choose between merge (preserves complete history) or rebase (creates linear history).

Merge approach (recommended for most users):

git checkout main
git merge upstream/main

Rebase approach (cleaner commit history, requires force push):

git checkout main
git rebase upstream/main
git push origin main --force-with-lease

4. Resolve Skill File Conflicts

After integrating upstream changes, check if the .cursor copy needs manual alignment. The cursor-skill-sync.yml workflow validates file parity using a simple comparison check.

If the CI job fails or you see divergence locally, execute:

# Copy the canonical skill file to the .cursor location

cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md

# Stage and commit if changed

git add .cursor/skills/i-have-adhd/SKILL.md
git commit -m "Sync .cursor copy with canonical SKILL.md"

5. Push Synchronized State to Your Fork

git push origin main

Your fork now reflects the upstream state, and the sync workflow will pass on subsequent pull requests.

Automating Sync with Git Aliases

For frequent synchronization, add these shortcuts to your Git configuration:

git config --global alias.sync-upstream '!git fetch upstream && git checkout main && git merge upstream/main'
git config --global alias.sync-skill '!cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md && git add .cursor/skills/i-have-adhd/SKILL.md && git commit -m "Sync .cursor copy with canonical SKILL.md"'

Key Files Involved in Synchronization

File	Purpose
skills/i-have-adhd/SKILL.md	Canonical skill definition; treat as source of truth
.cursor/skills/i-have-adhd/SKILL.md	IDE-specific copy; must match canonical exactly
.github/workflows/cursor-skill-sync.yml	CI enforcement preventing drift between copies
plugin.json	Plugin metadata; rarely changes during sync
INSTALL.md	Instructions dependent on synchronized file structure

Summary

• Add upstream remote pointing to https://github.com/ayghri/i-have-adhd.git
• Fetch and integrate using git merge upstream/main or git rebase upstream/main
• Reconcile duplicated files with cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md when the sync workflow flags discrepancies
• Push to your fork to complete the synchronization cycle

Regular synchronization ensures your fork benefits from upstream improvements while maintaining the dual-file integrity required by the Cursor IDE integration.

Frequently Asked Questions

How often should I sync my fork with upstream?

Sync your fork before starting any new work and after significant upstream releases. Weekly synchronization is sufficient for active development; monthly works for casual users. The cursor-skill-sync.yml workflow will block contributions if you're significantly behind upstream changes that modified SKILL.md.

What happens if I forget to sync the .cursor copy with SKILL.md?

The GitHub Actions workflow defined in .github/workflows/cursor-skill-sync.yml compares the two files on every push and pull request. If they differ, the check fails with an error message directing you to run the copy command. Your contribution cannot merge until both files match.

Can I automate the entire sync process?

Partial automation is possible. Configure a GitHub Actions workflow in your own fork to periodically create pull requests from upstream. However, the .cursor copy reconciliation requires manual intervention or a custom script since automated merges cannot predict which file version takes precedence during conflicts.

Should I use merge or rebase when syncing with upstream?

Merge preserves the complete history including upstream's commit sequence—ideal when you want traceability. Rebase rewrites your local commits atop upstream's tip, creating linear history preferred by maintainers reviewing your pull requests. Never rebase commits already pushed to shared branches unless you coordinate with collaborators.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}