sync-ag-shared

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sync ag-shared Subrepo Across AG Repos

在AG系列仓库间同步ag-shared子仓库

Orchestrate syncing

external/ag-shared/

changes from the current repo to all other AG repos that consume the subrepo. This handles the full

yarn subrepo push

pull

cycle, companion changes, and cross-linked PRs.

协调将当前仓库中

external/ag-shared/

的变更同步到所有其他使用该子仓库的AG系列仓库。该流程会处理完整的

yarn subrepo push

pull

周期、配套变更以及交叉关联的PR。

Help

帮助

If the user provides a command option of

help

Explain how to use this skill.
Explain the prerequisites and what will happen.
DO NOT proceed, exit the skill immediately after these steps.

如果用户提供

help

命令选项：

解释如何使用该技能。
说明前置条件以及执行后会发生的操作。
完成上述步骤后立即退出该技能，不继续执行后续流程。

Prerequisites

前置条件

Git CLI, GitHub CLI (
```
gh
```
), and
```
yarn
```
must be available.
```
git subrepo
```
must be installed (
```
git subrepo --version
```
).
Use
yarn subrepo
for push and pull (never raw
```
git subrepo push
```
/
```
pull
```
). The wrapper handles edge cases like stale parent references. Other subrepo commands (e.g.
```
git subrepo status
```
,
```
git subrepo clean
```
) use
```
git subrepo
```
directly.
Never edit
external/ag-shared/.gitrepo
manually. Only subrepo commands should modify this file.
Must be on a feature branch (not
```
latest
```
,
```
main
```
, or
```
master
```
).
Working tree must be clean (
```
git status --porcelain
```
is empty).
The current repo must have
```
external/ag-shared/.gitrepo
```
.

必须已安装Git CLI、GitHub CLI（
```
gh
```
）和
```
yarn
```
。
必须已安装
```
git subrepo
```
（可通过
```
git subrepo --version
```
验证）。
请使用
yarn subrepo
执行push和pull操作（切勿直接使用
```
git subrepo push
```
/
```
pull
```
）。该封装工具会处理诸如陈旧父引用等边缘情况。其他子仓库命令（如
```
git subrepo status
```
、
```
git subrepo clean
```
）可直接使用
```
git subrepo
```
执行。
切勿手动编辑
external/ag-shared/.gitrepo
文件。仅可通过子仓库命令修改该文件。
必须处于功能分支（而非
```
latest
```
、
```
main
```
或
```
master
```
分支）。
工作区必须干净（
```
git status --porcelain
```
输出为空）。
当前仓库必须存在
```
external/ag-shared/.gitrepo
```
文件。

STEP 1: Gather State

步骤1：收集状态信息

Collect all context needed to plan the sync.

收集规划同步所需的所有上下文信息。

1a. Identify Source Repo

1a. 识别源仓库

bash

undefined

bash

undefined

The working directory where the skill was invoked — use this for ALL

技能被调用时的工作目录 —— 在源仓库中执行所有git/子仓库命令时都要使用该目录（对于工作树而言至关重要）。

git/subrepo commands in the source repo (critical for worktrees).

—

SOURCE_WD=$(pwd)

Resolve the real repo root (worktrees resolve to actual repo location).

解析真实的仓库根目录（工作树会解析到实际仓库位置）。

Only used for discovering sibling destination repos, NOT for running commands.

仅用于发现同级的目标仓库，不用于执行命令。

REPO_GIT_DIR=$(git rev-parse --git-common-dir) SOURCE_ROOT=$(cd "$(dirname "$REPO_GIT_DIR")" && pwd)

Current branch

当前分支

SOURCE_BRANCH=$(git rev-parse --abbrev-ref HEAD)

Repo name (for display)

仓库名称（用于展示）

SOURCE_REPO=$(basename "$SOURCE_ROOT")


**Important — worktree awareness:** When invoked from a git worktree, the feature branch is checked out in the worktree, and the main repo checkout is typically on `latest` (or another branch). You **cannot** `git checkout` the feature branch in the main repo because git prevents a branch from being checked out in two places simultaneously. Always run subrepo and git commands from `SOURCE_WD` (the worktree), never from `SOURCE_ROOT`.

