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

GitHub CLI (
gh
): Must be installed and authenticated
bash
```
gh --version
gh auth login
gh auth status
```

GitHub Token: Add

GITHUB_TOKEN

to root

.env

file

bash

GITHUB_TOKEN=your_token_here

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:

bash

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:

bash

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:

bash

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:

bash

# 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:

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
Check Local Customizations: Review current local files to identify:
- Custom modifications that might conflict
- Local additions that should be preserved
- Configuration differences
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.

<critical> - **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 </critical>

Refactor Tool Usage:

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

Run Pal Refactor Analysis:

typescript

// 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"]

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
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:

Prioritize Changes: Order by dependencies (apply dependencies first), risk level (low-risk first), impact (critical files first)
Identify Conflicts: Document files with local customizations that conflict with upstream changes, strategy for resolving each conflict, decisions on what to preserve vs. update
Plan Testing Strategy: Define which tests to run after each change, how to verify local customizations are preserved, integration points to test
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

<critical> - **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 </critical>

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

For Modified Files: Apply changes according to refactor plan, preserving local customizations
For Added Files: Add new files following project standards
For Removed Files: Evaluate if removal should be applied locally (may need to preserve)
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:

bash

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

Example Workflow

Syncing claude-code Provider

bash

# 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

<critical> - **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/<commit_hash>/` 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) </critical>

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:

bash

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

sync-provider

NPX Install

Tags

SKILL.md Content

Sync Provider

Overview

Prerequisites

Workflow

Step 1: Identify Provider and Repository

Step 2: Check for New Commits

Step 3: Run Git Diff Script

Step 4: Deep Research and Analysis

Step 5: Create Refactoring Plan Using Pal MCP

Step 6: Create Implementation Plan

Step 7: Apply Changes According to Plan

Step 8: Update State File

Example Workflow

Syncing claude-code Provider

Available Providers

Critical Requirements

Troubleshooting

No files matching glob pattern

State file not found

Binary files detected

GitHub API rate limits

After Syncing