sync-template

スキル：sync-template

概要

目的とコンテキスト

• 目的： プロジェクトと https://github.com/Rheinmir/setup.git の間で、構造やテンプレートの改善を同期します。
• 使用するタイミング：
  • アップストリーム： テンプレートをローカルで改善した場合 → Master に保存します。
  • ダウンストリーム： Master に新しい修正がある場合 → プロジェクトに取り込みます。
• 対象外： .env、認証情報、業務ドキュメントは同期しません。時間短縮のために --strategy pull を自動で指定しません。テンプレートを git clone しません。自動では起動しません（disable-model-invocation: true）。Antigravity ではサンドボックスがツールをブロックするため、このスキルを実行できません。

メンタルモデル

ダウンストリームのデフォルト：version.json + manifest remote → 3つのハッシュ基準を分類（disk ↔ R0 remote_synced ↔ remote 現在）→ NEW/UPDATE は自動で PULL · KEPT は維持 · CONFLICT はローカルを維持し、リモート版を保存 → OKF backfill → fingerprint → スキルを3か所にインストール → 3つの場所を検証 → log。アップストリーム／移行／デバッグでは、Step 5 でユーザーに確認して STOP する箇所を設けた MANUAL STEPS 0–8 を実行します。

入出力の契約

	Field	必須？	意味
In	同期の方向	はい	ダウンストリーム（デフォルト、FAST PATH）またはアップストリーム（MANUAL）
In	.template-manifest.json + harness/version.json	はい	inclusion list、remote URL、branch、remote_synced
In	--branch、--strategy pull、--dry-run、--json	いいえ	ブランチの変更、CONFLICT 時にリモートを取得、プレビュー、機械可読形式で出力
In	ユーザーの判断	CONFLICT または Step 5 の場合	リモートを取得するかローカルを維持するか、どのファイルを pull/push するか
Out	同期済みのテンプレートファイル + OKF backfill	はい	古い wiki ファイルの bold を YAML に変換
Out	harness/version.json の更新	はい	OKF 後の fingerprint + template_version + remote_synced
Out	.claude/commands/、~/.claude/skills/、~/.claude/commands/ にインストールされたスキル	ダウンストリーム	3つの場所を検証
Out	レポート + 終了コード	はい	0 は問題なし、1 はダウンロード／OKF／検証エラー、3 は判断が必要な CONFLICT
Out	wiki/log.md の1行 + レポートのドラフト出力	はい	--full の場合、スクリプトがログを自動記録

ルールと機能

• RULE-01（必須）：.env、認証情報、業務ドキュメントは絶対に同期しません。
• RULE-02（必須）：リモートブランチを必ず監査します。デフォルト以外のブランチが最新の場合があります。
• RULE-03（必須）：[CONFLICT] の diff を必ず表示し、指示を待ちます。
• RULE-04（必須）：cp -R は絶対に使用しません。ファイルごとに処理します。
• RULE-05（必須）：同期のたびに Step 3 を実行し、古い skills/ を検出したら移行を提案します。
• RULE-06（必須）：ダウンストリーム同期のたびに Step 7 を実行し、Claude Code の3つの場所すべてにインストールします。
• RULE-07（必須）：[NEW]：アップストリームへのコミット前に、manifest に追加します。
• RULE-08（必須）：[MISSING]：ダウンストリームでコピーした後に、manifest に追加します。
• RULE-09（必須）：Frontmatter：スキルには name: + description:、スラッシュコマンドには description: のみを指定します。
• RULE-10（必須）：README.md、index.md、log.md、Purpose/Steps のないファイルはスキップします。
• 機能：リモートテンプレートの読み取り（HTTP/GitHub API）；プロジェクト内およびユーザー単位のスキル／コマンドディレクトリへのファイル書き込み；アップストリームの場合はリモートテンプレートへのプッシュ（承認後のみ）。

失敗時の境界