Validate:

-   `SOURCE_BRANCH` is not `latest`, `main`, or `master`.
-   `git status --porcelain` is empty.
-   `external/ag-shared/.gitrepo` exists.

If any validation fails, report the issue and **STOP**.

SOURCE_REPO=$(basename "$SOURCE_ROOT")


**重要提示 —— 工作树适配：** 当从Git工作树中调用该技能时，功能分支已在工作树中检出，而主仓库通常处于`latest`（或其他分支）。你**无法**在主仓库中检出该功能分支，因为Git不允许同一个分支同时在两个位置被检出。请始终在`SOURCE_WD`（工作树目录）中执行子仓库和Git命令，切勿在`SOURCE_ROOT`中执行。

验证：

-   `SOURCE_BRANCH`不是`latest`、`main`或`master`。
-   `git status --porcelain`输出为空。
-   `external/ag-shared/.gitrepo`文件存在。

如果任何验证失败，请报告问题并**终止流程**。

1b. Discover Destination Repos

1b. 发现目标仓库

Destination repos are siblings of the source repo root. Look for directories at the same level that contain

external/ag-shared/.gitrepo

bash

PARENT_DIR=$(dirname "$SOURCE_ROOT")
for dir in "$PARENT_DIR"/*/; do
    if [ "$dir" != "$SOURCE_ROOT/" ] && [ -f "${dir}external/ag-shared/.gitrepo" ]; then
        echo "Found destination: $dir"
    fi
done

Collect the list of destination repos. Typical destinations are two of

ag-charts

ag-grid

and

ag-studio

, but discover dynamically.

目标仓库是源仓库根目录的同级目录。在同一层级下查找包含

external/ag-shared/.gitrepo

文件的目录。

bash

PARENT_DIR=$(dirname "$SOURCE_ROOT")
for dir in "$PARENT_DIR"/*/; do
    if [ "$dir" != "$SOURCE_ROOT/" ] && [ -f "${dir}external/ag-shared/.gitrepo" ]; then
        echo "找到目标仓库：$dir"
    fi
done

收集目标仓库列表。典型的目标仓库是

ag-charts

、

ag-grid

和

ag-studio

中的两个，但需动态发现。

1c. Validate Destinations

1c. 验证目标仓库

For each destination repo:

Check it has a clean working tree.
Check it is on
```
latest
```
or a feature branch.
Run
```
git fetch origin
```
to ensure it is up to date.

If any destination has uncommitted changes, default to stashing all changes and continuing - but ask the user to confirm.

针对每个目标仓库：

检查工作区是否干净。
检查当前分支是否为
```
latest
```
或功能分支。
执行
```
git fetch origin
```
确保仓库已同步到最新状态。

如果任何目标仓库存在未提交的变更，默认会暂存所有变更并继续执行，但需先征得用户确认。

STEP 2: Analyse Source Changes

步骤2：分析源仓库变更

Use a sub-agent (Task tool,

subagent_type: Explore

) to analyse changes on the source branch:

bash

undefined

使用子代理（任务工具，

subagent_type: Explore

）分析源分支上的变更：

bash

undefined

Changes inside ag-shared

ag-shared内部的变更

git diff latest...HEAD -- external/ag-shared/

Changes outside ag-shared

ag-shared外部的变更

git diff latest...HEAD -- ':!external/ag-shared/'

Commit log

提交日志

git log --oneline latest...HEAD


The sub-agent should produce:

1.  **Change summary** — what files changed in `external/ag-shared/` and why.
2.  **Companion change predictions** — based on the ag-shared changes, what companion changes are likely needed in each destination repo. For example:
    -   New/renamed skills may need symlink updates in `.rulesync/`.
    -   Changed rule globs may need `.claude/settings.json` updates.
    -   Script changes may need `package.json` or CI updates.
    -   Setup-prompts changes need `setup-prompts.sh` re-run in each repo.

git log --oneline latest...HEAD


子代理应生成以下内容：

