openclix-init

OpenClix Init

目的

このスキルは、SDK パッケージをインストールするのではなく、クライアントコードをユーザープロジェクトにコピーして OpenClix の機能を追加します。
ローカルソース統合モデル（shadcn スタイル）を使用します。コピーし、適応し、接続し、検証します。

基本ルール

• プロジェクトファイルを使って、まず実際のプラットフォームを検出します。
• 既存のユーザーコードへの変更を最小限に抑えます。
• すべての OpenClix ファイルを専用の名前空間／ディレクトリに配置します。
• .openclix/** の下にローカルの計画／レポート用アーティファクトを作成する場合は、.openclix/ が .gitignore に記載されていることを確認します（記載がなければ追加します）。
• 可能な限り既存の依存関係を再利用します。
• ユーザーの明示的な承認なしに、依存関係を追加または更新しないでください。
• 統合後にビルドを実行し、統合によって発生した問題のみを修正します。
• 本番環境の統合経路では、メモリ内フォールバックを使用しないでください。
• バンドルされた JSON 設定を配信する場合は、実行時のローダーパスとコピー先のファイルパスを同一に保ちます（同じディレクトリと、大文字と小文字を区別した同一のファイル名）。
• デフォルトのファイル名には openclix-config.json を使用し、OpenClix-config.json のような大文字・小文字の異なる名前は作成しないでください。

プラットフォームの検出

次の順序でファイルの証拠を確認します。

優先度	プラットフォーム	必要な証拠
1	Expo	expo を含む app.json または app.config.*
2	React Native	react-native を含む package.json と、一般的な ios/ および android/ の構成
3	Flutter	Flutter SDK を含む pubspec.yaml
4	iOS ネイティブ	*.xcodeproj、*.xcworkspace、または Package.swift
5	Android ネイティブ	build.gradle または build.gradle.kts

シグナルが矛盾する場合は、具体的なファイルの証拠を優先し、不一致を報告します。

テンプレートの選択

• Expo / React Native：templates/react-native/
• Flutter：templates/flutter/
• iOS：templates/ios/
• Android：templates/android/（パッケージ名前空間 ai.openclix.*）

プラットフォーム間で調整が必要な場合は、templates/react-native/ を標準的な参照元とします。

既存のローカル通知の検出

テンプレートをコピーしたり、OpenClix の接続箇所を設定したりする前に、ホストアプリの OpenClix 名前空間外に既存のローカル通知コードがないか確認します。

該当する場合は、次の処理を検出します。

• 通知のスケジュール
• 通知の権限要求／ステータス
• フォアグラウンドでの表示処理
• 通知のタップ／オープン処理

検出した各処理を、次のいずれかに分類します。

• migration-capable：変更範囲を限定し、新しい依存関係を追加せず、大規模なリファクタリングも行わずに OpenClix へ振り替え可能
• keep-as-is：OpenClix の統合中も変更せずに維持すべき

既存のローカル通知コードが見つからない場合は、通常の統合フローを続行します。

既存のローカル通知コードが見つかった場合は、次の内容を報告します。

• 検出したファイルまたはエントリーポイント
• 各処理が migration-capable または keep-as-is のどちらか
• migration-capable にできない処理がある場合は、その理由

移行対応ルール

次のルールは慎重に適用してください。

• React Native / Expo：
  • アプリがすでに @notifee/react-native または expo-notifications を使用している場合に限り、migration-capable とします
  • これらのライブラリに照らして、既存のスケジューラー、権限、フォアグラウンド、および開封処理のコードを検出し、分類します
  • その他の通知スタックは keep-as-is のままにします
• Flutter：
  • 既存のプラグインが、現在の OpenClix コールバック契約である schedule、cancel、listPending、権限のリクエスト／ステータス、およびオプションのフォアグラウンド設定を提供できる場合に限り、migration-capable とします
  • 依存関係の追加や大規模な書き換えを行わずにプラグインがこの契約を満たせない場合は、keep-as-is とします
• iOS ネイティブ：
  • アプリがすでに UNUserNotificationCenter のローカル通知を使用しており、既存の権限／デリゲート経路を局所的な編集で再利用できる場合は、migration-capable とします
  • OpenClix のコンテンツモデルでサポートされていない通知動作はそのまま維持します
• Android ネイティブ：
  • 現在のローカル通知フローが、依存関係の追加や大規模なリファクタリングを行わずに OpenClix スケジューラー経路へ振り向けられる、プラットフォーム上のローカルなスケジューリング／表示である場合は、migration-capable とします
  • ベンダー所有のフローや高度にカスタマイズされたフローは keep-as-is のままにします

ユーザーが別途再設計を依頼しない限り、次のシナリオは必ず keep-as-is とします。

• リモートプッシュ配信インフラストラクチャ
• 現在の OpenClix アダプターでサポートされていない、ベンダー固有の通知製品
• 現在の OpenClix コンテンツモデルで表現されていないリッチアクションや高度な機能
• 関連のないビジネスロジックと密接に結び付いた通知フロー

移行の判断

検出したパスが 1 つ以上 migration-capable の場合は、既存の通知動作を書き換える前にユーザーに確認してください。

次の文言で確認します。

I found existing local notifications outside OpenClix. Some paths are migration-capable. Do you want me to migrate the supported local-notification flows into OpenClix, or keep the existing implementation unchanged? If you do not choose, I will keep the existing implementation.

判断ルール：

• ユーザーが明示的に選択しない場合、migration-capable のパスは keep-as-is を既定とします
• ユーザーが keep を選んだ場合、migration-capable のパスを keep-as-is として扱い、OpenClix を現在の通知システムと併用し、既存の通知フローを書き換えないでください
• ユーザーが migrate を選んだ場合、現在の OpenClix モデルに適合する、サポート対象のエンゲージメント向けローカル通知フローのみを移行します
• ユーザーが migrate を選んだ場合でも、サポート対象外または無関係な通知フローには手を加えないでください
• 検出したパスに migration-capable がない場合は、その旨を説明し、共存のみで進めてください
• 既存の通知実装を黙って置き換えてはいけません
• 統合の引き継ぎ／レポートには、最終的なユーザーの選択を含めてください

統合ワークフロー

1. プラットフォームと、現在の起動／イベント／ライフサイクルのエントリーポイントを特定します。
2. 既存のローカル通知パスを検出し、migration-capable または keep-as-is に分類します。
3. migration-capable のパスがある場合は、サポート対象のフローを移行するか、既存の実装を変更せずに維持するかを確認します。既存の実装を維持することを既定とします。
4. 選択したテンプレートを、ユーザープロジェクト内の OpenClix 専用領域にコピーします。
5. 必要な接点のみを接続します。
   • アプリ起動時の初期化
   • イベント追跡の呼び出し経路
   • フォアグラウンド／アプリのライフサイクルのトリガー
6. 既存のアーキテクチャとコードスタイルを維持し、大規模なリファクタリングを避けます。
7. 設定／スキーマに変更がある場合は、references/openclix.schema.json に照らして検証します。

アダプターの選択ルール

既存の依存関係のみを使用してアダプターを選択します。

1. 統合時に具体的なアダプターを選択し、実行時の依存関係の自動検出は避けてください。
2. プロジェクトに対応する永続ストレージの依存関係がすでにある場合は、その実装を接続してください。
3. 通知ライブラリがすでにある場合は、対応するスケジューラーアダプターを接続してください。
4. 互換性のある依存関係がない場合は、明確な統合エラーを表示して速やかに失敗させてください。
5. 本番用テンプレートのデフォルトに、機能が低下したインメモリ経路を含めないでください。

React Native / Expo のストレージ選択：

• AsyncStorage を使用するプロジェクト：AsyncStorageCampaignStateRepository を使用します。
• MMKV を使用するプロジェクト：MmkvCampaignStateRepository を使用します。
• 両方ある場合は、プロジェクトの標準を優先し、ストレージアダプターは1つだけアプリにコピーします。
• OpenClix.initialize(...) の呼び出し時に、campaignStateRepository を明示的に注入します。

React Native / Expo のスケジューラー選択：

• Notifee を使用するプロジェクト：new NotifeeScheduler(notifee) を作成します。
• Expo notifications を使用するプロジェクト：new ExpoNotificationScheduler(ExpoNotifications) を作成します。
• OpenClix.initialize(...) の呼び出し時に、messageScheduler を明示的に注入します。

プラットフォームごとの要件：

• React Native / Expo：
  • ストレージおよびスケジューラーアダプターについて、OpenClix コアで実行時のアダプター自動検出を使用しないでください。統合時に選択してください。
  • 統合時にストレージとスケジューラーの実装を選択し、それらの依存関係を明示的に注入してください。lifecycleStateReader などのライフサイクルヘルパーは、プロジェクト固有の実装が不要な場合、実行環境に基づいてテンプレートコアが選択できます。
  • 互換性のある実装がない場合は、明確な手順を示して初期化に失敗させてください。
• Flutter：
  • 既存の通知プラグインには、コールバックベースのスケジューラーアダプターを使用します。
  • 初期化時にスケジューラーと状態リポジトリの依存関係を明示的に指定する必要があります。
• iOS / Android ネイティブ：
  • デフォルトでプラットフォームネイティブの実装を使用します。
  • デフォルトの実行時の動作として、インメモリまたは何もしないフォールバックを導入しないでください。

通知の許可とフォアグラウンドの設定

キャンペーンのトリガーが発火する前に、通知の許可を求める必要があります。各プラットフォームのテンプレートには許可リクエスト用ユーティリティが含まれています。統合エージェントは、ホストアプリの適切な場所でこれを接続してください。

React Native / Expo — 許可

• Notifee を使用するプロジェクト： infrastructure/NotifeeNotificationSetup から requestNotifeePermission をインポートします。アプリの起動時（例：App.tsx または起動時のフック）に、Notifee アダプターを渡して呼び出します。フォアグラウンドハンドラーは不要です。Notifee は presentationOptions を介してフォアグラウンド表示をネイティブに処理します。
• Expo を使用するプロジェクト： infrastructure/ExpoNotificationSetup から requestExpoPermission と setupExpoForegroundHandler をインポートします。初期化中に setupExpoForegroundHandler を1回呼び出し、その後、アプリの起動時に requestExpoPermission を呼び出します。

iOS — 許可とフォアグラウンド表示

1. 許可： アプリの起動時（例：application(_:didFinishLaunchingWithOptions:) または SwiftUI の .task 修飾子）に await NotificationPermission.request() を呼び出します。これは UNUserNotificationCenter.requestAuthorization を呼び出します。
2. フォアグラウンド表示： iOS では、アプリがアクティブなときに通知バナーが抑制されます。テンプレートには、静的メソッドとして ForegroundNotificationHandler.handleWillPresent(notification:completionHandler:) が用意されています。
   • 重要： iOS では、1つのアプリにつき UNUserNotificationCenterDelegate は1つしか設定できません。ForegroundNotificationHandler をデリゲートとして割り当てないでください。代わりに、アプリ既存のデリゲート（通常は AppDelegate）を UNUserNotificationCenter.current().delegate = self として設定し、そのデリゲートの willPresent 実装から静的メソッドを呼び出してください。

Android — 権限

1. マニフェスト： AndroidManifest.xml に <uses-permission android:name="android.permission.POST_NOTIFICATIONS" /> を追加します。
2. 実行時のリクエスト： API 33 以降（Android 13）では、起動時に NotificationPermission.shouldRequestPermission(context) を呼び出します。true が返された場合は、Activity の requestPermissions() または ActivityResultLauncher を使用して、NotificationPermission.getPermissionString() をリクエストします。
3. Android ではフォアグラウンド表示の設定は不要です。アプリの状態に関係なく、NotificationManager.notify() は常に通知を表示します。

Flutter — 権限とフォアグラウンド表示

notification/notification_permission.dart の NotificationPermission クラスはコールバックを受け取ります。ホストアプリの通知プラグインを接続します。

1. プラグインの権限リクエスト API を呼び出す requestPermission コールバックを指定します。
2. 現在の状態を確認する checkPermissionStatus コールバックを指定します。
3. 必要に応じて、フォアグラウンド表示を設定する setupForegroundHandler コールバックを指定します（iOS では必須ですが、Android では不要です）。
4. キャンペーンのトリガーが実行される前に、アプリの起動時に permission.request() を呼び出します。
5. ハンドラーを指定した場合は、初期化中に permission.setupForeground() を呼び出します。

ディレクトリと名前空間のポリシー

OpenClix のファイルは、専用の場所にまとめて配置する必要があります。

• React Native / Expo：src/openclix/
• Flutter：lib/openclix/
• iOS：OpenClix/ または Sources/OpenClix/
• Android：app/src/main/kotlin/ai/openclix/、パッケージは ai.openclix.*

バンドル設定ファイルのパスに関する契約

統合にバンドル設定ファイルの配信（HTTP エンドポイント以外）が含まれる場合は、次の契約を適用します。

1. まず、現在の起動コードから、実行時の正確な読み込みパスを特定します。
2. openclix-config.json をその正確なパスにコピーします。
3. 実行時の読み込みパスがまだ存在しない場合は、次のデフォルトを使用します。
   • React Native / Expo：assets/openclix/openclix-config.json
   • Flutter：assets/openclix/openclix-config.json に配置し、pubspec.yaml に追加します
   • iOS：<app-target>/OpenClix/openclix-config.json に配置し、「Copy Bundle Resources」に含めます
   • Android：app/src/main/assets/openclix/openclix-config.json
4. バンドルパスの識別子（OpenClixConfig.endpoint、アセットキー、バンドルファイル名）が、コピーしたファイルのパスと正確に一致することを確認します。
5. 引き渡し前に最終的なパスの整合性を確認し、次の内容を報告します。
   • ソース設定ファイルのパス
   • バンドルされた実行時ファイルのパス
   • 実行時ローダーの参照箇所

依存関係のポリシー

依存関係を変更する前に、次のことを行います。

1. 選択したテンプレートが想定している内容を確認します。
2. ユーザーのプロジェクトにすでに含まれているものを確認します。
3. 既存のプロジェクトライブラリまたはプラットフォーム API を優先します。
4. 置き換えが可能な場合は、依存関係を追加せず、テンプレートコードを調整します。
5. 安全に置き換えられるものがない場合は、依存関係を追加または更新する前に承認を求めます。

承認なしに、パッケージマネージャーのインストール／更新コマンドを実行してはいけません。

ビルドの検証

接続後、検出したプロジェクト構造に応じたプラットフォーム固有のビルド／解析コマンドを実行します。 まず、プロジェクト標準のコマンド（既存のスクリプト、Gradle タスク、Xcode スキーム、Flutter のワークフロー）を優先します。

判断が難しい場合は、一般的な代替コマンドを使用します。

• React Native / Expo：npx tsc --noEmit
• Android：./gradlew assembleDebug
• iOS：xcodebuild -scheme <scheme> build または swift build
• Flutter：flutter analyze

ビルドに失敗した場合は、最小限かつ対象を絞った修正を適用して再試行します。重大な阻害要因がある場合にのみ停止します。

エージェント指示ファイルの更新

統合後、今後のセッションで参照できるよう、プロジェクトのエージェント指示ファイルに OpenClix のセクションを追記します。

更新するファイルを次のように判定します。

• CLAUDE.md が存在する場合：CLAUDE.md を更新します（Claude Code）
• AGENTS.md が存在する場合：AGENTS.md を更新します（Codex またはその他のエージェント）
• 両方が存在する場合：現在のエージェントに対応するファイルを更新します
• どちらも存在しない場合：現在のエージェントの規約に合ったファイルを作成します

既存の内容は上書きせず、次のセクションを追記します。

## OpenClix

OpenClix is integrated in this project. It provides local-first, config-driven mobile engagement logic.

Available skills:

- `openclix-design-campaigns`: Create and iterate campaign configurations from product goals.
- `openclix-analytics`: Wire events to a PA provider and produce retention impact reports.
- `openclix-update-campaigns`: Propose campaign operations from measured analytics performance.
- `openclix-update`: Sync integration source code with the latest template baseline.

完了チェックリスト

• OpenClix のコードを専用の名前空間／ディレクトリに追加しています。
• 既存アプリのコード変更は最小限に抑え、局所化しています。
• 統合前に、既存のローカル通知経路を検出し、分類しています。
• 対応可能な経路が見つかった場合は移行の判断を記録し、ユーザーが移行を選択しなかった場合は、既存の動作を維持することをデフォルトにしています。
• 引き継ぎ／レポートには、検出した内容、移行可能だった内容、変更せずに残した内容、変更した内容が記載されています。
• 承認されていない依存関係の追加やアップグレードはありません。
• アダプターの配線では既存の依存関係を優先し、利用できない場合は速やかに失敗します。
• ローカルリソース配信を使用する場合、バンドルされた設定のパス／ファイル名の整合性を検証しています。
• ビルド検証を実行しています。
• 残っている阻害要因があれば、明確に報告しています。