# Contributor handoff — flutter/flutter

> Canonical page: https://codevetter.com/unpack/flutter/agent-handoff

# Contributor handoff — flutter/flutter

Scanned commit acb8fd51143a49384799557cb1df6ecead61a55a (2026-09-22). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

This repo punishes agents that skip the bootstrap layer: the CLI only works from a real git clone with git on PATH, and editing flutter_tools' pubspec triggers a full snapshot rebuild on next run. Shell logic is duplicated between .sh and .bat files and must be kept in sync. The DI layer (context.get/globals + overrides) is the sanctioned way to reach services — do not construct singletons directly. Most engine-facing changes need a local engine build via --local-engine flags. Tests run through dev/bots/test.dart with SHARD/SUBSHARD, and the authoritative CI config is .ci.yaml, not .github/workflows.
- Read first (tool work): bin/internal/shared.sh (bootstrap+locking), packages/flutter_tools/lib/executable.dart (command table + overrides), lib/runner.dart (error/exit semantics), lib/src/runner/flutter_command.dart + flutter_command_runner.dart (arg plumbing), lib/src/base/context.dart + globals.dart (DI). — [bin/internal/shared.sh](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh) [packages/flutter_tools/lib/executable.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart) [packages/flutter_tools/lib/runner.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart) [packages/flutter_tools/lib/src/runner/flutter_command_runner.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/runner/flutter_command_runner.dart)
- The tool hard-fails if $FLUTTER_ROOT/.git is missing or git is not on PATH — packaged archives rely on a different code path, so test changes against a real clone. — [bin/internal/shared.sh#L229-242](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L229-L242)
- Editing packages/flutter_tools/pubspec.yaml invalidates the tool snapshot (mtime check) — the next `flutter` invocation rebuilds it; commit pubspec.lock consistently or users hit unexpected rebuilds. — [bin/internal/shared.sh#L124-146](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L124-L146)
- Keep paired scripts in sync by convention: bin/flutter <-> flutter.bat, shared.sh <-> shared.bat, update_dart_sdk.sh <-> .ps1, update_engine_version.sh <-> .ps1 — headers explicitly demand parity. — [bin/flutter#L6-12](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/flutter#L6-L12) [bin/internal/shared.sh#L6-12](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L6-L12)
- Files under packages/flutter_tools/lib/src/isolated are excluded from google3; anything depending on dwds/devtools sources must stay there or be injected via the overrides map — moving imports out silently breaks internal builds. — [packages/flutter_tools/lib/executable.dart#L61-73](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L61-L73) [packages/flutter_tools/lib/executable.dart#L140-155](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L140-L155)
- Run tests the repo's way: `dart dev/bots/test.dart` with SHARD=/SUBSHARD= (e.g. SHARD=tool_tests SUBSHARD=general), or `flutter test` inside a package dir; pass --local-engine=host_debug_unopt when validating against a locally built engine. — [dev/bots/test.dart#L25-40](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L25-L40) [dev/bots/test.dart#L84-103](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L84-L103)
- Framework edits: source in packages/flutter/lib/src/<area> mirrors tests in packages/flutter/test/<area>; golden-image changes flow through packages/flutter_goldens and Skia Gold — expect golden tests to fail until images are triaged. — [packages/flutter/lib/src](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/src) [packages/flutter/test](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/test) [packages/flutter_goldens](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_goldens)
- Engine edits live in engine/src/flutter (GN/Ninja, not pub): unit tests are *_unittests.cc beside sources; DEPS holds pinned dep revisions that should be rolled with the documented tooling rather than hand-edited. — [engine/src/flutter/shell/common/engine_unittests.cc](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/common/engine_unittests.cc) [DEPS#L30-60](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/DEPS#L30-L60) [engine/src/flutter/BUILD.gn](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/BUILD.gn)
- Lint/style: every Dart file starts with the BSD license header; root analysis_options.yaml/analysis_options_common.yaml enforce strict lints; dev/bots/analyze.dart plus cross-import checkers run in CI — run them before pushing. — [analysis_options.yaml](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/analysis_options.yaml) [analysis_options_common.yaml](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/analysis_options_common.yaml) [dev/bots/analyze.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/analyze.dart) [dev/bots/check_tests_cross_imports.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/check_tests_cross_imports.dart)
- CI truth source is .ci.yaml + dev/bots/test.dart shards; .github/workflows only runs auxiliary PR checks — adding a CI target means editing .ci.yaml (and likely registering a suite runner), not a GitHub workflow. — [.ci.yaml#L1-14](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.ci.yaml#L1-L14) [dev/bots/test.dart#L124-140](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L124-L140) [.github/workflows/tool-test-general.yml#L1-35](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.github/workflows/tool-test-general.yml#L1-L35)
- Error paths are contractual: throw ToolExit/throwToolExit for user-facing failures (maps to exit codes), UsageException gives exit 64 — never call exit() directly from command code because shutdown hooks and crash reporting are bypassed. — [packages/flutter_tools/lib/runner.dart#L243-265](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart#L243-L265)
- Common trap: 'files scanned' inventories miss most of this repo — the file walk capped at 4000 of a much larger tree; rely on grep/glob inside packages/flutter_tools/lib/src and engine/src/flutter rather than assuming a small codebase. (inferred) — [packages/flutter_tools/lib/src](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src) [engine/src/flutter](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)