From 70315a56f155f4894d2b99ad9c083c061bdbd363 Mon Sep 17 00:00:00 2001 From: Ermilov Aleksei Date: Mon, 20 Apr 2026 16:42:02 +0300 Subject: [PATCH 1/5] Add AGENTS.md for AI coding agent guidelines and update .NET version references to 10.0 --- .github/workflows/dotnet.yml | 2 +- AGENTS.md | 278 +++++++++++++++++++++++++++++++++++ Framework.slnx | 1 + README.md | 12 +- global.json | 2 +- 5 files changed, 287 insertions(+), 8 deletions(-) create mode 100644 AGENTS.md diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml index 971a9fb..2dd9ff7 100644 --- a/.github/workflows/dotnet.yml +++ b/.github/workflows/dotnet.yml @@ -24,7 +24,7 @@ jobs: - name: Setup dotnet uses: actions/setup-dotnet@v4 with: - dotnet-version: 9.0.x + dotnet-version: 10.0.x - name: Compute version shell: bash diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ed4d6ce --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,278 @@ +Based on https://github.com/microsoft/skills/blob/main/Agents.md (MIT License) + +# Agent Guidelines + +This file provides instructions for AI coding agents working with this repository. + +## Repository Overview + +**AuroraScienceHub.Framework** — a collection of reusable NuGet infrastructure packages for building modern .NET applications. +All packages are published under the `AuroraScienceHub.Framework.*` namespace and distributed via NuGet.org. + +This is a **library repository** — it produces NuGet packages consumed by downstream applications, not a runnable application itself. + +--- + +## Core Principles + +These principles reduce common LLM coding mistakes. Apply them to every task. + +### 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +- State assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them — don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +### 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines, and it could be 50, rewrite it. + +**The test:** Would a senior engineer say this is overcomplicated? If yes, simplify. + +### 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it — don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +**The test:** Every changed line should trace directly to the user's request. + +### 4. Goal-Driven Execution (TDD) + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: + +| Instead of... | Transform to... | +|---------------|-----------------| +| "Add validation" | "Write tests for invalid inputs, then make them pass" | +| "Fix the bug" | "Write a test that reproduces it, then make it pass" | +| "Refactor X" | "Ensure tests pass before and after" | + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +## Project Structure + +``` +src/ +├── / # Each subfolder is a separate NuGet package +│ └── .csproj # Inherits shared props from Directory.Build.props +tests/ +├── UnitTests/ # xUnit v3 + AutoFixture + Shouldly + +Directory.Build.props # Root build properties (TFM, lang, analyzers) +Directory.Build.targets # Build targets +Directory.Packages.props # Central NuGet version management +Framework.slnx # Solution file +global.json # SDK version pinning +``` + +Each package under `src/` maps to a NuGet package named `AuroraScienceHub.Framework.`. +Refer to the individual `README.md` within each package directory for details. + +--- + +## Development Workflow + +### Prerequisites + +- .NET 10 SDK (see `global.json` for exact version) + +### Commands + +```bash +dotnet restore # Restore packages +dotnet build # Build all projects +dotnet test # Run unit tests +dotnet pack # Create NuGet packages +dotnet format # Format code per .editorconfig before every commit +``` + +### Adding a New Package + +1. Create a new directory under `src/` with the package name +2. Create a `.csproj` file — it will inherit shared properties from `Directory.Build.props` +3. Add a reference in `Framework.slnx` + +--- + +## Conventions + +### Clean Code Checklist + +Before completing any code change: + +- [ ] Functions do one thing +- [ ] No unnecessary dependencies added +- [ ] New functionality has corresponding unit tests +- [ ] Names are descriptive and intention-revealing +- [ ] No magic numbers or strings (use constants) +- [ ] Error handling is explicit (no empty catch blocks) +- [ ] No commented-out code +- [ ] Nullable annotations are correct +- [ ] New public APIs have XML documentation +- [ ] Builds without warnings (`dotnet build`) +- [ ] Tests pass (`dotnet test`) +- [ ] Code formatted per `.editorconfig` (`dotnet format --verify-no-changes`) + +### Project setting (inherited from `Directory.Build.props`) + +- **Target framework:** `net10.0` +- **Language version:** `latest` +- **Nullable reference types:** enabled globally +- **Warnings as errors:** enabled (`TreatWarningsAsErrors`) +- **Code style:** defined in `.editorconfig` (based on Azure SDK .NET guidelines) +- **PDB:** embedded in assemblies + +### Code Style + +- Prefer `async/await` for all I/O operations + +### Naming + +- Namespaces: `AuroraScienceHub.Framework.` +- Follow standard .NET naming conventions (PascalCase for public members, camelCase for locals) +- Interface prefix: `I` (e.g., `IEntity`, `IModule`) + +### API Design + +- Follow [Microsoft .NET Library Design Guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/) +- Prefer extension methods for optional functionality +- Use `IServiceCollection` extensions for DI registration +- Mark public API surface intentionally — don't expose internals accidentally +- Use XML documentation comments on all public types and members + +### Dependencies + +- All NuGet package versions are managed centrally in `Directory.Packages.props` +- Never specify versions in individual `.csproj` files — use `` without `Version` +- Minimize external dependencies; prefer BCL types where possible +- When adding a new dependency, justify it + +--- + +## Package Versioning + +- Versioning is managed by **MinVer** based on git tags +- Base version is defined in `Directory.Build.props` as `PackageBaseVersion` +- Release versions are produced from semver git tags (e.g., `10.0.3`) +- Pre-release versions are generated automatically on non-main branches + +**Do not** manually set `` or `` in project files. + +--- + +## Testing + +- **Framework:** xUnit v3 +- **Assertions:** Shouldly +- **Mocking:** Moq + AutoFixture.AutoMoq +- **Test data:** AutoFixture + +### Conventions + +- Test project: `tests/UnitTests/` +- Test class naming: `{ClassUnderTest}Tests` +- Test method naming: `{Method}_{Scenario}_{ExpectedBehavior}` or descriptive names +- Follow Arrange-Act-Assert pattern + +```csharp +[Fact] +public void Parse_ValidInput_ReturnsExpectedResult() +{ + // Arrange + var input = "test-value"; + + // Act + var result = MyParser.Parse(input); + + // Assert + result.ShouldNotBeNull(); + result.Value.ShouldBe("test-value"); +} +``` + +### Running Tests + +```bash +dotnet test # All tests +dotnet test --filter "ClassName=FooTests" # Specific class +``` + +--- + +## CI/CD + +GitHub Actions workflow (`.github/workflows/dotnet.yml`): + +| Trigger | Behavior | +|---------|----------| +| Push to `main` | Build → Test → Pack → Push to **NuGet.org** | +| Push to other branches | Build → Test → Pack → Push pre-release to **GitHub Packages** | +| Semver tag (`*.*.*`) | Produces stable version packages | + +--- + +## Do's and Don'ts + +### Do + +- ✅ Use central package management (`Directory.Packages.props`) for all dependencies +- ✅ Follow existing patterns in the codebase +- ✅ Use XML doc comments on public API surface +- ✅ Use `internal` and `sealed` modifiers by default; only expose what consumers need +- ✅ Validate changes compile with warnings-as-errors enabled +- ✅ Use async/await for all I/O operations +- ✅ Write tests for new functionality before or alongside implementation +- ✅ Keep functions small and focused +- ✅ Keep packages focused — one responsibility per package + +### Don't + +- ❌ Suppress warnings with `#pragma` or `` without justification +- ❌ Add `Version` attributes to individual `.csproj` files +- ❌ Modify `Directory.Build.props` or `Directory.Packages.props` without explicit request +- ❌ Add dependencies that duplicate BCL functionality +- ❌ Add dependencies without justification +- ❌ Leave empty catch blocks or swallow exceptions silently +- ❌ Use `dynamic` or reflection where generics/interfaces suffice +- ❌ Break public API contracts (this is a library — consumers depend on stability) +- ❌ Skip nullable annotations on public APIs + +--- + +## Success Indicators + +These principles are working if you see: + +- Fewer unnecessary changes in diffs +- Fewer rewrites due to overcomplication +- Clarifying questions come before implementation (not after mistakes) +- Clean, minimal PRs without drive-by refactoring +- Tests that document expected behavior diff --git a/Framework.slnx b/Framework.slnx index c442905..0748e0f 100644 --- a/Framework.slnx +++ b/Framework.slnx @@ -13,6 +13,7 @@ + diff --git a/README.md b/README.md index cf3b1f9..c69c756 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,11 @@
- A comprehensive collection of reusable infrastructure packages for building modern .NET 9 applications. + A comprehensive collection of reusable infrastructure packages for building modern .NET 10 applications.

