package.json

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

https://github.com/owner/repo-name

owner/repo-name

• 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)

check-provider-commit.sh

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

2>/dev/null

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

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

undefined

**调研步骤：**

1. **分析所有差异**：查看每个差异文件，了解以下信息：
   - 被修改、新增或删除的文件
   - 变更的性质（bug修复、功能新增、重构、破坏性变更）
   - 对现有本地自定义内容的影响
   - 变更之间的依赖关系

2. **检查本地自定义内容**：查看当前本地文件，识别：
   - 可能产生冲突的自定义修改
   - 需要保留的本地新增内容
   - 配置差异

3. **查看项目规则**：【必填步骤】- 查看`.cursor/rules`了解：
   - 适用于该provider的规则（TypeScript、React等）
   - 项目标准和规范
   - 相关技术的最佳实践

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

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

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

• 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

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

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

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

• 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

cat providers/<provider>/diff_last_commit.txt

undefined

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

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

.diffs/<commit_hash>/<file-path>.txt