AG-UI .NET SDK — Feature Workflow (Orchestrator)

This is the hub skill. Given a request to build or change a feature in the AG-UI .NET SDK (sdks/dotnet/), it lays out the correct end-to-end order and routes the depth of each step to a focused sibling skill. It does not duplicate their content.

The SDK has a multi-artifact definition of done. An agent working ad hoc forgets artifacts — most often cross-language parity, docs, AGENTS.md/docs/architecture.md sync, and PublicAPI.Unshipped.txt. Use this skill to avoid that.

Package map

sdks/dotnet/src/:

ASP.NET hosting glue lives in samples/AGUI.Samples.Shared (not a src/ package). sdks/dotnet/AGENTS.md and docs/architecture.md are the canonical description of the layout and conventions (kept current via agui-dotnet-agents-sync); AGUI.slnx is the ground truth if you need to re-derive the package list.

Build & test commands

# from sdks/dotnet/
dotnet build sdks/dotnet/AGUI.slnx        # whole solution
dotnet test  tests/AGUI.Abstractions.UnitTests/   # per-project, fast feedback

Directory.Build.props treats warnings as errors, and PublicApiAnalyzers is on for every src/ project with a PublicAPI.Shipped.txt. The build fails if you skip the AOT serialization wiring or forget PublicAPI.Unshipped.txt — these are not optional polish steps, they are enforced.

Definition of done (feature checklist)

• Wire contract understood (matched against TS/Python reference if wire-affecting)
• Type/behavior implemented in the right package (see map)
• AOT serialization wired ([JsonSerializable] in AGUIJsonSerializerContext, converter case, [JsonPropertyName])
• Client/server mapping updated (AGUI.Client event→update and/or AGUI.Server update→event)
• Unit tests (serialization round-trip + behavior)
• Integration tests (full pipeline) if it crosses the HTTP/SSE boundary
• Cross-language parity tests if wire-affecting
• PublicAPI.Unshipped.txt updated for every changed public member
• Docs updated (docs.ag-ui.com / SDK docs) if user-facing
• AGENTS.md / docs/architecture.md synced if structure/recipe changed
• dotnet build sdks/dotnet/AGUI.slnx and relevant dotnet test projects green

Ordered workflow → route each step

Do the steps in this order. Skip a step only if it genuinely doesn't apply (e.g. a non-wire-affecting internal refactor skips cross-language parity).

1. Understand the wire contract. Read the TypeScript (and Python) reference for the type/behavior so the .NET shape matches the spec. Porting an existing feature from another SDK? → agui-cross-sdk-parity.

2. Implement the type/behavior in the right package.

   • New/changed wire type (event, message, tool, capability) → agui-dotnet-wire-types (covers the AGUI.Abstractions recipe: class in Events/, AGUIEventTypes constant, converter case, AOT registration, PublicAPI.Unshipped.txt).
   • New/changed transport or encoding (SSE, protobuf, formatter) → agui-dotnet-transport (AGUI.Formatting, AGUI.Protobuf).

3. Wire AOT serialization. Every protocol type goes through AGUIJsonSerializerContext — no reflection. agui-dotnet-wire-types has the per-type recipe; the build enforces it.

4. Update client/server mapping. Server-side ChatResponseUpdate → event lives in AGUI.Server; client-side event → ChatResponseUpdate lives in AGUI.Client (EventStreamConverter, builders). Update both directions if the wire shape changed.

5. Unit tests (round-trip + behavior) → agui-dotnet-unit-tests.

6. Integration tests (HTTP + SSE pipeline, WebApplicationFactory, AGUIChatClient) → agui-dotnet-integration-tests. Required when the change crosses the transport boundary.

7. Cross-language parity tests (if wire-affecting) → agui-dotnet-cross-language-tests (tests/AGUI.CrossLanguage.IntegrationTests, CrossLanguage.TestServer, CrossLanguage.Vitest). This is the step agents most often forget — .NET must agree with TS/Python on the bytes.

8. Update PublicAPI.Unshipped.txt for every changed public member, in each affected src/ project. The PublicAPI analyzer fails the build otherwise.

9. Docs (user-facing change) → agui-dotnet-sdk-docs (docs.ag-ui.com).

10. Sync AGENTS.md / docs/architecture.md if you changed structure, recipes, or commands → agui-dotnet-agents-sync. Fix stale package references while here.

11. Build + test green. dotnet build sdks/dotnet/AGUI.slnx, then the relevant dotnet test <project> (unit + integration + cross-language as applicable).

12. Validate & review. Run/inspect in the dojo → agui-dojo; manual UI/docs checks → agui-playwright-validate; review the change → agui-dotnet-code-review.

Routing table (quick reference)

The depth of each step lives in the sibling skill it routes to; fall back to the recipes in AGENTS.md and the deep content in docs/architecture.md for anything a sibling doesn't cover.

❌ Anti-patterns

1. Don't stop at "it compiles and unit tests pass." Wire-affecting changes are not done until cross-language parity tests and docs are updated.
2. Don't put protocol or server code in a sample. It belongs in src/; the server is AGUI.Server, hosting glue is in samples/AGUI.Samples.Shared, and no src/ project references ASP.NET.
3. Don't skip PublicAPI.Unshipped.txt or AOT registration "to fix later" — the warnings-as-errors build will block you immediately.
4. Don't do the deep work here. This skill routes; the depth lives in the sibling skills. Open the relevant one before implementing a step.