From 5b2cb6a9da4cd30085c29122c8c189bc404b94bd Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Fri, 26 Jun 2026 16:24:56 -0700 Subject: [PATCH 01/11] first draft --- .../camera/camera_android_camerax/AGENTS.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 packages/camera/camera_android_camerax/AGENTS.md diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md new file mode 100644 index 000000000000..a67eafeb4390 --- /dev/null +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -0,0 +1,32 @@ +# AGENTS.md: Project One Shot Guide for flutter/packages + +This document provides context, behavioral guidelines, and core commands for AI agents contributing to the `flutter/packages` repository as part of **Project One Shot**. + +Your goal is to autonomously solve complex engineering issues in a single, high-quality execution pass, requiring human intervention *only* during the initial planning phase and the final code review. + +## 1. Agent Persona & Communication Protocol + +To achieve a "one-shot" resolution, you must act as a world-class, deeply skeptical software engineer. +- **Zero Fluff ("No Bullshit"):** Never praise questions, validate premises, or use conversational pleasantries. Output concise, markdown-formatted responses. +- **Be Direct & Critical:** If a human's proposed plan is flawed or introduces unnecessary complexity, state so immediately. Lead with the strongest counterargument. +- **Skeptical Verification:** When writing or reviewing tests, act as a deeply skeptical engineer. Actively look for ways the test could generate a false positive or pass when the underlying feature is broken. + +## 2. The One-Shot Workflow + +You must operate in three distinct phases. **Do not move to the next phase until the requirements of the current phase are met.** + +1. **Phase A: Planning:** Analyze the issue and generate a highly specific `implementation_plan.md` containing code pointers, exact files to modify, and a robust testing strategy. **Wait for human approval.** +2. **Phase B: Execution:** Implement the code strictly according to the approved plan. Do not introduce unrequired code complexity or unpinned dependency version bumps. +3. **Phase C: Validation:** Autonomously run the Core Tooling validation checks (see below). Do not declare your work "done" or request human review until all checks pass with zero failures. + +## 3. Environment Setup + +The primary tool for this repository is `flutter_plugin_tools.dart`. Before running commands, ensure you define the repository root: + +```bash +# Define an environment variable for the repository root. +export REPO_ROOT=$(pwd) + +# Verify setup +echo "Repository root directory: $REPO_ROOT" +dart pub get -C $REPO_ROOT/script/tool From 5248366343bae8ede0035edb475346889c0298fb Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Mon, 29 Jun 2026 17:14:54 -0700 Subject: [PATCH 02/11] rewrite draft --- .../camera/camera_android_camerax/AGENTS.md | 71 +++++++++++++------ 1 file changed, 51 insertions(+), 20 deletions(-) diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md index a67eafeb4390..f51934ef62c3 100644 --- a/packages/camera/camera_android_camerax/AGENTS.md +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -1,32 +1,63 @@ -# AGENTS.md: Project One Shot Guide for flutter/packages +# Agent Guide for camera_android_camerax -This document provides context, behavioral guidelines, and core commands for AI agents contributing to the `flutter/packages` repository as part of **Project One Shot**. +This document provides context, architectural details, and core workflows for contributing to the `camera_android_camerax` package. -Your goal is to autonomously solve complex engineering issues in a single, high-quality execution pass, requiring human intervention *only* during the initial planning phase and the final code review. +For general repository-wide guidelines (including environment setup, versioning, formatting, and general testing patterns), refer to the main [AGENTS.md](../../../AGENTS.md). -## 1. Agent Persona & Communication Protocol +## 1. Architectural Overview -To achieve a "one-shot" resolution, you must act as a world-class, deeply skeptical software engineer. -- **Zero Fluff ("No Bullshit"):** Never praise questions, validate premises, or use conversational pleasantries. Output concise, markdown-formatted responses. -- **Be Direct & Critical:** If a human's proposed plan is flawed or introduces unnecessary complexity, state so immediately. Lead with the strongest counterargument. -- **Skeptical Verification:** When writing or reviewing tests, act as a deeply skeptical engineer. Actively look for ways the test could generate a false positive or pass when the underlying feature is broken. +The `camera_android_camerax` package is the Android platform implementation of the `camera` plugin, using the **Android Jetpack CameraX** library. -## 2. The One-Shot Workflow +### ProxyApi Binding System +This plugin utilizes **Pigeon's ProxyApi** to bind Dart objects directly to native Android CameraX Java/Kotlin objects. +- **Pigeon Definition**: The API surfaces are defined in [pigeons/camerax_library.dart](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/pigeons/camerax_library.dart). +- **Generated Code**: + - Dart proxy classes: [lib/src/camerax_library.g.dart](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/lib/src/camerax_library.g.dart) + - Kotlin proxy classes: [android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt) +- **Plugin Entry Point**: [lib/src/android_camera_camerax.dart](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/lib/src/android_camera_camerax.dart) implements `CameraPlatform` using the generated proxy classes. -You must operate in three distinct phases. **Do not move to the next phase until the requirements of the current phase are met.** +## 2. Code Generation -1. **Phase A: Planning:** Analyze the issue and generate a highly specific `implementation_plan.md` containing code pointers, exact files to modify, and a robust testing strategy. **Wait for human approval.** -2. **Phase B: Execution:** Implement the code strictly according to the approved plan. Do not introduce unrequired code complexity or unpinned dependency version bumps. -3. **Phase C: Validation:** Autonomously run the Core Tooling validation checks (see below). Do not declare your work "done" or request human review until all checks pass with zero failures. +When you modify the Pigeon API definition or any mocked files, you must regenerate the respective code. -## 3. Environment Setup +### Regenerating Pigeon Bindings +If you modify [pigeons/camerax_library.dart](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/pigeons/camerax_library.dart), run: +```bash +# Run from this directory +dart run pigeon --input pigeons/camerax_library.dart +``` + +### Regenerating Mockito Mocks +Tests in this package use `mockito` for mocking. If you add new classes to mock or modify existing mocked classes, run: +```bash +# Run from this directory +dart run build_runner build -d +``` + +## 3. Running Tests -The primary tool for this repository is `flutter_plugin_tools.dart`. Before running commands, ensure you define the repository root: +All changes must pass all three levels of tests: Dart unit tests, Android native unit tests, and integration tests. +### Dart Unit Tests +Dart unit tests are located in [test/](./test/). +To run them from this directory: ```bash -# Define an environment variable for the repository root. -export REPO_ROOT=$(pwd) +dart run ../../../script/tool/bin/flutter_plugin_tools.dart dart-test --packages=camera_android_camerax +``` -# Verify setup -echo "Repository root directory: $REPO_ROOT" -dart pub get -C $REPO_ROOT/script/tool +### Android Native Unit Tests +Android unit tests are located in [android/src/test/](./android/src/test/) and run using Robolectric. +To run them from this directory: +```bash +# From this directory +dart run ../../../script/tool/bin/flutter_plugin_tools.dart native-test --android --packages=camera_android_camerax +``` + +### Integration Tests +Integration tests are located in [example/integration_test/integration_test.dart](./example/integration_test/integration_test.dart). + +#### Running Integration Tests +With an emulator or physical device connected, run from this directory: +```bash +dart run ../../../script/tool/bin/flutter_plugin_tools.dart integration-test --android --packages=camera_android_camerax +``` From ad19064bfff6af9f779c536c0274669d8fad0112 Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Mon, 29 Jun 2026 17:17:35 -0700 Subject: [PATCH 03/11] nit --- packages/camera/camera_android_camerax/AGENTS.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md index f51934ef62c3..0f0de6a3765b 100644 --- a/packages/camera/camera_android_camerax/AGENTS.md +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -55,8 +55,6 @@ dart run ../../../script/tool/bin/flutter_plugin_tools.dart native-test --androi ### Integration Tests Integration tests are located in [example/integration_test/integration_test.dart](./example/integration_test/integration_test.dart). - -#### Running Integration Tests With an emulator or physical device connected, run from this directory: ```bash dart run ../../../script/tool/bin/flutter_plugin_tools.dart integration-test --android --packages=camera_android_camerax From 773288c1bb1dc6b3e6881cecc1b9c0d5a6c6c688 Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Tue, 30 Jun 2026 16:10:22 -0700 Subject: [PATCH 04/11] focus draft --- .../camera/camera_android_camerax/AGENTS.md | 50 +++++++++++-------- 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md index 0f0de6a3765b..4db79a5b6d6c 100644 --- a/packages/camera/camera_android_camerax/AGENTS.md +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -1,42 +1,53 @@ # Agent Guide for camera_android_camerax -This document provides context, architectural details, and core workflows for contributing to the `camera_android_camerax` package. +This document provides context, architectural details, and core workflows for making high quality contributions to the `camera_android_camerax` package. -For general repository-wide guidelines (including environment setup, versioning, formatting, and general testing patterns), refer to the main [AGENTS.md](../../../AGENTS.md). - -## 1. Architectural Overview +## Architectural Overview The `camera_android_camerax` package is the Android platform implementation of the `camera` plugin, using the **Android Jetpack CameraX** library. ### ProxyApi Binding System This plugin utilizes **Pigeon's ProxyApi** to bind Dart objects directly to native Android CameraX Java/Kotlin objects. -- **Pigeon Definition**: The API surfaces are defined in [pigeons/camerax_library.dart](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/pigeons/camerax_library.dart). +- **Pigeon Definition**: The API surfaces are defined in [pigeons/camerax_library.dart](pigeons/camerax_library.dart). - **Generated Code**: - - Dart proxy classes: [lib/src/camerax_library.g.dart](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/lib/src/camerax_library.g.dart) - - Kotlin proxy classes: [android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt) -- **Plugin Entry Point**: [lib/src/android_camera_camerax.dart](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/lib/src/android_camera_camerax.dart) implements `CameraPlatform` using the generated proxy classes. + - Dart proxy classes: [lib/src/camerax_library.g.dart](lib/src/camerax_library.g.dart) + - Kotlin proxy classes: [android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt) +- **Plugin Entry Point**: [lib/src/android_camera_camerax.dart](lib/src/android_camera_camerax.dart) implements `CameraPlatform` using the generated proxy classes. + +## Required Steps Before Making Any Changes + +Before making any changes, run the the [check-readiness skill](.agents/skills/check-readiness/SKILL.md) to ensure your environment has all the required tooling. -## 2. Code Generation +## Required Steps After Making Any Changes -When you modify the Pigeon API definition or any mocked files, you must regenerate the respective code. +1. **Regenerate Code (if applicable)**: + - If you modified [pigeons/camerax_library.dart](pigeons/camerax_library.dart), run the Pigeon generation command under [Code Generation](#code-generation). + - If you modified any classes that are mocked or added new mocks, run the Mockito generation command under [Code Generation](#code-generation). +2. **Verify Tests**: + - Ensure you have added or updated unit tests to cover your changes. + - Run and pass all tests (see [Running Tests](#running-tests) for details): + - Dart unit tests. + - Android native unit tests. + - Integration tests. + +## Code Generation + +When you modify the Pigeon API [pigeons/camerax_library.dart](pigeons/camerax_library.dart), you must regenerate the respective code to update the Dart proxy class [lib/src/camerax_library.g.dart](lib/src/camerax_library.g.dart) and the Kotlin proxy class [android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt). Run from this directory: -### Regenerating Pigeon Bindings -If you modify [pigeons/camerax_library.dart](file:///Users/camillesimon/packages/packages/camera/camera_android_camerax/pigeons/camerax_library.dart), run: ```bash -# Run from this directory dart run pigeon --input pigeons/camerax_library.dart ``` -### Regenerating Mockito Mocks -Tests in this package use `mockito` for mocking. If you add new classes to mock or modify existing mocked classes, run: +Because test in this package use `mockito` for mocking, you must also regenerate the Mockito mocks that are used for unit testing any changes you make. So, also run from this directory: + ```bash -# Run from this directory dart run build_runner build -d ``` -## 3. Running Tests +## Running Tests -All changes must pass all three levels of tests: Dart unit tests, Android native unit tests, and integration tests. +All changes you make require at least a unit test in the respective language where you make changes (Dart or Android/Java). Furthermore, all tests must pass after you make changes (Dart unit tests, Android native unit tests, Flutter integration tests). +Details on running each of these below. ### Dart Unit Tests Dart unit tests are located in [test/](./test/). @@ -49,11 +60,10 @@ dart run ../../../script/tool/bin/flutter_plugin_tools.dart dart-test --packages Android unit tests are located in [android/src/test/](./android/src/test/) and run using Robolectric. To run them from this directory: ```bash -# From this directory dart run ../../../script/tool/bin/flutter_plugin_tools.dart native-test --android --packages=camera_android_camerax ``` -### Integration Tests +### Flutter Integration Tests Integration tests are located in [example/integration_test/integration_test.dart](./example/integration_test/integration_test.dart). With an emulator or physical device connected, run from this directory: ```bash From 80aa881aba5794658d670fae258ca15fc21d8558 Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Tue, 30 Jun 2026 16:16:08 -0700 Subject: [PATCH 05/11] wording --- packages/camera/camera_android_camerax/AGENTS.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md index 4db79a5b6d6c..d866a5b94722 100644 --- a/packages/camera/camera_android_camerax/AGENTS.md +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -46,8 +46,7 @@ dart run build_runner build -d ## Running Tests -All changes you make require at least a unit test in the respective language where you make changes (Dart or Android/Java). Furthermore, all tests must pass after you make changes (Dart unit tests, Android native unit tests, Flutter integration tests). -Details on running each of these below. +When you make a change, add a test if you can (either a Dart unit test, Android native unit test, or Flutter integration tests). Regardless of if tests are added or not, all tests must pass after you make changes. How to run the tests: ### Dart Unit Tests Dart unit tests are located in [test/](./test/). From aea5aa1a63c66eeee2433ac9d5612d2323465d4f Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Wed, 8 Jul 2026 09:47:02 -0700 Subject: [PATCH 06/11] add pre-push skill and other lessons learned from project --- .../camera/camera_android_camerax/AGENTS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md index d866a5b94722..5668f068cc53 100644 --- a/packages/camera/camera_android_camerax/AGENTS.md +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -29,6 +29,8 @@ Before making any changes, run the the [check-readiness skill](.agents/skills/ch - Dart unit tests. - Android native unit tests. - Integration tests. +3. **Static Analysis**: + - Do not rely on ad-hoc or generic commands to check for formatting or lint errors. Always use the [dart-run-static-analysis skill](.agents/skills/dart-run-static-analysis/SKILL.md) during development to analyze the code and apply automated fixes. ## Code Generation @@ -68,3 +70,19 @@ With an emulator or physical device connected, run from this directory: ```bash dart run ../../../script/tool/bin/flutter_plugin_tools.dart integration-test --android --packages=camera_android_camerax ``` + +## Required Steps Before Pushing + +You MUST read and follow the [pre-push skill](.agents/skills/pre-push-skill/SKILL.md) immediately whenever: +- The user asks to push changes. +- The user asks if you or they are ready to push. +- The user wants to validate that local changes are ready to become a pull request. +- It is the final step when you are ready to make a PR and consider an issue solved. + +This skill will execute all the required pre-push checks (e.g., tests, publish checks, license formatting) for the `flutter/packages` repository. + +## Agent Coding and Review Guidelines + +- **Communication and Code Review**: When receiving code review feedback, DO NOT be overly accommodating or blindly agree with the user if the feedback seems technically questionable. Instead, use the [receiving-code-review skill](.agents/skills/receiving-code-review/SKILL.md) to apply technical rigor and verify the suggestions. Be direct if you believe the feedback is incorrect. +- **Code Quality and Complexity**: Do not produce low-quality or overly complex code. For complex features, propose using the `/grill-me` or `/plan` slash commands to create a design plan before writing code. Enforce strict minimum test coverage and cognitive complexity standards. Use the [dart-add-unit-test skill](.agents/skills/dart-add-unit-test/SKILL.md) and [dart-collect-coverage skill](.agents/skills/dart-collect-coverage/SKILL.md) to ensure high coverage. +- **Duplicate Code**: Avoid duplicating code, especially constant strings. Instead of duplicating, look for existing patterns in adjacent code and extract shared values into constants. \ No newline at end of file From 7f90a49d7de8c64e75b07d41c5cec720e7737bbc Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Mon, 13 Jul 2026 10:52:36 -0700 Subject: [PATCH 07/11] self review --- .../camera/camera_android_camerax/AGENTS.md | 116 ++++++++++++++---- 1 file changed, 92 insertions(+), 24 deletions(-) diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md index 5668f068cc53..9af5d8899e43 100644 --- a/packages/camera/camera_android_camerax/AGENTS.md +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -1,28 +1,45 @@ # Agent Guide for camera_android_camerax -This document provides context, architectural details, and core workflows for making high quality contributions to the `camera_android_camerax` package. +This document provides context, architectural details, and core workflows +for making high quality contributions to the `camera_android_camerax` package. ## Architectural Overview -The `camera_android_camerax` package is the Android platform implementation of the `camera` plugin, using the **Android Jetpack CameraX** library. +The `camera_android_camerax` package is the Android platform implementation +of the `camera` plugin, using the **Android Jetpack CameraX** library. ### ProxyApi Binding System -This plugin utilizes **Pigeon's ProxyApi** to bind Dart objects directly to native Android CameraX Java/Kotlin objects. -- **Pigeon Definition**: The API surfaces are defined in [pigeons/camerax_library.dart](pigeons/camerax_library.dart). + +This plugin utilizes **Pigeon's ProxyApi** to bind Dart objects directly +to native Android CameraX Java/Kotlin objects. + +- **Pigeon Definition**: The API surfaces are defined in + [pigeons/camerax_library.dart](pigeons/camerax_library.dart). - **Generated Code**: - - Dart proxy classes: [lib/src/camerax_library.g.dart](lib/src/camerax_library.g.dart) - - Kotlin proxy classes: [android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt) -- **Plugin Entry Point**: [lib/src/android_camera_camerax.dart](lib/src/android_camera_camerax.dart) implements `CameraPlatform` using the generated proxy classes. + - Dart proxy classes: + [lib/src/camerax_library.g.dart](lib/src/camerax_library.g.dart) + - Kotlin proxy classes: + [android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt) +- **Plugin Entry Point**: + [lib/src/android_camera_camerax.dart](lib/src/android_camera_camerax.dart) + implements `CameraPlatform` using the generated proxy classes. ## Required Steps Before Making Any Changes -Before making any changes, run the the [check-readiness skill](.agents/skills/check-readiness/SKILL.md) to ensure your environment has all the required tooling. +Before making any changes, run the +[check-readiness skill](.agents/skills/check-readiness/SKILL.md) +to ensure your environment has all the required tooling. ## Required Steps After Making Any Changes 1. **Regenerate Code (if applicable)**: - - If you modified [pigeons/camerax_library.dart](pigeons/camerax_library.dart), run the Pigeon generation command under [Code Generation](#code-generation). - - If you modified any classes that are mocked or added new mocks, run the Mockito generation command under [Code Generation](#code-generation). + - If you modified + [pigeons/camerax_library.dart](pigeons/camerax_library.dart), + run the Pigeon generation command under + [Code Generation](#code-generation). + - If you modified any classes that are mocked or added new mocks, + run the Mockito generation command under + [Code Generation](#code-generation). 2. **Verify Tests**: - Ensure you have added or updated unit tests to cover your changes. - Run and pass all tests (see [Running Tests](#running-tests) for details): @@ -30,59 +47,110 @@ Before making any changes, run the the [check-readiness skill](.agents/skills/ch - Android native unit tests. - Integration tests. 3. **Static Analysis**: - - Do not rely on ad-hoc or generic commands to check for formatting or lint errors. Always use the [dart-run-static-analysis skill](.agents/skills/dart-run-static-analysis/SKILL.md) during development to analyze the code and apply automated fixes. + - Run the + [dart-run-static-analysis skill](.agents/skills/dart-run-static-analysis/SKILL.md) + to analyze the code and apply automated fixes. ## Code Generation -When you modify the Pigeon API [pigeons/camerax_library.dart](pigeons/camerax_library.dart), you must regenerate the respective code to update the Dart proxy class [lib/src/camerax_library.g.dart](lib/src/camerax_library.g.dart) and the Kotlin proxy class [android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt). Run from this directory: +When you modify the Pigeon API +[pigeons/camerax_library.dart](pigeons/camerax_library.dart), +you must regenerate the respective code to update the Dart proxy class +[lib/src/camerax_library.g.dart](lib/src/camerax_library.g.dart) +and the Kotlin proxy class +[android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt). +Run from this directory: ```bash dart run pigeon --input pigeons/camerax_library.dart ``` -Because test in this package use `mockito` for mocking, you must also regenerate the Mockito mocks that are used for unit testing any changes you make. So, also run from this directory: +Because test in this package use `mockito` for mocking, you must also +regenerate the Mockito mocks that are used for unit testing any changes +you make by running in this directory: ```bash dart run build_runner build -d ``` +For more in-depth guidance on creating or updating mocks, refer to the +[dart-generate-test-mocks skill](.agents/skills/dart-generate-test-mocks/SKILL.md). + ## Running Tests -When you make a change, add a test if you can (either a Dart unit test, Android native unit test, or Flutter integration tests). Regardless of if tests are added or not, all tests must pass after you make changes. How to run the tests: +When you make a change, add a test if you can (either a Dart unit test, +Android native unit test, or Flutter integration tests). Regardless of +whether you add a test or not, all tests must pass after you make changes. +How to run the tests: ### Dart Unit Tests + Dart unit tests are located in [test/](./test/). To run them from this directory: + ```bash dart run ../../../script/tool/bin/flutter_plugin_tools.dart dart-test --packages=camera_android_camerax ``` ### Android Native Unit Tests -Android unit tests are located in [android/src/test/](./android/src/test/) and run using Robolectric. + +Android unit tests are located in [android/src/test/](./android/src/test/). To run them from this directory: + ```bash dart run ../../../script/tool/bin/flutter_plugin_tools.dart native-test --android --packages=camera_android_camerax ``` ### Flutter Integration Tests -Integration tests are located in [example/integration_test/integration_test.dart](./example/integration_test/integration_test.dart). -With an emulator or physical device connected, run from this directory: + +Integration tests are located in +[example/integration_test/integration_test.dart](./example/integration_test/integration_test.dart). +For guidance on writing new integration tests or using MCP to explore +UI flows interactively, refer to the +[flutter-add-integration-test skill](.agents/skills/flutter-add-integration-test/SKILL.md). +They require an Android emulator or physical device to be connected. +To check if this is true, run `flutter devices` and verify that an +Android device/emulator is listed. If not, prompt the user to start one. +If so, run from this directory: + ```bash dart run ../../../script/tool/bin/flutter_plugin_tools.dart integration-test --android --packages=camera_android_camerax ``` ## Required Steps Before Pushing -You MUST read and follow the [pre-push skill](.agents/skills/pre-push-skill/SKILL.md) immediately whenever: +You must run the +[pre-push skill](.agents/skills/pre-push-skill/SKILL.md) +immediately whenever: + - The user asks to push changes. - The user asks if you or they are ready to push. -- The user wants to validate that local changes are ready to become a pull request. -- It is the final step when you are ready to make a PR and consider an issue solved. +- The user wants to validate that local changes are ready to become + a pull request. +- It is the final step when you are ready to make a PR and consider + an issue solved. -This skill will execute all the required pre-push checks (e.g., tests, publish checks, license formatting) for the `flutter/packages` repository. +This skill will execute all the required pre-push checks (tests and +checks for static analysis, licenses, and formatting) for the +`flutter/packages` repository. ## Agent Coding and Review Guidelines -- **Communication and Code Review**: When receiving code review feedback, DO NOT be overly accommodating or blindly agree with the user if the feedback seems technically questionable. Instead, use the [receiving-code-review skill](.agents/skills/receiving-code-review/SKILL.md) to apply technical rigor and verify the suggestions. Be direct if you believe the feedback is incorrect. -- **Code Quality and Complexity**: Do not produce low-quality or overly complex code. For complex features, propose using the `/grill-me` or `/plan` slash commands to create a design plan before writing code. Enforce strict minimum test coverage and cognitive complexity standards. Use the [dart-add-unit-test skill](.agents/skills/dart-add-unit-test/SKILL.md) and [dart-collect-coverage skill](.agents/skills/dart-collect-coverage/SKILL.md) to ensure high coverage. -- **Duplicate Code**: Avoid duplicating code, especially constant strings. Instead of duplicating, look for existing patterns in adjacent code and extract shared values into constants. \ No newline at end of file +- **Communication and Code Review**: When receiving code review feedback, + do not be overly accommodating or blindly agree with the user if the + feedback seems technically questionable. Instead, use the + [receiving-code-review skill](.agents/skills/receiving-code-review/SKILL.md) + to apply technical rigor and verify the suggestions. Be direct if you + believe the feedback is incorrect. +- **Code Quality and Complexity**: Do not produce low-quality or overly + complex code. For complex features, propose using the `/grill-me` or + `/plan` slash commands to create a design plan before writing code. + Enforce strict minimum test coverage and cognitive complexity standards. + Use the + [dart-add-unit-test skill](.agents/skills/dart-add-unit-test/SKILL.md) + and + [dart-collect-coverage skill](.agents/skills/dart-collect-coverage/SKILL.md) + to ensure high coverage. +- **Duplicate Code**: Avoid duplicating code, especially constant strings. + Instead of duplicating, look for existing patterns in adjacent code + and extract shared values into constants. \ No newline at end of file From 9029420fe94a5786564e791c392a0b7189554329 Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Mon, 13 Jul 2026 10:55:19 -0700 Subject: [PATCH 08/11] bump version --- packages/camera/camera_android_camerax/CHANGELOG.md | 4 ++++ packages/camera/camera_android_camerax/pubspec.yaml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/camera/camera_android_camerax/CHANGELOG.md b/packages/camera/camera_android_camerax/CHANGELOG.md index 02dbe8a8691c..ef800408e617 100644 --- a/packages/camera/camera_android_camerax/CHANGELOG.md +++ b/packages/camera/camera_android_camerax/CHANGELOG.md @@ -1,3 +1,7 @@ +## 0.7.5 + +* Adds [AGENTS.md](./AGENTS.md) to provide AI agents with repository-specific context. + ## 0.7.4+1 * Fixes a `StateError` ("Bad state: No element") in `setFocusMode(FocusMode.auto)` diff --git a/packages/camera/camera_android_camerax/pubspec.yaml b/packages/camera/camera_android_camerax/pubspec.yaml index d81aa4190c7e..585ec3bb67d8 100644 --- a/packages/camera/camera_android_camerax/pubspec.yaml +++ b/packages/camera/camera_android_camerax/pubspec.yaml @@ -2,7 +2,7 @@ name: camera_android_camerax description: Android implementation of the camera plugin using the CameraX library. repository: https://github.com/flutter/packages/tree/main/packages/camera/camera_android_camerax issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+camera%22 -version: 0.7.4+1 +version: 0.7.5 environment: sdk: ^3.12.0 From 0af9ff19d0222d5eaf05c464c746df0af8cfc3ef Mon Sep 17 00:00:00 2001 From: Camille Simon <43054281+camsim99@users.noreply.github.com> Date: Mon, 13 Jul 2026 11:58:22 -0700 Subject: [PATCH 09/11] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- packages/camera/camera_android_camerax/AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md index 9af5d8899e43..d260d92e7b2d 100644 --- a/packages/camera/camera_android_camerax/AGENTS.md +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -65,7 +65,7 @@ Run from this directory: dart run pigeon --input pigeons/camerax_library.dart ``` -Because test in this package use `mockito` for mocking, you must also +Because tests in this package use mockito for mocking, you must also regenerate the Mockito mocks that are used for unit testing any changes you make by running in this directory: @@ -79,7 +79,7 @@ For more in-depth guidance on creating or updating mocks, refer to the ## Running Tests When you make a change, add a test if you can (either a Dart unit test, -Android native unit test, or Flutter integration tests). Regardless of +Android native unit test, or a Flutter integration test). Regardless of whether you add a test or not, all tests must pass after you make changes. How to run the tests: From c28c0d3df74535a5574cf94794b64935f11cd752 Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Wed, 15 Jul 2026 11:58:14 -0700 Subject: [PATCH 10/11] address review --- .../camera/camera_android_camerax/AGENTS.md | 177 +++--------------- .../camera_android_camerax/CHANGELOG.md | 4 - .../camera_android_camerax/pubspec.yaml | 2 +- 3 files changed, 24 insertions(+), 159 deletions(-) diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md index 9af5d8899e43..e57f0da1fd65 100644 --- a/packages/camera/camera_android_camerax/AGENTS.md +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -1,156 +1,25 @@ # Agent Guide for camera_android_camerax -This document provides context, architectural details, and core workflows -for making high quality contributions to the `camera_android_camerax` package. - -## Architectural Overview - -The `camera_android_camerax` package is the Android platform implementation -of the `camera` plugin, using the **Android Jetpack CameraX** library. - -### ProxyApi Binding System - -This plugin utilizes **Pigeon's ProxyApi** to bind Dart objects directly -to native Android CameraX Java/Kotlin objects. - -- **Pigeon Definition**: The API surfaces are defined in - [pigeons/camerax_library.dart](pigeons/camerax_library.dart). -- **Generated Code**: - - Dart proxy classes: - [lib/src/camerax_library.g.dart](lib/src/camerax_library.g.dart) - - Kotlin proxy classes: - [android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt) -- **Plugin Entry Point**: - [lib/src/android_camera_camerax.dart](lib/src/android_camera_camerax.dart) - implements `CameraPlatform` using the generated proxy classes. - -## Required Steps Before Making Any Changes - -Before making any changes, run the -[check-readiness skill](.agents/skills/check-readiness/SKILL.md) -to ensure your environment has all the required tooling. - -## Required Steps After Making Any Changes - -1. **Regenerate Code (if applicable)**: - - If you modified - [pigeons/camerax_library.dart](pigeons/camerax_library.dart), - run the Pigeon generation command under - [Code Generation](#code-generation). - - If you modified any classes that are mocked or added new mocks, - run the Mockito generation command under - [Code Generation](#code-generation). -2. **Verify Tests**: - - Ensure you have added or updated unit tests to cover your changes. - - Run and pass all tests (see [Running Tests](#running-tests) for details): - - Dart unit tests. - - Android native unit tests. - - Integration tests. -3. **Static Analysis**: - - Run the - [dart-run-static-analysis skill](.agents/skills/dart-run-static-analysis/SKILL.md) - to analyze the code and apply automated fixes. - -## Code Generation - -When you modify the Pigeon API -[pigeons/camerax_library.dart](pigeons/camerax_library.dart), -you must regenerate the respective code to update the Dart proxy class -[lib/src/camerax_library.g.dart](lib/src/camerax_library.g.dart) -and the Kotlin proxy class -[android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt](android/src/main/java/io/flutter/plugins/camerax/CameraXLibrary.g.kt). -Run from this directory: - -```bash -dart run pigeon --input pigeons/camerax_library.dart -``` - -Because test in this package use `mockito` for mocking, you must also -regenerate the Mockito mocks that are used for unit testing any changes -you make by running in this directory: - -```bash -dart run build_runner build -d -``` - -For more in-depth guidance on creating or updating mocks, refer to the -[dart-generate-test-mocks skill](.agents/skills/dart-generate-test-mocks/SKILL.md). - -## Running Tests - -When you make a change, add a test if you can (either a Dart unit test, -Android native unit test, or Flutter integration tests). Regardless of -whether you add a test or not, all tests must pass after you make changes. -How to run the tests: - -### Dart Unit Tests - -Dart unit tests are located in [test/](./test/). -To run them from this directory: - -```bash -dart run ../../../script/tool/bin/flutter_plugin_tools.dart dart-test --packages=camera_android_camerax -``` - -### Android Native Unit Tests - -Android unit tests are located in [android/src/test/](./android/src/test/). -To run them from this directory: - -```bash -dart run ../../../script/tool/bin/flutter_plugin_tools.dart native-test --android --packages=camera_android_camerax -``` - -### Flutter Integration Tests - -Integration tests are located in -[example/integration_test/integration_test.dart](./example/integration_test/integration_test.dart). -For guidance on writing new integration tests or using MCP to explore -UI flows interactively, refer to the -[flutter-add-integration-test skill](.agents/skills/flutter-add-integration-test/SKILL.md). -They require an Android emulator or physical device to be connected. -To check if this is true, run `flutter devices` and verify that an -Android device/emulator is listed. If not, prompt the user to start one. -If so, run from this directory: - -```bash -dart run ../../../script/tool/bin/flutter_plugin_tools.dart integration-test --android --packages=camera_android_camerax -``` - -## Required Steps Before Pushing - -You must run the -[pre-push skill](.agents/skills/pre-push-skill/SKILL.md) -immediately whenever: - -- The user asks to push changes. -- The user asks if you or they are ready to push. -- The user wants to validate that local changes are ready to become - a pull request. -- It is the final step when you are ready to make a PR and consider - an issue solved. - -This skill will execute all the required pre-push checks (tests and -checks for static analysis, licenses, and formatting) for the -`flutter/packages` repository. - -## Agent Coding and Review Guidelines - -- **Communication and Code Review**: When receiving code review feedback, - do not be overly accommodating or blindly agree with the user if the - feedback seems technically questionable. Instead, use the - [receiving-code-review skill](.agents/skills/receiving-code-review/SKILL.md) - to apply technical rigor and verify the suggestions. Be direct if you - believe the feedback is incorrect. -- **Code Quality and Complexity**: Do not produce low-quality or overly - complex code. For complex features, propose using the `/grill-me` or - `/plan` slash commands to create a design plan before writing code. - Enforce strict minimum test coverage and cognitive complexity standards. - Use the - [dart-add-unit-test skill](.agents/skills/dart-add-unit-test/SKILL.md) - and - [dart-collect-coverage skill](.agents/skills/dart-collect-coverage/SKILL.md) - to ensure high coverage. -- **Duplicate Code**: Avoid duplicating code, especially constant strings. - Instead of duplicating, look for existing patterns in adjacent code - and extract shared values into constants. \ No newline at end of file +## Core Workflows + +- **Check Environment**: Run [check-readiness](.agents/skills/check-readiness/SKILL.md) + when starting a new task or if you suspect environment issues. +- **Regenerate Code**: + - Pigeon (`dart run pigeon --input pigeons/camerax_library.dart`): Run after + modifying `pigeons/camerax_library.dart`. + - Mocks (`dart run build_runner build -d`): Run after modifying mocked + classes or adding new mocks. (see [dart-generate-test-mocks](.agents/skills/dart-generate-test-mocks/SKILL.md)) +- **Verify Tests**: All tests must pass before landing. Add or update tests for + any new logic. For integration tests, see [flutter-add-integration-test](.agents/skills/flutter-add-integration-test/SKILL.md). +- **Run Pre-Push Checks**: Run [pre-push-skill](.agents/skills/pre-push-skill/SKILL.md) + before pushing to prevent CI failures and code review blocks. + +## Agent Guidelines + +- Use [receiving-code-review](.agents/skills/receiving-code-review/SKILL.md) + to technically verify review feedback before blindly implementing suggestions, + especially if feedback seems technically questionable. +- Use `/grill-me` or `/plan` for complex features before writing code. +- Maintain high test coverage using [dart-add-unit-test](.agents/skills/dart-add-unit-test/SKILL.md) + and [dart-collect-coverage](.agents/skills/dart-collect-coverage/SKILL.md). +- Avoid duplicating constant strings; reuse existing ones from adjacent code. \ No newline at end of file diff --git a/packages/camera/camera_android_camerax/CHANGELOG.md b/packages/camera/camera_android_camerax/CHANGELOG.md index ef800408e617..02dbe8a8691c 100644 --- a/packages/camera/camera_android_camerax/CHANGELOG.md +++ b/packages/camera/camera_android_camerax/CHANGELOG.md @@ -1,7 +1,3 @@ -## 0.7.5 - -* Adds [AGENTS.md](./AGENTS.md) to provide AI agents with repository-specific context. - ## 0.7.4+1 * Fixes a `StateError` ("Bad state: No element") in `setFocusMode(FocusMode.auto)` diff --git a/packages/camera/camera_android_camerax/pubspec.yaml b/packages/camera/camera_android_camerax/pubspec.yaml index 585ec3bb67d8..d81aa4190c7e 100644 --- a/packages/camera/camera_android_camerax/pubspec.yaml +++ b/packages/camera/camera_android_camerax/pubspec.yaml @@ -2,7 +2,7 @@ name: camera_android_camerax description: Android implementation of the camera plugin using the CameraX library. repository: https://github.com/flutter/packages/tree/main/packages/camera/camera_android_camerax issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+camera%22 -version: 0.7.5 +version: 0.7.4+1 environment: sdk: ^3.12.0 From d7c49785c7fdef7a6bbbddb57970737287946ea6 Mon Sep 17 00:00:00 2001 From: Camille Simon <43054281+camsim99@users.noreply.github.com> Date: Wed, 15 Jul 2026 11:59:20 -0700 Subject: [PATCH 11/11] Apply suggestions from code review Co-authored-by: Reid Baker <1063596+reidbaker@users.noreply.github.com> --- packages/camera/camera_android_camerax/AGENTS.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/camera/camera_android_camerax/AGENTS.md b/packages/camera/camera_android_camerax/AGENTS.md index d260d92e7b2d..c4d2e0b9733a 100644 --- a/packages/camera/camera_android_camerax/AGENTS.md +++ b/packages/camera/camera_android_camerax/AGENTS.md @@ -6,11 +6,11 @@ for making high quality contributions to the `camera_android_camerax` package. ## Architectural Overview The `camera_android_camerax` package is the Android platform implementation -of the `camera` plugin, using the **Android Jetpack CameraX** library. +of the (camera)[../camera] plugin, using the (**Android Jetpack CameraX**)[https://developer.android.com/jetpack/androidx/releases/camera] library. ### ProxyApi Binding System -This plugin utilizes **Pigeon's ProxyApi** to bind Dart objects directly +This plugin utilizes (**Pigeon's ProxyApi**)[../../pigeon] to bind Dart objects directly to native Android CameraX Java/Kotlin objects. - **Pigeon Definition**: The API surfaces are defined in @@ -26,9 +26,9 @@ to native Android CameraX Java/Kotlin objects. ## Required Steps Before Making Any Changes -Before making any changes, run the +Before working, run the [check-readiness skill](.agents/skills/check-readiness/SKILL.md) -to ensure your environment has all the required tooling. +to ensure your environment has all the expected tooling. ## Required Steps After Making Any Changes @@ -78,7 +78,7 @@ For more in-depth guidance on creating or updating mocks, refer to the ## Running Tests -When you make a change, add a test if you can (either a Dart unit test, +When you make a change, add a test if other similar code has tests(either a Dart unit test, Android native unit test, or a Flutter integration test). Regardless of whether you add a test or not, all tests must pass after you make changes. How to run the tests: