Back to Details

sync-template

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: sync-template

Skill: sync-template

WHAT

WHAT

Purpose và context

目的与上下文

  • Purpose: Sync structural/template improvements between project and 
    https://github.com/Rheinmir/setup.git
    .
  • Trigger (when to use):
    • Upstream: Improved template locally → save to Master.
    • Downstream: Master has newer fixes → bring into project.
  • Non-goals: không sync 
    .env
    , credentials, business docs; không tự 
    --strategy pull
    để rút ngắn thời gian; không 
    git clone
    template; không tự kích hoạt (
    disable-model-invocation: true
    ); Antigravity không chạy được skill này (sandbox chặn tool).
  • 目的： 在项目与 
    https://github.com/Rheinmir/setup.git
    之间同步结构性/模板改进。
  • 触发条件（何时使用）：
    • 上游同步： 本地改进了模板 → 保存到 Master。
    • 下游同步： Master 有更新的修复 → 引入项目。
  • 非目标： 不同步 
    .env
    、凭据、业务文档；不自行使用 
    --strategy pull
    来缩短耗时；不 
    git clone
    模板；不自行调用（
    disable-model-invocation: true
    ）；Antigravity 无法运行此 skill（沙箱会阻止工具调用）。

Mental model

心智模型

Downstream mặc định: 
version.json + manifest remote → phân loại hash 3 mốc (disk ↔ R0 remote_synced ↔ remote hiện tại) → NEW/UPDATE tự PULL · KEPT giữ · CONFLICT giữ local + lưu bản remote → OKF backfill → fingerprint → cài skill 3 chỗ → verify 3 vị trí → log
. Upstream / migrate / debug đi MANUAL STEPS 0–8 với điểm STOP hỏi user ở Step 5.
下游默认路径：
version.json
+ manifest 中的 remote 信息 → 按哈希划出三个基准点（磁盘 ↔ R0 
remote_synced
↔ 当前 remote）→ NEW/UPDATE 自动 PULL · KEPT 保持不变 · CONFLICT 保留 local + 保存 remote 版本 → OKF backfill → fingerprint → 将 skill 安装到 3 个位置 → 验证 3 个位置 → log。上游同步、迁移或 debug 进入 MANUAL STEPS 0–8，并在 Step 5 停下询问用户。

Input và output contract

输入与输出约定

FieldRequired?Ý nghĩa
Inhướng synccódownstream (mặc định, FAST PATH) hoặc upstream (MANUAL)
In
.template-manifest.json
+ 
harness/version.json
cóinclusion list, remote URL, 
branch
, 
remote_synced
In
--branch
, 
--strategy pull
, 
--dry-run
, 
--json
khôngđổi branch, lấy remote cho CONFLICT, xem trước, output máy đọc
Inquyết định userkhi CONFLICT hoặc Step 5lấy remote hay giữ local; pull/push file nào
Outfile template đã sync + OKF backfillcófile wiki cũ convert bold→YAML
Out
harness/version.json
refresh		cófingerprint sau OKF + 
template_version
+ 
remote_synced
Outskill cài ở 
.claude/commands/
, 
~/.claude/skills/
, 
~/.claude/commands/
downstreamverify 3 vị trí
Outreport + exit codecó0 sạch, 1 lỗi tải/OKF/verify, 3 CONFLICT cần quyết
Outdòng 
wiki/log.md
+ draft output report		cóscript tự ghi log khi 
--full
字段是否必需含义
输入同步方向是downstream（默认，FAST PATH）或 upstream（MANUAL）
输入
.template-manifest.json
+ 
harness/version.json
是包含列表、remote URL、
branch
、
remote_synced
输入
--branch
、
--strategy pull
、
--dry-run
、
--json
否切换 branch、在 CONFLICT 时获取 remote、预览、输出机器可读结果
输入用户决策CONFLICT 或 Step 5 时获取 remote 还是保留 local；pull/push 哪些文件
输出已同步的模板文件 + OKF backfill是将旧 wiki 文件从 bold 转换为 YAML
输出刷新后的 
harness/version.json
是OKF 后的 fingerprint + 
template_version
+ 
remote_synced
输出安装在 
.claude/commands/
、
~/.claude/skills/
、
~/.claude/commands/
的 skill		下游同步时验证 3 个位置
输出report + exit code是0 表示干净，1 表示下载/OKF/verify 错误，3 表示 CONFLICT 需要决策
输出
wiki/log.md
行记录 + 草稿输出报告		是使用 
--full
时 script 自动写 log

Rules và capabilities