1.  **变更摘要** —— `external/ag-shared/`中哪些文件发生了变更，以及变更原因。
2.  **配套变更预测** —— 基于ag-shared的变更，预测每个目标仓库可能需要哪些配套变更。例如：
    -   新增/重命名的技能可能需要更新`.rulesync/`中的符号链接。
    -   规则通配符变更可能需要更新`.claude/settings.json`。
    -   脚本变更可能需要更新`package.json`或CI配置。
    -   初始化提示变更需要在每个仓库中重新运行`setup-prompts.sh`。

STEP 3: Present Plan and Confirm

步骤3：展示计划并确认

Display to the user:

undefined

向用户展示以下内容：

undefined

ag-shared Sync Plan

ag-shared同步计划

Source: <SOURCE_REPO> @ <SOURCE_BRANCH> Destinations: <list of destination repos>

源仓库： <SOURCE_REPO> @ <SOURCE_BRANCH> 目标仓库： <目标仓库列表>

Changes in ag-shared

ag-shared中的变更

<步骤2生成的摘要>

Changes outside ag-shared

ag-shared外的变更

<步骤2生成的摘要>

Predicted Companion Changes

预测的配套变更

<per-destination predictions from step 2>

<步骤2生成的各仓库预测内容>

Steps

执行步骤

Push ag-shared from <SOURCE_REPO>
Create sync/<SOURCE_BRANCH> branches in each destination
Pull ag-shared in each destination
Apply companion changes in each destination
Verify all repos
Push branches and create cross-linked PRs (reuse existing source PR if one exists)


Use `AskUserQuestion` to confirm before proceeding. The user may want to adjust the plan or skip certain destinations.

从<SOURCE_REPO>推送ag-shared变更
在每个目标仓库中创建sync/<SOURCE_BRANCH>分支
在每个目标仓库中拉取ag-shared变更
在每个目标仓库中应用配套变更
验证所有仓库
推送分支并创建交叉关联的PR（如果源分支已有PR则复用）


使用`AskUserQuestion`工具请求用户确认后再继续执行。用户可能需要调整计划或跳过某些目标仓库。

STEP 4: Push Source ag-shared

步骤4：推送源仓库的ag-shared变更

From the source working directory (the worktree or repo where the skill was invoked):

bash

cd "$SOURCE_WD"
yarn subrepo push ag-shared

从源工作目录（调用技能的工作树或仓库）执行：

bash

cd "$SOURCE_WD"
yarn subrepo push ag-shared

Handling "need to pull first"

处理「需要先拉取」的情况

If the push fails with "There are new changes upstream, you need to pull first", this means the ag-shared remote has commits not yet in this branch. Handle it:

bash

cd "$SOURCE_WD"
yarn subrepo pull ag-shared   # Integrates upstream changes
git diff HEAD~1 --stat        # Show what the pull changed — verify before continuing
yarn subrepo push ag-shared   # Retry the push

如果推送失败并提示_"There are new changes upstream, you need to pull first"_，说明ag-shared远程仓库有该分支尚未同步的新变更。处理方式如下：

bash

cd "$SOURCE_WD"
yarn subrepo pull ag-shared   # 集成上游变更
git diff HEAD~1 --stat        # 展示拉取带来的变更 —— 确认后再继续
yarn subrepo push ag-shared   # 重试推送

Stale lock files

陈旧的锁文件

If a subrepo command fails mid-operation, it may leave a stale git lock file. Check for and remove it before retrying:

bash

undefined

如果子仓库命令在执行过程中失败，可能会遗留陈旧的Git锁文件。在重试前请检查并删除该文件：

bash

undefined

For worktrees:

针对工作树：

LOCK_FILE=$(git rev-parse --git-dir)/index.lock [ -f "$LOCK_FILE" ] && rm "$LOCK_FILE"

Also restore any partially-modified .gitrepo:

同时恢复可能被部分修改的.gitrepo文件：

git checkout -- external/ag-shared/.gitrepo


If the push still fails after pulling, report the error and **STOP**.

git checkout -- external/ag-shared/.gitrepo


