sync-provider

Sync Provider

Sync changes from cloned provider repositories while preserving local customizations.

Overview

Most providers (except opencode) are cloned from external repositories and need to be kept in sync with upstream changes. This skill guides the complete workflow from checking for updates to applying changes safely.

Prerequisites

1. GitHub CLI (gh): Must be installed and authenticated

   gh --version
   gh auth login
   gh auth status
   

2. GitHub Token: Add GITHUB_TOKEN to root .env file

   GITHUB_TOKEN=your_token_here
   

3. Repository Info: Each provider's package.json contains repository.url field (format: https://github.com/owner/repo-name)

Workflow

Step 1: Identify Provider and Repository

Check the provider's package.json for repository URL:

cat providers/<provider>/package.json | grep -A 2 repository

Extract owner/repo format: https://github.com/owner/repo-name → owner/repo-name

Step 2: Check for New Commits

Use check-provider-commit.sh to automatically check for new commits:

COMMIT_HASH=$(scripts/check-provider-commit.sh <provider> 2>/dev/null)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ] && [ -n "$COMMIT_HASH" ]; then
  echo "Proceeding with sync from commit: $COMMIT_HASH"
elif [ $EXIT_CODE -eq 0 ]; then
  echo "Already up to date - no sync needed"
  exit 0
else
  echo "No state file found - need to determine initial commit hash manually"
  exit 1
fi

Script Behavior:

• Up to date: Exits with code 0, shows "Already up to date"
• New commits: Outputs commit hash (last synced), exits with code 0
• No state file: Exits with code 1, shows latest commit (requires manual determination for first sync)

Important: Redirect stderr (2>/dev/null) when capturing commit hash to avoid mixing informational messages.

Step 3: Run Git Diff Script

Execute the sync script with appropriate parameters:

REPO=$(cat providers/<provider>/package.json | grep -A 2 repository | grep url | cut -d'"' -f4 | sed 's|https://github.com/||')

pnpm exec tsx scripts/git-diff.ts \
  -r $REPO \
  -c "$COMMIT_HASH" \
  -i "src/**/*" \
  -i "docs/**/*" \
  -i "examples/**/*" \
  --state-file-path ./providers/<provider>/diff_last_commit.txt

Parameters:

• -r, --repo: GitHub repository in owner/repo format (required)
• -c, --commit: Commit hash to compare from (required) - use last synced commit from state file
• -i, --include: Glob pattern(s) to filter files (can specify multiple times)
  • Always use these three default patterns:
    • src/**/* - All source files
    • docs/**/* - Documentation files
    • examples/**/* - Example files
• --state-file-path: Path to store last synced commit hash

Step 4: Deep Research and Analysis

MANDATORY: Before applying any changes, perform deep research:

# List all generated diff files
ls -R .diffs/<commit_hash>/

# Review all diffs to understand scope
find .diffs/<commit_hash>/ -name "*.txt" -exec echo "=== {} ===" \; -exec cat {} \;

# Get list of affected files
find .diffs/<commit_hash>/ -name "*.txt" | sed "s|\.diffs/<commit_hash>/||" | sed 's|\.txt$||'

Research Steps:

1. Analyze All Diffs: Review every diff file to understand:

   • Files being modified, added, or removed
   • Nature of changes (bug fixes, features, refactoring, breaking changes)
   • Impact on existing local customizations
   • Dependencies between changes

2. Check Local Customizations: Review current local files to identify:

   • Custom modifications that might conflict
   • Local additions that should be preserved
   • Configuration differences

3. Review Project Rules: MANDATORY STEP - Check .cursor/rules to understand:

   • Which rules apply to this provider (TypeScript, React, etc.)
   • Project standards and patterns
   • Best practices for the technologies involved

Step 5: Create Refactoring Plan Using Pal MCP

MANDATORY: Use Pal MCP refactor tool with Gemini 3.0 Pro to create comprehensive plan.

- **TASK INVALIDATION**: **THE TASK WILL BE INVALIDATED** if you make ANY edits to files before completing ALL steps of the Pal Refactor tool - **NO EXCEPTIONS**: You MUST complete the entire Pal Refactor workflow (all steps until `next_step_required: false`) before touching ANY files - **VERIFICATION**: Only proceed to Step 7 after receiving confirmation that all Pal Refactor steps are complete

