thierryc/glyphs3-to-glyphs4-skill

Glyphs 3 プラグインを Glyphs 4 に移行する

Python プラグインのレビュー可能な移行コピーを作成します。静的な移行は、Glyphs 4 での手動起動テストの準備として扱い、実行時の互換性を証明するものではありません。

ガードレール

• 元のプラグインまたはリポジトリを保持すること。
• その場で移行しないこと。既存の出力パスが指定された場合は拒否すること。
• ユーザーが明示的に要求しない限り、Glyphs のインストール、実行、再読み込み、再起動、またはライブの Plugins フォルダを変更しないこと。
• Glyphs MCP の docs_search および docs_get ツールを主要な開発知識ベースとして使用すること。ツール名の名前空間はクライアントによって異なるため、最終的なツール名と説明で解決すること。
• GlyphsApp API、プラグインのライフサイクルメソッド、セレクタ、コールバック、バンドルメタデータ、シェイプ処理を変更する前に、焦点を絞った公式ガイダンスを取得すること。
• 通常の作業で docs_enable_page_resources を呼び出さないこと。ページはオンデマンドで取得すること。
• schriftgestalt/GlyphsSDK の現在の Glyphs4 ブランチを優先すること。Glyphs 3 のテンプレートやキャッシュされたローダーが最新であると想定しないこと。
• 動作の変更は、機械的な移行の変更と分離して管理すること。

Glyphs MCP 知識ベースのワークフロー

API 固有の調査結果を確認する前に、references/glyphs-mcp-development-kb.md を読むこと。

1. docs_search と docs_get が Glyphs MCP サーバーから利用可能であることを確認する。
2. 編集前にドキュメントのベースラインを確立する：
   • plugins を検索し、公式のプラグインハンドブック結果を取得する。
   • Info.plist を検索し、Python プラグインテンプレートの概要と plist テンプレートを取得する。
   • 正確な基底クラス（例：GeneralPlugin、ReporterPlugin、FilterWithoutDialog、PalettePlugin、SelectTool、FileFormatPlugin）を検索し、そのガイド、ソーステンプレート、関連するプラグイン API セクションを取得する。
3. 未知のクラス、プロパティ、コールバック、またはセレクタは個別に検索する。GSLayer、shapes、addCallback のような短い正確なシンボルを優先する。
4. 返された doc_id または path で結果を取得する。truncated が true の場合は、関連するセクションが完了するまで nextOffset から続ける。
5. 取得した各ページのタイトル、docId、sourceKind、sourceUrl、およびそれをサポートする移行判断を記録する。この証拠を引継ぎ情報に含める。
6. ツールが利用できない場合は、Glyphs MCP ドキュメントレビューがブロックされていることを報告する。静的な監査は継続できるが、未検証の API やライフサイクルの変更を移行準備完了として提示しないこと。

ワークフロー

1. ソースプラグインまたはリポジトリ、意図する互換性ターゲット（Glyphs 4 only または Glyphs 3 and 4）、および新しい出力パスを特定する。

2. Glyphs MCP 開発知識ベースに接続し、検出されたプラグインファミリのベースラインページを取得する。

3. 公式 GlyphsSDK Glyphs4 ブランチの最新チェックアウトを入手または特定する。

4. コピー前に監査を実行する：

   python3 scripts/migrate_plugin.py "/path/to/source" \
     --sdk "/path/to/GlyphsSDK"
   

5. references/migration-review.md を読む。API 固有の調査結果ごとに、バンドルされた Glyphs ドキュメントでそのクラス、プロパティ、コールバック、セレクタ、またはプラグインタイプを検索し、関連するページのみを取得する。

6. 移行コピーを作成し、控えめなフレームワークインポート修正を適用する：

   python3 scripts/migrate_plugin.py "/path/to/source" \
     --output "/path/to/new-glyphs4-copy" \
     --sdk "/path/to/GlyphsSDK" \
     --apply-safe-fixes
   

7. 影響を確認した後でのみ、オプションの書き換えを使用する：

   • --rewrite-wildcard-imports を追加して、Glyphs 4 の .pyi スタブで見つかったシンボルを使用して単純な from GlyphsApp import * 文を置き換える。
   • --replace-loader を追加して、SDK テンプレートの Contents/MacOS/plugin を各バンドルにコピーする。
   • --align-glyphs4-plist を追加して、現在の Glyphs 4 テンプレートに存在しないレガシーな更新フィードキーを削除する。事前にプラグインが独自の更新フィードに依存していないことを確認すること。

8. 生成された移行レポートと完全なソース差分をレビューする。ライフサイクル、API、依存関係、UI、または混合シェイプに関する問題を手動で修正する。API 固有の変更はそれぞれ、取得した KB ページに関連付けること。

9. すべてのバンドルを検証する：

   • 対象の Glyphs Python バージョンですべての Python ファイルをパースする。
   • すべての Contents/Info.plist で plutil -lint を実行する。
   • NSPrincipalClass、PyMainFileNames、およびプリンシパル Python クラスが一致することを確認する。
   • バンドル構造を、対応する最新の Glyphs 4 SDK テンプレートと比較する。
   • インターフェースが変更された場合は、.xib ファイルを再コンパイルする。

10. 手動テスト計画を引き継ぐ。使い捨てのコピーを Glyphs 4 でテストし、すべてのメニューエントリとコールバックを実行し、Macro Panel と Console の出力を検査し、プラグインに関連するアンドゥ、エクスポート、描画、依存関係のパスをテストする。

互換性の判断

• Glyphs 4 only の場合：現在のスタブで確認した上で、Glyphs 4 ランタイムがサポートする API と Python 構文のみを許可する。
• Glyphs 3 and 4 の場合：可能な場合は共有コードパスを維持し、実際の API の違いは機能チェックでガードし、両方のアプリでテストする。注釈のみのために Glyphs 4 専用の構文を追加しないこと。
• プラグインが layer.paths、layer.components、または layer.shapes を再構築する場合、混合シェイプの順序や新しいシェイプの種類を保持する必要があるかどうかを検査すること。パスのみの書き換えがロスレスであると推測しないこと。

成果物

新しいコピー、移行レポート、互換性ターゲット、静的検証結果、および残っている手動の Glyphs 4 テストを返すこと。各ページのタイトル、Glyphs MCP の docId、公式の sourceUrl、およびそれがサポートする判断を含むドキュメントエビデンステーブルを含めること。実際に実行時テストを行わなかった場合は、その旨を明確に記載すること。

リソース

• scripts/migrate_plugin.py：監査および非破壊コピーヘルパー。
• references/migration-review.md：エビデンスベースのレビューチェックリストとエスカレーションポイント。
• references/glyphs-mcp-development-kb.md：MCP ルックアップ、ページング、エビデンス、および復旧プロトコルの詳細。
• .mcp.json：ローカルの Glyphs MCP サーバーへの Claude Code プラグイン接続。
• mcp.json：ローカルの Glyphs MCP サーバーへの Cursor プラグイン接続。
• .claude-plugin/plugin.json：Claude Code コミュニティ/プラグインメタデータ。このフォルダを claude --plugin-dir で読み込みます。
• .cursor-plugin/plugin.json：ルートの SKILL.md と mcp.json を登録する Cursor プラグインメタデータ。
• agents/openai.yaml：Codex の表示メタデータと Glyphs MCP 依存関係。