• CONFLICT（両方で変更あり）→ ローカルを維持し、リモート版を /tmp/sync-template-conflicts/ に保存して、終了コード 3 → ユーザーに確認します。
• ダウンロード／OKF／検証エラー → 終了コード 1 → 失敗。完了前に ✗ を修正します。
• 最新のリモートブランチが不明 → 確認し、どのブランチかユーザーに尋ねます。
• health-check が OK → 同期は不要です。停止します（成功、no-op）。
• 古い skills/ レイアウト → 移行を提案し、削除前に確認します。

手順

主なワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	判断	要求	経路を選択：通常の downstream → FAST PATH --full；upstream、旧構造の移行、デバッグ → MANUAL（B01）	経路	—
W02	効果	manifest、remote	python3 harness/scripts/sync-template.py --full を1回実行（sync + OKF + fingerprint + 3か所へのインストール + verify + ログ）	レポート	exit 1 → failed；exit 3 → W03
W03	判断	レポート	レポートを読む；CONFLICT で remote を取得したい場合 → --strategy pull で再実行；別の branch → --branch	判断	不明な場合 → user に確認
W04	決定的処理	レポート	okf-check、health-check、verify の反復を追加で呼び出さず、ログを自分で修正しない	user への報告	—
W05	効果	結果	Report のドラフトを出力	draft + index + log	artefact が0件 → skip

各ステップの詳細（W01–W05 と MANUAL 分岐の信頼できる情報源）：

FAST PATH — downstream は --full の1コマンド（30秒未満、デフォルト）

Downstream sync は、自己完結した1つの非対話型スクリプトです。--full を付けて1回呼び出すと、sync 後のすべての手順（Step 6a/6b/8 + ログ記録）が同じプロセス内で実行されます。エージェントはレポートを1つ読み、報告します。個別のコマンドを繰り返し実行しないでください。このリポジトリのベンチマーク：full steady-state 0.27s · full pull+install+verify 0.76s （harness/metrics/sync-template-bench.json）。

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 を直接編集したりしないでください（スクリプトがすべて実行済みです）。これがスキルを30秒未満に保つ方法です。以前のボトルネックは CPU ではなく、sync 後の手順で発生するエージェントのラウンドトリップ数でした。--full を付けない場合の動作は、従来どおりです。

3つの地点のハッシュで分類します — disk ↔ R0（前回の sync 時点の remote、version.json:remote_synced に保存） ↔ 現在の remote：

• NEW（local に存在しない）+ UPDATE（remote が新しく、local は未変更） → 自動で PULL。
• KEPT（独自にカスタマイズ済みで、remote はそれより新しくない） → そのまま保持し、確認しません。
• CONFLICT（両方で変更あり） → デフォルトではlocal を保持し、diff 用に remote のコピーを /tmp/sync-template-conflicts/ に保存します。exit code は 3 です。時間短縮のために --strategy pull を自動実行することは決してありません。

スクリプト内の自動処理（--full）：remote の version.json+manifest を fetch → 分類 → 並列ダウンロード → プロセス内で OKF backfill（bold→YAML へ移行、冪等） → version.json を更新（OKF 後の fingerprint + template_version + remote_synced） → 3か所に skill をインストール（.claude/commands/、~/.claude/skills/、~/.claude/commands/） → 3か所を自己検証 → wiki/log.md に追記。終了コード：0 は問題なし · 1 はダウンロード/OKF/verify のエラー · 3 は判断が必要な CONFLICT。

手動での介入が必要な場合（先にスクリプトを実行し、レポートを読む）：

• レポートに CONFLICT があり、remote を取得したい → --strategy pull で再実行します（必要な判断は1つで、3つではありません）。
• remote の branch が version.json:branch と異なる → --branch <名前>（branch の監査については Step 2 を参照）。
• 旧 skills/ 構造の移行（Step 3）が必要、または upstream（push）が必要 → 以下の MANUAL STEPS を使用します。

⚠ 修正済みのバグ：health-check --update は baseline を disk に設定するため、sync が「remote が新しい」のか「独自にカスタマイズ済み」なのかを区別できず、カスタムファイルを上書きしかけていました。このスクリプトは専用の remote_synced baseline（sync 時点の remote のハッシュ）を使用するため、正しく区別できます。分類の baseline として patterns（disk）を再び使わないでください。