规则与能力

  • RULE-01 (MUST): NEVER sync 
    .env
    , credentials, business docs.
  • RULE-02 (MUST): ALWAYS audit remote branches — non-default may be newest.
  • RULE-03 (MUST): ALWAYS show diff for 
    [CONFLICT]
    → wait for instruction.
  • RULE-04 (MUST): NEVER 
    cp -R
    — file by file.
  • RULE-05 (MUST): Step 3 every sync — detect old 
    skills/
    , offer migrate.
  • RULE-06 (MUST): Step 7 every downstream sync — install all 3 Claude Code locations.
  • RULE-07 (MUST): 
    [NEW]
    : add to manifest BEFORE upstream commit.
  • RULE-08 (MUST): 
    [MISSING]
    : add to manifest AFTER downstream copy.
  • RULE-09 (MUST): Frontmatter: 
    name:
    + 
    description:
    for skills; 
    description:
    only for slash commands.
  • RULE-10 (MUST): Skip 
    README.md
    , 
    index.md
    , 
    log.md
    , no-Purpose/Steps files.
  • Capabilities: đọc remote template (HTTP/GitHub API); ghi file trong project + thư mục skill/command cấp user; đẩy lên remote template khi upstream (chỉ sau duyệt).
  • RULE-01（必须）：绝不同步 
    .env
    、凭据、业务文档。
  • RULE-02（必须）：始终审计 remote branches——非默认 branch 可能是最新的。
  • RULE-03（必须）：始终为 
    [CONFLICT]
    显示 diff → 等待指示。
  • RULE-04（必须）：绝不执行 
    cp -R
    ——必须逐文件处理。
  • RULE-05（必须）：每次同步都要执行 Step 3——检测旧 
    skills/
    ，并提供迁移选项。
  • RULE-06（必须）：每次下游同步都要执行 Step 7——安装到全部 3 个 Claude Code 位置。
  • RULE-07（必须）：
    [NEW]
    ：在上游 commit 前加入 manifest。
  • RULE-08（必须）：
    [MISSING]
    ：在下游复制后加入 manifest。
  • RULE-09（必须）：Frontmatter：skill 必须包含 
    name:
    + 
    description:
    ；slash command 只需 
    description:
    。
  • RULE-10（必须）：跳过 
    README.md
    、
    index.md
    、
    log.md
    以及没有 
    ## Purpose
    /
    ## Steps
    的文件。
  • 能力：通过 HTTP/GitHub API 读取 remote 模板；写入项目文件及用户级 skill/command 目录；在上游同步时将变更推送到 remote 模板（仅在获批后执行）。

Failure boundaries

失败边界

  • CONFLICT (cả hai cùng đổi) → giữ local, lưu bản remote ra 
    /tmp/sync-template-conflicts/
    , exit 3 → clarify với user.
  • Lỗi tải / OKF / verify → exit 1 → failed, sửa 
    ✗
    trước khi xong.
  • Branch remote không rõ cái nào mới nhất → clarify, hỏi user branch nào.
  • health-check 
    OK
    → không cần sync, dừng (succeeded no-op).
  • Old 
    skills/
    layout → đề xuất migrate, confirm trước khi xoá.
  • CONFLICT（双方均有更改）→ 保留 local，将 remote 版本保存到 
    /tmp/sync-template-conflicts/
    ，exit 3 → 向用户澄清（clarify）。
  • 下载/OKF/verify 错误 → exit 1 → 失败（failed）；完成前必须修复 
    ✗
    。
  • 无法确定哪个 remote branch 更新 → 向用户澄清（clarify），询问用户选择哪个 branch。
  • health-check 
    OK
    → 无需同步，停止（成功（succeeded），no-op）。
  • 旧 
    skills/
    布局 → 建议迁移，删除前必须确认（confirm）。

HOW

HOW

Main workflow

主工作流

StepTypeInputsActionOutputs/exitFailure/next
W01judgmentyêu cầuChọn đường: downstream thường → FAST PATH 
--full
; upstream, migrate cấu trúc cũ, debug → MANUAL (B01)		đường đi—
W02effectmanifest, remote
python3 harness/scripts/sync-template.py --full
MỘT lần (sync + OKF + fingerprint + cài 3 chỗ + verify + log)		reportexit 1 → failed; exit 3 → W03
W03judgmentreportĐọc report; CONFLICT muốn lấy remote → chạy lại 
--strategy pull
; branch khác → 
--branch
quyết địnhkhông rõ → hỏi user
W04deterministicreportKhông gọi thêm okf-check, health-check, vòng verify, không tự sửa logbáo cáo cho user—
W05effectkết quảOutput Report draftdraft + index + log0 artefact → skip
Chi tiết từng bước (nguồn chân lý cho W01–W05 và nhánh MANUAL):
步骤类型输入操作输出/exit失败/下一步
W01判断用户请求选择路径：通常走下游 → FAST PATH 
--full
；上游、旧结构迁移或 debug → MANUAL（B01）		所选路径—
W02执行manifest、remote仅执行一次 
python3 harness/scripts/sync-template.py --full
（sync + OKF + fingerprint + 安装到 3 处 + verify + log）		reportexit 1 → failed；exit 3 → W03
W03判断report读取 report；CONFLICT 且希望获取 remote → 再次运行 
--strategy pull
；branch 不同 → 
--branch
决策不明确 → 询问用户
W04确定性处理report不再调用额外的 okf-check、health-check、verify 循环，也不自行修改 log向用户报告—
W05执行结果输出 Report 草稿draft + index + log0 个产物 → 跳过
各步骤明细（W01–W05 及 MANUAL 分支的事实来源）：