Refactor Tool Usage:

1. Identify Relevant Files: Collect all files that will be affected:

   • Files from .diffs/<commit_hash>/ that have changes
   • Current local files in providers/<provider>/ that correspond to changed files
   • Use FULL absolute paths for all files

2. Run Pal Refactor Analysis:

   // Use mcp_zen_refactor with:
   // - model: "gemini-3.0-pro" or "anthropic/claude-opus-4.6"
   // - relevant_files: Array of absolute paths to affected files
   // - refactor_type: "modernize" or "organization" (as appropriate)
   // - focus_areas: ["sync-upstream-changes", "preserve-local-customizations"]
   

3. Complete ALL Steps: MANDATORY - Finalize ALL steps until next_step_required: false

   • Continue calling the refactor tool until you receive confirmation that all steps are complete
   • Do NOT proceed to any file edits until this is confirmed
   • TASK WILL BE INVALIDATED if you skip this step

4. Review Refactoring Recommendations: The tool will provide:

   • Best approach for applying changes
   • How to preserve local customizations
   • Potential conflicts and how to resolve them
   • Code quality improvements
   • Architecture considerations

Refactor Tool Requirements:

• Model: Must use gemini-3.0-pro or anthropic/claude-opus-4.6
• Multi-step: Complete ALL steps until next_step_required: false - NO EXCEPTIONS
• File Paths: Use FULL absolute paths (e.g., /Users/pedronauck/Dev/compozy/compozy-code/providers/claude-code/src/index.ts)
• Focus Areas: Include context about syncing upstream changes while preserving local customizations
• Completion Verification: Only proceed when the tool confirms all steps are complete

Step 6: Create Implementation Plan

Based on the Pal refactor analysis, create detailed implementation plan:

1. Prioritize Changes: Order by dependencies (apply dependencies first), risk level (low-risk first), impact (critical files first)

2. Identify Conflicts: Document files with local customizations that conflict with upstream changes, strategy for resolving each conflict, decisions on what to preserve vs. update

3. Plan Testing Strategy: Define which tests to run after each change, how to verify local customizations are preserved, integration points to test

4. Document Decisions: Record why certain changes are applied or skipped, how local customizations are preserved, any architectural decisions made

Step 7: Apply Changes According to Plan

- **VERIFICATION REQUIRED**: Before proceeding, verify that: 1. All Pal Refactor steps are complete (`next_step_required: false`) 2. You have received the complete refactoring analysis and recommendations 3. You have created a detailed implementation plan (Step 6) - **TASK INVALIDATION**: **THE TASK WILL BE INVALIDATED** if you start editing files before completing ALL Pal Refactor steps - **NO EXCEPTIONS**: Even if you think you understand the changes, you MUST complete the full Pal Refactor workflow first

Only after completing steps 4-6 AND verifying Pal Refactor completion, apply changes:

1. For Modified Files: Apply changes according to refactor plan, preserving local customizations
2. For Added Files: Add new files following project standards
3. For Removed Files: Evaluate if removal should be applied locally (may need to preserve)
4. For Renamed Files: Handle rename and content changes according to plan

Best Practices:

• Apply changes incrementally, following the prioritized plan
• Test after each significant change
• Preserve local customizations as identified in the plan
• Document any deviations from the plan

Step 8: Update State File

After successfully applying changes, verify state file was updated:

cat providers/<provider>/diff_last_commit.txt
# Should contain the latest commit hash that was synced

Example Workflow

Syncing claude-code Provider

# 1. Check repository info
cat providers/claude-code/package.json | grep repository

# 2. Check for new commits
COMMIT_HASH=$(scripts/check-provider-commit.sh claude-code 2>/dev/null)
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "⚠️  No state file found - need to determine initial commit hash manually"
  exit 1
elif [ -z "$COMMIT_HASH" ]; then
  echo "✅ Already up to date - no sync needed"
  exit 0
fi

# 3. Extract repository name
REPO=$(cat providers/claude-code/package.json | grep -A 2 repository | grep url | cut -d'"' -f4 | sed 's|https://github.com/||')