如果拉取后推送仍然失败，请报告错误并**终止流程**。

STEP 5: Create Sync Branches and Pull

步骤5：创建同步分支并拉取变更

For each destination repo:

bash

cd "<DEST_ROOT>"

针对每个目标仓库：

bash

cd "<DEST_ROOT>"

Fetch latest

获取最新代码

git fetch origin

Create sync branch from origin/latest

基于origin/latest创建同步分支

git checkout -b "sync/${SOURCE_BRANCH}" origin/latest

Pull ag-shared updates

拉取ag-shared更新

yarn subrepo pull ag-shared

Show what the pull changed — verify files match expected changes from Step 2

展示拉取带来的变更 —— 验证文件是否与步骤2中的预期一致

git diff HEAD~1 --stat

Verify the pull succeeded

验证拉取是否成功

git subrepo status external/ag-shared


If `subrepo pull` fails in any repo, report the error and **STOP** — ask the user how to proceed.

git subrepo status external/ag-shared


如果任何仓库中的`subrepo pull`失败，请报告错误并**终止流程** —— 询问用户如何处理。

STEP 6: Apply Companion Changes

步骤6：应用配套变更

For each destination repo, launch a sub-agent (Task tool,

subagent_type: general-purpose

) to apply predicted companion changes. Provide the sub-agent with:

The destination repo path.
The change summary from Step 2.
The predicted companion changes for this specific repo.
Instructions to replicate patterns from the source repo.

Common companion tasks:

Run

./external/ag-shared/scripts/setup-prompts/setup-prompts.sh

to regenerate

.claude/

from

.rulesync/

Update
```
.rulesync/
```
symlinks if skills/rules were added, renamed, or removed.
Update product-specific configurations if ag-shared scripts changed.

Run verification:

./external/ag-shared/scripts/setup-prompts/verify-rulesync.sh

Run
npx nx format
(or equivalent formatter) before committing to avoid CI formatting check failures.

针对每个目标仓库，启动子代理（任务工具，

subagent_type: general-purpose

）来应用预测的配套变更。向子代理提供以下信息：

目标仓库路径。
步骤2生成的变更摘要。
针对该特定仓库的配套变更预测。
从源仓库复制模式的说明。

常见的配套任务：

执行

./external/ag-shared/scripts/setup-prompts/setup-prompts.sh

从

.rulesync/

重新生成

.claude/

目录。

如果技能/规则被新增、重命名或删除，更新
```
.rulesync/
```
中的符号链接。
如果ag-shared脚本变更，更新产品特定的配置。

执行验证：

./external/ag-shared/scripts/setup-prompts/verify-rulesync.sh

。

提交前执行
npx nx format
（或等效的格式化工具），避免CI格式化检查失败。

Iterative Push/Pull (if needed)

迭代推送/拉取（如有需要）

If companion changes modify files inside

external/ag-shared/

(rare but possible):

Commit the changes in the destination repo.
```
yarn subrepo push ag-shared
```
from the destination.
Go back to the source repo and other destinations:
```
yarn subrepo pull ag-shared
```
.
Re-verify.

Cap iterations at 3. If changes still bounce after 3 rounds, stop and ask the user.

如果配套变更修改了

external/ag-shared/

内的文件（罕见但有可能）：

在目标仓库中提交变更。
从目标仓库执行
```
yarn subrepo push ag-shared
```
。
返回源仓库和其他目标仓库，执行
```
yarn subrepo pull ag-shared
```
。
重新验证。

迭代次数上限为3次。如果经过3轮后变更仍在来回同步，请终止流程并询问用户。

STEP 7: Verify

步骤7：验证

For each repo (source + all destinations):

bash

undefined

针对每个仓库（源仓库+所有目标仓库）：

bash

undefined

Check subrepo status

检查子仓库状态

git subrepo status external/ag-shared

Verify clean working tree

验证工作区是否干净

git status --porcelain

Run rulesync verification if available

如果存在验证脚本则执行

if [ -f "./external/ag-shared/scripts/setup-prompts/verify-rulesync.sh" ]; then ./external/ag-shared/scripts/setup-prompts/verify-rulesync.sh fi