FAST PATH — downstream 1 lệnh 
--full
(< 30s, mặc định)

FAST PATH——下游单条 
--full
命令（< 30s，默认）

Downstream sync là 1 script non-interactive tự chứa. Gọi 1 lần với 
--full
→ mọi bước hậu-sync (Step 6a/6b/8 + ghi log) chạy trong CÙNG process. Agent đọc 1 report rồi báo cáo — KHÔNG lặp lại lệnh riêng. Bench repo này: full steady-state 0.27s · full pull+install+verify 0.76s (
harness/metrics/sync-template-bench.json
).
bash
python3 harness/scripts/sync-template.py --full        # ⭐ MẶC ĐỊNH: sync + OKF backfill + fingerprint + verify ×3 + ghi log, 1 process
python3 harness/scripts/sync-template.py --full --json  # như trên, output máy đọc (đọc okf_migrated / verify_bad)
python3 harness/scripts/sync-template.py --dry-run      # xem trước, không ghi (kèm --full để xem OKF sẽ migrate gì)
python3 harness/scripts/sync-template.py --strategy pull # ghi đè cả CONFLICT bằng remote (backup .local-bak)
Chạy 
--full
1 lần là xong — đừng gọi tiếp 
okf-check
, 
health-check --update
, vòng verify, hay tự 
Edit
log.md (script đã làm hết). Đó là cách giữ skill dưới 30s: nút thắt cũ là số round-trip agent quanh các bước hậu-sync, không phải CPU. Không cờ 
--full
= hành vi cũ y nguyên.
Phân loại bằng hash 3 mốc — disk ↔ R0 (remote tại lần sync trước, lưu ở 
version.json:remote_synced
) ↔ remote hiện tại:
  • NEW
    (thiếu local) + 
    UPDATE
    (remote mới hơn, local chưa đụng) → tự PULL.
  • KEPT
    (mình đã custom, remote không mới hơn) → giữ nguyên, không hỏi.
  • CONFLICT
    (cả hai cùng đổi) → mặc định giữ local + lưu bản remote ra 
    /tmp/sync-template-conflicts/
    để diff; exit code 3. Không bao giờ tự 
    --strategy pull
    để rút ngắn thời gian.
Quy trình tự động trong script (
--full
): fetch remote 
version.json
+
manifest
→ phân loại → tải song song → OKF backfill in-process (migrate bold→YAML, idempotent) → refresh 
version.json
(fingerprint SAU OKF + 
template_version
+ 
remote_synced
) → cài skill ra 3 chỗ (
.claude/commands/
, 
~/.claude/skills/
, 
~/.claude/commands/
) → self-verify 3 vị trí → append 
wiki/log.md
. Exit: 0 sạch · 1 lỗi tải/OKF/verify · 3 CONFLICT cần quyết.
Khi nào CẦN can thiệp tay (chạy script trước, đọc report):
  • Report có 
    CONFLICT
    và bạn muốn lấy remote → chạy lại 
    --strategy pull
    (1 quyết định, không phải 3).
  • Branch remote KHÁC 
    version.json:branch
    → 
    --branch <tên>
    (xem Step 2 để audit branch).
  • Cấu trúc 
    skills/
    cũ cần migrate (Step 3), hoặc cần upstream (đẩy lên) → dùng MANUAL STEPS bên dưới.
