@cratis/pi 7.102.0 → 7.103.0

package/package/corpus/skills/extension-points/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: extension-points
+description: 'Owns MSBuild import and hook discovery: CustomBefore and CustomAfter hooks, ordered wildcard and NuGet auto-imports, control properties, build and buildTransitive packed layout, package ID and file-name matching, per-TFM forwarders, and tracing why assets or hooks are missing, broken, or replaced. Use when imports or hooks do not run, run in the wrong order, or are overwritten. Not for a verdict on whether one Import needs an Exists guard (use the msbuild skill''s antipatterns reference), target Inputs/Outputs or incremental skipping (use target-authoring), or props-versus-targets placement (use directory-build-organization).'
+license: MIT
+---
+
+<!-- Modified by Cratis from dotnet's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/dotnet/skills (plugins/dotnet-msbuild/skills/extension-points/SKILL.md; see NOTICE) -->
+
+# MSBuild Extension Points
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
+
+How the MSBuild pipeline provides hooks for SDKs, NuGet packages, repos, and users to inject custom logic.
+
+## CustomBefore / CustomAfter Hooks
+
+Every major `.targets` file defines import hooks:
+
+```xml
+<PropertyGroup>
+  <CustomBeforeMicrosoftCommonTargets Condition="'$(CustomBeforeMicrosoftCommonTargets)' == ''">
+    $(MSBuildExtensionsPath)\v$(MSBuildToolsVersion)\Custom.Before.Microsoft.Common.targets
+  </CustomBeforeMicrosoftCommonTargets>
+</PropertyGroup>
+
+<Import Project="$(CustomBeforeMicrosoftCommonTargets)"
+    Condition="'$(CustomBeforeMicrosoftCommonTargets)' != '' and Exists('$(CustomBeforeMicrosoftCommonTargets)')"/>
+<!-- ... core targets ... -->
+<Import Project="$(CustomAfterMicrosoftCommonTargets)"
+    Condition="'$(CustomAfterMicrosoftCommonTargets)' != '' and Exists('$(CustomAfterMicrosoftCommonTargets)')"/>
+```
+
+### Rules
+
+- Default path includes version (`v$(MSBuildToolsVersion)`) for side-by-side installations.
+- Always check `Exists()`. The file may not be present on every machine.
+- **Append** to the property (don't overwrite) to chain multiple hooks:
+
+```xml
+<PropertyGroup>
+  <CustomBeforeMicrosoftCommonTargets>
+    $(CustomBeforeMicrosoftCommonTargets);$(MSBuildThisFileDirectory)MyExtension.targets
+  </CustomBeforeMicrosoftCommonTargets>
+</PropertyGroup>
+```
+
+## Wildcard Import Directories
+
+MSBuild imports all files in extension directories, sorted alphabetically:
+
+```xml
+<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Imports\Microsoft.Common.props\ImportBefore\*"
+    Condition="'$(ImportByWildcardBeforeMicrosoftCommonProps)' == 'true'
+               and Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Imports\Microsoft.Common.props\ImportBefore')" />
+```
+
+### Key paths
+
+| Property | Resolves to | Scope |
+|---|---|---|
+| `$(MSBuildUserExtensionsPath)` | `%APPDATA%\Microsoft\MSBuild` | Per-user |
+| `$(MSBuildExtensionsPath)` | MSBuild install directory | Machine-wide |
+| `$(MSBuildProjectExtensionsPath)` | `obj/` directory | Per-project (NuGet) |
+
+Name files with numeric prefixes for ordering: `01-first.props`, `02-second.props`.
+
+## Import Gating — Control Properties
+
+Every wildcard import is gated by a boolean property:
+
+```xml
+<PropertyGroup>
+  <ImportByWildcardBeforeMicrosoftCommonProps
+      Condition="'$(ImportByWildcardBeforeMicrosoftCommonProps)' == ''">true</ImportByWildcardBeforeMicrosoftCommonProps>
+  <ImportDirectoryBuildProps
+      Condition="'$(ImportDirectoryBuildProps)' == ''">true</ImportDirectoryBuildProps>
+</PropertyGroup>
+```
+
+### Available control properties
+
+| Property | What it disables |
+|---|---|
+| `ImportDirectoryBuildProps` | Directory.Build.props auto-discovery |
+| `ImportDirectoryBuildTargets` | Directory.Build.targets auto-discovery |
+| `ImportProjectExtensionProps` | NuGet-generated `*.props` in obj/ |
+| `ImportProjectExtensionTargets` | NuGet-generated `*.targets` in obj/ |
+| `ImportByWildcardBefore*` | Machine-level ImportBefore extensions |
+| `ImportByWildcardAfter*` | Machine-level ImportAfter extensions |
+
+## NuGet Package Build Extension Layout
+
+NuGet packages inject build logic via `build/` or `buildTransitive/` folders:
+
+```text
+MyPackage/
+  build/
+    MyPackage.props      ← imported via *.props wildcard
+    MyPackage.targets    ← imported via *.targets wildcard
+  buildTransitive/
+    MyPackage.props      ← imported by transitive consumers
+    MyPackage.targets
+```
+
+### Rules
+
+- File names **must match the package ID** exactly.
+- `build/` affects direct consumers only. `buildTransitive/` affects the entire dependency chain.
+- Props are imported early (before the project), targets are imported late (after the project).
+
+### Forwarding chain: `buildTransitive/` → `build/` → shared
+
+Forward `buildTransitive/*.props` and `buildTransitive/*.targets` through their sibling `build/*.props` / `build/*.targets` files (chain `buildTransitive → build → shared`) instead of importing `buildMultiTargeting/` directly. This keeps `build/` as the single source of truth with a clear ownership chain, so transitive consumers stay in sync with direct consumers instead of the two layouts drifting apart.
+
+When `build/` is packed **per-TFM** (`build/<tfm>/`, via `TfmSpecificPackageFile`, a per-TFM `<PackagePath>`, or SDK conventions) while `buildMultiTargeting/` is not, a `buildTransitive/<tfm>/` forwarder **must include the TFM segment** — dropping it resolves to a non-existent package-root `build/MyPackage.props` and fails transitive consumers with **`MSB4019`**. Derive the segment from the file's own folder, never `$(TargetFramework)` (NuGet nearest-match can serve a `net10.0` consumer the `net9.0` folder, so `$(TargetFramework)` may name a folder that was never restored):
+
+```xml
+<!-- buildTransitive/<tfm>/MyPackage.props -->
+<Import Project="$(MSBuildThisFileDirectory)..\..\build\$([System.IO.Path]::GetFileName($([System.IO.Path]::GetDirectoryName('$(MSBuildThisFileDirectory)'))))\MyPackage.props" />
+```
+
+## Source Tree vs Packed Layout
+
+When reviewing a NuGet build-extension package, the **source layout** in the repository can legitimately differ from the **packed layout** inside the produced `.nupkg`. This is a common source of false-positive "import points at a missing file" findings.
+
+Three packaging mechanisms reshape the layout at pack time:
+
+1. **`.nuspec` `<file src=… target=…>` mappings** — copy a single source file into multiple per-TFM targets:
+
+   ```xml
+   <!-- Source tree has ONE shared file:
+          buildTransitive\common\MyAdapter.props
+        Pack rewrites it to per-TFM targets inside the .nupkg:
+          buildTransitive\net462\MyAdapter.props
+          buildTransitive\net8.0\MyAdapter.props
+          buildTransitive\net9.0\MyAdapter.props -->
+   <files>
+     <file src="buildTransitive\common\MyAdapter.props" target="buildTransitive\net462\MyAdapter.props" />
+     <file src="buildTransitive\common\MyAdapter.props" target="buildTransitive\net8.0\MyAdapter.props" />
+     <file src="buildTransitive\common\MyAdapter.props" target="buildTransitive\net9.0\MyAdapter.props" />
+   </files>
+   ```
+
+   In the `<file>` element, a `target` ending in `\` is treated as a folder (filename preserved from `src`); a `target` ending in a filename renames the file.
+
+2. **`.csproj` `<PackagePath>` metadata** on `<None Update=…>` or `<Content Include=…>` items — same effect via SDK pack. Use one item per destination to keep the mapping unambiguous:
+
+   ```xml
+   <ItemGroup>
+     <None Include="buildTransitive\common\MyAdapter.props" Pack="true" PackagePath="buildTransitive\net8.0\MyAdapter.props" />
+     <None Include="buildTransitive\common\MyAdapter.props" Pack="true" PackagePath="buildTransitive\net9.0\MyAdapter.props" />
+   </ItemGroup>
+   ```
+
+   NuGet/SDK pack also accepts a semicolon-separated list (`PackagePath="buildTransitive\net8.0\;buildTransitive\net9.0\"`) to fan one source out to multiple destinations, but the multi-item form above is harder to misread.
+
+3. **SDK conventions** — `IncludeBuildOutput`, `BuildOutputTargetFolder`, `IncludeContentInPack` automatically place built outputs under `lib/<tfm>/` or `build/<tfm>/`.
+
+### Implication for reviewers
+
+A forwarder like the following inside a packed `build/net462/` folder is **not** a "missing-file" bug, even if the source tree has no `buildTransitive/net462/` directory:
+
+```xml
+<!-- In packed build/net462/MyAdapter.props -->
+<Project>
+  <Import Project="$(MSBuildThisFileDirectory)..\..\buildTransitive\net462\MyAdapter.props" />
+</Project>
+```
+
+Before flagging an unguarded `<Import>` inside a `build/<tfm>/` or `buildTransitive/<tfm>/` folder:
+
+1. Look for `*.nuspec` in the project directory and its immediate parent directory (do not walk further up). Read every `<file target=…>` whose `target` matches the imported path.
+2. Read the `.csproj` for `<PackagePath>` metadata on `<None>`/`<Content>` items.
+3. Only flag the import if the target path is missing from **both** the source tree *and* the projected package layout.
+
+See also msbuild antipatterns AP-13 ("NuGet package forwarders" exception).
+
+## Import Guard Pattern
+
+The `.targets` file ensures `.props` was imported using a guard property:
+
+```xml
+<!-- End of Microsoft.Common.props -->
+<PropertyGroup>
+  <MicrosoftCommonPropsHasBeenImported>true</MicrosoftCommonPropsHasBeenImported>
+</PropertyGroup>
+
+<!-- Top of Microsoft.Common.CurrentVersion.targets -->
+<Import Project="Microsoft.Common.props"
+    Condition="'$(MicrosoftCommonPropsHasBeenImported)' != 'true'" />
+```
+
+This handles projects that only import `.targets`.
+
+## Directory.Build Discovery
+
+MSBuild walks up the directory tree to find the nearest `Directory.Build.props`:
+
+```xml
+<_DirectoryBuildPropsBasePath>
+  $([MSBuild]::GetDirectoryNameOfFileAbove('$(MSBuildProjectDirectory)', 'Directory.Build.props'))
+</_DirectoryBuildPropsBasePath>
+```
+
+Only the **nearest** file is discovered. Nested hierarchies must explicitly import parents:
+
+```xml
+<!-- src/Directory.Build.props -->
+<PropertyGroup>
+  <_ParentPropsPath>$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))</_ParentPropsPath>
+</PropertyGroup>
+<Import Project="$(_ParentPropsPath)" Condition="'$(_ParentPropsPath)' != ''" />
+```
+
+## Creating Your Own Extension Point
+
+```xml
+<!-- MySDK.targets -->
+<Project>
+  <Import Project="MySDK.props" Condition="'$(MySDKPropsImported)' != 'true'" />
+
+  <PropertyGroup>
+    <CustomBeforeMySDK Condition="'$(CustomBeforeMySDK)' == ''">$(MSBuildProjectDirectory)\MySDK.Before.targets</CustomBeforeMySDK>
+    <CustomAfterMySDK Condition="'$(CustomAfterMySDK)' == ''">$(MSBuildProjectDirectory)\MySDK.After.targets</CustomAfterMySDK>
+  </PropertyGroup>
+
+  <Import Project="$(CustomBeforeMySDK)" Condition="Exists('$(CustomBeforeMySDK)')" />
+
+  <PropertyGroup>
+    <MySDKBuildDependsOn>BeforeMySDKBuild;CoreMySDKBuild;AfterMySDKBuild</MySDKBuildDependsOn>
+  </PropertyGroup>
+  <Target Name="MySDKBuild" DependsOnTargets="$(MySDKBuildDependsOn)" />
+  <Target Name="BeforeMySDKBuild" />
+  <Target Name="AfterMySDKBuild" />
+  <Target Name="CoreMySDKBuild">
+    <!-- implementation -->
+  </Target>
+
+  <Import Project="$(CustomAfterMySDK)" Condition="Exists('$(CustomAfterMySDK)')" />
+</Project>
+```
+
+## Common Pitfalls
+
+- **Missing `Exists()` on optional imports** causes build failures when files are absent. **Exception**: imports inside published `build/<tfm>/` and `buildTransitive/<tfm>/` folders of a NuGet package are a package contract — the target is guaranteed by the packed layout (see "Source Tree vs Packed Layout" above). Don't guard them and don't flag them.
+- **Overwriting Custom* properties** drops prior hooks. Append with `;` separator.
+- **NuGet package file names not matching package ID** silently skips the import.
+- **Nested Directory.Build.props** without parent import loses repo-root settings.

package/package/corpus/skills/filter-syntax/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package/corpus/skills/filter-syntax/NOTICE

@@ -0,0 +1,17 @@
+Test Filter Syntax Reference
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet-test/skills/filter-syntax/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Normalize frontmatter serialization, add MIT license where absent; move user-invocable, disable-model-invocation under metadata as strings.
+- Add marked modification/source comment and applicability/Cratis precedence line with the skill-specific safety, ownership or compatibility caveat.
+- Rewrite the description to the Cratis shape (what it does, Use when, Not for) and drop references to skills that are not part of this corpus.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.

package/package/corpus/skills/filter-syntax/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: filter-syntax
+description: 'Reference-only filter syntax for VSTest and Microsoft Testing Platform (MTP) with MSTest, NUnit, xUnit v3, and TUnit. Use when run-tests needs to create or translate a test filter after the platform and framework are known. Not for unfiltered runs or platform detection (use platform-detection); loaded by run-tests, never invoked directly.'
+license: MIT
+metadata:
+  user-invocable: 'false'
+  disable-model-invocation: 'true'
+---
+
+<!-- Modified by Cratis from dotnet's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/dotnet/skills (plugins/dotnet-test/skills/filter-syntax/SKILL.md; see NOTICE) -->
+
+# Test Filter Syntax Reference
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ. Specification authoring belongs to **cratis-specifications-csharp**; Cratis core repositories run xUnit v2 on VSTest.
+
+Filter syntax depends on the **platform** and **test framework**.
+
+## VSTest filters (MSTest, xUnit v2, NUnit on VSTest)
+
+```bash
+dotnet test --filter <EXPRESSION>
+```
+
+Expression syntax: `<Property><Operator><Value>[|&<Expression>]`
+
+**Operators:**
+
+| Operator | Meaning |
+|----------|---------|
+| `=` | Exact match |
+| `!=` | Not exact match |
+| `~` | Contains |
+| `!~` | Does not contain |
+
+**Combinators:** `|` (OR), `&` (AND). Parentheses for grouping: `(A|B)&C`
+
+**Supported properties by framework:**
+
+| Framework | Properties |
+|-----------|-----------|
+| MSTest | `FullyQualifiedName`, `Name`, `ClassName`, `Priority`, `TestCategory` |
+| xUnit | `FullyQualifiedName`, `DisplayName`, `Traits` |
+| NUnit | `FullyQualifiedName`, `Name`, `Priority`, `TestCategory` |
+
+An expression without an operator is treated as `FullyQualifiedName~<value>`.
+
+**Examples (VSTest):**
+
+```bash
+# Run tests whose name contains "LoginTest"
+dotnet test --filter "Name~LoginTest"
+
+# Run a specific test class
+dotnet test --filter "ClassName=MyNamespace.MyTestClass"
+
+# Run tests in a category
+dotnet test --filter "TestCategory=Integration"
+
+# Exclude a category
+dotnet test --filter "TestCategory!=Slow"
+
+# Combine: class AND category
+dotnet test --filter "ClassName=MyNamespace.MyTestClass&TestCategory=Unit"
+
+# Either of two classes
+dotnet test --filter "ClassName=MyNamespace.ClassA|ClassName=MyNamespace.ClassB"
+```
+
+## MTP filters — MSTest and NUnit
+
+MSTest and NUnit on MTP use the **same `--filter` syntax** as VSTest (same properties, operators, and combinators). The only difference is how the flag is passed:
+
+```bash
+# .NET SDK 8/9 (after --)
+dotnet test -- --filter "Name~LoginTest"
+
+# .NET SDK 10+ (direct)
+dotnet test --filter "Name~LoginTest"
+```
+
+## MTP filters — xUnit (v3)
+
+xUnit v3 on MTP uses **framework-specific filter flags** instead of the generic `--filter` expression:
+
+| Flag | Description |
+|------|-------------|
+| `--filter-class "name"` | Run all tests in a given class |
+| `--filter-not-class "name"` | Exclude all tests in a given class |
+| `--filter-method "name"` | Run a specific test method |
+| `--filter-not-method "name"` | Exclude a specific test method |
+| `--filter-namespace "name"` | Run all tests in a namespace |
+| `--filter-not-namespace "name"` | Exclude all tests in a namespace |
+| `--filter-trait "name=value"` | Run tests with a matching trait |
+| `--filter-not-trait "name=value"` | Exclude tests with a matching trait |
+
+Multiple values can be specified with a single flag: `--filter-class Foo Bar`.
+
+```bash
+# .NET SDK 8/9
+dotnet test -- --filter-class "MyNamespace.LoginTests"
+
+# .NET SDK 10+
+dotnet test --filter-class "MyNamespace.LoginTests"
+
+# Combine: namespace + trait
+dotnet test --filter-namespace "MyApp.Tests.Integration" --filter-trait "Category=Smoke"
+```
+
+### xUnit v3 query filter language
+
+For complex expressions, use `--filter-query` with a path-segment syntax:
+
+```text
+/<assemblyFilter>/<namespaceFilter>/<classFilter>/<methodFilter>[traitName=traitValue]
+```
+
+Each segment matches against: assembly name, namespace, class name, method name. Use `*` for "match all" in any segment. Documentation: <https://xunit.net/docs/query-filter-language>
+
+```shell
+# xUnit.net v3 MTP — using query language (assembly/namespace/class/method[trait])
+dotnet test -- --filter-query "/*/*/*IntegrationTests*/*[Category=Smoke]"
+```
+
+## MTP filters — TUnit
+
+TUnit uses `--treenode-filter` with a path-based syntax:
+
+```text
+--treenode-filter "/<Assembly>/<Namespace>/<ClassName>/<TestName>"
+```
+
+Wildcards (`*`) are supported in any segment. Filter operators can be appended to test names for property-based filtering.
+
+| Operator | Meaning |
+|----------|---------|
+| `*` | Wildcard match |
+| `=` | Exact property match (e.g., `[Category=Unit]`) |
+| `!=` | Exclude property value |
+| `&` | AND (combine conditions) |
+| `\|` | OR (within a segment, requires parentheses) |
+
+**Examples (TUnit):**
+
+```bash
+# All tests in a class
+dotnet run --treenode-filter "/*/*/LoginTests/*"
+
+# A specific test
+dotnet run --treenode-filter "/*/*/*/AcceptCookiesTest"
+
+# By namespace prefix (wildcard)
+dotnet run --treenode-filter "/*/MyProject.Tests.Api*/*/*"
+
+# By custom property
+dotnet run --treenode-filter "/*/*/*/*[Category=Smoke]"
+
+# Exclude by property
+dotnet run --treenode-filter "/*/*/*/*[Category!=Slow]"
+
+# OR across classes
+dotnet run --treenode-filter "/*/*/(LoginTests)|(SignupTests)/*"
+
+# Combined: namespace + property
+dotnet run --treenode-filter "/*/MyProject.Tests.Integration/*/*/*[Priority=Critical]"
+```
+
+## VSTest → MTP filter translation (for migration)
+
+**MSTest, NUnit, and xUnit.net v2 (with `YTest.MTP.XUnit2`)**: The VSTest `--filter` syntax is identical on both VSTest and MTP. No changes needed.
+
+**xUnit.net v3 (native MTP)**: xUnit.net v3 does NOT support the VSTest `--filter` syntax on MTP. Translate filters using xUnit.net v3's native options:
+
+| VSTest `--filter` syntax | xUnit.net v3 MTP equivalent | Notes |
+|---|---|---|
+| `FullyQualifiedName~ClassName` | `--filter-class *ClassName*` | Wildcards required for substring match |
+| `FullyQualifiedName=Ns.Class.Method` | `--filter-method Ns.Class.Method` | Exact match on fully qualified method |
+| `Name=MethodName` | `--filter-method *MethodName*` | Wildcards for substring match |
+| `Category=Value` (trait) | `--filter-trait "Category=Value"` | Filter by trait name/value pair |
+| Complex expressions | `--filter-query "expr"` | Uses xUnit.net query filter language (see above) |

package/package/corpus/skills/including-generated-files/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package/corpus/skills/including-generated-files/NOTICE

@@ -0,0 +1,17 @@
+Including Generated Files Into Your Build
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet-msbuild/skills/including-generated-files/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Add marked modification/source comment and applicability/Cratis precedence line.
+- Rewrite the description to the Cratis shape (what it does, Use when, Not for) and drop references to skills that are not part of this corpus.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.

package/package/corpus/skills/including-generated-files/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: including-generated-files
+description: 'Owns MSBuild generated-artifact integration: a target that creates source, Content, None, or another physical file that is missing from compilation or output, target timing, evaluation-time glob misses, IntermediateOutputPath placement, and FileWrites clean tracking. Use when a generated file is missing from the build even if the prompt does not name the producing task. Not for general Include/Remove/Update semantics, item metadata or batching, duplicate declarations, Roslyn source-generator internals, or non-MSBuild systems.'
+license: MIT
+---
+
+<!-- Modified by Cratis from dotnet's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/dotnet/skills (plugins/dotnet-msbuild/skills/including-generated-files/SKILL.md; see NOTICE) -->
+
+# Including Generated Files Into Your Build
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
+
+## Overview
+
+Files generated during the build are generally ignored by the build process. This leads to confusing results such as:
+- Generated files not being included in the output directory
+- Generated source files not being compiled
+- Globs not capturing files created during the build
+
+This happens because of how MSBuild's build phases work.
+
+## Quick Takeaway
+
+For code files generated during the build - we need to add those to `Compile` and `FileWrites` item groups within the target generating the file(s):
+
+```xml
+  <ItemGroup>
+    <Compile Include="$(GeneratedFilePath)" />
+    <FileWrites Include="$(GeneratedFilePath)" />
+  </ItemGroup>
+```
+
+The target generating the file(s) should be hooked before CoreCompile and BeforeCompile targets - `BeforeTargets="CoreCompile;BeforeCompile"`
+
+## Why Generated Files Are Ignored
+
+For detailed explanation, see [How MSBuild Builds Projects](https://docs.microsoft.com/visualstudio/msbuild/build-process-overview).
+
+### Evaluation Phase
+
+MSBuild reads your project, imports everything, creates Properties, expands globs for Items **outside of Targets**, and sets up the build process.
+
+### Execution Phase
+
+MSBuild runs Targets & Tasks with the provided Properties & Items to perform the build.
+
+**Key Takeaway:** Files generated during execution don't exist during evaluation, therefore they aren't found. This particularly affects files that are globbed by default, such as source files (`.cs`).
+
+## Solution: Manually Add Generated Files
+
+When files are generated during the build, manually add them into the build process. The approach depends on the type of file being generated.
+
+### Use `$(IntermediateOutputPath)` for Generated File Location
+
+Always use `$(IntermediateOutputPath)` as the base directory for generated files. **Do not** hardcode `obj\` or construct the intermediary path manually (e.g., `obj\$(Configuration)\$(TargetFramework)\`). The intermediate output path can be redirected to a different location in some build configurations (e.g., shared output directories, CI environments). Using `$(IntermediateOutputPath)` ensures your target works correctly regardless of the actual path.
+
+### Always Add Generated Files to `FileWrites`
+
+Every generated file should be added to the `FileWrites` item group. This ensures that MSBuild's `Clean` target properly removes your generated files. Without this, generated files will accumulate as stale artifacts across builds.
+
+```xml
+<ItemGroup>
+  <FileWrites Include="$(IntermediateOutputPath)my-generated-file.xyz" />
+</ItemGroup>
+```
+
+### Basic Pattern (Non-Code Files)
+
+For generated files that need to be copied to output (config files, data files, etc.), add them to `Content` or `None` items before `BeforeBuild`:
+
+```xml
+<Target Name="IncludeGeneratedFiles" BeforeTargets="BeforeBuild">
+
+  <!-- Your logic that generates files goes here -->
+
+  <ItemGroup>
+    <None Include="$(IntermediateOutputPath)my-generated-file.xyz" CopyToOutputDirectory="PreserveNewest"/>
+
+    <!-- Capture all files of a certain type with a glob -->
+    <None Include="$(IntermediateOutputPath)generated\*.xyz" CopyToOutputDirectory="PreserveNewest"/>
+
+    <!-- Register generated files for proper cleanup -->
+    <FileWrites Include="$(IntermediateOutputPath)my-generated-file.xyz" />
+    <FileWrites Include="$(IntermediateOutputPath)generated\*.xyz" />
+  </ItemGroup>
+</Target>
+```
+
+### For Generated Source Files (Code That Needs Compilation)
+
+If you're generating `.cs` files that need to be compiled, use **`BeforeTargets="CoreCompile;BeforeCompile"`**. This is the correct timing for adding `Compile` items — it runs late enough that the file generation has occurred, but before the compiler runs. Using `BeforeBuild` is too early for some scenarios and may not work reliably with all SDK features.
+
+```xml
+<Target Name="IncludeGeneratedSourceFiles" BeforeTargets="CoreCompile;BeforeCompile">
+  <PropertyGroup>
+    <GeneratedCodeDir>$(IntermediateOutputPath)Generated\</GeneratedCodeDir>
+    <GeneratedFilePath>$(GeneratedCodeDir)MyGeneratedFile.cs</GeneratedFilePath>
+  </PropertyGroup>
+
+  <MakeDir Directories="$(GeneratedCodeDir)" />
+
+  <!-- Your logic that generates the .cs file goes here -->
+
+  <ItemGroup>
+    <Compile Include="$(GeneratedFilePath)" />
+    <FileWrites Include="$(GeneratedFilePath)" />
+  </ItemGroup>
+</Target>
+```
+
+Note: Specifying both `CoreCompile` and `BeforeCompile` ensures the target runs before whichever target comes first, providing robust ordering regardless of customizations in the build.
+
+## Target Timing
+
+Choose the `BeforeTargets` value based on the type of file being generated:
+
+- **`BeforeTargets="BeforeBuild"`** — For non-code files added to `None` or `Content`. Runs early enough for copy-to-output scenarios.
+- **`BeforeTargets="CoreCompile;BeforeCompile"`** — For generated source files added to `Compile`. Ensures the file is included before the compiler runs.
+- **`BeforeTargets="AssignTargetPaths"`** — The "final stop" before `None` and `Content` items (among others) are transformed into new items. Use as a fallback if `BeforeBuild` is too early.
+
+## Globbing Behavior
+
+Globs behave according to **when** the glob took place:
+
+| Glob Location | Files Captured |
+|---------------|----------------|
+| Outside of a target | Only files visible during Evaluation phase (before build starts) |
+| Inside of a target | Files visible when the target runs (can capture generated files if timed correctly) |
+
+This is why the solution places the `<ItemGroup>` inside a `<Target>` - the glob runs during execution when the generated files exist.
+
+## Relevant Links
+
+- [How MSBuild Builds Projects](https://docs.microsoft.com/visualstudio/msbuild/build-process-overview)
+- [Evaluation Phase](https://docs.microsoft.com/visualstudio/msbuild/build-process-overview#evaluation-phase)
+- [Execution Phase](https://docs.microsoft.com/visualstudio/msbuild/build-process-overview#execution-phase)
+- [Common Item Types](https://docs.microsoft.com/visualstudio/msbuild/common-msbuild-project-items)
+- [How the SDK imports items by default](https://github.com/dotnet/sdk/blob/main/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.Sdk.DefaultItems.props)
+- [Official docs: Handle generated files](https://learn.microsoft.com/visualstudio/msbuild/customize-your-build#handle-generated-files)