---

MANUAL STEPS（フォールバック — upstream、旧構造の移行、またはデバッグ）

Step 0: 事前確認 — health-check（sync 前の診断）

/health-check（python3 harness/scripts/health-check.py --root .）を実行し、どの方向に sync すべきか確認します：

• NEEDS-SYNC（遅れている/不足している） → downstream（pull）。
• DRIFT（local を変更済み） → upstream（push）または revert。
• OK → sync は不要なので、停止します。

Step 1: Manifest の読み込み

.template-manifest.json を読み込みます — 対象リスト + remote URL。

Step 2: Fetch と Branch の監査

• 重要：すべての remote branch を一覧表示します：gh api repos/<owner>/<repo>/branches。
• 各 branch の commit 日付を確認します — master/main が最新だと決めつけないでください。
• 判断できない場合 → どの branch を使うか user に確認します。
• gh api + curl で fetch します — git clone は使用しません。

Step 3: 古い構造からの移行を検出

llmwiki/ への移行が必要な古い skills/ レイアウトがないか確認します。

# Signs of old structure:
[ -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: マニフェストファイルを比較

includes 内の各ファイルについて、ローカルとリモートを diff で比較します。

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 — リモートにのみ存在します → 下流候補
• NEW — ローカルにのみ存在します → 上流候補
• ABSENT — どちらにも存在しません

Step 5: 同期計画

テーブルを表示します。停止 → ユーザーに確認します：すべてをプル／すべてをプッシュ／特定のファイル／DIFF ごとに方向を指定。

Step 6: 実行

• 下流：mkdir -p → curl -sfL <url> -o <local_path> → wiki/log.md を更新します
• 上流：gh/git でコミットしてプッシュします
• ファイルごとに処理します。cp -R は使用しません

Step 6a/6b/8 は --full に統合済みです。 FAST PATH --full を実行する場合、6a/6b/8 はスキップしてください — スクリプトがプロセス内で OKF のバックフィル、フィンガープリントの更新、検証、ログ記録をすでに行います。以下の手順は MANUAL 実行時 （デバッグ／上流同期／古い構造の移行）にのみ使用し、--full の後には実行しません。

Step 6a: OKF のバックフィル (MANUAL — --full で実行済み)

新しいテンプレート／スキルによって、Wiki のフォーマット（例：OKF v0.1 標準）が更新されることがあります。プル後、R9 に抵触しないよう、太字の擬似フロントマター **Type:** 形式を使用している古いコンテンツファイルをすべて YAML フロントマターに変換します。

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)

• 冪等です。すでに --- フロントマターがあるファイルはスキップします。予約済みのファイル（index/log/README/decisions/_template…）は自動的に対象外です。
• 移行後、DAT CHUAN OKF v0.1 になるまで --check を再実行し、Wiki に変更を加えたときと同様に index/log を更新します。

Step 6b: バージョンフィンガープリントを更新 (MANUAL — --full で実行済み)

パターンの内容を変更したばかりの場合は、ヘルスチェックで誤って DRIFT と報告されないように、harness/version.json を更新します。

python3 harness/scripts/health-check.py --update   # KHÔNG --bump ở project con

• --bump major|minor|patch は、新しいパターンバージョンをリリースするときに、テンプレートリポジトリ Rheinmir/setup でのみ実行します。
• テンプレートリポジトリで上流同期を行う場合、プッシュ後に --update --bump <part> を実行し、harness/version.json をコミットします。

Step 7: ネイティブスキルとしてインストール (下流同期のたびに実行)

同期したスキルファイルを収集します（マニフェスト内の llmwiki/skills/ 配下）。README.md、index.md、log.md、## Purpose／## Steps がないファイルはスキップします。

A. プロジェクトレベル（.claude/commands/ — このリポジトリ）：

mkdir -p .claude/commands/
# Add description: frontmatter if missing, then copy
printf -- "---\ndescription: %s\n---\n\n" "$desc" | cat - <src> > .claude/commands/<name>.md

