| name | flutter-mcp-toolkit-repo-maintainer |
| description | Maintain mcp_flutter releases, CHANGELOG, version pins, docs, and CI. Use when cutting a release, editing CHANGELOG.md, bumping VERSION, running release-please, sync-skills, check-contracts, or updating install/docs for npx skills and flutter-mcp-toolkit init. |
flutter-mcp-toolkit repo maintainer
Golden path for this repository (not end-user Flutter apps). Prefer
release-please on main; use manual steps only when the Release PR path is blocked.
When to use
- Cutting a release or promoting
## [Unreleased] in CHANGELOG.md
- Adding/editing contributor docs, AI agent install docs, or plugin skills
- Verifying version sync or skill asset drift before merge
- Troubleshooting release-please,
release.yml binaries, or install.sh version pins
Version touchpoints (must match root VERSION)
After any version bump: run make sync-version, then make sync-skills, then make check-contracts (includes check_version_sync.sh and check_skill_assets_drift.sh). tool/release/sync_version.sh derives all version touchpoints from root VERSION.
Harness / video (separate repos): flutter_harness, flutter_mcp_video — not maintained in this plugin tree. Three-repo layout: flutter_harness/docs/RELATED_REPOS.md.
Changelog workflow
- Add user-facing notes under
## [Unreleased] in CHANGELOG.md (Keep a Changelog sections: Added, Changed, Fixed, Documentation).
- Use conventional commit titles on
main (feat:, fix:, docs:) so release-please can aggregate.
- Do not edit the plan file in
.cursor/plans/.
Markdown lint (MD052)
Keep a Changelog requires version headings like ## [3.0.1]. Linters treat [3.0.1] as an undefined reference link (MD052: "No link definition found").
- Do not remove the file-top
<!-- markdownlint-disable MD052 --> in CHANGELOG.md (release-please must keep it when prepending sections).
- In bullet text, use backticks for code identifiers:
`AgentCallEntry`, not [AgentCallEntry].
- Before merge:
bash tool/contracts/check_changelog_markdown.sh (also in make check-contracts).
Automated release (preferred)
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]
- Merge PRs to
main with conventional commits.
- Wait for Release PR from release-please.yml.
- version train: release_pr_sync_versions.yml runs
tool/release/sync_version.sh on Release PRs and commits any drift from root VERSION.
- skill assets: release_pr_sync_skills.yml auto-commits
skill_assets.g.dart on Release PRs when drift is detected; posts a checklist comment on PR open. If skill-assets-drift still fails, run make sync-skills locally and push.
- Review VERSION, CHANGELOG, pubspecs, plugin pins in that PR → merge.
- release-please creates
vX.Y.Z + GitHub release notes.
- release.yml asserts tag ==
VERSION, then attaches flutter_mcp_* tarballs (does not overwrite release body).
- pub_publish.yml publishes pub.dev packages in dependency order through OIDC:
flutter_mcp_toolkit_core → flutter_mcp_toolkit_capability_kernel → flutter_mcp_toolkit_capability_core → mcp_toolkit.
Before automated pub.dev publishing can run, each package must already have a first manual publish and pub.dev Admin must enable GitHub Actions publishing for this repository with tag pattern v{{version}}. Use GitHub environment pub.dev with required reviewers.
Config: release-please-config.json.
Manual release (fallback)
Use when release-please is unavailable or you must ship from a branch:
- Move
## [Unreleased] bullets into ## [X.Y.Z] (add date), leave empty ## [Unreleased].
- Update
VERSION to X.Y.Z.
make sync-version to derive all version touchpoints and .release-please-manifest.json.make sync-skills (required whenever plugin manifests or skills change).make check-contracts- Commit:
chore: release X.Y.Z
- Optional pub.dev preflight:
make publish-pub-dry-run.
- Tag:
git tag vX.Y.Z and push tag (triggers binary and pub.dev workflows).
Build artifacts locally: make release-artifacts or bash tool/release/build_release_artifacts.sh --version X.Y.Z.
Publish pub.dev packages locally only as a fallback: make publish-pub.
Docs map (single sources of truth)
Avoid duplicating install tables in README — link to overview.
Skills maintenance
- Canonical skills:
plugin/skills/ (repo root skills/ → symlink for npx skills).
- New bundled skill: add
plugin/skills/<id>/SKILL.md, append id to expectedSkillIds in build_skill_assets.dart, run make sync-skills.
- Local Cursor copy:
.cursor/skills/<id>/ may symlink to plugin/skills/<id>/.
- Platform dogfood skills:
flutter-mcp-toolkit-maintain-web, flutter-mcp-toolkit-maintain-macos, flutter-mcp-toolkit-dogfood-iterations.
HyperFrames promo (flutter_mcp_video repo)
Video skill and projects live in flutter_mcp_video (skills/hyperframes-video/, projects/video-projects/<id>/). Not bundled in toolkit make sync-skills.
When shipping a promo there: edit the video repo; run bash tool/check_doc_paths.sh in that repo before merge. Toolkit repo only hosts shared brand assets under plugin/assets/ (symlink targets for v7-weaver).
IntentCall consumer maintainer gate
When changing IntentCall consumer integration in mcp_flutter:
- Append
flutter-mcp-toolkit-intentcall-migration to expectedSkillIds in build_skill_assets.dart if not already present.
make sync-skills — commit skill_assets.g.dart with skill edits.bash tool/contracts/check_intentcall_skills_grep.sh — no legacy call-entry symbol outside migration skill.cd mcp_server_dart && dart test test/contract/flutter-mcp-toolkit migrate agent-entries --check flutter_test_app/lib (expect exit 0)- Keep canonical IntentCall design links pointed at the IntentCall repository; keep this repo focused on hosted dependency and regression proof.
Pre-merge checklist
