If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dotnet/maui shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 27+ active contributors
• Distributed ownership (top contributor 16% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dotnet/maui repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dotnet/maui.

What it runs against: a local clone of dotnet/maui — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dotnet/maui | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dotnet/maui. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dotnet/maui.git
#   cd maui
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dotnet/maui and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dotnet/maui(\\.git)?\\b" \\
  && ok "origin remote is dotnet/maui" \\
  || miss "origin remote is not dotnet/maui (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".github/DEVELOPMENT.md" \\
  && ok ".github/DEVELOPMENT.md" \\
  || miss "missing critical file: .github/DEVELOPMENT.md"
test -f ".github/CONTRIBUTING.md" \\
  && ok ".github/CONTRIBUTING.md" \\
  || miss "missing critical file: .github/CONTRIBUTING.md"
test -f ".editorconfig" \\
  && ok ".editorconfig" \\
  || miss "missing critical file: .editorconfig"
test -f ".github/CODEOWNERS" \\
  && ok ".github/CODEOWNERS" \\
  || miss "missing critical file: .github/CODEOWNERS"
test -f ".config/dotnet-tools.json" \\
  && ok ".config/dotnet-tools.json" \\
  || miss "missing critical file: .config/dotnet-tools.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dotnet/maui"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

.NET MAUI is a cross-platform framework for building native mobile and desktop applications from a single C# and XAML codebase, targeting Android, iOS, macOS, and Windows simultaneously. It is the successor to Xamarin.Forms, providing unified UI controls, layout systems, and platform handlers that abstract away native API differences while preserving native performance characteristics. Monorepo structure with separate concerns: src/Core/ contains the cross-platform abstraction layer and XAML parsing, src/Controls/ defines all UI controls, src/Handlers/ contains platform-specific implementations (one per platform: Android, iOS, macOS, Windows), and src/Layouts/ has the flexbox-based layout engine. Platform handlers follow a handler pattern where each control (Button, Label, etc.) has a corresponding handler per platform that bridges MAUI abstractions to native APIs.

.NET developers and enterprise teams building consumer applications for mobile and desktop who want to share business logic and UI code across Android, iOS, macOS, and Windows without maintaining separate platform-specific codebases.

Production-ready and actively developed. .NET MAUI is an official Microsoft framework (released stable in May 2022, latest .NET 9 support November 2024) with substantial community adoption and regular feature releases (.NET 10 features announced for 2025). The massive C# codebase (33.5M lines), comprehensive CI/CD in .azuredevops/, and active GitHub issues indicate a mature, well-maintained project with strong organizational backing.

Low risk for established .NET teams; moderate risk for platform fragmentation. The codebase is large and complex with platform-specific handlers for Android (Java), iOS (Swift), and Windows code, creating potential for subtle cross-platform bugs. Dependency on .NET 6+ LTS versions and per-platform SDKs (XCode, Android SDK, Windows SDK) creates environmental setup complexity. Breaking changes possible between major .NET versions, though Microsoft typically provides migration guides.

.NET MAUI for .NET 9 is current stable (November 2024), with .NET 10 features actively being developed. Recent focus areas include performance optimization, CollectionView enhancements, improved layout system reliability, and safe area handling on iOS. The .github/instructions/ directory with task-specific guides (collectionview-android.instructions.md, performance-hotpaths.instructions.md, handler-patterns.instructions.md) indicates active areas of work and mentoring for contributors.

Clone the repo and install prerequisites: git clone https://github.com/dotnet/maui.git && cd maui. Install .NET 9 SDK (minimum 9.0.0). Run dotnet workload restore to install MAUI workloads. Build the framework: dotnet build src/Controls/src/Maui.Controls.csproj. See .github/DEVELOPMENT.md for platform-specific setup (XCode for iOS/macOS, Android SDK, Visual Studio Community for Windows).

Daily commands: Build and test locally: dotnet build. Run unit tests: dotnet test src/Controls/tests/UnitTests/Controls.Core.UnitTests/Controls.Core.UnitTests.csproj. Device/emulator testing requires platform SDKs: for Android use Android Emulator or device with dotnet build -f net9.0-android; for iOS use Xcode simulator with dotnet build -f net9.0-ios. Full test suite runs in CI via .azuredevops/ pipelines.

• .github/DEVELOPMENT.md — Entry point for developer setup and contribution workflow; every contributor must read this before working on the codebase.
• .github/CONTRIBUTING.md — Defines contribution guidelines, PR requirements, and code standards that all contributors must follow.
• .editorconfig — Establishes code style and formatting rules across the entire repository; ensures consistency in all submissions.
• .github/CODEOWNERS — Specifies ownership and review requirements for critical areas; determines who must review changes to key components.
• .config/dotnet-tools.json — Defines required .NET toolchain versions and dependencies for building and testing the framework.
• .github/dependabot.yml — Manages dependency updates and security patches; critical for maintaining framework stability and security.
• .github/copilot-instructions.md — Provides AI assistant context and guidance on codebase patterns; helps maintain consistency in code generation and reviews.

Add a New Control Handler (Platform-Specific Implementation)

1. Review the handler pattern documentation to understand the abstraction (.github/instructions/handler-patterns.instructions.md)
2. Check platform-specific handler detection patterns (e.g., Android, iOS, Windows) (.github/instructions/collectionview-handler-detection.instructions.md)
3. Implement platform binding following the documented patterns (.github/instructions/android.instructions.md)
4. Add unit and integration tests using the test templates (.github/instructions/xaml-unittests.instructions.md)

Expand Layout System for New Measurement Logic

1. Understand the cross-platform layout architecture (.github/instructions/layout-system.instructions.md)
2. Review performance-critical hotpaths to avoid regressions (.github/instructions/performance-hotpaths.instructions.md)
3. Implement platform-specific overrides (e.g., safe area on iOS) (.github/instructions/safe-area-ios.instructions.md)
4. Validate with device tests on the Helix infrastructure (.github/instructions/helix-device-tests.instructions.md)

Add Public API and Ensure Compatibility

1. Review public API surface and versioning expectations (.github/instructions/public-api.instructions.md)
2. Ensure thread-safety and async compatibility (.github/instructions/threading-async.instructions.md)
3. Follow code style and editor configuration standards (.editorconfig)
4. Verify changes pass automated code review checks (.github/skills/code-review/SKILL.md)

Create a UI Test for Cross-Platform Feature

1. Use the Appium test template for mobile UI automation (.github/scripts/templates/RunWithAppiumTest.template.cs)
2. Reference UI testing patterns and best practices (.github/instructions/uitests.instructions.md)
3. Submit test execution to Helix for multi-device validation (.github/instructions/helix-device-tests.instructions.md)

• C# and XAML — Core language for cross-platform app development; leverages .NET ecosystem for native performance on iOS, Android, macOS, and Windows
• .NET MAUI Framework — Provides unified abstraction layer across platforms; enables single codebase for mobile and desktop targets
• GitHub Actions with PowerShell Scripts — Automates build, test, and deployment workflows; enables CI/CD across multiple target platforms
• Helix Infrastructure — Provides hardware-accelerated device testing across real iOS, Android, macOS, and Windows devices
• Azure Pipelines — Enterprise-grade CI/CD and policy enforcement; integrates with Microsoft's infrastructure for scale

• Single codebase with platform-specific handlers

  • Why: Maximizes code reuse while preserving platform-native capabilities
  • Consequence: Developers must understand handler abstraction pattern; testing burden increases across platforms

• Centralized toolchain via .config/dotnet-tools.json

  • Why: Enforces consistent build environment across all contributors and CI pipelines
  • Consequence: Onboarding requires exact toolchain setup; less flexibility for local experimentation

• AI-assisted code review with human gatekeeping

  • Why: Scales review capacity while maintaining human oversight on complex changes
  • Consequence: Review latency may increase; requires tuning AI instruction accuracy

• Multi-platform device testing on Helix

  • Why: Validates real hardware behavior and platform-specific edge cases early
  • Consequence: Test infrastructure costs; longer feedback loop (5-10 min per test run)

• Does not provide cross-platform game engine or 3D rendering (use Godot, Unity instead)
• Does not handle server-side backend logic (client-side UI framework only)
• Does not support non-.NET languages (C#/XAML only)
• Does not abstract platform-specific APIs completely (some platform knowledge required for advanced features)

Platform SDKs must be installed and configured separately: Android SDK (API 21+), XCode 12+ for iOS/macOS, Visual Studio 2022+ for Windows. MAUI workloads installation via dotnet workload restore is required and can fail silently if .NET SDK is wrong version. iOS simulator and Android emulator require significant disk space and system resources. Handlers follow strict patterns—deviating causes runtime binding failures that are hard to debug. Platform-specific bugs (especially iOS safe area, Android layout inflation) require testing on actual device/emulator, not just desktop. CollectionView has known platform-specific issues documented in .github/instructions/collectionview-*.instructions.md—check these before implementing collection changes.

• Handler Pattern — Core MAUI architecture where each cross-platform control (Button, Label) has a corresponding Handler subclass per platform that translates MAUI method calls to native API calls; understanding this is essential to adding features or fixing platform-specific bugs
• Yoga Layout Engine (Flexbox for Native) — MAUI's layout system is ported from Facebook's Yoga (C++ flexbox implementation); knowing how flexbox sizing, padding, margin, and flex-grow work is critical for debugging layout issues across platforms
• Cross-Platform Dependency Abstraction (Permissions, Geolocation, Sensors) — MAUI provides a unified .NET API (in src/Core/src/Essentials/) that abstracts Android's runtime permissions, iOS capabilities, and Windows app manifest permissions; developers need to understand this layer to safely access device features
• XAML Hot Reload and Binding Resolution — MAUI's XAML parser in src/Core/src/Xaml/ enables live code-replacement during development; binding path resolution failures cause runtime errors that are cryptic if you don't understand the binding context and name resolution pipeline
• Platform-Specific Conditional Compilation (#if NET9_0_ANDROID, etc.) — MAUI heavily uses compile-time platform selection to exclude iOS/Android code from Windows builds; incorrect conditional directives cause link-time or runtime failures, especially in handlers
• MauiContext and Handler Registration — Each platform has a MauiContext that holds the service provider, logger, and handler factory; handlers are registered in this context and resolution failures cascade through the entire control tree
• Safe Area Insets (Notches, Status Bar, Navigation Bar) — iOS and Android have platform-specific safe area constraints (notches, status bars) that MAUI must account for during layout; this is a frequent source of UI bugs and requires per-platform handling in handlers and layout code

• xamarin/xamarin.forms — Direct predecessor to .NET MAUI; shares handler architecture and control model but targets older Xamarin ecosystem
• dotnet/maui-samples — Official sample applications demonstrating MAUI patterns, controls, and platform-specific features; primary reference for how to use framework correctly
• CommunityToolkit/Maui — Community-maintained extensions and utility controls for .NET MAUI, often backported into framework; shows real-world handler and control patterns
• dotnet/runtime — Core .NET runtime that MAUI depends on; threading, async/await, reflection, and GC behavior originate here
• dotnet/wpf — Windows Presentation Foundation predecessor to MAUI's Windows handler; shares XAML parsing and data binding concepts

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create comprehensive GitHub Agent documentation and testing framework

The repo contains multiple AI agents (.github/agents/) including maui-expert-reviewer.md, learn-from-pr.agent.md, write-tests-agent.agent.md, and sandbox-agent.agent.md, but lacks structured documentation on how to test, validate, and extend these agents. This would help contributors understand the agent system and enable safer iteration on AI-assisted workflows.

• [ ] Create .github/agents/README.md documenting each agent's purpose, triggers, and expected outputs
• [ ] Add validation tests in .github/agents/tests/ to verify agent prompts produce expected code/review quality
• [ ] Document the agent lifecycle in .github/DEVELOPMENT.md with examples of modifying copilot-instructions.md and testing changes locally
• [ ] Create .github/agents/CONTRIBUTING.md with guidelines for adding new agents or modifying existing ones

Implement comprehensive testing instructions for new handler patterns

.github/instructions/handler-patterns.instructions.md exists but the repo structure shows specialized instructions for specific handlers (collectionview-android, collectionview-ios, collectionview-windows) without parallel test coverage documentation. New contributors need clear guidance on testing newly created handlers across platforms.

• [ ] Expand .github/instructions/handler-patterns.instructions.md with mandatory test scenarios (unit, integration, platform-specific)
• [ ] Create .github/instructions/handler-testing-checklist.instructions.md referencing actual test files in src/ and the helix-device-tests pipeline
• [ ] Document how to validate handler behavior against the layout-system.instructions.md and performance-hotpaths.instructions.md requirements
• [ ] Add examples linking handler code to corresponding test files for CollectionView, Layout, and core handlers

Create structured onboarding for Dependabot and dependency management policies

The repo has both .azuredevops/dependabot.yml and .github/dependabot.yml configurations, but lacks clear documentation on dependency upgrade workflows, security policy application, and the relationship between Azure DevOps and GitHub dependency management. This creates confusion for contributors handling dependency PRs.

• [ ] Create .github/docs/dependency-management.md documenting the purpose of both dependabot configs and when each is used
• [ ] Document the resource management policies in .github/policies/resourceManagement.yml and how they affect dependency updates
• [ ] Add troubleshooting guide for common Dependabot scenarios (version conflicts, security patches, multi-platform dependencies)
• [ ] Reference this guide in .github/CONTRIBUTING.md for contributors who encounter or create dependency update PRs

• Add missing unit tests for src/Handlers/Windows/ handlers, which are significantly under-tested compared to Android and iOS handlers. Start with Button or Label handler tests following the pattern in src/Handlers/Android/ tests.
• Implement structured logging for platform handler initialization to help diagnose 'handler not found' errors. Add diagnostic output in src/Handlers/[Platform]/MauiContext.cs to log handler registration and resolution.
• Document the hot-reload flow for XAML in .github/instructions/ with concrete examples from src/Core/src/Xaml/. Current documentation in .github/DEVELOPMENT.md lacks step-by-step debugging guidance for when hot-reload fails.

The .NET MAUI repository demonstrates generally good security posture with no critical vulnerabilities detected from the static file structure analysis. However, there are moderate concerns regarding configuration file exposure (Copilot and AI agent instructions), PowerShell script management, and the need for verification of Azure DevOps security policies. The codebase includes comprehensive development guidelines and security documentation (.github/SECURITY.md), which is positive. No hardcoded secrets, SQL injection patterns, or Docker misconfigurations were identified in the file structure. Recommendations focus on protecting configuration files, ensuring proper script validation, and maintaining robust dependency management through Dependabot configuration.

• Medium · Copilot Configuration Exposure — .github/copilot/settings.json, .github/copilot-instructions.md. The repository contains Copilot configuration files (.github/copilot/settings.json and .github/copilot-instructions.md) that may contain sensitive instructions or system prompts. These files are version controlled and publicly accessible, potentially exposing internal development practices and AI system prompts. Fix: Review Copilot configuration files for sensitive information. Consider moving sensitive configuration to environment variables or secret management systems. Ensure no API keys, tokens, or sensitive instructions are committed to version control.
• Low · AI Agent Instructions in Repository — .github/agents/, .github/instructions/. Multiple AI agent instruction files are stored in version control (.github/agents/, .github/instructions/). While these may be intentional, they could potentially contain sensitive information about internal processes, testing strategies, or security procedures. Fix: Audit all agent and instruction files to ensure they don't contain sensitive security information, API endpoints, or internal security procedures. Consider whether these files should be in a private location or protected with access controls.
• Low · Potential Hardcoded Baseline Configuration — .github/scripts/EstablishBrokenBaseline.ps1. Script file 'EstablishBrokenBaseline.ps1' suggests automated baseline establishment which could potentially be misconfigured or create security baselines that are unintentionally permissive. Fix: Review the baseline establishment process to ensure security baselines are set appropriately. Verify that broken baselines don't inadvertently lower security standards. Ensure proper change control and review processes for baseline modifications.
• Low · PowerShell Script Execution — .github/scripts/ (all .ps1 files). Multiple PowerShell scripts are present in the repository that execute build, deployment, and testing operations. PowerShell scripts can be security-sensitive and may require additional validation. Fix: Implement code review processes for all PowerShell scripts. Use execution policies to restrict script execution. Validate and sanitize any user inputs to these scripts. Consider using signed scripts to ensure integrity.
• Low · Azure DevOps Pipeline Configuration — .azuredevops/dependabot.yml, .azuredevops/policies/. Azure DevOps pipeline configuration files are present (.azuredevops/dependabot.yml, .azuredevops/policies/). These should be reviewed to ensure security policies and dependency management are properly configured. Fix: Verify that Dependabot is configured to check for and alert on security vulnerabilities. Ensure branch protection policies enforce security reviews. Review pipeline permissions and ensure least-privilege access is enforced.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.