DevFlow Onboard

Use this skill to add MAUI DevFlow to a project after maui devflow init has installed the DevFlow skills.

When to Use

• The project has no Microsoft.Maui.DevFlow.* package references yet.
• The user asks how to onboard, initialize, install, integrate, or set up DevFlow.
• The agent needs to choose between standard, Blazor, GTK, or GTK + Blazor DevFlow packages.
• The repo uses Central Package Management and package edits need to be split correctly.
• maui devflow init has installed skills and the user asks for the next project edits.

Route Elsewhere

• If package references and AddMauiDevFlowAgent() are already present but the CLI cannot connect, use maui-devflow-debug.
• If an agent is reachable and the user wants to inspect, tap, screenshot, or debug UI, use maui-devflow-debug.

Workflow

1. Optionally run maui devflow skills check and update bundled skills before editing if it reports update-available-from-current-cli.
2. Find MAUI app projects in the workspace. Prefer app projects with UseMaui, platform TFMs such as net*-android/net*-ios/net*-maccatalyst/net*-windows, or GTK MAUI package references.
3. Determine whether each target project is standard MAUI, MAUI + Blazor WebView, GTK, or GTK + Blazor.
4. Add the correct DevFlow package references. Respect Central Package Management if Directory.Packages.props is present.
5. Register DevFlow in MauiProgram.cs inside #if DEBUG.
6. Build and run the app.

7. Verify with:

   maui devflow diagnose
   maui devflow wait
   maui devflow ui tree --depth 1

If verification fails after integration, switch to maui-devflow-debug for connectivity recovery.

Stop Signals

• Stop before editing if multiple MAUI app projects exist and the user has not indicated which one to onboard.
• Stop and ask before enabling DevFlow outside Debug builds.
• Stop after package/registration edits and verify with a build before doing runtime debugging.

Critical Anti-patterns

• Do not add versions to project PackageReference items when Directory.Packages.props is managing package versions.
• Do not add Blazor DevFlow packages unless the app uses Blazor WebView.
• Do not register DevFlow outside #if DEBUG unless the user explicitly asks.
• Do not use the old builder.Services.AddMauiDevFlowAgent() pattern; use builder.AddMauiDevFlowAgent().

Package Selection

Blazor WebView indicators include a Microsoft.AspNetCore.Components.WebView.Maui package reference or AddMauiBlazorWebView() in MauiProgram.cs.

GTK indicators include Microsoft.Maui.Platforms.Linux.Gtk4 or Microsoft.Maui.Platforms.Linux.Gtk4.BlazorWebView. Migrate superseded Platform.Maui.Linux.Gtk4* references before adding the current GTK DevFlow packages; do not mix the two backends.

Central Package Management

If the repo uses Directory.Packages.props, put versions there and leave project PackageReference entries versionless.

<!-- Directory.Packages.props -->
<PackageVersion Include="Microsoft.Maui.DevFlow.Agent" Version="<current-version>" />

<!-- App.csproj -->
<PackageReference Include="Microsoft.Maui.DevFlow.Agent" />

If the repo does not use Central Package Management, put the version on the PackageReference.

MauiProgram.cs Registration

For standard MAUI:

using Microsoft.Maui.DevFlow.Agent;

// inside CreateMauiApp(), before return builder.Build();
#if DEBUG
builder.AddMauiDevFlowAgent();
#endif

For MAUI + Blazor WebView:

using Microsoft.Maui.DevFlow.Agent;
using Microsoft.Maui.DevFlow.Blazor;

// inside CreateMauiApp(), before return builder.Build();
#if DEBUG
builder.AddMauiDevFlowAgent();
builder.AddMauiBlazorDevFlowTools();
#endif

For GTK, use the .Gtk namespaces and packages. AddMauiDevFlowAgent() starts automatically when GtkMauiApplication creates its first window. An explicit this.StartDevFlowAgent() hook is also available inside a GtkMauiApplication.OnStarted() override; builder registration is still required.

For Mac Catalyst, ensure the Debug entitlements allow the in-app HTTP server:

<key>com.apple.security.network.server</key>
<true/>

Validation Checklist

• MauiProgram.cs registers DevFlow only in Debug builds.
• The app project references the package flavor that matches the target platform.
• Blazor DevFlow tools are added only when the app uses Blazor WebView.
• GTK apps use the current backend and start the DevFlow agent automatically after the first window is created.
• Mac Catalyst Debug entitlements include com.apple.security.network.server.
• dotnet build succeeds.
• A running app appears in maui devflow list.
• maui devflow ui tree --depth 1 returns a visual tree.

References

• See references/package-selection.md for package/flavor details.
• See references/mauiprogram-registration.md for registration patterns.