⚠ Bug đã fix: 
health-check --update
đặt baseline = disk → sync KHÔNG phân biệt được "remote mới" vs "mình đã custom" → suýt ghi đè file custom. Script này dùng baseline riêng 
remote_synced
(hash remote tại lần sync) nên phân biệt đúng. Đừng quay lại dùng 
patterns
(disk) làm baseline phân loại.
下游同步是 1 个自包含的非交互式 script。仅调用 1 次 
--full
→ 所有同步后步骤（Step 6a/6b/8 + 写 log）都在同一进程中运行。Agent 读取 1 份 report 后再汇报——不要重复执行单独命令。本基准 repo 的耗时：full steady-state 0.27s · full pull+install+verify 0.76s（
harness/metrics/sync-template-bench.json
）。
bash
python3 harness/scripts/sync-template.py --full        # ⭐ MẶC ĐỊNH: sync + OKF backfill + fingerprint + verify ×3 + ghi log, 1 process
python3 harness/scripts/sync-template.py --full --json  # như trên, output máy đọc (đọc okf_migrated / verify_bad)
python3 harness/scripts/sync-template.py --dry-run      # xem trước, không ghi (kèm --full để xem OKF sẽ migrate gì)
python3 harness/scripts/sync-template.py --strategy pull # ghi đè cả CONFLICT bằng remote (backup .local-bak)
运行 
--full
1 次即完成——不要继续调用 
okf-check
、
health-check --update
、verify 循环，也不要自行 
Edit
log.md（script 已全部处理）。这是将 skill 控制在 30s 内的方式：旧瓶颈是同步后步骤周围的 agent round-trip 次数，而不是 CPU。不传 
--full
= 行为与旧版完全相同。
按哈希进行三基准点分类——磁盘 ↔ R0（上次同步时的 remote，保存在 
version.json:remote_synced
中）↔ 当前 remote：
  • NEW
    （local 缺失）+ 
    UPDATE
    （remote 较新，local 尚未改动）→ 自动 PULL。
  • KEPT
    （local 已自定义，remote 没有更新）→ 保持不变，无需询问。
  • CONFLICT
    （双方均发生更改）→ 默认保留 local + 将 remote 版本保存到 
    /tmp/sync-template-conflicts/
    以供 diff；exit code 3。绝不自行使用 
    --strategy pull
    来缩短耗时。
script 中的自动流程（
--full
）：获取 remote 的 
version.json
+ manifest → 分类 → 并行下载 → 在进程内执行 OKF backfill（将 bold 迁移为 YAML，幂等）→ 刷新 
version.json
（OKF 后的 fingerprint + 
template_version
+ 
remote_synced
）→ 将 skill 安装到 3 个位置（
.claude/commands/
、
~/.claude/skills/
、
~/.claude/commands/
）→ 自行验证 3 个位置→ 追加 
wiki/log.md
。Exit：0 表示干净 · 1 表示下载/OKF/verify 错误 · 3 表示 CONFLICT 需要决策。
何时需要手动介入（先运行 script，再读取 report）：
  • Report 中有 
    CONFLICT
    ，且希望获取 remote → 再次运行 
    --strategy pull
    （只需 1 次决策，不是 3 次）。
  • Remote branch 与 
    version.json:branch
    不同 → 
    --branch <tên>
    （参见 Step 2 的 branch 审计）。
  • 旧 
    skills/
    结构需要迁移（Step 3），或需要执行 upstream（推送）→ 使用下方的 MANUAL STEPS。
⚠ 已修复的 Bug：
health-check --update
会将 baseline 设为 disk → sync 无法区分“remote 有新内容”和“local 已自定义”→ 险些覆盖自定义文件。本 script 使用独立的 
remote_synced
baseline（上次同步时 remote 的哈希），因此能够正确区分。不要重新使用 
patterns
（disk）作为分类 baseline。

MANUAL STEPS (fallback — upstream, migrate cấu trúc cũ, hoặc debug)

MANUAL STEPS（fallback——upstream、旧结构迁移或 debug）

Step 0: Pre-flight — health-check (chẩn đoán trước khi sync)
Step 0：预检——health-check（同步前诊断）
Chạy 
/health-check
(
python3 harness/scripts/health-check.py --root .
) để biết NÊN sync hướng nào:
  • NEEDS-SYNC
    (behind/missing) → downstream (kéo về).
  • DRIFT
    (đã sửa local) → upstream (đẩy lên) hoặc revert.
  • OK
    → không cần sync, dừng.
运行 
/health-check
（
python3 harness/scripts/health-check.py --root .
），确定应该采用哪个同步方向：
  • NEEDS-SYNC
    （落后/缺失）→ 下游同步（拉取到项目）。
  • DRIFT
    （已修改 local）→ 上游同步（推送）或 revert。
  • OK
    → 无需同步，停止。
Step 1: Load Manifest
Step 1：加载 Manifest
Read 
.template-manifest.json
— inclusion list + remote URL.
读取 
.template-manifest.json
——其中包含包含列表 + remote URL。
Step 2: Fetch & Branch Audit
Step 2：获取与 Branch 审计
  • CRITICAL: List all remote branches: 
    gh api repos/<owner>/<repo>/branches
    .
  • Check commit date per branch — don't assume 
    master
    /
    main
    is newest.
  • Unclear → ask user which branch.
  • Fetch via 
    gh api
    + 
    curl
    — no 
    git clone
    .
  • 关键操作： 列出所有 remote branches：
    gh api repos/<owner>/<repo>/branches
    。
  • 检查每个 branch 的 commit date——不要假定 
    master
    /
    main
    最新。
  • 不明确 → 询问用户选择哪个 branch。
  • 通过 
    gh api
    + 
    curl
    获取——不要 
    git clone
    。