Report any issues. All repos must have clean working trees and passing verification.

if [ -f "./external/ag-shared/scripts/setup-prompts/verify-rulesync.sh" ]; then ./external/ag-shared/scripts/setup-prompts/verify-rulesync.sh fi


报告所有问题。所有仓库的工作区必须干净且验证通过。

STEP 8: Commit, Push, and Create PRs

步骤8：提交、推送并创建PR

8a. Push All Branches

8a. 推送所有分支

For the source repo (if not already pushed):

bash

cd "$SOURCE_WD"
git push -u origin "$SOURCE_BRANCH"

For each destination repo:

bash

cd "<DEST_ROOT>"
git push -u origin "sync/${SOURCE_BRANCH}"

针对源仓库（如果尚未推送）：

bash

cd "$SOURCE_WD"
git push -u origin "$SOURCE_BRANCH"

针对每个目标仓库：

bash

cd "<DEST_ROOT>"
git push -u origin "sync/${SOURCE_BRANCH}"

8b. Audit PR Diffs for Unrelated Changes

8b. 检查PR差异中的无关变更

Before creating PRs, check each destination branch for unrelated changes that may have crept in (e.g. files modified on

origin/latest

after the branch point):

bash

cd "<DEST_ROOT>"
git diff origin/latest...HEAD --stat

Review the diff stat. If any files outside

external/ag-shared/

and

.rulesync/

appear that are not companion changes, revert them:

bash

git checkout origin/latest -- <unrelated-file>
git commit -m "Revert unrelated changes to <file>"

创建PR前，请检查每个目标分支是否引入了无关变更（例如，分支创建后

origin/latest

上被修改的文件）：

bash

cd "<DEST_ROOT>"
git diff origin/latest...HEAD --stat

查看差异统计。如果

external/ag-shared/

和

.rulesync/

之外出现了不属于配套变更的文件，请还原这些变更：

bash

git checkout origin/latest -- <unrelated-file>
git commit -m "还原对<file>的无关变更"

8c. Create Cross-Linked PRs

8c. 创建交叉关联的PR

Create a PR in each repo. All PRs should reference each other.

Check for existing PRs first. The source branch may already have an open PR. Always check before creating:

bash

cd "$SOURCE_WD"
SOURCE_PR_URL=$(gh pr view "$SOURCE_BRANCH" --json url -q '.url' 2>/dev/null)

If an existing PR is found, reuse it — update its description to add cross-repo links rather than creating a new PR. Only create a new PR if none exists:

bash

if [ -z "$SOURCE_PR_URL" ]; then
    SOURCE_PR_URL=$(gh pr create --base latest --title "<title>" --body "...")
fi

For destination repos, create new PRs (these are always new sync branches):

bash

cd "<DEST_ROOT>"
DEST_PR_URL=$(gh pr create --base latest --title "Sync ag-shared from <SOURCE_BRANCH>" --body "$(cat <<'EOF'

在每个仓库中创建PR。所有PR都应互相引用。

首先检查是否已存在PR。源分支可能已经有一个开放的PR。创建前请务必检查：

bash

cd "$SOURCE_WD"
SOURCE_PR_URL=$(gh pr view "$SOURCE_BRANCH" --json url -q '.url' 2>/dev/null)

如果找到已存在的PR，请复用该PR —— 更新其描述以添加跨仓库链接，而非创建新PR。仅当不存在现有PR时才创建新PR：

bash

if [ -z "$SOURCE_PR_URL" ]; then
    SOURCE_PR_URL=$(gh pr create --base latest --title "<标题>" --body "...")
fi

针对目标仓库，创建新的PR（这些始终是新的同步分支）：

bash

cd "<DEST_ROOT>"
DEST_PR_URL=$(gh pr create --base latest --title "Sync ag-shared from <SOURCE_BRANCH>" --body "$(cat <<'EOF'

Summary

摘要

Sync ag-shared subrepo from <SOURCE_REPO>@<SOURCE_BRANCH>.

从<SOURCE_REPO>@<SOURCE_BRANCH>同步ag-shared子仓库。

<配套变更摘要（如有）>

Cross-repo PRs

跨仓库PR

Source: <SOURCE_PR_URL>

源仓库：<SOURCE_PR_URL>

Test plan

测试计划

Verify ag-shared content matches source
Run setup-prompts verification EOF )")


Then update all PR descriptions (source and destinations) to cross-link with each other. For existing source PRs, **append** the cross-repo links section rather than replacing the entire body.

验证ag-shared内容与源仓库一致
执行初始化提示验证 EOF )")


