feat: add CommunityToolkit.Aspire.Hosting.Squad - first-class Aspire resource for Squad AI-agent teams #1393

Overview

Add a CommunityToolkit.Aspire.Hosting.Squad integration that lets developers model a Squad AI-agent team as a first-class .NET Aspire resource in their AppHost. Squad is a multi-agent CLI orchestration framework whose teams live under a .squad/ workspace folder; today there is no idiomatic way to surface a Squad team in the Aspire dashboard or pass team identity into downstream service projects.

This proposal models a Squad team as a logical Aspire Resource that:

• Auto-discovers the team roster from .squad/team.md
• Implements IResourceWithConnectionString so service projects can .WithReference(squad) and receive a squad://resource/{name}?teamRoot={...}&agents={csv}&protocol=maf-1.0 descriptor
• Surfaces roster metadata as resource properties on the dashboard
• Wires dashboard commands (e.g., "Open Copilot CLI" on the team root)
• Plays nicely with Squad.Agents.AI (Microsoft Agent Framework adapter, published from the upstream Squad repo) so a service project resolving an AIAgent from DI gets a wrapper backed by the referenced Squad team

This is a follow-up to bradygaster/squad#1144 — "Squad telemetry from embedded host processes: how should it reach Aspire?" — and to Squad.Agents.AI v0.1.0-preview.2 which shipped the MAF adapter.

A working standalone prototype already exists at https://github.com/tamirdresher/aspire-squad-resource and builds cleanly against Aspire 13.2 + .NET 10. This proposal is about upstreaming it into Community Toolkit following the conventions in docs/create-integration.md.

Usage example

using Aspire.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

// Register a Squad team as a logical Aspire resource.
// Auto-reads .squad/team.md from the supplied workspace root.
var research = builder.AddSquad("research-squad",
    teamRoot: @"C:\repos\my-research-team");

var incident = builder.AddSquad("incident-team",
    teamRoot: @"C:\repos\incident-runbook");

// Wire the team into a downstream service project.
// The service receives the squad://... connection string and can use it
// to construct a Squad.Agents.AI agent that resolves to this team.
builder.AddProject<Projects.IncidentWorkflowApi>("incident-workflow")
    .WithReference(incident)
    .WithHttpEndpoint(name: "http", env: "HTTP_PORTS");

builder.Build().Run();

In the Aspire dashboard each squad row exposes:

• Team root path
• Agent roster (parsed from .squad/team.md)
• Protocol version
• Dashboard commands (e.g., open Copilot CLI in the team root)

Breaking change?

No — net-new package.

Alternatives

1. Ad-hoc env vars — pass SQUAD_TEAM_ROOT to service projects manually. No dashboard surface, no roster awareness, no WithReference ergonomics.
2. Process resource — model Squad as a ContainerResource or external process. Doesn't fit Squad's identity model (a team is a folder under .squad/, not a long-running daemon) and loses the metadata surface.
3. Keep it out-of-tree — leave it as the standalone https://github.com/tamirdresher/aspire-squad-resource. Loses Community Toolkit discoverability and integration with the standard test/CI/dashboard infrastructure.

Additional context

Upstream readiness (everything already exists and is published, this is only the Aspire packaging):

• Squad.Agents.AI 0.1.0-preview.2 on nuget.org (Microsoft Agent Framework AIAgent over Squad CLI; ships from the Squad org via OIDC Trusted Publishing).
• Standalone prototype: https://github.com/tamirdresher/aspire-squad-resource
  • SquadResource : Resource, IResourceWithConnectionString
  • SquadBuilderExtensions.AddSquad(...), dashboard commands, lifecycle hook
  • End-to-end demo with logical squad rows + an HTTP-hosted MAF workflow that loads the real Squad agents

Scope for the first PR (kept minimal so it's reviewable):

• src/CommunityToolkit.Aspire.Hosting.Squad/ package + README
• tests/CommunityToolkit.Aspire.Hosting.Squad.Tests/ xUnit unit tests (resource defaults, roster discovery formats, fluent API)
• examples/CommunityToolkit.Aspire.Hosting.Squad.AppHost/ minimal sample
• Solution / root README / tests.yml matrix updates per docs/create-integration.md
• No container image (Squad is a CLI/SDK that runs in-process, not a containerized service)

Out of scope (would land as follow-up PRs, kept out to keep this reviewable):

• OpenTelemetry signals (spawns, token usage, session metrics) — depends on the Squad telemetry contract still being designed in bradygaster/squad#1144
• Direct integration with Squad.Agents.AI DI extensions in service projects — separate consumer-side extension

Past attempt context: I previously opened PR #1233 for a different integration (Kind clusters) and closed it myself without maintainer engagement because I wasn't ready. This time I'm opening the proposal first, per CONTRIBUTING.md, before submitting the draft PR.

Help us help you

Yes, I'd like to be assigned to work on this item.