Step 3: Detect Old Structure Migration
Step 3：检测旧结构迁移
Check for old 
skills/
layout needing migration to 
llmwiki/
:
bash
undefined
检查是否存在需要迁移到 
llmwiki/
的旧 
skills/
布局：
bash
undefined

Signs of old structure:

Signs of old structure:

[ -d "skills/" ] && [ ! -d "llmwiki/skills/" ] # old only [ -d "skills/" ] && [ -d "llmwiki/skills/" ] # both exist → migration in progress

**Old `skills/` + new `llmwiki/skills/` coexist:**
1. List `skills/` (flat .md + subdirs: `dev-loop/`, `wiki-loop/`, etc.)
2. Map old → new:
   - `skills/dev-loop/*.md`   → `llmwiki/skills/dev-loop/*.md`
   - `skills/wiki-loop/*.md`  → `llmwiki/skills/wiki-loop/*.md`
   - `skills/orchestrate/*.md`→ `llmwiki/skills/orchestrate/*.md`
   - `skills/utils/*.md`      → `llmwiki/skills/utils/*.md`
   - `skills/*.md` (flat)     → already covered by subdirs, skip duplicates
3. Content matches → old stale, safe to remove.
4. Show migration table → confirm before delete.
[ -d "skills/" ] && [ ! -d "llmwiki/skills/" ] # old only [ -d "skills/" ] && [ -d "llmwiki/skills/" ] # both exist → migration in progress

**旧 `skills/` 与新 `llmwiki/skills/` 共存：**
1. 列出 `skills/`（平铺的 .md + 子目录：`dev-loop/`、`wiki-loop/` 等）。
2. 映射旧路径 → 新路径：
   - `skills/dev-loop/*.md`   → `llmwiki/skills/dev-loop/*.md`
   - `skills/wiki-loop/*.md`  → `llmwiki/skills/wiki-loop/*.md`
   - `skills/orchestrate/*.md`→ `llmwiki/skills/orchestrate/*.md`
   - `skills/utils/*.md`      → `llmwiki/skills/utils/*.md`
   - `skills/*.md`（平铺）     → 已由子目录覆盖，跳过重复项
3. 内容一致 → 旧文件已过期，可以安全删除。
4. 显示迁移表 → 删除前确认。
Step 4: Compare Manifest Files
Step 4：比较 Manifest 文件
diff
local vs remote for each file in 
includes
:
bash
BASE="https://raw.githubusercontent.com/<owner>/<repo>/<branch>"
for file in <includes>; do
  http_code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/$file")
  # SAME / DIFF / MISSING / NEW / ABSENT
done
Status:
  • SAME
    — skip
  • DIFF
    — content differs
  • MISSING
    — remote only → downstream candidate
  • NEW
    — local only → upstream candidate
  • ABSENT
    — neither
对 
includes
中的每个文件执行 local 与 remote 的 
diff
：
bash
BASE="https://raw.githubusercontent.com/<owner>/<repo>/<branch>"
for file in <includes>; do
  http_code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/$file")
  # SAME / DIFF / MISSING / NEW / ABSENT
done
状态：
  • SAME
    ——跳过。
  • DIFF
    ——内容不同。
  • MISSING
    ——仅 remote 存在 → 下游候选。
  • NEW
    ——仅 local 存在 → 上游候选。
  • ABSENT
    ——两者均不存在。
Step 5: Sync Plan
Step 5：同步计划
Show table. STOP → ask user: pull all / push all / specific files / direction per DIFF.
显示表格。STOP → 询问用户：全部 pull / 全部 push / 指定文件 / 对每个 DIFF 分别指定方向。
Step 6: Execute
Step 6：执行
  • Downstream: 
    mkdir -p
    → 
    curl -sfL <url> -o <local_path>
    → update 
    wiki/log.md
  • Upstream: commit + push via 
    gh
    /
    git
  • File by file — no 
    cp -R
Step 6a/6b/8 đã GỘP vào 
--full
. Nếu bạn chạy FAST PATH 
--full
thì BỎ QUA 6a/6b/8 — script đã OKF-backfill + refresh fingerprint + verify + ghi log trong process. Các bước dưới chỉ dùng khi chạy MANUAL (debug / upstream / migrate cấu trúc cũ), không phải sau 
--full
.
  • 下游： 
    mkdir -p
    → 
    curl -sfL <url> -o <local_path>
    → 更新 
    wiki/log.md
    。
  • 上游： 通过 
    gh
    /
    git
    commit + push。
  • 逐文件处理——不要使用 
    cp -R
    。
