CompaniesHouse.NET AGENTS.md

AGENTS.md

Guidance for AI agents (and humans) working in this repository. Read this before making changes, then read the relevant plan in .plans/outstanding/.

What this project is

CompaniesHouse.NET is a .NET client SDK for the Companies House Public Data API. It is published as two NuGet packages:

• CompaniesHouse — the core client (CompaniesHouseClient) and all request/response models.
• CompaniesHouse.Extensions.Microsoft.DependencyInjection — DI helpers for registering the client with IServiceCollection.

Current state: a v-next rewrite

We are building a new major version on the prerelease branch. Breaking changes are expected and welcome. The old surface lives on master and can be referenced for behaviour, but we are rebuilding the client endpoint-by-endpoint from the official API documentation rather than porting the old code verbatim.

The single source of truth for the work is .plans/. Do not freelance a large redesign — pick up an outstanding plan, refine it if needed, and execute it.

Non-negotiable design decisions

These are settled for the new major version. Do not reverse them without updating the relevant plan and calling it out explicitly.

1. Multi-target net8.0;net9.0;net10.0. No netstandard, no net45. Drop the Microsoft.NETFramework.ReferenceAssemblies and Microsoft.Net.Http references.
2. System.Text.Json only. Remove every reference to Newtonsoft.Json (see issue #188). No new dependency on Json.NET in any project, including tests.
3. No plain C# enums on the wire. Every API "enum" is modelled as a string-backed readonly record struct that preserves the raw value and never throws on an unrecognised value. See .plans/outstanding/03-string-backed-value-types.md and the design blog post: https://kevsoft.net/2026/06/28/enums-in-api-contracts.html.
4. Enum values are generated, not hand-written. A Roslyn source generator produces the string-backed types from the Companies House api-enumerations YAML (pulled in as a git submodule) plus our own local "extra" lists. We ship a new package version to pick up new values — we do not hand-edit generated types. See plans 04 and 05.
5. CompaniesHouseClient stays the entry point. Every capability hangs off it as its own focused sub-client (e.g. search, company profile, officers), each behind its own interface, exactly as today.
6. DI uses IOptions<>. The DI package uses AddOptions, IConfiguration binding and validation, with overloads to configure the client several ways. See .plans/outstanding/02-di-extensions-ioptions.md.
7. nullable reference types enabled across all projects.
8. Test stack: xUnit + Shouldly. No NUnit, no FluentAssertions (license changed to a paid tier from v8). Use [Fact]/[Theory]/[MemberData] and IAsyncLifetime for async setup/teardown; assert with Shouldly's .ShouldBe(...) family. For deep object-graph comparisons against test fixtures that hold raw wire strings, use the repo's own EquivalencyAssertionExtensions.ShouldBeEquivalentTo(...) helper in CompaniesHouse.Tests (bridges enum <-> wire string, no FluentAssertions IEquivalencyStep needed).