sync-template

テンプレートの同期

blogic-template-ts から生成された派生プロジェクトを、最新の上流テンプレートの状態と同期します。

信頼できる情報源として blogic-cz/blogic-template-ts を使用します。

利用できる場合は、次のローカルパスを優先します。

opensrc/repos/github.com/blogic-cz/blogic-template-ts/

コマンドでは、このパスを $TPL として参照します。

前提条件

• 利用できる場合は、gh CLI で認証してください。
• 利用できる場合は、debugging-with-opensrc スキルを読み込みます。利用できない場合は、同等の opensrc / git コマンドを直接実行します。
• 利用できる場合は、agent-tools（gh-tool release list/view）を使用します。利用できない場合は、ネイティブの gh release list/view を使用します。
• 利用できる場合は、opensrc でテンプレートをクローンします。利用できない場合は、https://github.com/blogic-cz/blogic-template-ts を一時ローカルディレクトリにクローンし、そのパスを $TPL として使用します。

フェーズ 0：調査 — テンプレートで変更された内容

ステップ 0：テンプレートのソースをローカルに用意する

差分を確認する前に、テンプレートのリポジトリをローカルに用意します。

bun run opensrc:use blogic-cz/blogic-template-ts
ls opensrc/repos/github.com/blogic-cz/blogic-template-ts/

opensrc を利用できない場合は、git clone でクローンし、クローン先のパスを $TPL に設定します。

ステップ 1：プロジェクト内の現在のテンプレートバージョンを検出する

現在のテンプレートバージョンを示すマーカーを検出します。

• package.json（templateVersion、template-version、synced-from）
• .template-version
• 同期コミットの Git 履歴
• CHANGELOG.md の同期エントリ

ベースラインが見つからない場合は、続行する前にユーザーにベースラインのバージョンを確認します。

ステップ 2：ベースライン以降の上流の変更を列挙する

リリース、コミット、PR のメタデータを使って変更を列挙します。

gh-tool release list --repo blogic-cz/blogic-template-ts
gh-tool release view <tag> --repo blogic-cz/blogic-template-ts
gh pr list --repo blogic-cz/blogic-template-ts --state merged --search "merged:>YYYY-MM-DD" --limit 50

gh-tool を利用できない場合は、gh-tool コマンドを gh release ... コマンドに置き換えます。

ステップ 3：変更を分類し、適用方針を決める

各変更を次のいずれかのカテゴリに分類します。

カテゴリ	説明	対応
Infrastructure	CI/CD、Docker、Helm、設定、ツール	（名前を置換して）直接適用します
Dependencies	パッケージのバージョン更新、新しい依存関係	update-packages スキルに委任します
Patterns	コードパターン、規約、Lint ルール	適宜調整して適用します
Features	新しいアプリ機能、ルート、サービス	評価します — 適用できない場合があります
Fixes	共有コードのバグ修正	プロジェクトにそのバグがある場合に適用します

概要の表を出力します。

| # | Category | Change | Template Files | Effort | Priority |
|---|----------|--------|---------------|--------|----------|

---

フェーズ 1：最初にパッケージを更新する（必須）

テンプレートファイルを同期する前に、パッケージのバージョンを揃えます。

ステップ 1：プロジェクトとテンプレートのパッケージバージョンを比較する

両方のツリーにあるパッケージマニフェストを読み取り、バージョン差分の表を作成します。

比較表を作成します。

| Package | Project Version | Template Version | Gap |
|---------|----------------|-----------------|-----|

ステップ 2：パッケージを更新する

パッケージが古い場合は、update-packages スキルを優先します。そのスキルを利用できない場合は、同じ制約に従って同等の手動更新を実行します。

次の順序で適用します。

1. ブランチを作成します：chore/sync-template-packages-$(date +%y%m%d-%H%M)
2. すでに使用しているパッケージのみを、テンプレートのバージョン以上に更新します。
3. テンプレートファイルの同期コミットとは別に、パッケージ更新をコミットします。
4. 続行する前に、プロジェクトのチェックを実行して検証します。

次のルールを適用します。

• テンプレートを変更する前に、パッケージ更新を必ずコミットしてください
• パッケージグループ間の連携を維持してください（tanstack、trpc、effect、drizzle）
• プロジェクトで使用していないパッケージを追加しないでください — 既存のパッケージのみを更新します

---

フェーズ 2：詳細スキャンと差分確認

プロジェクトとテンプレートをファイル単位で比較し、すべての相違点を特定します。

ステップ 1：適用するインフラストラクチャファイルを特定する

カテゴリ別のファイル一覧を確認するには、references/template-files.md を読み込みます。

各インフラストラクチャファイルについて、次の操作を行います。

1. プロジェクト内にファイルが存在するか確認します
2. 存在する場合は、テンプレートのバージョンと差分を確認します
3. 存在しない場合は、「プロジェクトにありません」として記録します

git diff --no-index $TPL/<file> <file>

