You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+8-1Lines changed: 8 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -155,6 +155,7 @@ For this app:
155
155
- architecture work must keep a vertical-slice shape: each feature owns its contracts, orchestration, and tests behind clear boundaries instead of growing a shared horizontal service layer
156
156
-`DotPilot.Core` is the default home for non-UI code, but once a feature becomes large enough to deserve an architectural boundary, extract it into its own DLL instead of bloating `DotPilot.Core`
157
157
- do not create or reintroduce generic project, folder, namespace, or product language named `Runtime` unless the user explicitly asks for that exact boundary; the default non-UI home is `DotPilot.Core`, and vague runtime naming is considered architectural noise in this repo
158
+
- do not create or keep project, folder, or namespace names like `ControlPlaneDomain`; shared identifiers, contracts, models, and policies must live under explicit roots such as `Identifiers`, `Contracts`, `Models`, and `Policies` instead of behind a vague umbrella name
158
159
- every new large feature DLL must reference `DotPilot.Core` for shared abstractions and contracts, and the desktop app should reference that feature DLL explicitly instead of dragging the feature back into the UI project
159
160
- when a feature slice grows beyond a few files, split it into responsibility-based subfolders that mirror the slice's real concerns such as chat, drafting, providers, persistence, settings, or tests; do not leave large flat file dumps that force unrelated code to coexist in one directory
160
161
- do not hide multiple real features under one umbrella folder such as `AgentSessions` when the code actually belongs to distinct features like `Chat`, `AgentBuilder`, `Settings`, `Providers`, or `Workspace`; use explicit feature roots and keep logs, models, services, and tests under the feature that owns them
@@ -180,7 +181,10 @@ For this app:
180
181
- The deterministic debug provider is an internal fallback, not an operator-facing authoring choice: do not surface it as a selectable provider or suggested model in the `New agent` creation flow; if no real provider is enabled or installed, send the operator to provider settings instead of defaulting the form to debug
181
182
- Do not invent agent roles, tool catalogs, skill catalogs, or capability tags in code or UI unless the product has a real backing registry and runtime path for them; absent a real implementation, leave those selections out of the product surface.
182
183
- User-facing UI must not expose backlog numbers, issue labels, workstream labels, "workbench", "domain", or similar internal planning and architecture language unless a feature explicitly exists to show source-control metadata
183
-
- Provider integrations should stay SDK-first: when Codex, Claude Code, GitHub Copilot, or debug/test providers already expose an `IChatClient`-style abstraction, build agent orchestration on top of that instead of inventing parallel request/result wrappers without a clear gap
184
+
- Provider integrations must stay SDK-first: when Codex, Claude Code, GitHub Copilot, or debug/test providers already expose a `Microsoft Agent Framework` or `Microsoft.Extensions.AI` path, compose agent orchestration directly on that official surface instead of inventing parallel request/result abstractions.
185
+
- Do not add or keep provider-specific wrapper chat clients, compatibility shims, or extra adapter layers for `Codex`, `Claude Code`, or `GitHub Copilot`; use the provider SDK and `Microsoft Agent Framework` integration path directly.
186
+
- Do not use `AgentSessionProviderCatalog` or `AgentSessionCommandProbe` as provider-runtime indirection layers; provider registration, readiness, and session creation must come from the actual `Microsoft Agent Framework` plus provider SDK composition path.
187
+
- For `Codex` and `Claude Code`, prefer `ManagedCode.CodexSharpSDK.Extensions.AgentFramework`, `ManagedCode.CodexSharpSDK.Extensions.AI`, `ManagedCode.ClaudeCodeSharpSDK.Extensions.AgentFramework`, and `ManagedCode.ClaudeCodeSharpSDK.Extensions.AI` when those packages are available in the repo, and use them as the primary integration path instead of building repo-local wrappers; remove `AI.Fluent.Assertions` usage instead of layering it beside the Agent Framework path.
184
188
- Do not leave Uno binding on reflection fallback: when the shell binds to view models or option models, annotate or shape those types so the generated metadata provider can resolve them without runtime reflection warnings or performance loss
185
189
- Persist app models and durable session state through `SQLite` plus `EF Core` when the data must survive restarts; do not keep the core chat/session experience trapped in seed data or transient in-memory catalogs
186
190
- When agent conversations must survive restarts, persist the full `AgentSession` plus chat history through an Agent Framework history/storage provider backed by a local desktop folder; do not reduce durable conversation state to transcript text rows only
@@ -407,6 +411,7 @@ Ask first:
407
411
- Keep `dotPilot` positioned as a general agent control plane, not a coding-only shell.
408
412
- Keep the visible product direction aligned with desktop chat apps such as Codex and Claude: sessions first, chat first, streaming first, with repo and git actions as optional utilities inside a session instead of the primary navigation model.
409
413
- Keep provider integrations SDK-first where good typed SDKs already exist.
414
+
- Prefer `ManagedCode` provider SDK bridges for `Codex` and `Claude Code` when they already expose `Microsoft Agent Framework` and `Microsoft.Extensions.AI` integration points, instead of keeping parallel custom adapters or `AI.Fluent.Assertions` glue.
410
415
- Keep evaluation and observability aligned with official Microsoft `.NET` AI guidance when building agent-quality and trust features.
411
416
412
417
### Dislikes
@@ -420,5 +425,7 @@ Ask first:
420
425
- Switching desktop Uno pages into stacked or mobile-style responsive layouts during resize work unless the user explicitly asks for a different composition; desktop pages must stay desktop-first and protect geometry through sizing constraints instead.
421
426
- Adding extra UI-test orchestration complexity when the actual goal is simply to run the tests and get an honest pass or fail result.
422
427
- Planning `MLXSharp` into the first product wave before it is ready for real use.
428
+
- Keeping `AI.Fluent.Assertions` in the provider/chat stack after an official `Microsoft Agent Framework` plus `ManagedCode` integration path is available.
429
+
- Reintroducing `AgentSessionProviderCatalog`, `AgentSessionCommandProbe`, or provider-specific wrapper chat clients after the repo has official `Microsoft Agent Framework` plus provider SDK integration packages available.
423
430
- Letting internal implementation labels such as `Workbench`, issue numbers, or architecture slice names leak into the visible product wording or navigation when the app should behave like a clean desktop chat client.
424
431
- Leaving deprecated product slices, pages, view models, or contracts in place "for later cleanup" after the replacement direction is already chosen.
@@ -33,16 +36,17 @@ Stack: `.NET 10`, class library, non-UI contracts, orchestration, persistence, a
33
36
- do not leave extracted subsystem contracts half-inside `DotPilot.Core`; when a future subsystem is split into its own DLL, its feature-facing interfaces and implementation seams should move with it
34
37
- keep feature-specific heavy infrastructure out of this project once it becomes its own subsystem; `DotPilot.Core` should stay cohesive instead of half-owning an extracted runtime
35
38
- Do not collect unrelated code under an umbrella directory such as `AgentSessions`; split session, workspace, settings, providers, and host code into explicit feature roots when the surface grows.
36
-
-Keep `ControlPlaneDomain`explicit too: identifiers belong under `Identifiers`, participant/provider/session DTOs under `Contracts`, cross-flow state under `Models`, and policy shapes under `Policies` instead of leaving one flat dump.
39
+
-Do not introduce or keep a `ControlPlaneDomain`umbrella in this project; shared identifiers belong under `Identifiers`, participant/provider/session DTOs under `Contracts`, cross-flow state under `Models`, and policy shapes under `Policies`.
37
40
- Keep contract-centric slices explicit inside each feature root: commands live under `Commands`, public DTO shapes live under `Contracts`, public service seams live under `Interfaces`, state records or enums live under `Models`, diagnostics under `Diagnostics`, and persistence under `Persistence`.
38
41
- When a slice exposes `Commands` and `Results`, use the solution-standard `ManagedCode.Communication` primitives instead of hand-rolled command/result record types.
39
42
- Keep the top level readable as two kinds of folders:
40
-
- shared/domain folders such as `ControlPlaneDomain` and `Workspace`
43
+
- shared roots such as `Identifiers`, `Contracts`, `Models`, `Policies`, and `Workspace`
41
44
- operational/system folders such as `AgentBuilder`, `ChatSessions`, `Providers`, and `HttpDiagnostics`
42
45
- keep this structure SOLID at the folder and project level too: cohesive feature slices stay together, but once a slice becomes too large or too independent, it should graduate into its own project instead of turning `DotPilot.Core` into mud
43
46
- Keep provider-independent testing seams real and deterministic so CI can validate core flows without external CLIs.
44
47
- Keep provider readiness probing explicit and coalesced: ordinary workspace reads may share one in-flight CLI probe, but normal navigation must not fan out into repeated PATH/version probing loops.
45
48
- The approved caching exception in this project is startup readiness hydration: Core may keep one startup-owned provider/CLI snapshot after the initial splash-time probe, but it must invalidate that snapshot on explicit refresh or provider preference changes instead of drifting into a long-lived opaque cache layer.
49
+
- Do not introduce or keep `AgentSessionProviderCatalog`, `AgentSessionCommandProbe`, or provider-specific wrapper chat clients in this project; provider session creation and readiness must compose directly from `Microsoft Agent Framework` plus the provider SDK extension packages.
46
50
- Treat superseded async loads as cancellation, not failure; Core services should not emit error-level noise for expected state invalidation or navigation churn.
0 commit comments