flutter-mcp-toolkit-repo-maintainer

flutter-mcp-toolkit リポジトリのメンテナー向け

このリポジトリ（エンドユーザー向けの Flutter アプリではありません）における推奨手順です。main では release-please を優先し、Release PR の手順が妨げられている場合に限り、手動の手順を使用してください。

使用する場面

• リリースを作成する場合、または CHANGELOG.md の ## [Unreleased] をリリースに昇格させる場合
• コントリビューター向けドキュメント、AI エージェントのインストール手順、またはプラグインのスキルを追加・編集する場合
• マージ前にバージョンの同期やスキルアセットのずれを確認する場合
• release-please、release.yml のバイナリ、または install.sh のバージョン固定の問題をトラブルシューティングする場合

バージョンに関わる箇所（ルートの VERSION と一致させる必要があります）

File	Field
VERSION	repo pin
plugin/EXPECTED_SERVER_VERSION	installer pin
packages/core/lib/src/runtime_version.dart	kFlutterMcpVersion (x-release-please-version)
packages/server_capability_core/lib/src/fmt_capability.dart	version getter
mcp_server_dart/pubspec.yaml	version:
mcp_toolkit/pubspec.yaml	version:
packages/core/pubspec.yaml	version:
packages/server_capability_kernel/pubspec.yaml	version: + same-train dependency constraints
packages/server_capability_core/pubspec.yaml	version: + same-train dependency constraints
plugin/.cursor-plugin/plugin.json	version
plugin/.codex-plugin/plugin.json	version
plugin/.claude-plugin/plugin.json	version
.claude-plugin/marketplace.json	plugins[0].version
.release-please-manifest.json	"." key
mcp_server_dart/lib/src/skill_assets.g.dart	generated — embeds plugin/.cursor-plugin/plugin.json, plugin/.codex-plugin/plugin.json, plugin/mcp.json, and all plugin/skills/*/SKILL.md

バージョンを更新したら、make sync-version、make sync-skills、make check-contracts の順に実行してください（check_version_sync.sh と check_skill_assets_drift.sh を含みます）。tool/release/sync_version.sh は、ルートの VERSION からすべてのバージョン関連箇所を導出します。

Video（別リポジトリ）： flutter_mcp_video — このプラグインツリーではメンテナンスされていません。外部の flutter_harness リポジトリは廃止されています（ADR-0017）。そのシナリオレイヤーは移行されていません。

変更履歴のワークフロー

1. CHANGELOG.md の ## [Unreleased] の下に、ユーザー向けの変更点を追加します（Keep a Changelog のセクション：Added、Changed、Fixed、Documentation）。
2. main では、release-please が変更を集約できるよう、Conventional Commits 形式のタイトル（feat:、fix:、docs:）を使用します。
3. .cursor/plans/ 内の計画ファイルは編集しないでください。

Markdown の lint（MD052）

Keep a Changelog では、## [3.0.1] のようなバージョン見出しが必須です。リンターは [3.0.1] を未定義の参照リンクとして扱います（MD052：「リンク定義が見つかりません」）。

• CHANGELOG.md のファイル先頭にある `` は削除しないでください（release-please がセクションを先頭に追加する際に必要です）。
• 箇条書きの本文では、コード識別子にバッククォートを使用してください。`AgentCallEntry` のように記述し、[AgentCallEntry] とはしないでください。
• マージ前に bash tool/contracts/check_changelog_markdown.sh を実行します（make check-contracts にも含まれています）。

自動リリース（推奨）

flowchart LR
  main[merge_to_main] --> rp[release-please.yml]
  rp --> pr[Release_PR]
  pr --> sync[release_pr_sync_versions.yml]
  pr --> assets[release_pr_sync_skills.yml]
  pr --> tag[vX_Y_Z_tag]
  tag --> rel[release.yml_binaries]
  tag --> pub[pub_publish.yml_pubdev]

1. Conventional Commits 形式のコミットで PR を main にマージします。
2. release-please.yml による Release PR を待ちます。
3. バージョン系列： release_pr_sync_versions.yml は Release PR に対して tool/release/sync_version.sh を実行し、ルートの VERSION との不整合があればコミットします。
4. スキルアセット： release_pr_sync_skills.yml は、差分が検出された場合、Release PR に skill_assets.g.dart を自動コミットします。また、PR のオープン時にチェックリストのコメントを投稿します。skill-assets-drift が引き続き失敗する場合は、ローカルで make sync-skills を実行してプッシュしてください。
5. その PR で VERSION、CHANGELOG、pubspec、プラグインのピン留めを確認してからマージします。
6. release-please が vX.Y.Z と GitHub リリースノートを作成します。
7. release.yml はタグが VERSION と一致することを検証してから、flutter_mcp_* の tarball を添付します（リリース本文は上書きしません）。
8. pub_publish.yml は、OIDC を使用して依存関係の順に pub.dev パッケージを公開します：flutter_mcp_toolkit_core → flutter_mcp_toolkit_capability_kernel → flutter_mcp_toolkit_capability_core → mcp_toolkit。

自動で pub.dev に公開するには、各パッケージをあらかじめ一度手動で公開しておく必要があります。また、pub.dev の管理者が、このリポジトリでタグパターン v{{version}} を指定して GitHub Actions による公開を有効にする必要があります。必須レビュアーを設定した GitHub 環境 pub.dev を使用してください。

設定：release-please-config.json。

手動リリース（フォールバック）

release-please を利用できない場合や、ブランチからリリースする必要がある場合に使用します。

1. ## [Unreleased] の箇条書きを ## [X.Y.Z] に移動し（日付を追加）、## [Unreleased] は空のままにします。
2. VERSION を X.Y.Z に更新します。
3. make sync-version を実行して、すべてのバージョン参照箇所と .release-please-manifest.json を生成します。
4. make sync-skills を実行します（プラグインマニフェストまたはスキルが変更された場合は必須です）。
5. make check-contracts
6. コミットします：chore: release X.Y.Z
7. 任意の pub.dev 公開前チェック：make publish-pub-dry-run。
8. タグを付けます：git tag vX.Y.Z を実行し、タグをプッシュします（バイナリと pub.dev のワークフローが起動します）。

ローカルでビルド成果物を作成するには、make release-artifacts または bash tool/release/build_release_artifacts.sh --version X.Y.Z を実行します。 ローカルで pub.dev パッケージを公開するのは、フォールバックとしてのみ行います：make publish-pub。

ドキュメント一覧（信頼できる唯一の情報源）

トピック	正式なドキュメント
エンドユーザー向けエージェントのインストール	docs/ai_agents/overview.mdx
npx skills とロックファイル	overview § npx skills でインストール；.skills.json.example
貢献者／リリース	docs/contributing/contribution_guide.mdx
プラグインの構成	plugin/README.md
マーケットプレイス掲載文の信頼できる唯一の情報源	docs/ai_agents/marketplace_copy.yaml
配布／ストア	docs/ai_agents/marketplace_distribution.mdx
ストア申請手順書	docs/contributing/marketplace_submission_runbook.mdx
スキルの本文	plugin/skills/<id>/SKILL.md → make sync-skills

README にインストール表を重複して記載するのは避け、overview へのリンクを使用してください。

スキルのメンテナンス

• 正式なスキル：plugin/skills/（リポジトリルートの skills/ は npx skills 用のシンボリックリンクです）。
• 新しいバンドル済みスキル：plugin/skills/<id>/SKILL.md を追加し、build_skill_assets.dart の expectedSkillIds に id を追加して、make sync-skills を実行します。
• ローカルの Cursor 用コピー：.cursor/skills/<id>/ から plugin/skills/<id>/ へシンボリックリンクを作成してもかまいません。
• プラットフォームのドッグフーディング用スキル：flutter-mcp-toolkit-maintain-web、flutter-mcp-toolkit-maintain-macos、flutter-mcp-toolkit-dogfood-iterations。

HyperFrames のプロモーション（flutter_mcp_video リポジトリ）

動画スキルとプロジェクトは flutter_mcp_video（skills/hyperframes-video/、projects/video-projects/<id>/）にあります。ツールキットの make sync-skills には含まれません。

そこでプロモーションを公開する場合は、動画リポジトリを編集し、マージ前にそのリポジトリで bash tool/check_doc_paths.sh を実行します。ツールキットのリポジトリには、共有ブランドアセットを plugin/assets/（v7-weaver 用のシンボリックリンク先）にのみ置きます。

IntentCall のコンシューマー統合に関するメンテナーの確認事項

mcp_flutter の IntentCall コンシューマー統合を変更する場合：

1. まだ追加されていない場合は、build_skill_assets.dart の expectedSkillIds に flutter-mcp-toolkit-intentcall-migration を追加します。
2. make sync-skills を実行し、スキルの編集内容とともに skill_assets.g.dart をコミットします。
3. bash tool/contracts/check_intentcall_skills_grep.sh を実行します。移行スキル以外にレガシーの呼び出しエントリーシンボルがないことを確認します。
4. cd mcp_server_dart && dart test test/contract/ を実行します。
5. flutter-mcp-toolkit migrate agent-entries --check showcase/flutter_test_app/lib を実行します（終了コード 0 が想定されます）。
6. IntentCall の正規デザインへのリンクは IntentCall リポジトリを参照するようにし、このリポジトリはホストされる依存関係とリグレッションの検証に専念させます。

マージ前のチェックリスト

• make check-contracts
• plugin/skills/ または plugin/*-plugin/plugin.json を変更した場合は make sync-skills を実行する
• ユーザーに見える変更について CHANGELOG の [Unreleased] を更新する
• コミットする設定ファイルにシークレットが含まれていないこと