B. グローバルユーザーレベル（~/.claude/skills/<name>/SKILL.md — すべてのプロジェクト）：

mkdir -p ~/.claude/skills/<name>/
# Requires name: + description: frontmatter
printf -- "---\nname: %s\ndescription: %s\n---\n\n" "$name" "$desc" | cat - <src> > ~/.claude/skills/<name>/SKILL.md

C. グローバルスラッシュコマンド（~/.claude/commands/<name>.md）：

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: 検証と完了

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

完了前に ✗ を修正します。再起動は不要です。

分岐

ID	種類	条件	動作	スキップ／失敗	再合流
B01	conditional_required	上流同期、古い skills/ 構造の移行、またはデバッグが必要	MANUAL STEPS 0–8 を実行し、Step 5 で停止してユーザーに確認します	通常の下流同期 → FAST PATH	W05
B02	recovery	exit 3 CONFLICT で、ユーザーがリモートを取得することを選択	--strategy pull を再実行します（上書きし、.local-bak にバックアップ）	ユーザーがローカルを保持 → 何もしません	W04
B03	conditional_required	リモートブランチが version.json:branch と異なる	ブランチを監査（Step 2）した後、--branch <ブランチ名> を指定します	—	W02
B04	user_optional	事前に確認したい	--dry-run を実行します（OKF の移行対象を確認するには --full を併用）	—	W02
B05	conditional_required	古い skills/ レイアウトを検出（Step 3）	移行テーブルを表示し、確認後に削除します	ユーザーが拒否 → 保持します	W05

検証と停止

必須事項：スクリプトの終了コード（0/1/3）、3 か所のインストール先での自己検証、okf-check.py --check が DAT CHUAN OKF v0.1 を出力すること（手動）。Step 8 の [ -f … ] ループに ✗ が残っていないこと。終了コードが 0 の場合は、--full を 1 回実行した時点で停止します。終了コードが 3 の場合は停止して、ユーザーの判断を待ちます。手動の場合は Step 5 で停止して、承認を待ちます。

例

• 成功例： 子プロジェクトで Master に新しい修正がある場合 → python3 harness/scripts/sync-template.py --full → 2 件の UPDATE を自動的に PULL、1 件の KEPT はそのまま維持、OKF が 3 ファイルを移行、3 か所での検証 ✓、1 秒未満で終了コード 0 → レポートを提示し、追加のコマンドは実行しません。
• 境界ケース／失敗例： ファイル llmwiki/skills/dev-loop/ship.md がローカルとリモートの両方で変更されている場合 → CONFLICT、ローカル版を維持し、リモート版は /tmp/sync-template-conflicts/ に保存、終了コード 3 → 差分を表示し、ユーザーを待ちます。--strategy pull は自動実行しません。

参考 — エージェントの互換性

エージェント	実行可能？	理由
Claude Code	はい	すべてのツールにアクセス可能
OpenCode	はい	すべてのツールにアクセス可能
Antigravity	いいえ	サンドボックスによりファイル／コマンド用ツールがブロックされる

納品 — 出力レポート

すべての主要なスキルタスクが完了したら、Wiki に提案のドラフトを作成します。

手順

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>
**Type:** draft
**Status:** proposed
**Tags:** <skill-name>, output-report
**Proposed:** YYYY-MM-DD

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

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

## Files
| File | Action |
|------|--------|
| `path/to/file` | created / modified |

## Notes
- Invoked via: `/<skill-name>` skill

## Origin
- **Draft:** `wiki/sources/draft/DDMMYY-<ten>.md`
- **Commit:** _(filled by verify-before-commit)_
- **Date promoted:** _(filled by verify-before-commit)_

3. Wiki のインデックスとログを更新します：

• llmwiki/wiki/index.md — 次の 1 行を追加します：| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |
• llmwiki/wiki/log.md — 次の行を追加します：## YYYY-MM-DD — <skill-name> — <ten>

スキルによって成果物も意思決定も一切生じない場合に限り、スキップします（例：/caveman-stats のような表示のみのモード）。