AG-UI .NET SDK — Docs Sync
sdks/dotnet/AGENTS.md (coding instructions) and sdks/dotnet/docs/architecture.md
(design overview) describe the SDK's structure, naming, and conventions. They
drift silently after refactors because nothing fails the build when prose goes
stale. This skill reconciles them against the live tree.
Typical drift this catches: a package rename, a moved/removed project, a changed
endpoint pattern, or a new sample step that the prose never caught up with. An agent
that edits these files from memory re-introduces the same kind of drift, so always
derive the truth from the tree first.
Process
- Establish ground truth from the tree, not from the doc. The authoritative
source is
sdks/dotnet/AGUI.slnx plus the folder listing — never the prose
you are about to edit.
- Projects: read
<Project Path=...> entries from AGUI.slnx.
- Folders:
Get-ChildItem src,tests,samples -Directory.
- Samples/steps: list
samples/GettingStarted/Step* to get the real range.
- Drift scan — diff each doc claim against the tree. For every concrete
claim in AGENTS.md / docs/architecture.md, confirm it against ground truth:
- Project & package names exist in
AGUI.slnx (and in src/, tests/).
- Symbols the docs name still exist:
Select-String -Path src\*\*.cs,samples\*\*.cs -Pattern "<Symbol>".
- Renamed/removed symbols are GONE everywhere: grep the repo for the old
name (e.g.
AGUI.Hosting.AspNetCore, TypedResults.ServerSentEvents); a
hit in prose-only is the drift to fix.
- Fix surgically. Edit only the stale lines. Match existing tone, tables,
and code-fence style. Do not restructure or invent conventions.
- Verify. Re-grep every symbol/name you wrote to confirm it exists in the
tree. Optionally
dotnet build from sdks/dotnet/ if you touched code-style
or build claims.
Drift checklist (the claims that rot)
| Doc claim |
Reconcile against |
| src package list / names |
AGUI.slnx /src/ folder + src/ dirs |
| Package dependency table & framework refs |
grep Microsoft.AspNetCore src\*\*.csproj (must be empty — no src project references ASP.NET) |
| Where ASP.NET glue lives |
samples/AGUI.Samples.Shared (the only FrameworkReference Microsoft.AspNetCore.App) |
| Test-project table & count |
AGUI.slnx /tests/ + tests/ dirs |
| Sample step range / count |
samples/GettingStarted/Step* listing |
| Endpoint pattern code |
actual sample Program.cs + samples/AGUI.Samples.Shared |
| Project layout bullet list |
src/, tests/, samples/ dirs |
| Code-style / naming / serialization rules |
Directory.Build.props/.targets, Directory.Packages.props, source |
| PublicAPI workflow |
presence of PublicAPI.*.txt in each src/ project |
Deriving ground truth (commands, not a snapshot)
Don't trust any embedded list (including this skill). Re-derive the current state
from the tree every time:
# from sdks/dotnet/
Select-String -Path AGUI.slnx -Pattern '<Project Path' # all projects
Get-ChildItem src,tests,samples -Directory # folders
Get-ChildItem samples/GettingStarted -Directory -Filter Step* # sample step range
Select-String -Path src\*\*.csproj -Pattern Microsoft.AspNetCore # must be empty (no ASP.NET in src/)
A couple of durable facts that are easy to get wrong: the server package is
AGUI.Server (ASP.NET hosting glue lives only in samples/AGUI.Samples.Shared),
and the integration-test project name stays AGUI.Hosting.AspNetCore.IntegrationTests
even though its types are in namespace AGUI.Server.IntegrationTests. Everything else,
derive from the commands above.
❌ Critical anti-patterns
- Never edit the docs from memory or from the doc's own current text. The
stale prose is exactly what misleads you. Derive every name from
AGUI.slnx
and the folder listing first.
- Never rename a symbol in prose without grepping the whole tree for the
old name — a lingering reference (or an unchanged code fence) is silent drift.
- Don't invent conventions or restructure the docs. Reconcile only what the
tree proves changed; keep tables, tone, and code-fence style intact.
- Don't confuse a kept project name with a moved concept. The integration
test project is still
AGUI.Hosting.AspNetCore.IntegrationTests even though
the src package was renamed to AGUI.Server.
Files to mine
sdks/dotnet/AGENTS.md, sdks/dotnet/docs/architecture.md, sdks/dotnet/AGUI.slnx,
sdks/dotnet/Directory.Build.props, Directory.Build.targets,
Directory.Packages.props, and the src/, tests/, samples/ folder trees.
1---2name: agui-dotnet-agents-sync3description: Keep the AG-UI .NET SDK docs (sdks/dotnet/AGENTS.md and docs/architecture.md) in sync with the real code tree after structural changes. USE FOR: "update AGENTS.md / docs/architecture.md", "check the dotnet docs are current", verifying docs after a .NET SDK refactor (package rename, added/removed project, changed endpoint pattern, new/renamed test project, sample step added, new convention). DO NOT USE FOR: writing product code or tests (follow AGENTS.md itself), Python/TypeScript SDK docs, or generic markdown editing unrelated to the dotnet SDK structure.4---5
6# AG-UI .NET SDK — Docs Sync
7
8`sdks/dotnet/AGENTS.md` (coding instructions) and `sdks/dotnet/docs/architecture.md`
9(design overview) describe the SDK's structure, naming, and conventions. They
10drift silently after refactors because nothing fails the build when prose goes
11stale. This skill reconciles them against the live tree.
12
13> Typical drift this catches: a package rename, a moved/removed project, a changed
14> endpoint pattern, or a new sample step that the prose never caught up with. An agent
15> that edits these files from memory re-introduces the same kind of drift, so always
16> derive the truth from the tree first.
17
18## Process
19
201. **Establish ground truth from the tree, not from the doc.** The authoritative
21 source is `sdks/dotnet/AGUI.slnx` plus the folder listing — never the prose
22 you are about to edit.
23 - Projects: read `<Project Path=...>` entries from `AGUI.slnx`.
24 - Folders: `Get-ChildItem src,tests,samples -Directory`.
25 - Samples/steps: list `samples/GettingStarted/Step*` to get the real range.
262. **Drift scan — diff each doc claim against the tree.** For every concrete
27 claim in AGENTS.md / docs/architecture.md, confirm it against ground truth:
28 - Project & package names exist in `AGUI.slnx` (and in `src/`, `tests/`).
29 - Symbols the docs name still exist: `Select-String -Path src\*\*.cs,samples\*\*.cs -Pattern "<Symbol>"`.
30 - Renamed/removed symbols are GONE everywhere: grep the repo for the old
31 name (e.g. `AGUI.Hosting.AspNetCore`, `TypedResults.ServerSentEvents`); a
32 hit in prose-only is the drift to fix.
333. **Fix surgically.** Edit only the stale lines. Match existing tone, tables,
34 and code-fence style. Do not restructure or invent conventions.
354. **Verify.** Re-grep every symbol/name you wrote to confirm it exists in the
36 tree. Optionally `dotnet build` from `sdks/dotnet/` if you touched code-style
37 or build claims.
38
39## Drift checklist (the claims that rot)
40
41| Doc claim | Reconcile against |
42|---|---|
43| **src package list / names** | `AGUI.slnx` `/src/` folder + `src/` dirs |
44| **Package dependency table & framework refs** | `grep Microsoft.AspNetCore src\*\*.csproj` (must be empty — no src project references ASP.NET) |
45| **Where ASP.NET glue lives** | `samples/AGUI.Samples.Shared` (the only `FrameworkReference Microsoft.AspNetCore.App`) |
46| **Test-project table & count** | `AGUI.slnx` `/tests/` + `tests/` dirs |
47| **Sample step range / count** | `samples/GettingStarted/Step*` listing |
48| **Endpoint pattern code** | actual sample `Program.cs` + `samples/AGUI.Samples.Shared` |
49| **Project layout bullet list** | `src/`, `tests/`, `samples/` dirs |
50| **Code-style / naming / serialization rules** | `Directory.Build.props/.targets`, `Directory.Packages.props`, source |
51| **PublicAPI workflow** | presence of `PublicAPI.*.txt` in each `src/` project |
52
53## Deriving ground truth (commands, not a snapshot)
54
55Don't trust any embedded list (including this skill). Re-derive the current state
56from the tree every time:
57
58```powershell
59# from sdks/dotnet/
60Select-String -Path AGUI.slnx -Pattern '<Project Path' # all projects
61Get-ChildItem src,tests,samples -Directory # folders
62Get-ChildItem samples/GettingStarted -Directory -Filter Step* # sample step range
63Select-String -Path src\*\*.csproj -Pattern Microsoft.AspNetCore # must be empty (no ASP.NET in src/)
64```
65
66A couple of durable facts that are easy to get wrong: the server package is
67`AGUI.Server` (ASP.NET hosting glue lives only in `samples/AGUI.Samples.Shared`),
68and the integration-test **project name** stays `AGUI.Hosting.AspNetCore.IntegrationTests`
69even though its types are in namespace `AGUI.Server.IntegrationTests`. Everything else,
70derive from the commands above.
71
72## ❌ Critical anti-patterns
73
741. **Never edit the docs from memory or from the doc's own current text.** The
75 stale prose is exactly what misleads you. Derive every name from `AGUI.slnx`
76 and the folder listing first.
772. **Never rename a symbol in prose without grepping the whole tree** for the
78 old name — a lingering reference (or an unchanged code fence) is silent drift.
793. **Don't invent conventions or restructure the docs.** Reconcile only what the
80 tree proves changed; keep tables, tone, and code-fence style intact.
814. **Don't confuse a kept project name with a moved concept.** The integration
82 test project is still `AGUI.Hosting.AspNetCore.IntegrationTests` even though
83 the src package was renamed to `AGUI.Server`.
84
85## Files to mine
86
87`sdks/dotnet/AGENTS.md`, `sdks/dotnet/docs/architecture.md`, `sdks/dotnet/AGUI.slnx`,
88`sdks/dotnet/Directory.Build.props`, `Directory.Build.targets`,
89`Directory.Packages.props`, and the `src/`, `tests/`, `samples/` folder trees.
gabrielmoreira