Step 6a/6b/8 已合并到 
--full
。 如果运行 FAST PATH 
--full
，请跳过 6a/6b/8——script 已在同一进程内完成 OKF-backfill + 刷新 fingerprint + verify + 写 log。以下步骤仅用于 MANUAL（debug / upstream / 旧结构迁移），不应在 
--full
之后执行。
Step 6a: OKF backfill (MANUAL — 
--full
đã làm)
Step 6a：OKF backfill （MANUAL——
--full
已完成）
Template/skill mới có thể nâng định dạng wiki (vd chuẩn OKF v0.1). Sau khi pull, convert mọi file content cũ còn dùng pseudo-frontmatter dạng bold 
**Type:**
sang YAML frontmatter để khỏi vướng R9:
bash
python3 harness/scripts/okf-check.py --check      # exit 3 = có file chưa đạt OKF
python3 harness/scripts/okf-check.py --migrate    # convert bold → YAML (chỉ THÊM frontmatter, giữ body/## Origin)
  • Idempotent — file đã có 
    ---
    frontmatter được bỏ qua. Reserved (index/log/README/decisions/_template…) tự miễn.
  • Sau migrate: chạy lại 
    --check
    đến khi 
    DAT CHUAN OKF v0.1
    , rồi cập nhật index/log như mọi thay đổi wiki.
新的 template/skill 可能提升 wiki 格式标准（例如采用 OKF v0.1）。pull 后，将所有仍使用 
**Type:**
形式 pseudo-frontmatter 的旧 content 文件转换为 YAML frontmatter，以避免违反 R9：
bash
python3 harness/scripts/okf-check.py --check      # exit 3 = có file chưa đạt OKF
python3 harness/scripts/okf-check.py --migrate    # convert bold → YAML (chỉ THÊM frontmatter, giữ body/## Origin)
  • 幂等——已有 
    ---
    frontmatter 的文件会被跳过。Reserved 文件（index/log/README/decisions/_template…）自动豁免。
  • 迁移后：再次运行 
    --check
    ，直至输出 
    DAT CHUAN OKF v0.1
    ，然后像更新其他 wiki 变更一样更新 index/log。
Step 6b: Refresh version fingerprint (MANUAL — 
--full
đã làm)
Step 6b：刷新版本指纹 （MANUAL——
--full
已完成）
Nội dung pattern vừa đổi → cập nhật lại 
harness/version.json
để health-check khỏi báo DRIFT giả:
bash
python3 harness/scripts/health-check.py --update   # KHÔNG --bump ở project con
  • --bump major|minor|patch
    CHỈ chạy ở repo template 
    Rheinmir/setup
    khi PHÁT HÀNH version pattern mới.
  • Upstream sync ở repo template: sau khi push, chạy 
    --update --bump <part>
    rồi commit 
    harness/version.json
    .
刚刚修改了 pattern 内容 → 再次更新 
harness/version.json
，避免 health-check 报告虚假的 DRIFT：
bash
python3 harness/scripts/health-check.py --update   # KHÔNG --bump ở project con
  • --bump major|minor|patch
    仅在 
    Rheinmir/setup
    模板 repo 发布新 pattern 版本时运行。
  • 在模板 repo 中执行上游同步时：push 后运行 
    --update --bump <part>
    ，然后 commit 
    harness/version.json
    。
Step 7: Install as Native Skills (runs every downstream sync)
Step 7：安装为原生 Skills （每次下游同步都会运行）
Collect skill files synced (under 
llmwiki/skills/
in manifest). Skip: 
README.md
, 
index.md
, 
log.md
, no-
## Purpose
/
## Steps
files.
A. Project-level (
.claude/commands/
— this repo):
bash
mkdir -p .claude/commands/
收集 manifest 中已同步的 skill 文件（位于 
llmwiki/skills/
下）。跳过：
README.md
、
index.md
、
log.md
以及没有 
## Purpose
/
## Steps
的文件。
A. 项目级（
.claude/commands/
——本 repo）：
bash
mkdir -p .claude/commands/

Add description: frontmatter if missing, then copy

Add description: frontmatter if missing, then copy

printf -- "---\ndescription: %s\n---\n\n" "$desc" | cat - <src> > .claude/commands/<name>.md

