| name | create-new-sample |
| description | Scaffolds, implements, and validates a new Flutter sample based on existing designs. |
Inputs
- sample_name: The name of the sample in TitleCase (e.g.,
"AnalyzeHotspots").
- sample_category: The category of the sample (e.g., "Analysis",
"Visualization").
- design_directory: The directory containing the design files for the sample,
located in
../common-samples/designs/.
- documentation_directory: Path to the API docs at
../flutter/arcgis_maps/doc/api/.
Expected Outputs
- New sample directory:
lib/samples/<sample_name_snake_case>/
- Sample implementation file(s)
- Sample
README.md
- Required registration updates so the sample appears in the app
AGENT_REPORT.md detailing execution status
Agent Workflow
Phase 1: Strict Validation & Setup
- Validate that the user provided
sample_name. If not provided, prompt the
user to input it. If necessary, convert it to TitleCase. If the input is
malformed, halt execution.
- Verify the
design_directory exists. If not found, halt execution.
- Validate that the user provided
sample_category or that
sample_category can be determined from the
implementation-details.md file in the design directory. If it cannot be
determined, halt execution.
- Verify the
documentation_directory exists and contains API reference
files. If not found, halt execution.
Phase 2: Scaffolding
Execute the scaffolding script:
dart tool/generate_new_sample.dart "<sample_name>" "<sample_category>"
If the script returns a non-zero exit code, halt execution and report the console error.
Phase 3: Targeted Context Gathering
Read the implementation-details.md file located within the provided design_directory.
Locate the corresponding Swift and Kotlin implementations by querying the repos defined in AGENTS.md.
Read only the core controller/view files from those cross-platform samples to
identify the primary ArcGIS mapping classes and architectural patterns
required.
Phase 4: Deterministic Implementation
Use the scaffolded Dart files as your foundation. If there are no interactive
controls, remove the SafeArea widget from the scaffolded code. Use simple
layouts and controls. Use styling inherited from the existing Theme.
API Reference Protocol: Do not attempt to ingest the entire
documentation_directory. Instead, cross-reference the specific ArcGIS
classes identified in Phase 3 by reading only their corresponding Dart
documentation files within ../flutter/arcgis_maps/doc/api/. Do not attempt
to read from the .pub-cache directory.
Translate the logic identified in Phase 3 into Dart/Flutter.
If a specific API file is missing, leave a
// TODO: Implement <Feature> - API doc missing comment in the Dart code and
continue.
Phase 5: Add Tutorial-style Comments
The purpose of comments in this sample is to provide the reader a
tutorial-style explanation of how the API is being used.
Add concise, imperative comments to each method and to each distinct block of
code within a method.
Ensure all comments are sentences ending with a period.
Phase 6: State Synchronization
Execute the initialization script to regenerate affected code:
dart tool/initialize.dart
If this fails, do not attempt to fix the generator script. Halt and report the failure.
Phase 7: Validation and Reporting
Run flutter analyze against the newly created sample directory.
Circuit Breaker: Attempt to resolve any detected analysis issues. You are
permitted a maximum of 3 iterative fix attempts. If issues persist after 3
attempts, cease fixing.
Provide a brief summary of each stage, including any errors encountered and how
they were resolved.
