App-vNext · martincostello · Mar 13, 2026 · Mar 13, 2026 · Mar 13, 2026 · Mar 13, 2026
diff --git a/.github/wordlist.txt b/.github/wordlist.txt
@@ -1,14 +1,18 @@
+actionlint
 alloc
+aot
 apis
 ASP.NET
 astask
 async
 azurefunctions
+backoff
 bcl
 bdd
 cancellable
 changelog
 circuitbreaker
+codecov
 comparer
 contrib
 deserialization
@@ -21,6 +25,8 @@ eshoponcontainers
 extensibility
 flurl
 fs
+fscheck
+halfopen
 hangfire
 httpclient
 httpclientfactory
@@ -35,17 +41,21 @@ markdownsnippets
 middleware
 minver
 moq
+msbuild
 namespace
 natively
 ndc
 nuget
+nullable
+opentelemetry
 oss
 paas
 parallelize
 pcl
 pluralsight
 pollydocs
 pre
+PSScriptAnalyzer
 rabbitmq
 ratelimit
 ratelimitheaders
@@ -65,6 +75,7 @@ runnable
 runtime
 saas
 sdk
+semver
 serializers
 silverlight
 simmy
@@ -84,3 +95,4 @@ vnext
 waitandretry
 wpf
 xunit
+zizmor
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,102 @@
+# Coding Agent Instructions
+
+This file provides guidance to agents when working with code in this repository.
+
+## Build Commands
+
+```bash
+# Full build (clean, restore, build, test, package)
+./build.ps1
+
+# Build only (no tests)
+dotnet build
+
+# Run all tests
+dotnet test
+
+# Run a specific test project
+dotnet test ./test/Polly.Core.Tests/Polly.Core.Tests.csproj
+
+# Run a single test by filter
+dotnet test ./test/Polly.Core.Tests --filter "FullyQualifiedName~CircuitBreakerTests"
+
+# Run tests for a specific framework
+dotnet test ./test/Polly.Core.Tests --framework net10.0
+
+# Mutation testing
+./build.ps1 -Target MutationTestsCore
+./build.ps1 -Target MutationTestsExtensions
+./build.ps1 -Target MutationTestsLegacy
+./build.ps1 -Target MutationTestsRateLimiting
+./build.ps1 -Target MutationTestsTesting
+```
+
+Lint runs in CI via GitHub Actions workflows (actionlint, zizmor, PSScriptAnalyzer).
+
+Linting for C# is enabled through analyzers configured to run during the build process.
+
+## Architecture
+
+Polly is a .NET resilience library. Version 8+ (`Polly.Core`) is a complete redesign; `Polly` (the root package) is the legacy pre-v8 API kept for backwards compatibility.
+
+### Core abstractions (`src/Polly.Core`)
+
+- **`ResiliencePipeline`** / **`ResiliencePipeline<T>`** — the main user-facing type. Wraps one or more strategies and executes them in sequence.
+- **`ResiliencePipelineBuilder`** / **`ResiliencePipelineBuilder<T>`** — fluent builder used to compose strategies.
+- **`ResilienceStrategy`** / **`ResilienceStrategy<T>`** — base class for all built-in and custom strategies.
+- **`ResilienceContext`** — per-execution context flowing through the pipeline (cancellation token, properties, result type, etc.).
+
+### Built-in strategies
+
+Strategies split into two categories:
+
+**Reactive** (respond to failures):
+
+- `RetryResilienceStrategy` — configurable backoff, jitter, attempt limits
+- `CircuitBreakerResilienceStrategy` — state machine: Closed → Open → HalfOpen
+- `FallbackResilienceStrategy` — returns an alternative value/action on failure
+- `HedgingResilienceStrategy` — fires parallel attempts and returns the fastest success
+
+**Proactive** (prevent overload):
+
+- `TimeoutResilienceStrategy` — bounds execution duration
+- `RateLimiterResilienceStrategy` (in `Polly.RateLimiting`) — wraps `System.Threading.RateLimiting`
+
+Each strategy has a corresponding `*Options` class (e.g., `RetryStrategyOptions`) that holds configuration.
+Predicates for which outcomes to handle are declared via the `PredicateBuilder` fluent API.
+
+### Supporting packages
+
+- **`Polly.Extensions`** — `IServiceCollection` extensions and telemetry/OpenTelemetry support.
+- **`Polly.Testing`** — `ResiliencePipelineDescriptor` and test helpers; accesses internals via `InternalsVisibleTo`.
+
+### Multi-targeting
+
+- `Polly.Core`: targets .NET Framework, .NET and .NET Standard.
+- Test projects: Target all supported versions of .NET plus the latest version of .NET Framework on Windows.
+- Targets for .NET 8 and later support native AoT.
+
+### Build system
+
+- **Cake** (bootstrapped by `build.ps1`) orchestrates the full pipeline via `cake.cs`.
+- **Centralized package management**: all NuGet versions in `Directory.Packages.props`.
+- **`Directory.Build.props` / `eng/Common.props`**: shared MSBuild properties (nullable enabled, warnings-as-errors, strong naming via `Polly.snk`, XML doc generation).
+- **`LegacySupport`**: a shared source project injected into `Polly` at compile time via a custom MSBuild target.
+- **MinVer** provides automatic SemVer versioning from git tags.
+
+### Testing patterns
+
+- **xUnit** for unit tests; **FsCheck** for property-based/fuzz tests.
+- Test projects access internals via `InternalsVisibleTo` declared in `eng/Library.targets` (brought in via the shared MSBuild imports).
+- `Polly.TestUtils` is a shared utilities project referenced by several test projects.
+- `Polly.AotTest` validates AOT compatibility by publishing a trimmed app.
+- Coverage is collected in CI and uploaded to Codecov.
+
+## General guidelines
+
+- Always ensure code compiles with no warnings or errors and tests pass locally before pushing changes.
+- Do not change the public API unless specifically requested.
+- Do not use APIs marked with `[Obsolete]`.
+- Bug fixes should **always** include a test that would fail without the corresponding fix.
+- Do not introduce new dependencies unless specifically requested.
+- Do not update existing dependencies unless specifically requested.