Skip to content

Commit 4d4b00a

Browse files
KSemenenkoKSemenenko
committed
Document FeatureChecker governance
1 parent 4ae019c commit 4d4b00a

10 files changed

Lines changed: 433 additions & 7 deletions

File tree

‎.editorconfig‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
trim_trailing_whitespace = true
8+
indent_style = space
9+
indent_size = 2
10+
11+
[*.cs]
12+
indent_size = 4
13+
dotnet_sort_system_directives_first = true
14+
dotnet_separate_import_directive_groups = false
15+
16+
dotnet_style_qualification_for_event = false:suggestion
17+
dotnet_style_qualification_for_field = false:suggestion
18+
dotnet_style_qualification_for_method = false:suggestion
19+
dotnet_style_qualification_for_property = false:suggestion
20+
21+
dotnet_style_predefined_type_for_locals_parameters_members = true:suggestion
22+
dotnet_style_predefined_type_for_member_access = true:suggestion
23+
24+
dotnet_style_object_initializer = true:suggestion
25+
dotnet_style_collection_initializer = true:suggestion
26+
dotnet_style_coalesce_expression = true:suggestion
27+
dotnet_style_null_propagation = true:suggestion
28+
29+
csharp_style_namespace_declarations = file_scoped:suggestion
30+
csharp_style_var_elsewhere = false:suggestion
31+
csharp_style_var_for_built_in_types = false:suggestion
32+
csharp_style_var_when_type_is_apparent = true:suggestion
33+
34+
dotnet_analyzer_diagnostic.category-Design.severity = warning
35+
dotnet_analyzer_diagnostic.category-Performance.severity = warning
36+
dotnet_analyzer_diagnostic.category-Reliability.severity = warning
37+
dotnet_analyzer_diagnostic.category-Security.severity = warning
38+
39+
[*.md]
40+
trim_trailing_whitespace = false

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ e2e/*.map
3333

3434
# System Files
3535
.DS_Store/
36+
.codex/
3637

3738
### ASPNETCore ###
3839
## Ignore Visual Studio temporary files, build results, and
@@ -863,4 +864,4 @@ FodyWeavers.xsd
863864
### VisualStudio Patch ###
864865
# Additional files built by Visual Studio
865866

866-
# End of https://www.toptal.com/developers/gitignore/api/windows,linux,macos,visualstudio,visualstudiocode,intellij,intellij+all,rider,angular,dotnetcore,aspnetcore,xamarinstudio
867+
# End of https://www.toptal.com/developers/gitignore/api/windows,linux,macos,visualstudio,visualstudiocode,intellij,intellij+all,rider,angular,dotnetcore,aspnetcore,xamarinstudio

‎AGENTS.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# FeatureChecker Agent Guide
2+
3+
Project: ManagedCode.FeatureChecker
4+
Stack: .NET 10 class library, TUnit tests, GitHub Actions, NuGet package publishing
5+
6+
Follows [MCAF](https://mcaf.managed-code.com/).
7+
8+
## Purpose
9+
10+
This file defines how AI agents work in this solution.
11+
12+
- Root `AGENTS.md` holds global workflow, shared commands, cross-cutting rules, and skill routing.
13+
- Local project rules live in `ManagedCode.FeatureChecker/AGENTS.md` and `ManagedCode.FeatureChecker.Tests/AGENTS.md`.
14+
- Local files refine or tighten root rules. They must not silently weaken this file.
15+
16+
## Solution Topology
17+
18+
- Solution root: `.`
19+
- Solution file: `ManagedCode.FeatureChecker.sln`
20+
- Production project: `ManagedCode.FeatureChecker/`
21+
- Test project: `ManagedCode.FeatureChecker.Tests/`
22+
- Architecture map: `docs/Architecture.md`
23+
- Agent skills: `.codex/skills/`
24+
25+
## Rule Precedence
26+
27+
1. Read this solution-root `AGENTS.md` first.
28+
2. Read the nearest local `AGENTS.md` for the files being edited.
29+
3. Apply the stricter rule when root and local files overlap.
30+
4. If a local rule appears weaker than root policy, stop and clarify or document an explicit exception.
31+
5. Document justified exceptions in the nearest local `AGENTS.md`, `docs/ADR/`, or `docs/Features/`.
32+
33+
## Conversations
34+
35+
Record durable user preferences and repeated corrections here instead of relying on chat history. Do not record one-off task scope.
36+
37+
Update this file when the user gives a permanent requirement, repeated correction, workflow change, or strong preference.
38+
39+
## Global Skills
40+
41+
MCAF skills are installed from the canonical MCAF tutorial and use current `mcaf-*` folders only:
42+
43+
- `mcaf-solution-governance` - root and project-local `AGENTS.md`, precedence, topology, and maintainability policy.
44+
- `mcaf-architecture-overview` - `docs/Architecture.md` and navigational system maps.
45+
- `mcaf-solid-maintainability` - SOLID, SRP, file/type/function limits, and exception handling policy.
46+
- `mcaf-testing` - automated testing rules and verification planning.
47+
- `mcaf-ci-cd` - GitHub Actions, NuGet publishing, release flow, and pipeline safety.
48+
- `mcaf-source-control` - branch, commit, review, and release hygiene.
49+
- `mcaf-documentation` - durable docs structure and source-of-truth placement.
50+
- `mcaf-feature-spec` - non-trivial feature behaviour specs under `docs/Features/`.
51+
- `mcaf-adr-writing` - architecture decisions under `docs/ADR/`.
52+
- `mcaf-code-review` - review readiness and PR hygiene.
53+
- `mcaf-security-baseline` - secrets, secure defaults, and security-impact checkpoints.
54+
- `mcaf-devex` - local setup, inner loop, onboarding, and reproducible commands.
55+
56+
.NET skills are installed from [Managed Code Skills](https://skills.managed-code.com/) into `.codex/skills/`:
57+
58+
- `dotnet`, `project-setup`, `modern-csharp`, `microsoft-extensions`
59+
- `format`, `analyzer-config`, `code-analysis`, `quality-ci`
60+
- `complexity`, `crap-score`, `roslynator`, `meziantou-analyzer`, `stylecop-analyzers`, `csharpier`
61+
- `run-tests`, `dotnet-test-frameworks`, `tunit`, `coverlet`, `coverage-analysis`, `reportgenerator`, `test-anti-patterns`
62+
- `nuget-trusted-publishing`
63+
64+
Skill management rules:
65+
66+
- Keep MCAF framework skills current and prefixed with `mcaf-`.
67+
- Fetch .NET-specific skills from `https://skills.managed-code.com/`.
68+
- Add new tool-specific skills only when the repo actually uses that tool in code, tests, CI, or release work.
69+
- After skill updates, recheck the build, test, format, analyze, coverage, and release commands below.
70+
71+
## Commands
72+
73+
- `restore`: `dotnet restore ManagedCode.FeatureChecker.sln`
74+
- `build`: `dotnet build ManagedCode.FeatureChecker.sln --configuration Release --no-restore`
75+
- `test`: `dotnet test --solution ManagedCode.FeatureChecker.sln --configuration Release --verbosity normal`
76+
- `format`: `dotnet format ManagedCode.FeatureChecker.sln --verify-no-changes`
77+
- `analyze`: `dotnet build ManagedCode.FeatureChecker.sln --configuration Release -p:RunAnalyzers=true`
78+
- `coverage`: `dotnet test --solution ManagedCode.FeatureChecker.sln --configuration Release -- --coverage --coverage-output-format cobertura`
79+
80+
.NET specifics:
81+
82+
- Target framework is `net10.0` from `Directory.Build.props`.
83+
- `LangVersion` is explicitly pinned to `14` in `Directory.Build.props`.
84+
- Test framework is TUnit.
85+
- Runner model is `Microsoft.Testing.Platform`, configured in `global.json`.
86+
- Coverage uses the `Microsoft.Testing.Platform` `--coverage` extension syntax. Do not use VSTest `--collect` syntax unless the runner model changes.
87+
- Repo-root `.editorconfig` is the source of truth for formatting, naming, style, and analyzer severity.
88+
- `Directory.Build.props`, `Directory.Packages.props`, and project files own package versions, analyzer switches, package metadata, and runner settings.
89+
90+
## Project AGENTS Policy
91+
92+
- This is a multi-project solution. Keep one root `AGENTS.md` and one local `AGENTS.md` in each project root.
93+
- Each local file must document purpose, entry points, boundaries, local commands, applicable skills, and local risks.
94+
- When adding a new project, add its local `AGENTS.md` in the same change.
95+
96+
## Maintainability Limits
97+
98+
- `file_max_loc`: `400`
99+
- `type_max_loc`: `200`
100+
- `function_max_loc`: `50`
101+
- `max_nesting_depth`: `3`
102+
- `exception_policy`: `Document any justified exception in the nearest ADR, feature doc, or local AGENTS.md with the reason, scope, verification, and removal or refactor plan.`
103+
104+
Local `AGENTS.md` files may tighten these values. They must not loosen them without an explicit root-level exception.
105+
106+
## Task Delivery
107+
108+
- Start non-trivial work from `docs/Architecture.md` and the nearest local `AGENTS.md`.
109+
- Use vertical slices for behaviour changes: keep code, tests, contracts, docs, and supporting artifacts close to the feature boundary.
110+
- For non-trivial work, create `<slug>.brainstorm.md` before `<slug>.plan.md`; skip the brainstorm only for simple or obvious tasks.
111+
- Put test strategy inside the plan before implementation starts.
112+
- Run a baseline test pass after planning non-trivial work so pre-existing failures are visible.
113+
- Implement code and tests together.
114+
- Run verification in layers: build, focused tests, related tests, broader suite, format, analyzers, coverage, and any relevant release checks.
115+
- Update `docs/Architecture.md`, `docs/Features/`, or `docs/ADR/` when architecture, behaviour, or durable rules change.
116+
117+
## Testing
118+
119+
- TDD is the default for new behaviour and bug fixes.
120+
- Bug fixes start with a failing regression test when practical.
121+
- New public behaviour needs positive, negative, and edge-case coverage.
122+
- Prefer testing caller-visible behaviour through public contracts over implementation details.
123+
- Flaky tests are failures. Fix the cause.
124+
- Production code changes should preserve or improve coverage. Public contracts and critical flows require explicit success and failure assertions.
125+
- Do not skip tests to make a branch green.
126+
127+
## Code and Design
128+
129+
- SOLID, SRP, cohesion, and composition over inheritance are default design rules.
130+
- Keep public API changes intentional, documented, and covered by tests.
131+
- Avoid hardcoded values and magic literals in implementation code. Prefer named constants, enums, options, or value objects.
132+
- Remove obsolete code when replacing an implementation. Do not leave shims or fallback paths unless an explicit temporary exception documents the owner, scope, verification, and removal plan.
133+
- Do not add runtime dependencies to the core library without a documented reason.
134+
135+
## Release and Source Control
136+
137+
- Never force-push to `main`.
138+
- Do not commit secrets, keys, or connection strings.
139+
- Release and NuGet changes must be validated with `mcaf-ci-cd` and `nuget-trusted-publishing`.
140+
- Package metadata lives in `Directory.Build.props` and `ManagedCode.FeatureChecker/ManagedCode.FeatureChecker.csproj`.
141+
- GitHub Actions workflows live in `.github/workflows/`.
142+
143+
## Preferences
144+
145+
### Likes
146+
147+
### Dislikes

‎ManagedCode.FeatureChecker.Tests/AGENTS.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# ManagedCode.FeatureChecker.Tests Agent Guide
2+
3+
Project: ManagedCode.FeatureChecker.Tests
4+
Parent: `../AGENTS.md`
5+
6+
## Purpose
7+
8+
- Verifies the public behaviour of `ManagedCode.FeatureChecker`.
9+
- Provides regression coverage for public API semantics and package-facing examples.
10+
11+
## Entry Points
12+
13+
- `Tests.cs` - TUnit tests for feature status lookup and filtering.
14+
- `MyEnum.cs` - test enum fixture.
15+
- `ManagedCode.FeatureChecker.Tests.csproj` - test dependencies, project reference, and coverage collector.
16+
17+
## Boundaries
18+
19+
- In scope: TUnit tests, test fixtures, coverage configuration, and behaviour-focused regression cases.
20+
- Out of scope: production API implementation, package metadata, and GitHub Actions workflow authoring.
21+
- High risk: tests that only mirror implementation details, fragile ordering assumptions, or missing negative cases for public behaviour.
22+
23+
## Project Commands
24+
25+
- `build`: `dotnet build ManagedCode.FeatureChecker.Tests/ManagedCode.FeatureChecker.Tests.csproj --configuration Release`
26+
- `test`: `dotnet test ManagedCode.FeatureChecker.Tests/ManagedCode.FeatureChecker.Tests.csproj --configuration Release --verbosity normal`
27+
- `coverage`: `dotnet test ManagedCode.FeatureChecker.Tests/ManagedCode.FeatureChecker.Tests.csproj --configuration Release -- --coverage --coverage-output-format cobertura`
28+
- `format`: `dotnet format ManagedCode.FeatureChecker.sln --verify-no-changes`
29+
- `analyze`: `dotnet build ManagedCode.FeatureChecker.Tests/ManagedCode.FeatureChecker.Tests.csproj --configuration Release -p:RunAnalyzers=true`
30+
31+
.NET specifics:
32+
33+
- Test framework: TUnit.
34+
- Runner model: `Microsoft.Testing.Platform`.
35+
- Coverage driver: `Microsoft.Testing.Platform` `--coverage` extension syntax. The project references `coverlet.collector`, but repo commands must not use VSTest `--collect` syntax while the runner model is `Microsoft.Testing.Platform`.
36+
- Analyzer severity owner: repo-root `.editorconfig`.
37+
38+
## Applicable Skills
39+
40+
- `mcaf-testing`
41+
- `mcaf-solid-maintainability`
42+
- `dotnet-test-frameworks`
43+
- `run-tests`
44+
- `tunit`
45+
- `coverlet`
46+
- `coverage-analysis`
47+
- `test-anti-patterns`
48+
49+
## Local Constraints
50+
51+
- Tests should exercise caller-visible behaviour through public APIs.
52+
- Add regression tests before fixing behaviour defects.
53+
- Keep fixtures small and explicit.
54+
- Local maintainability limits match the root defaults.
55+
56+
## Local Rules
57+
58+
- Prefer meaningful assertions over count-only tests.
59+
- Cover unknown features, all feature states, and status filtering when feature semantics change.
60+
- Do not weaken assertions to fit an implementation change.

‎ManagedCode.FeatureChecker/AGENTS.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# ManagedCode.FeatureChecker Agent Guide
2+
3+
Project: ManagedCode.FeatureChecker
4+
Parent: `../AGENTS.md`
5+
6+
## Purpose
7+
8+
- Provides the public enum-based feature checker library.
9+
- Owns the packageable API surface published as `ManagedCode.FeatureChecker`.
10+
11+
## Entry Points
12+
13+
- `IFeatureChecker.cs` - public feature checker contract.
14+
- `FeatureChecker.cs` - default immutable checker implementation.
15+
- `FeatureHolder.cs` - dictionary-based feature status holder.
16+
- `FeatureStatus.cs` - public feature state enum.
17+
- `ManagedCode.FeatureChecker.csproj` - NuGet package metadata and packability.
18+
19+
## Boundaries
20+
21+
- In scope: public feature-checking contracts, default implementation, package metadata, and README examples for the library API.
22+
- Out of scope: test-only fixtures, CI workflow implementation, external service integrations, and provider-specific storage packages.
23+
- High risk: public API changes, enum/value semantics, package identity, and behaviour that existing consumers may depend on.
24+
25+
## Project Commands
26+
27+
- `build`: `dotnet build ManagedCode.FeatureChecker/ManagedCode.FeatureChecker.csproj --configuration Release`
28+
- `test`: `dotnet test ManagedCode.FeatureChecker.Tests/ManagedCode.FeatureChecker.Tests.csproj --configuration Release --verbosity normal`
29+
- `format`: `dotnet format ManagedCode.FeatureChecker.sln --verify-no-changes`
30+
- `analyze`: `dotnet build ManagedCode.FeatureChecker/ManagedCode.FeatureChecker.csproj --configuration Release -p:RunAnalyzers=true`
31+
32+
.NET specifics:
33+
34+
- Target framework: `net10.0` from `../Directory.Build.props`.
35+
- Language version: `14` from `../Directory.Build.props`.
36+
- Analyzer severity owner: repo-root `.editorconfig`.
37+
- Tests: TUnit tests in `../ManagedCode.FeatureChecker.Tests/`.
38+
- Runner model: `Microsoft.Testing.Platform`.
39+
40+
## Applicable Skills
41+
42+
- `mcaf-solid-maintainability`
43+
- `mcaf-testing`
44+
- `mcaf-feature-spec`
45+
- `mcaf-documentation`
46+
- `dotnet`
47+
- `modern-csharp`
48+
- `code-analysis`
49+
- `analyzer-config`
50+
- `format`
51+
52+
## Local Constraints
53+
54+
- Keep the core package dependency-light. Add runtime dependencies only with a documented API and packaging reason.
55+
- Public API changes require matching tests and README updates.
56+
- Preserve deterministic, side-effect-free feature evaluation unless an ADR documents a new provider model.
57+
- Local maintainability limits match the root defaults.
58+
59+
## Local Rules
60+
61+
- Prefer immutable or copy-on-construction data for public checker state.
62+
- Do not add cloud-provider or storage-specific code to this project unless the API is explicitly provider-agnostic.
63+
- Keep examples aligned with the real public API.
64+

‎ManagedCode.FeatureChecker/FeatureChecker.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
namespace ManagedCode.FeatureChecker;
1+
namespace ManagedCode.FeatureChecker;
22

33
public class FeatureChecker : IFeatureChecker
44
{

‎ManagedCode.FeatureChecker/FeatureHolder.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
namespace ManagedCode.FeatureChecker;
1+
namespace ManagedCode.FeatureChecker;
22

33
public class FeatureHolder : Dictionary<Enum, FeatureStatus>
44
{
5-
}
5+
}

‎ManagedCode.FeatureChecker/FeatureStatus.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
namespace ManagedCode.FeatureChecker;
1+
namespace ManagedCode.FeatureChecker;
22

33
public enum FeatureStatus
44
{
55
Disabled,
66
Enabled,
77
Debug
8-
}
8+
}

‎ManagedCode.FeatureChecker/IFeatureChecker.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,4 @@ public interface IFeatureChecker
99
bool IsDebug(Enum feature);
1010
bool TryGetFeatureStatus(Enum feature, out FeatureStatus status);
1111
List<Enum> GetFeaturesByStatus(FeatureStatus status);
12-
}
12+
}

0 commit comments

Comments
 (0)