-[![](https://img.shields.io/badge/.NET-9.0-512BD4)](https://dotnet.microsoft.com/) -[![](https://img.shields.io/badge/C%23-13.0-239120)](https://learn.microsoft.com/en-us/dotnet/csharp/) +[![](https://img.shields.io/badge/.NET-10.0-512BD4)](https://dotnet.microsoft.com/) +[![](https://img.shields.io/badge/C%23-14.0-239120)](https://learn.microsoft.com/en-us/dotnet/csharp/) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Aurora-Science-Hub/Framework/blob/main/LICENSE) [![Build & test](https://github.com/Aurora-Science-Hub/Framework/actions/workflows/dotnet.yml/badge.svg)](https://github.com/Aurora-Science-Hub/Framework/actions/workflows/dotnet.yml) @@ -31,7 +31,7 @@ ## Getting Started -All packages are distributed via NuGet and target **.NET 9.0**. Install individual packages as needed: +All packages are distributed via NuGet and target **.NET 10.0**. Install individual packages as needed: ```bash dotnet add package AuroraScienceHub.Framework.Composition @@ -89,13 +89,13 @@ The framework follows these principles: - **Clean Architecture** - Clear separation of concerns with minimal coupling - **Domain-Driven Design** - Support for DDD patterns and practices - **Type Safety** - Strong typing with nullable reference types enabled -- **Modern .NET** - Leverages latest .NET 9 features and patterns +- **Modern .NET** - Leverages latest .NET 10 features and patterns ## Development ### Prerequisites -- .NET 9.0 SDK or later +- .NET 10.0 SDK or later - IDE with C# support (Rider, Visual Studio, VS Code) ### Building the Solution diff --git a/global.json b/global.json index 895d51b..d46d21e 100644 --- a/global.json +++ b/global.json @@ -1,7 +1,7 @@ { "sdk": { "version": "10.0.100", - "rollForward": "patch", + "rollForward": "latestFeature", "allowPrerelease": false } } From 656249504f1710bb75e383ba60179c9dc26c5bca Mon Sep 17 00:00:00 2001 From: Ermilov Aleksei Date: Thu, 23 Apr 2026 11:21:27 +0300 Subject: [PATCH 2/5] Update AGENTS.md to clarify authoritative sources and public API compatibility guidelines --- AGENTS.md | 8 ++++++++ Directory.Build.props | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ed4d6ce..269ce65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,6 +104,11 @@ Refer to the individual `README.md` within each package directory for details. - .NET 10 SDK (see `global.json` for exact version) +### Source of Truth + +- Treat `Directory.Build.props` and `global.json` as the authoritative source for SDK, target framework, nullable, warnings, and other build behavior. +- If `README.md`, package docs, or GitHub Actions workflow files diverge from those settings, follow the build configuration and update the surrounding documentation or automation to match. + ### Commands ```bash @@ -167,6 +172,7 @@ Before completing any code change: - Use `IServiceCollection` extensions for DI registration - Mark public API surface intentionally — don't expose internals accidentally - Use XML documentation comments on all public types and members +- Treat public APIs as versioned contracts for downstream consumers; prefer additive changes and explicitly evaluate source/binary compatibility before changing published APIs ### Dependencies @@ -247,6 +253,7 @@ GitHub Actions workflow (`.github/workflows/dotnet.yml`): - ✅ Follow existing patterns in the codebase - ✅ Use XML doc comments on public API surface - ✅ Use `internal` and `sealed` modifiers by default; only expose what consumers need +- ✅ Preserve public API compatibility for published packages unless a breaking change is explicitly requested - ✅ Validate changes compile with warnings-as-errors enabled - ✅ Use async/await for all I/O operations - ✅ Write tests for new functionality before or alongside implementation @@ -263,6 +270,7 @@ GitHub Actions workflow (`.github/workflows/dotnet.yml`): - ❌ Leave empty catch blocks or swallow exceptions silently - ❌ Use `dynamic` or reflection where generics/interfaces suffice - ❌ Break public API contracts (this is a library — consumers depend on stability) +- ❌ Rename, remove, or materially change behavior of published public APIs without explicit approval - ❌ Skip nullable annotations on public APIs --- diff --git a/Directory.Build.props b/Directory.Build.props index 8f2c14f..f68111a 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -29,7 +29,7 @@ - 10.0.3 + 10.0.5 From 4535fac22de63cfcc828a104e1b0f4acaddaa7dd Mon Sep 17 00:00:00 2001 From: Alexander Nikolaev Date: Thu, 23 Apr 2026 22:23:51 +0300 Subject: [PATCH 3/5] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 269ce65..e918a85 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -102,7 +102,7 @@ Refer to the individual `README.md` within each package directory for details. ### Prerequisites -- .NET 10 SDK (see `global.json` for exact version) +- .NET 10 SDK (see `global.json` for the required/minimum SDK version and roll-forward policy) ### Source of Truth From e567a75e8ffa20ebbdcbcb846e722b42effa1001 Mon Sep 17 00:00:00 2001 From: Alexander Nikolaev Date: Thu, 23 Apr 2026 22:24:50 +0300 Subject: [PATCH 4/5] Update .github/workflows/dotnet.yml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/workflows/dotnet.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml index 2dd9ff7..1128e86 100644 --- a/.github/workflows/dotnet.yml +++ b/.github/workflows/dotnet.yml @@ -24,7 +24,7 @@ jobs: - name: Setup dotnet uses: actions/setup-dotnet@v4 with: - dotnet-version: 10.0.x + global-json-file: global.json - name: Compute version shell: bash From 284dbfbd179e2def0bf263070c1a6d5df366ef21 Mon Sep 17 00:00:00 2001 From: Alexander Nikolaev Date: Thu, 23 Apr 2026 22:26:47 +0300 Subject: [PATCH 5/5] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e918a85..82ccb5f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -84,7 +84,7 @@ src/ ├── / # Each subfolder is a separate NuGet package │ └── .csproj # Inherits shared props from Directory.Build.props tests/ -├── UnitTests/ # xUnit v3 + AutoFixture + Shouldly +├── UnitTests/ # xUnit v3 + Moq + Shouldly Directory.Build.props # Root build properties (TFM, lang, analyzers) Directory.Build.targets # Build targets