The rules for code in the Anarchy I/O Toolkit repository. Unlike the conventions for adopters, these are required: they are enforced by the build and in review, and a pull request that breaks one is not merged.

Process lives in CONTRIBUTING.md. Branches, commit messages, history shaping and version bumps are described there, and it wins on any disagreement with this page. Coding agents get both through AGENTS.md and the anarchy-contribute skill.

Every convention is a rule here

Each adopter convention applies in full, without its Opting out section:

Convention Enforced by
Layering make check_layering (CI), the dependency map
Naming Review
UseCases and Aggregates Review
Code Organization Review; applied to new and touched code
Dependency Injection Review
Observability Review
Async Review
Exceptions Review
Enums Review
Endpoints Review
Testing Review; unit tests on every pull request

Rules that only apply to the toolkit

Packages

  • Follow the values. In particular: packages are domain-free (no business enums, entities or destinations), vendor-neutral (company specifics go behind extension points) and standalone (every dependency restores from nuget.org).
  • Test-only libraries stay in Testing.* kits. No production project references AwesomeAssertions, Moq or xUnit.
  • One README per package. src/<Project>/README.md describes the package and links to RELEASE-NOTES.md, which has a note per published version. The copies under docs/portal/packages/ are generated.
  • New packages are listed in the Package Catalog, named after their layer (<Layer>.<Name>).
  • Package names follow the dependency hierarchy. Within a layer, a package may only reference its name ancestors (Web.MockServer.Ui to Web.MockServer or Web), so a feature family such as Infrastructure.Persistence.Db.* shows its shared parent in its name. A project may always reference a lower layer; any other same-layer reference is an entry, with its reason, in build/PackageHierarchy.cs. make check_package_hierarchy and its unit test enforce it. This is a rule of the toolkit’s own monorepo, which uses prefix layering; it is not part of the adopter conventions and is never imposed on solutions that use folder-mode layering.
  • Versions are bumped with make release_bump, never by hand, and validated with make validate_release.

Build and code quality

  • The build that counts is Release with warnings as errors: dotnet build Anarchy.Toolkit.sln -c Release -p:TreatWarningsAsErrors=true. Analyzer findings only show up there.
  • make lint passes; make lint_fix applies the formatting.
  • Package versions are centrally managed in Directory.Packages.props; respect the compatibility notes in it.

Tests

  • Unit tests run on xUnit v3 and Microsoft.Testing.Platform in tests/Unit/, with folders mirroring the src/ projects; tests that drive real tools (Git, the .NET SDK) go to tests/Integration/, and those that run a user-facing entry point (the CLI, the packaged Makefile and scripts) to tests/EndToEnd/.
  • Pass TestContext.Current.CancellationToken to calls that accept a token (xUnit1051).

Generated files and skills

  • Regenerate and commit docs/portal/dependency-map.html (make dependency_map) with any new project, project reference or package dependency.
  • Commit .fallout/build.schema.json when the build regenerates it.
  • Make targets name their agent skill with #@; update the skill and run make skills_sync. make skills_validate runs in CI.

Documentation

  • Guides teach, conventions recommend, decisions explain. Put new pages in the matching section: Guides, Conventions or Decisions, and add them to docs/portal/_data/navigation.yml.
  • A convention page keeps the same shape: banner, why (linking to a value or ADR), the rules, Opting out or adapting.
  • A choice that shapes the packages gets an ADR in docs/portal/decisions/.
  • Conventions, decisions and the onboarding guides also ship inside the agent skills (make skills_docs_sync, checked in CI). Agents read them without the site: keep links relative, keep the elements they look for (ordered steps, Why, Opting out or adapting, “Done when” checks, symptom/cause/fix tables), and update the skill’s guidance when a page’s shape changes.

Checks before a pull request

make lint
make test_unit
make check_layering
make check_package_hierarchy   # when you changed a project reference between packages
make skills_validate   # when you changed make targets