create-new-sample

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

1. 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.
2. Verify the design_directory exists. If not found, halt execution.
3. 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.
4. 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.