ステップ 2：名前の置換マトリックスを作成する

references/substitution-rules.md に従って、置換マトリックスを作成します。

ステップ 3：プロジェクト固有の相違点を特定して維持する

意図的なビジネスロジックの相違点にフラグを付け、維持します。

• apps/web-app/src/routes/ — プロジェクト固有のルート
• packages/services/src/ — プロジェクト固有のサービス
• packages/db/src/schema/ — プロジェクト固有のスキーマ（テンプレートのデフォルトを超えるもの）
• 環境固有の設定（Helm の値、CI シークレット）

次のルールを適用します。

• プロジェクト固有のビジネスロジックをテンプレートのデフォルトで上書きしてはなりません
• テンプレートのインフラストラクチャファイル（lint、ツール、CI）は完全に採用してください
• ファイルにインフラストラクチャの変更とプロジェクト固有の内容の両方が含まれる場合は、選択的にマージしてください

---

フェーズ 3：トリアージと計画

.sisyphus/plans/ に段階的な実装計画を作成します。

ステップ 1：計画ファイルを作成する

mkdir -p .sisyphus/plans

名前：.sisyphus/plans/YYMMDDHHMM-sync-template-vX.Y.Z.md

ステップ 2：標準の計画形式を適用する

references/plan-template.md を読み込み、適用します。

ステップ 3：ウェーブの構成

テンプレート同期の標準的なウェーブパターン：

Wave 0 (Sequential — foundation):
└── Package updates (if not done in Phase 1)

Wave 1 (Parallel — infrastructure):
├── Skills & tooling updates
├── Lint & formatter config
├── CI/CD pipeline updates
├── Docker & Helm updates
└── Config file updates (tsconfig, vitest, etc.)

Wave 2 (After Wave 1 — code changes):
├── Fix lint violations from new rules
├── Apply code pattern updates
└── Update docs (AGENTS.md, README)

Wave 3 (After Wave 2 — cleanup):
└── Final cleanup + verification

Wave FINAL (After ALL — verification):
├── Plan compliance audit
├── Code quality review
└── Scope fidelity check

ステップ 4：計画をユーザーに提示する

概要を提示し、実行前に明示的な承認を待ちます。

## Sync Template v<old> → v<new>

**Changes**: N commits, M PRs, K releases
**Waves**: 4 (+ verification)
**Tasks**: N total
**Estimated effort**: [Small/Medium/Large]

Approve to start execution?

---

フェーズ 4：実行

計画をウェーブごとに実行します。

サブエージェントが利用可能な場合は、タスクの委任を優先してください。

サブエージェントが利用できない場合の代替策：メインエージェントでタスクを順番に実行し、同じ受け入れ基準を維持し、計画されたコミットのグループ分けを保持します。

タスクごとの実行フロー

計画内の各タスクについて、次の手順を実行します。

1. TODO を in_progress にする
2. タスクを実行する（可能な場合は委任し、それ以外の場合は直接実行する）
3. 受け入れ基準を検証する
4. QA シナリオを実行する
5. TODO を completed にする
6. 計画で指定されたとおりにコミットする

委任プロンプトのテンプレート

references/plan-template.md の委任プロンプトを使用します。

各ウェーブの後

bun run check
bun run test

次のウェーブに進む前に、失敗を解決してください。

---

フェーズ 5：検証とスタンプ

references/verification-recipes.md の検証レシピを実行します。

references/substitution-rules.md の置換ポリシーを適用します。

---

ガードレール

• 絶対にプロジェクト固有のビジネスロジック（ルート、サービス、デフォルトを超えるスキーマ）を上書きしないでください
• references/substitution-rules.md で承認された例外を除き、同期したプロジェクトファイルに @blogic-template/ または blogic-template-ts の文字列を絶対に残さないでください
• 必ず最初に bun run opensrc:use blogic-cz/blogic-template-ts でテンプレートをクローンしてください
• 必ずテンプレートからコピーしたすべてのファイルに名前置換マトリックスを適用してください
• 必ずインフラストラクチャの変更を適用する前に、パッケージを更新してください
• 必ず各ウェーブの後に bun run check && bun run test を実行してください
• 必ずプロジェクト固有の設定（Sentry プロジェクト、Helm の名前空間、CI シークレット）を維持してください
• プロジェクトで必要のないテンプレート専用の依存関係を追加しないでください
• プロジェクトで採用していないテンプレート機能を適用しないでください
• ハードコードされた絶対パスを使用しないでください。常に相対パス opensrc/repos/github.com/blogic-cz/blogic-template-ts/ を使用してください

完了の定義

• bun run check が成功する（エラー 0 件）
• bun run test が成功する
• references/substitution-rules.md で承認された例外を除き、同期したプロジェクトファイルに @blogic-template/ または blogic-template-ts の文字列がない
• .template-version ファイルが新しいバージョンに更新されている
• 計画のすべてのタスクが完了としてマークされている
• 計画ファイルが .sisyphus/plans/ に存在する