Skip to content
This repository was archived by the owner on Apr 18, 2026. It is now read-only.

AGENTS.md

Latest commit

 

History

History
89 lines (67 loc) · 4.61 KB

AGENTS.md

File metadata and controls

89 lines (67 loc) · 4.61 KB

AGENTS.md

Scope: This repository root and all child directories unless a deeper AGENTS.md overrides it.

Role of this repository

This is the source of truth for netagents, the .agents package manager and compile-time MCP server source generator.

Hard rules

  • Prefer the existing CLI, generator, runtime, and symlink patterns before inventing new abstractions.
  • Keep cross-repo integration with ANcpLua.Roslyn.Utilities explicit and local.
  • Preserve public behavior unless there is a clear correctness reason to change it.
  • Use System.Text.Json, TimeProvider.System, [GeneratedRegex], and Lock consistently with existing code.

Preferred toolchain

  • Source search/edit/builds: mcp__rider__* tools when available.
  • UI verification: mcp__playwright__* tools.
  • Build/test commands: use the repo's existing dotnet commands unless the user asks for something narrower.

Runtime/compiler context

  • C# 14 and .NET 10 are the baseline.
  • Qyl.Agents.Abstractions stays netstandard2.0.

Build and verification

  • dotnet build
  • dotnet test --project tests/NetAgents.Tests/NetAgents.Tests.csproj
  • dotnet test --project tests/Qyl.Agents.Generator.Tests/Qyl.Agents.Generator.Tests.csproj

Architecture map

src/
├── NetAgents/                     # CLI tool (dotnet tool)
│   ├── Program.cs                 # CLI entry point, command routing
│   ├── Scope.cs                   # Project/user scope resolution
│   ├── Cli/Commands/              # init, install, add, remove, sync, list, mcp, trust, doctor
│   ├── Mcp/                       # NetAgentsMcpServer — MCP server via Qyl.Agents
│   ├── Agents/                    # Agent definitions, MCP/hook config writers
│   ├── Config/                    # agents.toml schema, loader, writer
│   ├── Lockfile/                  # agents.lock schema, loader, writer
│   ├── Skills/                    # SKILL.md loader, discovery, resolver
│   ├── Sources/                   # GitSource, LocalSource, SkillCache
│   ├── Symlinks/                  # Symlink creation/management
│   ├── Trust/                     # Trust policy validation
│   ├── Gitignore/                 # .agents/.gitignore generation
│   └── Utils/                     # ProcessRunner, FileSystem helpers
├── Qyl.Agents.Abstractions/       # [McpServer], [Tool] marker attributes (netstandard2.0)
├── Qyl.Agents.Generator/          # IIncrementalGenerator: Extraction -> Models -> Generation
│   ├── Extraction/                # ServerExtractor, ToolExtractor, ParameterExtractor
│   ├── Models/                    # ServerModel, ToolModel, ToolParameterModel (value-equatable)
│   └── Generation/                # DispatchEmitter, SchemaEmitter, OTelEmitter, JsonContextEmitter, MetadataEmitter
└── Qyl.Agents/                    # Runtime: McpHost (stdio), McpEndpoints (HTTP), McpProtocolHandler (JSON-RPC), Tasks/

tests/
├── NetAgents.Tests/
├── Qyl.Agents.Generator.Tests/
└── Qyl.Agents.Tests/

shared/Polyfills/                  # netstandard2.0 polyfills for Abstractions + Generator

Relationship to official MCP C# SDK

  • Qyl.Agents is a compile-time source generator — no DI container, no runtime reflection.
  • McpEndpoints.MapMcpServer<T>() ≈ official SDK MapMcp().
  • Official SDK's AddMcpServer()/WithHttpTransport()/WithTools<T>() DI pattern has no equivalent — tools are wired at compile time.
  • Official SDK experimental RunSessionHandler is not applicable (stateless HTTP POST, no sessions).
  • Tasks (MCPEXP001) implemented in Qyl.Agents.Tasks — IMcpTaskStore, InMemoryMcpTaskStore, protocol methods.
  • [Experimental] polyfill exists in shared/Polyfills/ but must NOT be applied to types consumed by Qyl.Agents runtime — the internal polyfill metadata leaks to net10.0 consumers and causes QYLEXP errors that cannot be suppressed per repo rules.

Cross-repo dependencies

  • Qyl.Agents.Generator -> ANcpLua.Roslyn.Utilities
  • Qyl.Agents.Generator.Tests -> ANcpLua.Roslyn.Utilities.Testing
  • Qyl.Agents.Tests -> ANcpLua.Roslyn.Utilities.Testing.AgentTesting

These resolve to ../ANcpLua.Roslyn.Utilities/ as a sibling repo on disk.

Code style defaults

  • File-scoped namespaces and primary constructors.
  • Early returns, pattern matching, and switch expressions.
  • Tomlyn for TOML and Spectre.Console for terminal UI.
  • Roslyn generators use IIncrementalGenerator, ForAttributeWithMetadataName, and value-equatable models.
  • xUnit v3 with dotnet test --project <path>.