# 4. Run sync script
pnpm exec tsx scripts/git-diff.ts \
  -r $REPO \
  -c "$COMMIT_HASH" \
  -i "src/**/*" \
  -i "docs/**/*" \
  -i "examples/**/*" \
  --state-file-path ./providers/claude-code/diff_last_commit.txt

# 5. Deep research and analysis
find .diffs/$COMMIT_HASH/ -name "*.txt" -exec echo "=== {} ===" \; -exec cat {} \;

# 6. Use Pal MCP refactor tool (complete all steps)
# 7. Create implementation plan
# 8. Apply changes according to plan
# 9. Verify state file updated
cat providers/claude-code/diff_last_commit.txt

Available Providers

Provider	Repository	Notes
claude-code	ben-vargas/ai-sdk-provider-claude-code	Cloned
gemini	ben-vargas/ai-sdk-provider-gemini-cli	Cloned
codex	ben-vargas/ai-sdk-provider-codex-cli	Cloned
opencode	N/A	Created locally - no sync needed

Critical Requirements

- **YOU MUST** use `gh` CLI to automatically check for new commits before syncing - **YOU MUST** verify the repository URL from `package.json` before running the script - **YOU MUST** always use the three default include patterns: `src/**/*`, `docs/**/*`, `examples/**/*` - **YOU MUST** use the commit hash from the state file (last synced commit) as the `-c` parameter - **YOU MUST** perform deep research and analysis of all diffs before creating a plan - **YOU MUST** review `.cursor/rules` files to understand which rules apply (MANDATORY STEP) - **YOU MUST NEED** to use the Pal MCP refactor tool with Gemini 3.0 Pro to find out the best way to apply changes - **YOU MUST** complete ALL steps of the Pal refactor tool - don't stop the process in the middle - **YOU MUST** verify Pal Refactor completion (`next_step_required: false`) before proceeding to any file edits - **YOU MUST** create a detailed implementation plan based on the refactor analysis before applying changes - **YOU MUST** use FULL absolute paths when using Pal MCP tools (never relative paths) - **YOU MUST** preserve local customizations when applying upstream changes - **YOU MUST** test the provider after applying changes (`pnpm test` in provider directory) - **YOU MUST** run lint and typecheck after applying changes (`pnpm run lint && pnpm run typecheck`) - **YOU MUST** update the state file path to match the provider directory structure - **NEVER** sync `opencode` provider (it's created locally, not cloned) - **NEVER** apply changes directly without deep research and planning first - **NEVER** start editing files before completing ALL Pal Refactor steps - **NEVER** use workarounds - always prefer good and well-designed solutions - **ALWAYS** use the exact repository format: `owner/repo-name` (no `https://github.com/` prefix) - **ALWAYS** check `.diffs//` folder exists and contains expected files before planning - **ALWAYS** verify that `gh` CLI is authenticated (`gh auth status`) - **ALWAYS** follow greenfield approach - don't care about backwards compatibility, prioritize quality - **ALWAYS** double check which rules from `.cursor/rules` apply for the task before starting (MANDATORY STEP)

Troubleshooting

No files matching glob pattern

• Check if the commit hash is correct
• Verify the repository name format
• Use broader patterns like **/* to see all changes

State file not found

• First sync: Use the initial commit hash from when you cloned
• Subsequent syncs: The script creates the state file automatically

Binary files detected

Binary files are noted in .diffs/<commit_hash>/<file-path>.txt but not diffed. Handle these manually:

• Images: Review in GitHub or download directly
• Other binaries: Decide if update is needed

GitHub API rate limits

• Wait before retrying
• Use a GitHub token with higher rate limits
• Consider syncing in smaller batches

After Syncing

• MUST TEST: Run tests in the provider directory:

  cd providers/<provider>
  pnpm test
  pnpm run lint
  pnpm run typecheck
  

• MUST VERIFY: Ensure all changes are correctly applied and no local customizations are lost

• MUST DOCUMENT: Record any decisions made during the sync process, especially:

  • Conflicts resolved
  • Local customizations preserved
  • Deviations from upstream changes
  • Architectural decisions