1 Start here

• Confirm the target Flutter stable release from official Flutter sources.
• Read frb-dev-env before running setup, generation, lint, or tests. Use its per-worktree local Docker workflow.
• Read frb-upgrade-docker when the target toolchain changes the development image.
• Read frb-docker for ordinary local Docker usage.
• Read frb-code-generation before accepting generated or scaffold drift.
• Read frb-cargokit before changing any copied CargoKit file. Read frb-cargokit-dev only when the source change belongs in the external CargoKit repository.
• Read frb-pr-chain-split as soon as an independently landable prerequisite or cleanup appears.
• Read frb-prepare-pr and then frb-pr-review before treating the upgrade PR as ready.
• Read frb-fix-ci when CI starts failing.

2 Establish the version contract

• Record the target Flutter version, bundled Dart version, release date, and relevant release-note changes.
• Distinguish the primary Dart version from the minimum supported Dart SDK floor.
  • Upgrade the primary Dart pin with Flutter.
  • Do not raise package SDK constraints merely because the primary toolchain is newer.
  • When retaining an older SDK floor, run dependency resolution, analysis, and tests on that floor in CI.
• Inventory version-like values without assuming the target Dart major or minor:

rg -n "FRB_MAIN_|FLUTTER_VERSION|DART_VERSION|RUST_VERSION|setup-flutter|setup-dart|cirruslabs/flutter"
rg -n "flutter_rust_bridge_dev|stable|nightly|minimum.*version|deployment.*target" \
  .devcontainer .github tools frb_codegen frb_example

• Inspect at least:
  • .devcontainer/Dockerfile;
  • .github/workflows/ci.yaml and .github/workflows/post_release.yaml;
  • .github/workflows/publish_dev_docker.yaml;
  • tools/frb_internal/test/src/makefile_dart/test_dev_docker_metadata.dart;
  • package pubspec.yaml and checked-in pubspec.lock files;
  • frb_codegen/assets/integration_template/**;
  • tools/frb_internal/assets/apple_scaffold/**;
  • tools/tart_macos/**;
  • frb_example/**.

3 Choose PR boundaries before implementation

• When the development image changes, make its upgrade the first independent predecessor PR targeting master. Follow frb-upgrade-docker for its contents, candidate image, merge order, and stable-tag promotion.
• Keep generated snapshots, their generator changes, required tests, and upgrade-specific compatibility migrations in the main upgrade PR.
• Split independent bug fixes, hardening, and reusable prerequisites into predecessor PRs according to frb-pr-chain-split.
• Build and maintain any predecessor chain exclusively with the official gh stack workflow described there.
• Put ci-manual-dispatch on dormant predecessors unless a predecessor specifically needs GitHub-only validation.
• Do not move incidental skill or workflow cleanup into the upgrade PR when it can stand alone against master.

4 Upgrade the development toolchain

• Complete the independent Docker predecessor through frb-upgrade-docker before relying on the upgraded image.
• Use its immutable candidate tag for pre-merge validation when necessary; never move latest from a PR branch.
• After the predecessor merges and publishes stable tags, merge latest master into the remaining upgrade chain and use the canonical version tag.
• If Apple pins, simulators, or host tooling change, continue with the Tart workflow routed by frb-dev-env and read frb-tart-prepare before provisioning or validation.

5 Synchronize CI and post-release pins

• Update the top-level toolchain values together in .github/workflows/ci.yaml and .github/workflows/post_release.yaml:
  • FRB_MAIN_FLUTTER_VERSION;
  • FRB_MAIN_DART_VERSION;
  • FRB_MAIN_RUST_VERSION when the upgraded tooling requires it;
  • FRB_RUSTFMT_NIGHTLY_VERSION only when formatting or nightly rust-src behavior requires it.
• Keep a retained minimum Dart floor explicit and independently exercised; do not substitute the primary Dart pin for that compatibility lane.
• Review Java, Android SDK/NDK, Chrome/chromedriver, macOS runner, simulator, Windows ARM, and post-release install-mode assumptions.

6 Regenerate through owner workflows

• Follow frb-code-generation for command selection, convergence, generated-output provenance, legacy scaffold migrations, and OHOS integrate composition.
• Follow frb-cargokit and frb-cargokit-dev for CargoKit ownership and synchronization.

7 Validate in dependency order

• Use the environment selected by frb-dev-env. When the Docker image changed, use the candidate or canonical image selected by frb-upgrade-docker; do not reuse a stale per-worktree container.
• Read frb-lint and frb-test for exact commands.
• Validate in this order:
  1. dev-image metadata and tool versions;
  2. Dart analysis, tests, and the retained minimum-SDK lane;
  3. internal generation and second-pass cleanliness;
  4. integration generation and CargoKit synchronization;
  5. focused legacy Android and Apple platform builds affected by migrations;
  6. representative native and web examples.
• Before creating or updating the PR, run frb-prepare-pr.
• Before declaring it ready, run the independent review gate in frb-pr-review.

8 Triage CI and finish

• Read frb-fix-ci before deep CI debugging.
• Triage failures in dependency order: environment setup, generation, integration, platform builds, post-release, then coverage or uploads.
• Compare platform failures with target-Flutter release notes and fresh scaffold output before adding workarounds.
• Keep full CI on the top upgrade PR. Follow frb-pr-chain-split for filtered or deferred predecessor CI.
• The Docker predecessor must already be merged and stably published through frb-upgrade-docker; do not defer image publication until the main Flutter upgrade PR merges.

9 PR notes

• Record old and new Flutter and primary Dart versions.
• Record the retained or raised minimum Dart SDK floor and its validation lane.
• List generated files, direct Flutter migrator edits, CargoKit changes, and OHOS overlays by provenance.
• Link predecessor PRs and identify which ones intentionally use manual CI.
• Record the fresh dev-image tag, exact local validations, generation convergence result, and CI status.
• Call out any platform-specific follow-up that remains intentionally out of scope.