然后更新所有PR的描述（源仓库和目标仓库）以互相交叉关联。对于已存在的源仓库PR，请**追加**跨仓库链接部分，而非替换整个描述。

8d. Report Results

8d. 报告结果

Output a summary:

undefined

输出摘要：

undefined

Sync Complete

同步完成

Repo	Branch	PR
<source>	<branch>	<url>
<dest1>	sync/<branch>	<url>
<dest2>	sync/<branch>	<url>

All repos verified. Working trees clean.

undefined

仓库	分支	PR
<source>	<branch>	<url>
<dest1>	sync/<branch>	<url>
<dest2>	sync/<branch>	<url>

所有仓库已验证。工作区干净。

undefined

Error Handling

错误处理

Merge conflicts during subrepo pull: Stop and ask the user to resolve manually. Provide the conflicting files and repo path.
Auth failures: Check
```
gh auth status
```
and
```
git remote -v
```
. Ask the user to authenticate.
Dirty working tree: Always stop and report. Never force-clean a destination repo.
Subrepo push/pull failures: Report the full error output. Common causes: diverged history (pull first, then push), missing remote access. Always use
```
yarn subrepo
```
for push/pull — the wrapper handles stale parent references and other edge cases.
Never edit
.gitrepo
manually: Only
```
yarn subrepo
```
commands should modify
```
external/ag-shared/.gitrepo
```
. If the subrepo state is broken, ask the user to resolve it rather than editing the file directly.
Stale git lock files: A failed subrepo operation may leave
```
index.lock
```
in the git dir. Remove it and restore
```
.gitrepo
```
before retrying (see Step 4).
Worktree branch conflicts: Never try to
```
git checkout
```
the source branch in the main repo — it's already checked out in the worktree. Always
```
cd
```
to the worktree working directory for source repo commands.

子仓库拉取时出现合并冲突：终止流程并请用户手动解决。提供冲突文件和仓库路径。
认证失败：检查
```
gh auth status
```
和
```
git remote -v
```
。请用户重新认证。
工作区不干净：始终终止流程并报告。切勿强制清理目标仓库。
子仓库推送/拉取失败：报告完整的错误输出。常见原因：历史分歧（先拉取再推送）、远程访问权限缺失。请始终使用
```
yarn subrepo
```
执行推送/拉取 —— 该封装工具会处理陈旧父引用和其他边缘情况。
切勿手动编辑
.gitrepo
文件：仅
```
yarn subrepo
```
命令可修改
```
external/ag-shared/.gitrepo
```
。如果子仓库状态损坏，请让用户自行解决，而非直接编辑该文件。
陈旧的Git锁文件：子仓库操作失败可能会在Git目录中遗留
```
index.lock
```
文件。重试前请删除该文件并还原
```
.gitrepo
```
（见步骤4）。
工作树分支冲突：切勿尝试在主仓库中检出源分支 —— 该分支已在工作树中检出。执行源仓库命令时请始终切换到工作树目录。

Arguments

参数

${ARGUMENTS}

can optionally include:

```
--skip <repo>
```
— skip a specific destination repo.
```
--dry-run
```
— analyse and present plan only, do not execute.
```
--no-pr
```
— sync branches but do not create PRs.

${ARGUMENTS}

可选择性包含以下内容：

```
--skip <repo>
```
—— 跳过指定的目标仓库。
```
--dry-run
```
—— 仅分析并展示计划，不执行实际操作。
```
--no-pr
```
—— 同步分支但不创建PR。