From 5b2cb6a9da4cd30085c29122c8c189bc404b94bd Mon Sep 17 00:00:00 2001 From: Camille Simon Date: Fri, 26 Jun 2026 16:24:56 -0700 Subject: [PATCH 1/6] 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 2/6] 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 3/6] 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 4/6] 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 5/6] 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 6/6] 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