| name | sync-project-config |
| description | 把 claude-code-global 仓库管理的"跨项目共享开发配置模板"的最新变化同步进当前项目；含 adopt 模式（无 marker 老项目首次接入） |
| disable-model-invocation | false |
把 ~/.claude/templates/ 的变化反映到当前项目。两种模式：
- Normal sync（项目根有
.agent-template.yml marker）：算 diff → 智能 merge 提议 → 用户批量决策 → 执行
- Adopt（无 marker）：让用户选 stack → 当作「全是新增」完整套用一次 → 写 marker
动手改文件前先读 templates/MECHANICS.md —— 落点语义（__root__ / __subpath__ / _common）、fragment 合并、变体组落地、后端可跑化、前端装依赖、迁移去重全在那里，本 skill 不复述。字段 schema 与设计取舍见 ~/.claude/global-repo/docs/11-跨项目共享模板与sync-skill/。
三态收敛约定（下文统一遵循、不再逐处复述）：marker 的 stacks 可以有 0、1 或多条。凡「遍历 stacks」对每条各跑一遍；len == 1 退化为单条、行为与旧单 stack 完全一致；len == 0 走「仅 _common」分支。skipped 的读写位置随形态而定 —— len >= 1 用 stacks[].skipped（_common 归 stacks[0]），len == 0 用 marker 顶层 skipped（不为 _common 造虚拟 stack 条目，以免破坏「_common 不进 stacks 列表」的约定）。
len == 0 的用途：模板源仓库自身（claude-code-global），或所有 stack 都不合身、但仍想复用 _common 的 stack-无关资源的项目。
前置检查
按顺序，任一失败立即停止并报告：
- 当前目录是 git 仓库（
git rev-parse --is-inside-work-tree）
~/.claude/templates/ 存在且至少含一个 stack 子目录~/.claude/global-repo/ 存在、是指向本仓库的软链、且能跑 git rev-parse HEAD
失败 → 提示用户重跑 bash ~/.claude/global-repo/install.sh 并退出。
模式判断
旧名 marker 自动迁移
marker 文件名在 round 22 由 .cc-template.yml 改为 .agent-template.yml。读 marker 前先查：
- 只有旧名 →
git mv .cc-template.yml .agent-template.yml，并明确告知用户已自动迁移
- 两者同时存在 → 报冲突并停止，请用户手动处理（不猜哪个为准）
废弃 BACKLOG.md 一次性迁移
需求管理已改为「云端 issue 单一真源、无本地索引文件」（见 GLOBAL_AGENTS.md）。老项目遗留的 docs/BACKLOG.md 与云端 open issues 是双写副本，正是新约定要消除的 drift；sync 是「把约定变更落地到老项目」的天然承载点。
项目根无 docs/BACKLOG.md → 跳过本节（绝大多数项目走这里）。有则停下来引导一次性迁移，迁完 git rm 再继续正常 sync：
- 读文件，分出 open 项（
## P0/P1/P2 段，每行本就带云端 issue 链接）与**「刻意不做」项**（## 已完成 / 不再追踪 段，每条带原因）。
- open 项：逐条核对链接指向的 issue 仍 open（
python3 $HOME/.claude/scripts/platform_issue.py issue-view <N>）。都在 → 无需动作（云端已是真源，删文件不丢信息）。某行没有 issue 链接（极老的裸文本条目）→ 提示用户先 /backlog 补成云端 issue 再继续。
- 「刻意不做」项 → 按
/finish Step 2 的同一手法归档为带 wontfix 的 closed issue（body 保留原因文字）。
git rm docs/BACKLOG.md，告知用户：open 项速览改用 saved query，刻意不做项已归档为 wontfix closed issue。- 继续下面的模式判断，把本轮 sync 正常跑完（文件删除会一并进本轮收尾 diff）。
判断模式
读项目根 .agent-template.yml：不存在 → 第 4 节 Adopt；存在 → 第 2 节 Normal sync。
2. Normal sync：解析 marker + 计算变更
2.1 解析 marker
直接 Read、按 YAML 语义读：template_commit（旧 commit hash）、stacks 列表（每条读 stack / path / skipped / variants——variants 可缺省，视作空 map，老项目 bootstrap 时还没这机制）。
校验：各条 path 用其声明值（不再强制 path == .）；同一 marker 内出现重复 stack 名或重复 path → 报错请用户手动修。
2.2 拿当前模板 HEAD
NEW_COMMIT=$(git -C ~/.claude/global-repo rev-parse HEAD)
git -C ~/.claude/global-repo status --porcelain templates/ 非空 → 警告用户「templates 有未提交修改，sync 仅基于 HEAD，未提交内容不会同步」。
2.3 计算模板变更
生效模板源 = marker 里每个 stack 的 templates/<stack>/ + 始终自动应用的 _common/。把所有生效源作为 pathspec 一次性 diff：
git -C ~/.claude/global-repo diff --name-status <old>..<new> -- \
templates/python-uv/ templates/react-vite/ templates/_common/
⚠️ 不要省略 pathspec —— 不传路径会扫全 templates，把项目未接入的其他 stack 的变更也带进来。pathspec 只列 marker 里实际有的 stack。
输出为空 → 报告「模板自上次同步起未变化」，仍继续走 2.5 的 skipped 重检。
2.4 对每个变更文件做四象限分析
先按 diff 路径 templates/<source>/... 判定来源是哪个 stack 或 _common，再按 templates/MECHANICS.md §1 映射到项目侧路径。
读 3 份内容做对比：模板旧版 git -C ~/.claude/global-repo show <old>:templates/<source>/<scope>/<rel>、模板新版（直接读 ~/.claude/templates/...）、项目侧现状（直接 Read）。
| 模板侧 | 项目侧 | 默认建议 |
|---|
| 修改 | 与旧模板一致（未自定义） | take 新模板（clean update） |
| 修改 | 与旧模板不一致（已自定义） | AI 智能 merge：保留用户修改语义 + 引入模板新内容 |
| 新增 | 不存在 | 创建 |
| 新增 | 已存在（罕见） | 询问 take / 保留 / 智能 merge |
| 删除 | 仍存在 | 询问删除 / 保留（用户可能仍需要） |
三类特殊文件按 templates/MECHANICS.md 处理，都不走上表的普通路径：
*.fragment（§2）：永远合并进目标、不落地为同名文件。<target>.variant.<key>（§3）：先看 marker 里该 stack 的 variants[<target>] 记没记选择。有记录 → 只处理选中 key 那份变体与项目侧已落地 <target> 的四象限，其余 key 的 diff 一律忽略（用户没在用）。无记录（老项目）→ 标记「需补选」进 TODO，第 5 节问用户选一个，落地 + 写回 marker。- 迁移去重（§6）：diff 同时出现「删旧的」和「加新的」时，判断二者目标项目路径是否相同，相同则抑制删除提案。
2.5 处理 skipped 持久化语义
skipped 的读写位置按顶部「三态收敛约定」。汇总所有来源的 skipped 后，对每条做「是否又变过」重检：
git -C ~/.claude/global-repo log --oneline <skipped_at_commit>..<new> -- templates/<source>/<file>
输出为空（自 skip 后未变）→ 自动跳过、不进 TODO；非空（又改过）→ 重新进 TODO，标注「上次 skip 在 commit X，之后又改过」。
2.6 输出 TODO 清单
每文件一项：序号 + 文件（来源段）+ 模板侧动作（M/A/D）+ 变化摘要 + 项目侧状态 + 建议动作。
[1] .gitignore （root） M 新增 .ruff_cache/ | 项目侧已自定义(*.bak) → 智能 merge：保留 *.bak + 追加 .ruff_cache/
[2] .github/workflows/lint.yml （root） A | 项目侧不存在 → 创建
跳到第 5 节。
3. Normal sync 无变化退出条件
2.3 输出空 + 2.5 无被重新提案的 skipped 项 + 无需新增/删除的文件 → 报告「无需同步，模板与项目已对齐」并退出，不写 marker。
4. Adopt 模式（无 marker）
4.1–4.2 探测并选 stack
同 /bootstrap 3.1–3.2：列出 ~/.claude/templates/ 下非下划线开头的子目录，按各自 stack.yml 的 default_path 决定落点，让用户勾选 0 个或多个。一个都不选 = 无 stack（只 _common），marker stacks 最终写 []。
4.3 全套用模板（含冲突询问）
把生效源（_common/ + 每个选定 <stack>/）的 __root__/* 与 __subpath__/* 全部当作「待新增」列入 TODO。判断：
- 项目侧不存在 → 建议「创建」
- 项目侧已存在 → 对比内容：完全一致 → 「无需操作（已等价）」；不一致 → 建议智能 merge 或询问 take / 保留 / merge
*.fragment 与变体组按 2.4 的特殊处理（同一 <target> 的多个变体当作一条 TODO「选一个落地」，第 5 节问用户选 key）。含 .github/labels.yml 时额外把「调 helper label-sync-from-file 同步 labels」作为单独一条 TODO。
4.4 / 4.5 可跑化与装依赖
选中含 python-uv / python-uv-workspace → 按 templates/MECHANICS.md §4 走后端可跑化；选中含 react-vite → 按 §5 装前端依赖。都是先问用户确认（默认 yes，给「只要配置不要装依赖」选项）。
adopt 与 bootstrap 的唯一差别：这里 pyproject.toml 更可能已存在（老项目），§4 第 1 步跳过 uv init 是常态。
跳到第 5 节。
5. 用户批量决策
呈现 2.6 / 4.3 的 TODO，让用户给统一指令，例如：
「全部 accept；第 3 条 skip；第 5 条改成全替模板，不要 merge」
解析指令、产出最终执行计划，再次回显（per-file 写出每条最终动作）让用户显式确认后才执行。
6. 执行
按确认后的计划逐条执行：新增写文件、修改/智能 merge 用 Edit/Write 写回、删除删文件；fragment 与变体组按 templates/MECHANICS.md 落地。
label sync 项调 helper（exit 2/3/4 按契约降级、不阻塞其他 accept 项）：
python3 $HOME/.claude/scripts/platform_issue.py label-sync-from-file .github/labels.yml
skip 项在 marker 的 skipped 列表（位置按「三态收敛约定」）记 file / skipped_at_commit: <NEW_COMMIT> / reason。更新策略：已在列表且本次仍 skip → 更新 commit；已在列表但本次 accept（用户改主意）→ 移除；不在列表且本次新 skip → 追加。
6.1 更新 marker
回写 .agent-template.yml：template_commit 更新为 NEW_COMMIT；bootstrap_time 与 source 不动；skipped 按上述策略更新；variants 保留 marker 已有的选择（本次未触及的不动），本次落地 / 补选 / 改选的写进对应 stack。
Adopt 模式额外：bootstrap_time 设为当前 ISO 时间；source 取 git -C ~/.claude/global-repo config --get remote.origin.url（无则填占位）；stacks 按 4.2 的选择写，每条 path 取该 stack 的 default_path。
6.2 收尾反馈
列出实际改动的项目侧文件清单，提示用户：① git diff 自行 review；② 新加入的 .pre-commit-config.yaml 若还没生效，跑 pre-commit install（adopt 的 4.4 已自动做过，normal sync 不做），可选 pre-commit run --all-files 验证；③ 满意后 /commit。
不自动 commit —— 由用户决策（与 /bootstrap、/backlog 一致）。