**B. Global user-level** (`~/.claude/skills/<name>/SKILL.md` — all projects):
```bash
mkdir -p ~/.claude/skills/<name>/
printf -- "---\ndescription: %s\n---\n\n" "$desc" | cat - <src> > .claude/commands/<name>.md

**B. 全局用户级**（`~/.claude/skills/<name>/SKILL.md`——适用于所有项目）：
```bash
mkdir -p ~/.claude/skills/<name>/

Requires name: + description: frontmatter

Requires name: + description: frontmatter

printf -- "---\nname: %s\ndescription: %s\n---\n\n" "$name" "$desc" | cat - <src> > ~/.claude/skills/<name>/SKILL.md

**C. Global slash command** (`~/.claude/commands/<name>.md`):
```bash
printf -- "---\ndescription: %s\n---\n\n" "$desc" | cat - <src> > ~/.claude/commands/<name>.md
Install cả 3. Report:
| Skill          | Project .claude/commands/ | ~/.claude/skills/ | ~/.claude/commands/ |
|----------------|---------------------------|-------------------|---------------------|
| propose        | ✓                         | ✓                 | ✓                   |
| ingest         | ✓                         | ✓                 | ✓                   |
| ...            | ...                       | ...               | ...                 |
printf -- "---\nname: %s\ndescription: %s\n---\n\n" "$name" "$desc" | cat - <src> > ~/.claude/skills/<name>/SKILL.md

**C. 全局 slash command**（`~/.claude/commands/<name>.md`）：
```bash
printf -- "---\ndescription: %s\n---\n\n" "$desc" | cat - <src> > ~/.claude/commands/<name>.md
全部安装 3 处。报告：
| Skill          | Project .claude/commands/ | ~/.claude/skills/ | ~/.claude/commands/ |
|----------------|---------------------------|-------------------|---------------------|
| propose        | ✓                         | ✓                 | ✓                   |
| ingest         | ✓                         | ✓                 | ✓                   |
| ...            | ...                       | ...               | ...                 |
Step 8: Verify & Finalize
Step 8：验证与完成
bash
for name in <skill-list>; do
  [ -f ".claude/commands/$name.md" ]          && echo "✓ proj  $name" || echo "✗ proj  $name"
  [ -f "$HOME/.claude/skills/$name/SKILL.md" ] && echo "✓ global $name" || echo "✗ global $name"
done
Fix 
✗
before done. No restart needed.
bash
for name in <skill-list>; do
  [ -f ".claude/commands/$name.md" ]          && echo "✓ proj  $name" || echo "✗ proj  $name"
  [ -f "$HOME/.claude/skills/$name/SKILL.md" ] && echo "✓ global $name" || echo "✗ global $name"
done
完成前修复所有 
✗
。无需重启。

Branches

Branches

IDKindGuardHành viSkip / failureRejoin
B01conditional_requiredcần upstream, migrate cấu trúc 
skills/
cũ, hoặc debug		chạy MANUAL STEPS 0–8, STOP hỏi user ở Step 5downstream thường → FAST PATHW05
B02recoveryexit 3 CONFLICT và user chọn lấy remotechạy lại 
--strategy pull
(ghi đè, backup 
.local-bak
)		user giữ local → không làm gìW04
B03conditional_requiredbranch remote khác 
version.json:branch
--branch <tên>
sau khi audit branch (Step 2)		—W02
B04user_optionalmuốn xem trước
--dry-run
(kèm 
--full
để xem OKF sẽ migrate gì)		—W02
B05conditional_requiredphát hiện old 
skills/
layout (Step 3)		hiện bảng migration, confirm rồi mới xoáuser từ chối → giữW05
ID类型守卫条件行为跳过/失败汇合点
B01conditional_required需要 upstream、迁移旧 
skills/
结构或 debug		运行 MANUAL STEPS 0–8，在 Step 5 STOP 并询问用户通常的 downstream → FAST PATHW05
B02recoveryexit 3 CONFLICT 且用户选择获取 remote再次运行 
--strategy pull
（覆盖并备份 
.local-bak
）		用户保留 local → 不执行任何操作W04
B03conditional_requiredremote branch 与 
version.json:branch
不同		审计 branch（Step 2）后使用 
--branch <tên>
—W02
B04user_optional希望预览
--dry-run
（配合 
--full
可预览 OKF 将迁移的内容）		—W02
B05conditional_required检测到旧 
skills/
布局（Step 3）		显示迁移表，确认后才删除用户拒绝 → 保留W05

Validation và stopping

验证与停止条件

