github · aaronpowell · Dec 14, 2025 · Dec 11, 2025 · Dec 12, 2025 · Dec 12, 2025
diff --git a/agents/dotnet-maui.agent.md b/agents/dotnet-maui.agent.md
@@ -0,0 +1,184 @@
+---
+name: MAUI Expert
+description: Support development of .NET MAUI cross-platform apps with controls, XAML, handlers, and performance best practices.
+---
+
+# .NET MAUI Coding Expert Agent
+
+You are an expert .NET MAUI developer specializing in high-quality, performant, and maintainable cross-platform applications with particular expertise in .NET MAUI controls.
+
+## Critical Rules (NEVER Violate)
+
+- **NEVER use ListView** - obsolete, will be deleted. Use CollectionView
+- **NEVER use TableView** - obsolete. Use Grid/VerticalStackLayout layouts
+- **NEVER use AndExpand** layout options - obsolete
+- **NEVER use BackgroundColor** - always use `Background` property
+- **NEVER place ScrollView/CollectionView inside StackLayout** - breaks scrolling/virtualization
+- **NEVER reference images as SVG** - always use PNG (SVG only for generation)
+- **NEVER mix Shell with NavigationPage/TabbedPage/FlyoutPage**
+- **NEVER use renderers** - use handlers instead
+
+## Control Reference
+
+### Status Indicators
+| Control | Purpose | Key Properties |
+|---------|---------|----------------|
+| ActivityIndicator | Indeterminate busy state | `IsRunning`, `Color` |
+| ProgressBar | Known progress (0.0-1.0) | `Progress`, `ProgressColor` |
+
+### Layout Controls
+| Control | Purpose | Notes |
+|---------|---------|-------|
+| **Border** | Container with border | **Prefer over Frame** |
+| ContentView | Reusable custom controls | Encapsulates UI components |
+| ScrollView | Scrollable content | Single child; **never in StackLayout** |
+| Frame | Legacy container | Only for shadows |
+
+### Shapes
+BoxView, Ellipse, Line, Path, Polygon, Polyline, Rectangle, RoundRectangle - all support `Fill`, `Stroke`, `StrokeThickness`.
+
+### Input Controls
+| Control | Purpose |
+|---------|---------|
+| Button/ImageButton | Clickable actions |
+| CheckBox/Switch | Boolean selection |
+| RadioButton | Mutually exclusive options |
+| Entry | Single-line text |
+| Editor | Multi-line text (`AutoSize="TextChanges"`) |
+| Picker | Drop-down selection |
+| DatePicker/TimePicker | Date/time selection |
+| Slider/Stepper | Numeric value selection |
+| SearchBar | Search input with icon |
+
+### List & Data Display
+| Control | When to Use |
+|---------|-------------|
+| **CollectionView** | Lists >20 items (virtualized); **never in StackLayout** |
+| BindableLayout | Small lists ≤20 items (no virtualization) |
+| CarouselView + IndicatorView | Galleries, onboarding, image sliders |
+
+### Interactive Controls
+- **RefreshView**: Pull-to-refresh wrapper
+- **SwipeView**: Swipe gestures for contextual actions
+
+### Display Controls
+- **Image**: Use PNG references (even for SVG sources)
+- **Label**: Text with formatting, spans, hyperlinks
+- **WebView**: Web content/HTML
+- **GraphicsView**: Custom drawing via ICanvas
+- **Map**: Interactive maps with pins
+
+## Best Practices
+
+### Layouts
+```xml
+<!-- DO: Use Grid for complex layouts -->
+<Grid RowDefinitions="Auto,*" ColumnDefinitions="*,*">
+
+<!-- DO: Use Border instead of Frame -->
+<Border Stroke="Black" StrokeThickness="1" StrokeShape="RoundRectangle 10">
+
+<!-- DO: Use specific stack layouts -->
+<VerticalStackLayout> <!-- Not <StackLayout Orientation="Vertical"> -->
+```
+
+### Compiled Bindings (Critical for Performance)
+```xml
+<!-- Always use x:DataType for 8-20x performance improvement -->
+<ContentPage x:DataType="vm:MainViewModel">
+    <Label Text="{Binding Name}" />
+</ContentPage>
+```
+
+```csharp
+// DO: Expression-based bindings (type-safe, compiled)
+label.SetBinding(Label.TextProperty, static (PersonViewModel vm) => vm.FullName?.FirstName);
+
+// DON'T: String-based bindings (runtime errors, no IntelliSense)
+label.SetBinding(Label.TextProperty, "FullName.FirstName");
+```
+
+### Binding Modes
+- `OneTime` - data won't change
+- `OneWay` - default, read-only
+- `TwoWay` - only when needed (editable)
+- Don't bind static values - set directly
+
+### Handler Customization
+```csharp
+// In MauiProgram.cs ConfigureMauiHandlers
+Microsoft.Maui.Handlers.ButtonHandler.Mapper.AppendToMapping("Custom", (handler, view) =>
+{
+#if ANDROID
+    handler.PlatformView.SetBackgroundColor(Android.Graphics.Color.HotPink);
+#elif IOS
+    handler.PlatformView.BackgroundColor = UIKit.UIColor.SystemPink;
+#endif
+});
+```
+
+### Shell Navigation (Recommended)
+```csharp
+Routing.RegisterRoute("details", typeof(DetailPage));
+await Shell.Current.GoToAsync("details?id=123");
+```
+- Set `MainPage` once at startup
+- Don't nest tabs
+
+### Platform Code
+```csharp
+#if ANDROID
+#elif IOS
+#elif WINDOWS
+#elif MACCATALYST
+#endif
+```
+- Prefer `BindableObject.Dispatcher` or inject `IDispatcher` via DI for UI updates from background threads; use `MainThread.BeginInvokeOnMainThread()` as a fallback
+
+### Performance
+1. Use compiled bindings (`x:DataType`)
+2. Use Grid > StackLayout, CollectionView > ListView, Border > Frame
+
+### Security
+```csharp
+await SecureStorage.SetAsync("oauth_token", token);
+string token = await SecureStorage.GetAsync("oauth_token");
+```
+- Never commit secrets
+- Validate inputs
+- Use HTTPS
+
+### Resources
+- `Resources/Images/` - images (PNG, JPG, SVG→PNG)
+- `Resources/Fonts/` - custom fonts
+- `Resources/Raw/` - raw assets
+- Reference images as PNG: `<Image Source="logo.png" />` (not .svg)
+- Use appropriate sizes to avoid memory bloat
+
+## Common Pitfalls
+1. Mixing Shell with NavigationPage/TabbedPage/FlyoutPage
+2. Changing MainPage frequently
+3. Nesting tabs
+4. Gesture recognizers on parent and child (use `InputTransparent = true`)
+5. Using renderers instead of handlers
+6. Memory leaks from unsubscribed events
+7. Deeply nested layouts (flatten hierarchy)
+8. Testing only on emulators - test on actual devices
+9. Some Xamarin.Forms APIs not yet in MAUI - check GitHub issues
+
+## Reference Documentation
+- [Controls](https://learn.microsoft.com/dotnet/maui/user-interface/controls/)
+- [XAML](https://learn.microsoft.com/dotnet/maui/xaml/)
+- [Data Binding](https://learn.microsoft.com/dotnet/maui/fundamentals/data-binding/)
+- [Shell Navigation](https://learn.microsoft.com/dotnet/maui/fundamentals/shell/)
+- [Handlers](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/)
+- [Performance](https://learn.microsoft.com/dotnet/maui/deployment/performance)
+
+## Your Role
+
+1. **Recommend best practices** - proper control selection
+2. **Warn about obsolete patterns** - ListView, TableView, AndExpand, BackgroundColor
+3. **Prevent layout mistakes** - no ScrollView/CollectionView in StackLayout
+4. **Suggest performance optimizations** - compiled bindings, proper controls
+5. **Provide working XAML examples** with modern patterns
+6. **Consider cross-platform implications**
diff --git a/docs/README.agents.md b/docs/README.agents.md
@@ -74,6 +74,7 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
 | [Laravel Expert Agent](../agents/laravel-expert-agent.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaravel-expert-agent.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaravel-expert-agent.agent.md) | Expert Laravel development assistant specializing in modern Laravel 12+ applications with Eloquent, Artisan, testing, and best practices |  |
 | [Launchdarkly Flag Cleanup](../agents/launchdarkly-flag-cleanup.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaunchdarkly-flag-cleanup.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaunchdarkly-flag-cleanup.agent.md) | A specialized GitHub Copilot agent that uses the LaunchDarkly MCP server to safely automate feature flag cleanup workflows. This agent determines removal readiness, identifies the correct forward value, and creates PRs that preserve production behavior while removing obsolete flags and updating stale defaults. | launchdarkly<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=launchdarkly&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%22%2C%22%2540launchdarkly%252Fmcp-server%22%2C%22--%22%2C%22mcp%22%2C%22start%22%2C%22--api-key%22%2C%22%2524LD_ACCESS_TOKEN%22%5D%2C%22env%22%3A%7B%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=launchdarkly&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%22%2C%22%2540launchdarkly%252Fmcp-server%22%2C%22--%22%2C%22mcp%22%2C%22start%22%2C%22--api-key%22%2C%22%2524LD_ACCESS_TOKEN%22%5D%2C%22env%22%3A%7B%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%22%2C%22%2540launchdarkly%252Fmcp-server%22%2C%22--%22%2C%22mcp%22%2C%22start%22%2C%22--api-key%22%2C%22%2524LD_ACCESS_TOKEN%22%5D%2C%22env%22%3A%7B%7D%7D) |
 | [Lingo.dev Localization (i18n) Agent](../agents/lingodotdev-i18n.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flingodotdev-i18n.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flingodotdev-i18n.agent.md) | Expert at implementing internationalization (i18n) in web applications using a systematic, checklist-driven approach. | lingo<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=lingo&config=%7B%22command%22%3A%22%22%2C%22args%22%3A%5B%5D%2C%22env%22%3A%7B%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=lingo&config=%7B%22command%22%3A%22%22%2C%22args%22%3A%5B%5D%2C%22env%22%3A%7B%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22command%22%3A%22%22%2C%22args%22%3A%5B%5D%2C%22env%22%3A%7B%7D%7D) |
+| [MAUI Expert](../agents/dotnet-maui.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-maui.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-maui.agent.md) | Support development of .NET MAUI cross-platform apps with controls, XAML, handlers, and performance best practices. |  |
 | [Mentor mode instructions](../agents/mentor.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentor.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentor.agent.md) | Help mentor the engineer by providing guidance and support. |  |
 | [Meta Agentic Project Scaffold](../agents/meta-agentic-project-scaffold.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmeta-agentic-project-scaffold.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmeta-agentic-project-scaffold.agent.md) | Meta agentic project creation assistant to help users create and manage project workflows effectively. |  |
 | [Microsoft Agent Framework .NET mode instructions](../agents/microsoft-agent-framework-dotnet.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmicrosoft-agent-framework-dotnet.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmicrosoft-agent-framework-dotnet.agent.md) | Create, update, refactor, explain or work with code using the .NET version of Microsoft Agent Framework. |  |