@cratis/pi 7.101.0 → 7.103.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/package/corpus/harnesses/copilot/instructions/github-actions.instructions.md +17 -0
  2. package/package/corpus/harnesses/copilot/instructions/profiles.instructions.md +10 -1
  3. package/package/corpus/harnesses/copilot/instructions/pull-requests.instructions.md +2 -0
  4. package/package/corpus/harnesses/copilot/instructions/secrets.instructions.md +4 -0
  5. package/package/corpus/hooks/README.md +11 -1
  6. package/package/corpus/hooks/scripts/cratis-check-pr.mjs +12 -1
  7. package/package/corpus/hooks/scripts/cratis-guard-secrets.sh +79 -23
  8. package/package/corpus/hooks/scripts/cratis-guard-writes.sh +145 -40
  9. package/package/corpus/rules/github-actions.md +17 -0
  10. package/package/corpus/rules/profiles.md +10 -1
  11. package/package/corpus/rules/pull-requests.md +2 -0
  12. package/package/corpus/rules/secrets.md +4 -0
  13. package/package/corpus/skills/analyzing-dotnet-performance/LICENSE +23 -0
  14. package/package/corpus/skills/analyzing-dotnet-performance/NOTICE +36 -0
  15. package/package/corpus/skills/analyzing-dotnet-performance/SKILL.md +214 -0
  16. package/package/corpus/skills/analyzing-dotnet-performance/references/async-patterns.md +122 -0
  17. package/package/corpus/skills/analyzing-dotnet-performance/references/collections-and-linq.md +220 -0
  18. package/package/corpus/skills/analyzing-dotnet-performance/references/critical-patterns.md +291 -0
  19. package/package/corpus/skills/analyzing-dotnet-performance/references/io-and-serialization.md +135 -0
  20. package/package/corpus/skills/analyzing-dotnet-performance/references/memory-and-strings.md +219 -0
  21. package/package/corpus/skills/analyzing-dotnet-performance/references/regex-patterns.md +95 -0
  22. package/package/corpus/skills/analyzing-dotnet-performance/references/structural-patterns.md +38 -0
  23. package/package/corpus/skills/binlog-generation/LICENSE +23 -0
  24. package/package/corpus/skills/binlog-generation/NOTICE +22 -0
  25. package/package/corpus/skills/binlog-generation/SKILL.md +129 -0
  26. package/package/corpus/skills/check-bin-obj-clash/LICENSE +23 -0
  27. package/package/corpus/skills/check-bin-obj-clash/NOTICE +27 -0
  28. package/package/corpus/skills/check-bin-obj-clash/SKILL.md +127 -0
  29. package/package/corpus/skills/check-bin-obj-clash/references/common-causes-and-fixes.md +206 -0
  30. package/package/corpus/skills/coverage-analysis/LICENSE +23 -0
  31. package/package/corpus/skills/coverage-analysis/NOTICE +32 -0
  32. package/package/corpus/skills/coverage-analysis/SKILL.md +198 -0
  33. package/package/corpus/skills/coverage-analysis/references/guidelines.md +68 -0
  34. package/package/corpus/skills/coverage-analysis/references/output-format.md +91 -0
  35. package/package/corpus/skills/coverage-analysis/references/report-generation.md +58 -0
  36. package/package/corpus/skills/coverage-analysis/references/setup-discovery.md +307 -0
  37. package/package/corpus/skills/coverage-analysis/scripts/Compute-CrapScores.ps1 +80 -0
  38. package/package/corpus/skills/coverage-analysis/scripts/CoverageData.ps1 +272 -0
  39. package/package/corpus/skills/coverage-analysis/scripts/Extract-MethodCoverage.ps1 +65 -0
  40. package/package/corpus/skills/cratis-ci-pipeline-performance/LICENSE +2 -0
  41. package/package/corpus/skills/cratis-ci-pipeline-performance/SKILL.md +201 -0
  42. package/package/corpus/skills/cratis-ci-pipeline-performance/references/build-once-and-shard.md +158 -0
  43. package/package/corpus/skills/cratis-ci-pipeline-performance/references/caching.md +86 -0
  44. package/package/corpus/skills/cratis-ci-pipeline-performance/references/flaky-and-hung-jobs.md +70 -0
  45. package/package/corpus/skills/cratis-ci-pipeline-performance/references/publish-pipelines.md +67 -0
  46. package/package/corpus/skills/cratis-ci-pipeline-performance/references/required-checks-and-path-filters.md +117 -0
  47. package/package/corpus/skills/cratis-ci-pipeline-performance/references/runner-sizing-and-images.md +65 -0
  48. package/package/corpus/skills/cratis-ci-pipeline-performance/references/security-and-pinning.md +73 -0
  49. package/package/corpus/skills/cratis-ci-pipeline-performance/references/sources.md +33 -0
  50. package/package/corpus/skills/cratis-ci-pipeline-performance/references/test-setup-cost.md +82 -0
  51. package/package/corpus/skills/cratis-ci-pipeline-performance/scripts/ci-timings.sh +356 -0
  52. package/package/corpus/skills/cratis-ci-pipeline-performance/scripts/fixtures/jobs/1003.json +79 -0
  53. package/package/corpus/skills/cratis-ci-pipeline-performance/scripts/fixtures/jobs/1007.json +79 -0
  54. package/package/corpus/skills/cratis-ci-pipeline-performance/scripts/fixtures/jobs/1010.json +79 -0
  55. package/package/corpus/skills/cratis-ci-pipeline-performance/scripts/fixtures/runs.json +102 -0
  56. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/LICENSE +2 -0
  57. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/SKILL.md +244 -0
  58. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/docker-images.md +86 -0
  59. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/dotnet-nuget.md +87 -0
  60. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/go-jvm-python-elixir.md +83 -0
  61. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/npm-yarn.md +78 -0
  62. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/other-environments.md +60 -0
  63. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/worked-examples.md +97 -0
  64. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/scripts/cratis-local-packages.sh +778 -0
  65. package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/scripts/npm-restore-check.cjs +109 -0
  66. package/package/corpus/skills/csharp-refactoring/LICENSE +23 -0
  67. package/package/corpus/skills/csharp-refactoring/NOTICE +22 -0
  68. package/package/corpus/skills/csharp-refactoring/SKILL.md +175 -0
  69. package/package/corpus/skills/csharp-refactoring/references/operation-catalog.md +37 -0
  70. package/package/corpus/skills/directory-build-organization/LICENSE +23 -0
  71. package/package/corpus/skills/directory-build-organization/NOTICE +21 -0
  72. package/package/corpus/skills/directory-build-organization/SKILL.md +205 -0
  73. package/package/corpus/skills/directory-build-organization/references/common-patterns.md +56 -0
  74. package/package/corpus/skills/directory-build-organization/references/multi-level-examples.md +167 -0
  75. package/package/corpus/skills/directory-build-organization/references/targetframework-props-pitfall.md +54 -0
  76. package/package/corpus/skills/dotnet-aot-compat/LICENSE +23 -0
  77. package/package/corpus/skills/dotnet-aot-compat/NOTICE +18 -0
  78. package/package/corpus/skills/dotnet-aot-compat/SKILL.md +265 -0
  79. package/package/corpus/skills/dotnet-aot-compat/references/polyfills.md +43 -0
  80. package/package/corpus/skills/dotnet-trace-collect/LICENSE +23 -0
  81. package/package/corpus/skills/dotnet-trace-collect/NOTICE +65 -0
  82. package/package/corpus/skills/dotnet-trace-collect/SKILL.md +116 -0
  83. package/package/corpus/skills/dotnet-trace-collect/references/dotnet-monitor.md +97 -0
  84. package/package/corpus/skills/dotnet-trace-collect/references/dotnet-trace-collect-linux.md +84 -0
  85. package/package/corpus/skills/dotnet-trace-collect/references/dotnet-trace-collect.md +91 -0
  86. package/package/corpus/skills/dotnet-trace-collect/references/perfcollect.md +200 -0
  87. package/package/corpus/skills/dotnet-trace-collect/references/perfview.md +141 -0
  88. package/package/corpus/skills/dotnet-trace-collect/references/tool-selection.md +160 -0
  89. package/package/corpus/skills/dump-collect/LICENSE +23 -0
  90. package/package/corpus/skills/dump-collect/NOTICE +40 -0
  91. package/package/corpus/skills/dump-collect/SKILL.md +97 -0
  92. package/package/corpus/skills/dump-collect/references/container-dumps.md +412 -0
  93. package/package/corpus/skills/dump-collect/references/coreclr-dumps.md +108 -0
  94. package/package/corpus/skills/dump-collect/references/nativeaot-dumps.md +280 -0
  95. package/package/corpus/skills/eliminate-redundant-restores/LICENSE +23 -0
  96. package/package/corpus/skills/eliminate-redundant-restores/NOTICE +19 -0
  97. package/package/corpus/skills/eliminate-redundant-restores/SKILL.md +112 -0
  98. package/package/corpus/skills/extension-points/LICENSE +23 -0
  99. package/package/corpus/skills/extension-points/NOTICE +18 -0
  100. package/package/corpus/skills/extension-points/SKILL.md +248 -0
  101. package/package/corpus/skills/filter-syntax/LICENSE +23 -0
  102. package/package/corpus/skills/filter-syntax/NOTICE +17 -0
  103. package/package/corpus/skills/filter-syntax/SKILL.md +179 -0
  104. package/package/corpus/skills/including-generated-files/LICENSE +23 -0
  105. package/package/corpus/skills/including-generated-files/NOTICE +17 -0
  106. package/package/corpus/skills/including-generated-files/SKILL.md +139 -0
  107. package/package/corpus/skills/microbenchmarking/LICENSE +23 -0
  108. package/package/corpus/skills/microbenchmarking/NOTICE +36 -0
  109. package/package/corpus/skills/microbenchmarking/SKILL.md +131 -0
  110. package/package/corpus/skills/microbenchmarking/references/bdn-internals-and-tuning.md +143 -0
  111. package/package/corpus/skills/microbenchmarking/references/comparison-strategies.md +200 -0
  112. package/package/corpus/skills/microbenchmarking/references/diagnosers-and-exporters.md +150 -0
  113. package/package/corpus/skills/microbenchmarking/references/project-setup-and-running.md +189 -0
  114. package/package/corpus/skills/microbenchmarking/references/writing-benchmarks.md +310 -0
  115. package/package/corpus/skills/msbuild/LICENSE +23 -0
  116. package/package/corpus/skills/msbuild/NOTICE +55 -0
  117. package/package/corpus/skills/msbuild/SKILL.md +117 -0
  118. package/package/corpus/skills/msbuild/references/antipatterns/additional-antipatterns.md +291 -0
  119. package/package/corpus/skills/msbuild/references/antipatterns/incremental-build-inputs-outputs.md +57 -0
  120. package/package/corpus/skills/msbuild/references/antipatterns/private-assets.md +29 -0
  121. package/package/corpus/skills/msbuild/references/binlog-failure-analysis.md +85 -0
  122. package/package/corpus/skills/msbuild/references/binlog-generation.md +69 -0
  123. package/package/corpus/skills/msbuild/references/build-perf-baseline.md +493 -0
  124. package/package/corpus/skills/msbuild/references/build-perf-diagnostics.md +268 -0
  125. package/package/corpus/skills/msbuild/references/copy-to-output-directory.md +183 -0
  126. package/package/corpus/skills/msbuild/references/eval-performance.md +190 -0
  127. package/package/corpus/skills/msbuild/references/extension-points.md +281 -0
  128. package/package/corpus/skills/msbuild/references/incremental-build.md +365 -0
  129. package/package/corpus/skills/msbuild/references/msbuild-antipatterns.md +401 -0
  130. package/package/corpus/skills/orleans/LICENSE +21 -0
  131. package/package/corpus/skills/orleans/NOTICE +64 -0
  132. package/package/corpus/skills/orleans/SKILL.md +140 -0
  133. package/package/corpus/skills/orleans/references/anti-patterns.md +660 -0
  134. package/package/corpus/skills/orleans/references/configuration-api.md +933 -0
  135. package/package/corpus/skills/orleans/references/examples.md +66 -0
  136. package/package/corpus/skills/orleans/references/grain-api.md +784 -0
  137. package/package/corpus/skills/orleans/references/grains.md +75 -0
  138. package/package/corpus/skills/orleans/references/hosting.md +71 -0
  139. package/package/corpus/skills/orleans/references/implementation.md +591 -0
  140. package/package/corpus/skills/orleans/references/official-docs-index.md +250 -0
  141. package/package/corpus/skills/orleans/references/patterns.md +811 -0
  142. package/package/corpus/skills/orleans/references/persistence-api.md +495 -0
  143. package/package/corpus/skills/orleans/references/primitive-selection.md +35 -0
  144. package/package/corpus/skills/orleans/references/scheduling-and-services.md +295 -0
  145. package/package/corpus/skills/orleans/references/serialization-api.md +299 -0
  146. package/package/corpus/skills/orleans/references/streaming-api.md +396 -0
  147. package/package/corpus/skills/orleans/references/testing-patterns.md +210 -0
  148. package/package/corpus/skills/platform-detection/LICENSE +23 -0
  149. package/package/corpus/skills/platform-detection/NOTICE +17 -0
  150. package/package/corpus/skills/platform-detection/SKILL.md +230 -0
  151. package/package/corpus/skills/platform-detection/references/command-mode.md +27 -0
  152. package/package/corpus/skills/profiling/LICENSE +21 -0
  153. package/package/corpus/skills/profiling/NOTICE +50 -0
  154. package/package/corpus/skills/profiling/SKILL.md +144 -0
  155. package/package/corpus/skills/profiling/references/commands.md +439 -0
  156. package/package/corpus/skills/profiling/references/patterns.md +586 -0
  157. package/package/corpus/skills/profiling/references/profiling.md +190 -0
  158. package/package/corpus/skills/run-tests/LICENSE +23 -0
  159. package/package/corpus/skills/run-tests/NOTICE +19 -0
  160. package/package/corpus/skills/run-tests/SKILL.md +305 -0
  161. package/package/corpus/skills/target-authoring/LICENSE +23 -0
  162. package/package/corpus/skills/target-authoring/NOTICE +17 -0
  163. package/package/corpus/skills/target-authoring/SKILL.md +165 -0
  164. package/package/corpus/skills/vectorization/LICENSE +23 -0
  165. package/package/corpus/skills/vectorization/NOTICE +17 -0
  166. package/package/corpus/skills/vectorization/SKILL.md +189 -0
  167. package/package/profile-catalog.json +87 -1
  168. package/package.json +3 -2