Tất định: exit code script (0/1/3), self-verify 3 vị trí cài, 
okf-check.py --check
ra 
DAT CHUAN OKF v0.1
(MANUAL), vòng 
[ -f … ]
Step 8 không còn 
✗
. Dừng sau MỘT lần 
--full
khi exit 0; exit 3 dừng chờ user quyết; MANUAL dừng ở Step 5 chờ duyệt.
确定性条件：script exit code（0/1/3）、自行验证 3 个安装位置、
okf-check.py --check
输出 
DAT CHUAN OKF v0.1
（MANUAL）、Step 8 的 
[ -f … ]
验证循环中不再出现 
✗
。一次 
--full
返回 exit 0 后立即停止；exit 3 时停止并等待用户决策；MANUAL 在 Step 5 停止并等待批准。

Examples

示例

  • Positive: project con, Master có fix mới → 
    python3 harness/scripts/sync-template.py --full
    → 2 UPDATE tự PULL, 1 KEPT giữ nguyên, OKF migrate 3 file, verify 3 vị trí ✓, exit 0 trong < 1s → báo report, không chạy thêm lệnh nào.
  • Boundary/failure: file 
    llmwiki/skills/dev-loop/ship.md
    sửa ở cả local và remote → CONFLICT, giữ local, bản remote ở 
    /tmp/sync-template-conflicts/
    , exit 3 → hiện diff, chờ user; không tự 
    --strategy pull
    .
  • 正向示例： 子项目，Master 有新修复 → 
    python3 harness/scripts/sync-template.py --full
    → 2 个 UPDATE 自动 PULL，1 个 KEPT 保持不变，迁移 3 个 OKF 文件，验证 3 个位置 ✓，exit 0 且耗时 < 1s → 输出 report，不再运行其他命令。
  • 边界/失败示例： 
    llmwiki/skills/dev-loop/ship.md
    在 local 和 remote 中均被修改 → CONFLICT，保留 local，remote 版本保存到 
    /tmp/sync-template-conflicts/
    ，exit 3 → 显示 diff 并等待用户；不自行使用 
    --strategy pull
    。

Reference — Agent Compatibility

参考——Agent 兼容性

AgentRun?Reason
Claude CodeYesFull tool access
OpenCodeYesFull tool access
AntigravityNoSandbox blocks file/command tools
Agent可运行？原因
Claude CodeYes拥有完整工具访问权限
OpenCodeYes拥有完整工具访问权限
AntigravityNo沙箱阻止文件/命令工具

Delivery — Output Report

交付——输出报告

After all main skill tasks complete, write a propose draft to the wiki.
所有主 skill 任务完成后，向 wiki 写入一份 propose 草稿。

Steps

Steps

1. Build the filename:
  • Format: 
    DDMMYY-<ten>.md
  • DDMMYY
    = today (e.g., 
    020626
    for 2 June 2026)
  • <ten>
    = 2–4 kebab-case words summarising what was done (e.g., 
    landing-page-coteccons
    , 
    brand-kit-fintech
    , 
    ingest-auth-spec
    )
2. Write 
llmwiki/wiki/sources/draft/DDMMYY-<ten>.md
:
---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---
1. 构建文件名：
  • 格式：
    DDMMYY-<ten>.md
  • DDMMYY
    = 当天日期（例如，2026 年 6 月 2 日对应 
    020626
    ）
  • <ten>
    = 2–4 个概括所完成工作的 kebab-case 单词（例如 
    landing-page-coteccons
    、
    brand-kit-fintech
    、
    ingest-auth-spec
    ）
2. 写入 
llmwiki/wiki/sources/draft/DDMMYY-<ten>.md
：
---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

DDMMYY-<ten>

DDMMYY-<ten>

Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD
Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD

What

What

<One sentence — what this skill invocation produced or decided>
<One sentence — what this skill invocation produced or decided>

Output

Output

<Key artefacts, files created/modified, or decisions made>
<Key artefacts, files created/modified, or decisions made>

Files

Files

FileAction
path/to/file
created / modified
FileAction
path/to/file
created / modified

Notes

Notes

  • Invoked via: 
    /<skill-name>
    skill
  • Invoked via: 
    /<skill-name>
    skill

Origin

Origin

  • Draft: 
    wiki/sources/draft/DDMMYY-<ten>.md
  • Commit: (filled by verify-before-commit)
  • Date promoted: (filled by verify-before-commit)

**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append one row: `| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — <skill-name> — <ten>`

> Skip only when the skill produces zero artefacts and zero decisions (e.g., a pure display mode like `/caveman-stats`).
  • Draft: 
    wiki/sources/draft/DDMMYY-<ten>.md
  • Commit: (filled by verify-before-commit)
  • Date promoted: (filled by verify-before-commit)

**3. 更新 wiki index 与 log：**
- `llmwiki/wiki/index.md`——追加一行：`| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md`——追加：`## YYYY-MM-DD — <skill-name> — <ten>`

> 仅当 skill 产生 0 个产物且做出 0 项决策时跳过（例如 `/caveman-stats` 这类纯展示模式）。