@@ -0,0 +1,165 @@
1
+ ---
2
+ name: target-authoring
3
+ description: 'Canonical patterns for writing custom MSBuild targets: DependsOnTargets versus BeforeTargets and AfterTargets, the Build-to-CoreBuild three-level pattern, and the XxxDependsOn chain-extension pattern. Use when diagnosing or fixing custom-target anti-patterns: Directory.Build.targets redefining SDK targets, targets that replace CompileDependsOn instead of extending it, Outputs versus Returns misuse that returns stale results, missing Inputs/Outputs causing needless rebuilds, or missing FileWrites registration. Not for incremental build tuning or general anti-pattern review (use the msbuild skill), or non-MSBuild build systems.'
4
+ license: MIT
5
+ ---
6
+
7
+ <!-- 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/target-authoring/SKILL.md; see NOTICE) -->
8
+
9
+ # Custom Target Authoring Patterns
10
+
11
+ Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
12
+
13
+ Canonical patterns from `Microsoft.Common.CurrentVersion.targets` in the MSBuild repository.
14
+
15
+ ## The Three-Level Target Chain
16
+
17
+ Every major entry point (Build, Rebuild, Clean) delegates to a **property** listing its dependencies, which chains through Before → Core → After:
18
+
19
+ ```xml
20
+ <PropertyGroup>
21
+ <BuildDependsOn>
22
+ BeforeBuild;
23
+ CoreBuild;
24
+ AfterBuild
25
+ </BuildDependsOn>
26
+ </PropertyGroup>
27
+
28
+ <Target Name="Build"
29
+ Condition=" '$(_InvalidConfigurationWarning)' != 'true' "
30
+ DependsOnTargets="$(BuildDependsOn)"
31
+ Returns="@(TargetPathWithTargetPlatformMoniker)" />
32
+
33
+ <!-- Empty extensibility targets — users override these -->
34
+ <Target Name="BeforeBuild" />
35
+ <Target Name="AfterBuild" />
36
+ ```
37
+
38
+ `CoreBuild` delegates to `$(CoreBuildDependsOn)` and includes error handlers:
39
+
40
+ ```xml
41
+ <Target Name="CoreBuild" DependsOnTargets="$(CoreBuildDependsOn)">
42
+ <OnError ExecuteTargets="_TimeStampAfterCompile;PostBuildEvent"
43
+ Condition="'$(RunPostBuildEvent)' == 'Always'" />
44
+ <OnError ExecuteTargets="_CleanRecordFileWrites" />
45
+ </Target>
46
+ ```
47
+
48
+ ### Rules
49
+
50
+ - Delegate to a property (`DependsOnTargets="$(MyTargetDependsOn)"`), not hardcoded targets.
51
+ - `OnError` goes inside the orchestrating target to ensure cleanup runs even on failure.
52
+ - Empty Before/After targets are extensibility points. Users override them; SDKs never put logic in them.
53
+
54
+ ## Chain Extension — Append, Never Overwrite
55
+
56
+ When adding a custom target to an existing chain, **append** to the `DependsOn` property:
57
+
58
+ ```xml
59
+ <!-- GOOD: Append to existing chain -->
60
+ <PropertyGroup>
61
+ <CompileDependsOn>$(CompileDependsOn);MyCodeGenTarget</CompileDependsOn>
62
+ </PropertyGroup>
63
+
64
+ <!-- BAD: Overwrites the entire chain, dropping SDK targets -->
65
+ <PropertyGroup>
66
+ <CompileDependsOn>MyCodeGenTarget</CompileDependsOn>
67
+ </PropertyGroup>
68
+ ```
69
+
70
+ ## DependsOnTargets vs BeforeTargets vs AfterTargets
71
+
72
+ | Mechanism | Defined in | Best for |
73
+ |---|---|---|
74
+ | `DependsOnTargets` | The target that needs deps | Target explicitly requires others |
75
+ | `BeforeTargets` | The injecting target | Insert before a target you don't own |
76
+ | `AfterTargets` | The injecting target | Insert after a target you don't own |
77
+
78
+ Validation targets use `BeforeTargets` to intercept all entry points:
79
+
80
+ ```xml
81
+ <Target Name="_CheckForInvalidConfigurationAndPlatform"
82
+ BeforeTargets="$(BuildDependsOn);Build;$(RebuildDependsOn);Rebuild;$(CleanDependsOn);Clean">
83
+ </Target>
84
+ ```
85
+
86
+ **Rules:**
87
+
88
+ - Use `DependsOnTargets` when your target needs specific prerequisites.
89
+ - Use `BeforeTargets`/`AfterTargets` when injecting into a pipeline you don't own.
90
+ - Prefer `BeforeTargets="CoreCompile"` over modifying `$(CompileDependsOn)` when you don't control the targets file.
91
+
92
+ ## Returns vs Outputs
93
+
94
+ ```xml
95
+ <!-- Build returns items for consumption by referencing projects -->
96
+ <Target Name="Build"
97
+ DependsOnTargets="$(BuildDependsOn)"
98
+ Returns="@(TargetPathWithTargetPlatformMoniker)" />
99
+
100
+ <!-- GetTargetPath is a lightweight query target -->
101
+ <Target Name="GetTargetPath" Returns="@(TargetPathWithTargetPlatformMoniker)" />
102
+ ```
103
+
104
+ - **`Returns`** specifies what the MSBuild task receives when calling this project. Use for inter-project communication.
105
+ - **`Outputs`** on inner targets is for incrementality (timestamp checks). Use for up-to-date detection.
106
+ - Never mix the two purposes. Query targets (`GetTargetPath`, `GetTargetFrameworks`) should use `Returns`, not `Outputs`.
107
+
108
+ ## Target Naming Conventions
109
+
110
+ | Pattern | Meaning | Example |
111
+ |---|---|---|
112
+ | `_PrefixedName` | Internal/private target | `_TimeStampBeforeCompile` |
113
+ | `CoreXxx` | The actual implementation | `CoreBuild`, `CoreCompile` |
114
+ | `BeforeXxx` / `AfterXxx` | Empty extensibility hooks | `BeforeBuild`, `AfterCompile` |
115
+ | `PrepareXxx` | Setup/validation phase | `PrepareForBuild` |
116
+ | `ResolveXxx` | Discovery/resolution phase | `ResolveReferences` |
117
+ | `GetXxx` | Lightweight query (no side effects) | `GetTargetPath` |
118
+
119
+ ## Complete Custom Target Template
120
+
121
+ ```xml
122
+ <!-- 1. Define the DependsOn chain for extensibility -->
123
+ <PropertyGroup>
124
+ <MyFeatureDependsOn>
125
+ _ValidateMyFeatureInputs;
126
+ BeforeMyFeature;
127
+ CoreMyFeature;
128
+ AfterMyFeature
129
+ </MyFeatureDependsOn>
130
+ </PropertyGroup>
131
+
132
+ <!-- 2. Outer target with Returns for inter-project communication -->
133
+ <Target Name="MyFeature"
134
+ DependsOnTargets="$(MyFeatureDependsOn)"
135
+ Returns="@(MyFeatureOutput)" />
136
+
137
+ <!-- 3. Empty extensibility points -->
138
+ <Target Name="BeforeMyFeature" />
139
+ <Target Name="AfterMyFeature" />
140
+
141
+ <!-- 4. Core implementation with Inputs/Outputs for incrementality -->
142
+ <Target Name="CoreMyFeature"
143
+ Inputs="$(MSBuildAllProjects);@(MyFeatureInput)"
144
+ Outputs="$(IntermediateOutputPath)myfeature.generated.cs">
145
+ <Exec Command="my-tool.exe -o $(IntermediateOutputPath)myfeature.generated.cs" />
146
+ <!-- 5. Register outputs for clean tracking -->
147
+ <ItemGroup>
148
+ <Compile Include="$(IntermediateOutputPath)myfeature.generated.cs" />
149
+ <FileWrites Include="$(IntermediateOutputPath)myfeature.generated.cs" />
150
+ </ItemGroup>
151
+ </Target>
152
+
153
+ <!-- 6. Validation target runs first in the dependency chain -->
154
+ <Target Name="_ValidateMyFeatureInputs">
155
+ <Error Text="MyFeatureInput items are required."
156
+ Condition="'@(MyFeatureInput)' == ''" />
157
+ </Target>
158
+ ```
159
+
160
+ ## Common Pitfalls
161
+
162
+ - **Overwriting `DependsOn` properties** drops SDK targets silently. Always include `$(ExistingProperty)` when appending.
163
+ - **Using `Outputs` on query targets** causes MSBuild to skip them when "up to date," returning stale data. Use `Returns`.
164
+ - **Defining targets in `.props`** means `BeforeTargets` on SDK targets have nothing to hook into yet. Move targets to `.targets`.
165
+ - **Forgetting `OnError`** in orchestrating targets means file tracking fails on build errors, breaking subsequent incremental builds.
@@ -0,0 +1,23 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) .NET Foundation and Contributors
4
+
5
+ All rights reserved.
6
+
7
+ Permission is hereby granted, free of charge, to any person obtaining a copy
8
+ of this software and associated documentation files (the "Software"), to deal
9
+ in the Software without restriction, including without limitation the rights
10
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11
+ copies of the Software, and to permit persons to whom the Software is
12
+ furnished to do so, subject to the following conditions:
13
+
14
+ The above copyright notice and this permission notice shall be included in all
15
+ copies or substantial portions of the Software.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23
+ SOFTWARE.
@@ -0,0 +1,17 @@
1
+ .NET SIMD vectorization
2
+ Copyright (c) .NET Foundation and Contributors
3
+ Licensed under the MIT License. See LICENSE.
4
+
5
+ Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet-advanced/skills/vectorization/SKILL.md
6
+
7
+ Changes made by Cratis:
8
+
9
+ LICENSE:
10
+ - Copy upstream MIT license and copyright verbatim.
11
+
12
+ SKILL.md:
13
+ - Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
14
+ - Add marked modification/source comment and applicability/Cratis precedence line.
15
+ - 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.
16
+
17
+ NOTICE: Add this attribution, change list, and any download/execution disclosure.
@@ -0,0 +1,189 @@
1
+ ---
2
+ name: vectorization
3
+ description: 'Designs, implements, optimizes, and reviews SIMD code in .NET: vectorizing scalar loops with TensorPrimitives, Vector64, Vector128, Vector256, Vector512, or hardware intrinsics, and reviewing existing SIMD code, including the generic Vector type, for contract equivalence, tail handling, memory safety, portability, fallbacks, and measured performance. Use when a .NET loop or SIMD routine is being written or reviewed. Not for performance work unrelated to SIMD.'
4
+ license: MIT
5
+ ---
6
+
7
+ <!-- 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-advanced/skills/vectorization/SKILL.md; see NOTICE) -->
8
+
9
+ # .NET SIMD vectorization
10
+
11
+ Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
12
+
13
+ Produce a portable optimization that preserves the scalar contract, remains memory-safe at every
14
+ length, and earns its complexity with measured results. **Read the official
15
+ [SIMD and hardware-intrinsics guidance](https://learn.microsoft.com/dotnet/standard/simd) first**
16
+ and follow its comprehensive implementation templates. In particular, use its self-contained
17
+ per-width dispatch, dedicated small-input handling, loop, and remainder shapes rather than reducing
18
+ them to a chain of width checks. This skill supplies the decision rules and validation checks to
19
+ apply while changing real code.
20
+
21
+ ## Inputs and prerequisites
22
+
23
+ Discover these from the repository before asking the user:
24
+
25
+ | Input | Required | What to establish |
26
+ | --- | --- | --- |
27
+ | Scalar implementation and tests | Yes | Existing contract, representative call sites, and supported overlap |
28
+ | Target frameworks and platforms | Yes | Available SIMD APIs and architectures that must behave consistently |
29
+ | Build and test workflow | Yes | The repository's normal commands and how to launch separate test processes |
30
+ | Representative workload or benchmark | For optimization | Typical input sizes and the baseline to beat |
31
+
32
+ Do not add a package merely because an API exists there. First check the target framework and the
33
+ project's existing dependency/versioning policy.
34
+
35
+ ## Core rules
36
+
37
+ 1. **Use the highest-level API that matches the contract, then stop.** `Span<T>` and `string`
38
+ operations, `TensorPrimitives`, and tensor types already accelerate many operations. LINQ
39
+ reductions such as `Sum`, `Min`, `Max`, and `Average` can also accelerate when the source exposes
40
+ its underlying span. Verify empty-input and floating-point behavior rather than assuming similarly
41
+ named operations are interchangeable. Once an existing API preserves the contract, use it instead
42
+ of continuing into handwritten SIMD. Before writing an explicit loop, name the framework APIs
43
+ considered and why none applies. Fixed-shape `System.Numerics` types remain appropriate for
44
+ graphics and similar domains.
45
+ 2. **Start new explicit SIMD loops with `Vector128<T>`.** It is accelerated across the broadest
46
+ hardware set. Add wider fixed-width paths only when measurements justify them.
47
+ 3. **Keep platforms consistent.** Prefer cross-platform operations on the fixed-width vector types;
48
+ they lower to the appropriate target instructions. For example,
49
+ `(vector & mask) == Vector128<byte>.Zero` becomes `ptest` on x86/x64. Use
50
+ architecture-specific intrinsics only for a measured gap, guard them with `IsSupported`, and
51
+ retain equivalent portable or scalar behavior.
52
+ 4. **Read `IsHardwareAccelerated`, `IsSupported`, and `Count` directly.** The JIT treats them as
53
+ constants, so caching them adds no value and obscures which branches disappear.
54
+ 5. **Prefer operators where they are clear.** Parenthesize expressions that mix bitwise and
55
+ comparison operators so precedence is explicit.
56
+
57
+ If the task is review-only, do not rewrite the code. Report correctness and memory-safety defects
58
+ before performance opportunities.
59
+
60
+ ## Authoring checklist
61
+
62
+ - **Contract:** identify behavior for empty and short inputs, overlap, overflow, NaN, signed zero,
63
+ ordering, and exceptions before changing the implementation.
64
+ - **Framework gate:** inspect the target framework and existing package references, then compile or
65
+ probe the highest-level candidate API with the required edge cases. A small contract adapter, such
66
+ as preserving special empty-input behavior, does not justify reimplementing the operation. If the
67
+ API preserves the contract, use it and stop; do not claim it is unavailable without checking.
68
+ - **Structure:** for new explicit SIMD, implement `Vector128<T>` and scalar first. Only after
69
+ measurements justify wider paths, check `Vector512<T>`, then `Vector256<T>`, optional `Vector<T>`,
70
+ `Vector128<T>`, and finally scalar. Omit paths the implementation does not need. Each outer
71
+ fixed-width guard checks only its `IsHardwareAccelerated` property and, for generic element types,
72
+ `IsSupported`. Inside that block, run the width-specific helper when the input has at least
73
+ `Count` elements; otherwise run a dedicated small-input helper, then return. Do not put the length
74
+ check in the outer guard and fall through to repeat dispatch at narrower widths. Keeping each
75
+ supported-width block self-contained lets the JIT remove unsupported blocks and avoids redundant
76
+ work on common small inputs.
77
+ - **Loads and stores:** prefer span-based `Vector128.Create(span)` and `CopyTo`; the JIT keeps them
78
+ efficient and they require no pinning or reference arithmetic. Unsafe loads and stores are largely
79
+ unnecessary. When a path genuinely must walk a buffer by managed reference, use the element-offset
80
+ `LoadUnsafe(ref T, nuint)` and `StoreUnsafe` overloads rather than pointers or manually advanced
81
+ references.
82
+ - **Empty inputs:** in a reference-based path, obtain the starting reference with
83
+ `MemoryMarshal.GetReference(span)` or `MemoryMarshal.GetArrayDataReference(array)`, not by indexing
84
+ element `0`.
85
+ - **Unsupported element types:** the fixed-width vectors support primitive numeric element types,
86
+ not `char` or `bool`. Reinterpret with `MemoryMarshal.Cast` or `As<TFrom, TTo>`; reinterpretation
87
+ changes only the type, not the bits. Keep Boolean data as `0` or `1` and characters as valid
88
+ UTF-16, normalizing results before storing when necessary.
89
+ - **Offsets:** prove the input contains a full vector before subtracting `Count` or converting an
90
+ index to `nuint`; otherwise a negative value becomes a huge unsigned offset.
91
+ - **Managed references:** do not form references before the start or past the end of a span,
92
+ including a one-past-end reference. The runtime permits a non-dereferenced managed pointer exactly
93
+ one past an object or array, but this guidance intentionally prohibits the pattern because it is
94
+ fragile and easy to misuse. Keep the base reference in range and express traversal with an element
95
+ offset.
96
+ - **Remainders:** cover every length, including `0`, `Count - 1`, `Count`, `Count + 1`, and
97
+ nonmultiples of each width. Once the input contains a full vector, keep the tail vectorized by
98
+ reprocessing the last full vector. An idempotent operation can fold that overlap in directly. A
99
+ non-idempotent operation must use `ConditionalSelect` to replace repeated lanes with the
100
+ operation's identity before folding them in. This is the JIT-recognized general pattern; it can
101
+ reduce a zero-identity selection to a bitwise mask while retaining broader optimization
102
+ opportunities. For in-place transforms, preserve the original tail values before overlapping
103
+ stores and write only valid results.
104
+ - **Buffer overlap:** choose a traversal direction or staging strategy that prevents stores from
105
+ corrupting values not yet loaded.
106
+ - **Numeric behavior:** account for floating-point reassociation, NaN and signed-zero semantics,
107
+ checked or unchecked integer overflow, and endianness where the algorithm depends on byte order.
108
+ `Native` and `Estimate` operations can intentionally relax precision or IEEE edge-case behavior;
109
+ use them only when the contract permits it and measurements justify them.
110
+
111
+ The official guidance contains the complete dispatch, small-input, unrolling, and remainder
112
+ templates; use those for the full implementation. The following excerpt illustrates only the inner
113
+ safe `Vector128<T>` loop for an in-place elementwise transform, after its self-contained dispatch
114
+ block has established at least one full vector. `Transform` represents the operation being
115
+ implemented:
116
+
117
+ ```csharp
118
+ Span<int> tail = data.Slice(data.Length - Vector128<int>.Count);
119
+ Vector128<int> end = Vector128.Create<int>(tail);
120
+ Span<int> remaining = data;
121
+
122
+ while (remaining.Length >= Vector128<int>.Count)
123
+ {
124
+ Vector128<int> values = Vector128.Create<int>(remaining);
125
+ Transform(values).CopyTo(remaining);
126
+ remaining = remaining.Slice(Vector128<int>.Count);
127
+ }
128
+
129
+ if (!remaining.IsEmpty)
130
+ {
131
+ Transform(end).CopyTo(tail);
132
+ }
133
+ ```
134
+
135
+ The early `end` load preserves original values before overlapping stores. For a read-only reduction,
136
+ load the same final span after the main loop and use `ConditionalSelect` to replace already-processed
137
+ lanes with the operation's identity. Do not substitute `LoadUnsafe`/`StoreUnsafe` or a scalar
138
+ epilogue merely to avoid span bounds checks.
139
+
140
+ ## Testing checklist
141
+
142
+ - Compare the optimized implementation with the scalar contract across boundary lengths,
143
+ randomized values, empty inputs, supported overlap, and numeric edge cases. Cover every
144
+ implemented width and the scalar path with inputs both large enough and too small to benefit.
145
+ - Exercise every implemented width and the scalar fallback in separate processes. On x86/x64
146
+ CoreCLR, `DOTNET_EnableAVX2=0` disables AVX2 and `DOTNET_EnableHWIntrinsic=0` disables hardware
147
+ intrinsics. Use the repository's normal test command and do not change these process-wide
148
+ settings inside a unit test. These settings do not change code already compiled as ReadyToRun or
149
+ ahead of time, so confirm the target code is JIT-compiled when using them to force a path.
150
+ - For unsafe loads and stores, use guard-page or equivalent boundary tests when available. Put the
151
+ inaccessible page after the buffer for forward iteration and before it for backwards iteration,
152
+ and include nonmultiple lengths. An ordinary array allocation does not reliably expose an
153
+ out-of-bounds read.
154
+
155
+ ## Benchmarking
156
+
157
+ Use BenchmarkDotNet to measure representative small and large inputs before keeping the added
158
+ complexity. Compare scalar, `Vector128<T>`, and each wider implemented path in the same run. Small
159
+ inputs can be slower because setup dominates, and speedups are rarely the theoretical vector-width
160
+ multiple because memory throughput, alignment, and latency still apply. Report throughput or time
161
+ with noise context and, when relevant, generated code size or instruction counts. Control allocation
162
+ alignment for stable measurements or randomize it to observe the distribution. A wider vector is
163
+ not automatically faster.
164
+
165
+ If the project cannot target the required framework, run the relevant architecture, or execute the
166
+ fallback configuration, state exactly which path remains unverified. Do not claim success from a
167
+ default-hardware test alone.
168
+
169
+ ## Completion contract
170
+
171
+ - **Authoring:** leave the scalar contract covered by tests; identify the framework or SIMD layer
172
+ selected; report measurements for the representative workload; name any architecture or fallback
173
+ path that could not be exercised.
174
+ - **Review:** report only concrete findings, ordered by correctness, memory safety, portability,
175
+ tests, then performance evidence. If none remain, say so directly.
176
+ - Do not call an optimization complete when it only builds, only passes on the current machine, or
177
+ has no comparison against the scalar baseline.
178
+
179
+ ## Review checklist
180
+
181
+ Review in this order:
182
+
183
+ 1. Scalar-contract equivalence, including signed zero, NaN, overflow, and relevant endianness
184
+ 2. Reuse of an existing accelerated framework API
185
+ 3. Tail correctness for idempotent versus non-idempotent work
186
+ 4. Memory safety, unsigned offset arithmetic, empty inputs, and overlapping buffers
187
+ 5. Portable dispatch and behaviorally equivalent fallbacks
188
+ 6. Tests that force each width and the scalar path
189
+ 7. Benchmarks that justify explicit SIMD and additional widths
@@ -990,11 +990,13 @@
990
990
  {
991
991
  "id": "cratis/engineering/core",
992
992
  "availableTargets": [
993
+ "cratis-ci-pipeline-performance",
993
994
  "cratis-documentation-writing",
994
995
  "cratis-engineering-consolidation-guard",
995
996
  "cratis-engineering-decision-record",
996
997
  "cratis-engineering-docs-authoring",
997
998
  "cratis-engineering-effect-boundaries",
999
+ "cratis-engineering-local-cross-repo-verification",
998
1000
  "cratis-engineering-regression-cluster",
999
1001
  "cratis-release-notes",
1000
1002
  "cratis-technical-examples"
@@ -1006,7 +1008,8 @@
1006
1008
  {
1007
1009
  "id": "cratis/engineering/csharp",
1008
1010
  "composes": [
1009
- "cratis/engineering/core"
1011
+ "cratis/engineering/core",
1012
+ "cratis/engineering/dotnet"
1010
1013
  ],
1011
1014
  "availableTargets": [
1012
1015
  "cratis-engineering-csharp-conventions",
@@ -1016,6 +1019,89 @@
1016
1019
  "csharp"
1017
1020
  ]
1018
1021
  },
1022
+ {
1023
+ "id": "cratis/engineering/dotnet",
1024
+ "composes": [
1025
+ "cratis/engineering/dotnet/performance",
1026
+ "cratis/engineering/dotnet/diagnostics",
1027
+ "cratis/engineering/dotnet/msbuild",
1028
+ "cratis/engineering/dotnet/orleans",
1029
+ "cratis/engineering/dotnet/testing",
1030
+ "cratis/engineering/dotnet/refactoring"
1031
+ ],
1032
+ "languages": [
1033
+ "csharp"
1034
+ ]
1035
+ },
1036
+ {
1037
+ "id": "cratis/engineering/dotnet/performance",
1038
+ "availableTargets": [
1039
+ "microbenchmarking",
1040
+ "analyzing-dotnet-performance",
1041
+ "vectorization",
1042
+ "profiling"
1043
+ ],
1044
+ "languages": [
1045
+ "csharp"
1046
+ ]
1047
+ },
1048
+ {
1049
+ "id": "cratis/engineering/dotnet/diagnostics",
1050
+ "availableTargets": [
1051
+ "dotnet-trace-collect",
1052
+ "dump-collect"
1053
+ ],
1054
+ "languages": [
1055
+ "csharp"
1056
+ ]
1057
+ },
1058
+ {
1059
+ "id": "cratis/engineering/dotnet/msbuild",
1060
+ "availableTargets": [
1061
+ "msbuild",
1062
+ "directory-build-organization",
1063
+ "eliminate-redundant-restores",
1064
+ "check-bin-obj-clash",
1065
+ "including-generated-files",
1066
+ "target-authoring",
1067
+ "extension-points",
1068
+ "binlog-generation"
1069
+ ],
1070
+ "languages": [
1071
+ "csharp"
1072
+ ]
1073
+ },
1074
+ {
1075
+ "id": "cratis/engineering/dotnet/orleans",
1076
+ "availableTargets": [
1077
+ "orleans"
1078
+ ],
1079
+ "languages": [
1080
+ "csharp"
1081
+ ]
1082
+ },
1083
+ {
1084
+ "id": "cratis/engineering/dotnet/testing",
1085
+ "availableTargets": [
1086
+ "platform-detection",
1087
+ "run-tests",
1088
+ "filter-syntax",
1089
+ "coverage-analysis"
1090
+ ],
1091
+ "languages": [
1092
+ "csharp"
1093
+ ]
1094
+ },
1095
+ {
1096
+ "id": "cratis/engineering/dotnet/refactoring",
1097
+ "availableTargets": [
1098
+ "csharp-refactoring",
1099
+ "dotnet-aot-compat"
1100
+ ],
1101
+ "languages": [
1102
+ "csharp"
1103
+ ]
1104
+ },
1019
1105
  {
1020
1106
  "id": "cratis/engineering/elixir",
1021
1107
  "composes": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cratis/pi",
3
- "version": "7.101.0",
3
+ "version": "7.103.0",
4
4
  "description": "Configuration-aware Cratis AI integration for Pi",
5
5
  "type": "module",
6
6
  "files": [
@@ -20,7 +20,8 @@
20
20
  "ai",
21
21
  "skills"
22
22
  ],
23
- "homepage": "https://github.com/Cratis/AI",
23
+ "homepage": "https://www.cratis.io/ai/",
24
+ "author": "Cratis",
24
25
  "repository": {
25
26
  "type": "git",
26
27
  "url": "https://github.com/Cratis/AI",