Init release

.agents/agents/other-package-agent.md

@@ -0,0 +1 @@
+# Other package agent

.agents/agents/release-prep.md

@@ -0,0 +1,42 @@
+# release-prep (generic agent spec)
+
+## Goal
+
+Prepare a safe prerelease-ready update with minimal churn and clear validation.
+
+## Workflow
+
+1. Read current version from `package.json` and inspect pending `.changeset/*.md` files.
+2. Ensure release notes describe user-visible changes succinctly.
+3. Run repository validation commands:
+   - `just lint-check`
+   - `just build`
+   - `just test`
+4. If tests fail due to filtering invocation, use MTP-compatible `--treenode-filter` semantics.
+5. Summarize changed files, validation output, and any follow-up actions.
+
+## Constraints
+
+- Keep edits narrowly scoped to release prep.
+- Do not rewrite unrelated docs/code.
+- Follow existing conventional-commit and changesets conventions in this repository.
+
+## Available skills in this repository
+
+When relevant, explicitly use the matching skill guidance:
+
+- `changesets-prerelease` — prerelease bump and changeset/changelog quality.
+- `dotnet-tunit` — TUnit test-authoring conventions and assertion style.
+- `tunit-test-runner` — deep TUnit/MTP execution and troubleshooting guidance.
+- `tunit-filtering` — concise `--treenode-filter` syntax and examples for this repo.
+- `git-conventional-commits` — commit hygiene and commit message conventions.
+- `lefthook-integration` — local Git hook strategy and setup guidance.
+
+Paths:
+
+- `../skills/changesets-prerelease/SKILL.md`
+- `../skills/dotnet-tunit/SKILL.md`
+- `../skills/tunit-test-runner/SKILL.md`
+- `../skills/tunit-filtering/SKILL.md`
+- `../skills/git-conventional-commits/SKILL.md`
+- `../skills/lefthook-integration/SKILL.md`

.agents/agents/sdk-consumer-setup.md

@@ -0,0 +1,34 @@
+# sdk-consumer-setup (generic agent spec)
+
+## Goal
+
+Help a consuming repository adopt or troubleshoot `Purview.DotNetProjectSdk` correctly, without breaking existing build behaviour.
+
+## Workflow
+
+1. Confirm the SDK is imported in `Directory.Build.props`/`Directory.Build.targets` via
+   `<Import Sdk="Purview.DotNetProjectSdk" Project="Sdk.props" />` and the matching `Sdk.targets` import.
+2. Check pre-import bootstrap properties are set **before** the `Sdk.props` import when they must affect
+   evaluation: `NamespacePrefix`, `UsePackageJsonVersion`, `RootPackageJson`.
+3. If version resolution looks wrong, verify `package.json` discovery: explicit `RootPackageJson`, then CI
+   variables, `.git` root, or a nearby `package.json`. `UsePackageJsonVersion=Strict` fails fast instead of
+   silently skipping resolution.
+4. If the bundled `.agents/**` content isn't appearing in the repo root, check `EnableAgentFolderInPackage`
+   (default `true`) and `AgentPackDestinationFolder` (default `.agents`) — the copy runs before build via
+   `EnsureAgentFolderInPackageTarget`.
+5. For test-framework or project-shape questions, confirm the project follows repo naming and placement
+   conventions the SDK expects, rather than introducing bespoke structure.
+6. Re-run `dotnet build` (or the repo's canonical build command) after each configuration change to confirm
+   the fix.
+
+## Constraints
+
+- Prefer minimal, targeted property changes over broad `Directory.Build.props` rewrites.
+- Do not disable `PurviewAutoSdkPack` or `EnableAgentFolderInPackage` unless the consumer explicitly asks to
+  opt out.
+- Do not duplicate SDK-managed properties in individual project files unless the scenario is intentionally
+  project-specific.
+
+## Related skill
+
+See `../skills/sdk-configuration-reference/SKILL.md` for the full property reference.

.agents/prompts/project-harness-test.md

@@ -0,0 +1,25 @@
+# project-harness-test (generic prompt spec)
+
+Create or update an integration test in `src/tests/DotNetProjectSdk.IntegrationTests/Tests/` using `ProjectHarness`.
+
+## Required behaviour
+
+1. Keep scope to one behaviour (single focused scenario).
+2. Use `ProjectHarness` (`Harness/ProjectHarness.cs`) to construct a throwaway project for the scenario.
+3. Prefer evaluation helpers before build-log parsing:
+   - `GetPropertyAsync` / `GetPropertiesAsync`
+   - `GetItemIdentitiesAsync` / `GetProjectReferencesAsync`
+   - `GetPreprocessProjectAsync` when import/evaluation order matters
+4. Use `BuildAsync(restore: true)` only when the scenario requires restore/build behaviour.
+5. Follow TUnit conventions used in this repo:
+   - `[Test]` method attributes
+   - awaited assertions (e.g., `await Assert.That(actual).IsEqualTo(expected);`)
+6. Keep setup deterministic and minimal; avoid unrelated package/config changes.
+
+## Suggested output structure
+
+- Add/modify one test file under `src/tests/DotNetProjectSdk.IntegrationTests/Tests/`.
+- Include a short test comment describing **Given / When / Then** intent.
+- Validate by running targeted tests first, then broader tests if needed.
+
+If multiple test ideas are possible, pick the one with the smallest diff that still validates the intended SDK behaviour.

.agents/prompts/sdk-diagnose-agent-folder-copy.md

@@ -0,0 +1,26 @@
+# sdk-diagnose-agent-folder-copy (generic prompt spec)
+
+Diagnose why the bundled `.agents/**` folder from `Purview.DotNetProjectSdk` did not appear at the expected
+destination in a consuming repository.
+
+## Required behaviour
+
+1. Confirm the NuGet package actually contains `.agents/**` content (inspect the `.nupkg` if available).
+2. Confirm the consuming project is packable/buildable and imports the SDK via
+   `Sdk.props`/`Sdk.targets`, since the copy runs in `EnsureAgentFolderInPackageTarget` before build.
+3. Check `EnableAgentFolderInPackage` is not set to `false` anywhere in the build (project file,
+   `Directory.Build.props`, or command-line `-p:` overrides).
+4. Confirm the destination folder: default is `.agents` at the repo root, overridable per-build with
+   `-p:AgentPackDestinationFolder=<folder>`.
+5. Verify repo-root discovery succeeded: explicit `RepoRoot`, then a nearby `AGENTS.md`, then source-control
+   root metadata.
+6. Re-run the build and confirm the destination folder now contains the copied files (including the
+   generated `.gitignore` for skill/prompt/agent subfolders).
+
+## Suggested output
+
+- A short root-cause explanation (missing import, disabled flag, wrong destination override, or repo-root
+  discovery miss).
+- The exact command used to reproduce/verify the fix (for example
+  `dotnet build <project> -p:AgentPackDestinationFolder=<folder>`).
+- Confirmation that the expected files exist at the resolved destination path.

.agents/skills/changesets-prerelease/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: changesets-prerelease
+description: Create and apply a prerelease bump using Changesets CLI, with the new changeset markdown summarizing the actual changes since the last shipped release.
+---
+
+# Changesets Prerelease Skill
+
+Use this skill when preparing the next prerelease version in a project that uses Changesets.
+
+## Steps
+
+1. Add a new changeset:
+   - `npx @changesets/cli add --empty --message "<summary>"`
+   - update the generated `.changeset/*.md` frontmatter with the correct target package and bump type used by the repository.
+   - replace the placeholder body with a concise summary of the **actual user-facing changes since the last shipped release**, not just a generic "prepare prerelease" note.
+   - if the immediately previous prerelease number (for example `.24`) has **not** been released yet and you are preparing `.25`, the new markdown should still describe the cumulative changes that matter for the next published prerelease.
+
+2. Bump versions/changelog:
+   - `npx @changesets/cli version`
+3. Commit the resulting changes (`package.json`, `CHANGELOG.md`, and consumed `.changeset` files).
+
+## Writing the new `.changeset/*.md` body
+
+- Summarize the functional changes that should appear in the changelog for the next published prerelease.
+- Prefer short release-note language such as:
+  - fixed SQL snapshot translation for directly mapped complex mirror properties
+  - clarified provider documentation for scalar value object query behaviour
+  - aligned repo-local agent skills and instructions
+- Do **not** leave the body as a procedural placeholder such as `Prepare next prerelease` unless there were truly no meaningful changes.
+- If multiple unreleased prerelease bumps exist locally, write the new file so the generated changelog entry remains useful to an external consumer reading the next shipped release.
+
+## Notes
+
+- If the repository uses prerelease mode, check `.changeset/pre.json` for the active prerelease tag.
+- Ensure release notes/changelog are generated from actual changes, not placeholder text.
+- In prerelease mode, `changeset version` can record a changeset in `.changeset/pre.json` even if the new file was created with placeholder/empty content first. If that happens, correct the `.md` frontmatter/body before finalizing the release notes so the next shipped prerelease entry is accurate.

.agents/skills/dotnet-tunit/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: dotnet-tunit
+description: Use when creating or refactoring .NET tests with TUnit conventions (AAA pattern, naming, async assertions, and CancellationToken usage).
+category: dotnet
+roles:
+  - dotnet
+  - dotnet-tunit
+  - coding
+tags:
+  - dotnet
+  - csharp
+  - tunit
+  - tests
+---
+
+# dotnet-tunit Skill
+
+Use this skill when creating or refactoring tests in a .NET codebase that uses TUnit.
+
+## Authoring and refactoring rules (mandatory)
+
+- Always use TUnit (`TUnit.Core`, `TUnit.Assertions`).
+- Do not introduce xUnit, NUnit, MSTest, or FluentAssertions unless explicitly requested.
+- Test methods must have `[Test]`.
+- Assertion calls must be awaited.
+- Prefer `await Assert.That(actual).IsEqualTo(expected);`.
+
+### Arrange / Act / Assert structure
+
+- Always use Arrange / Act / Assert.
+- Always include explicit section comments in the test body:
+  - `// Arrange`
+  - `// Act`
+  - `// Assert`
+
+### Naming conventions
+
+- Test classes must be named `{ModuleOrClassBeingTested}Tests`.
+- Test classes must be in the same namespace as the module/class being tested (identical namespace).
+- Test methods must follow `{SubjectUnderTest}_{Scenario}_{Expectation}`.
+  - `SubjectUnderTest` is usually the method name.
+  - Use `ctor` for constructor-focused tests when appropriate.
+
+### CancellationToken rule
+
+- Always include `CancellationToken cancellationToken` as the last parameter when any called method in the test body supports a `CancellationToken` parameter.
+- Pass that token through in the call under test (for example: `var result = await sut.ProcessAsync(cancellationToken);`).
+
+## Refactoring expectation
+
+- When refactoring existing tests, bring them into compliance with all rules above (structure, naming, and cancellation-token usage), while preserving test intent.
+
+## Execution reminder
+
+- Run relevant tests before completion.
+- For execution/filtering details, use `../tunit-test-runner/SKILL.md`.

.agents/skills/git-conventional-commits/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: git-conventional-commits
+description: Git workflow and conventional commit guidance.
+---
+
+# Git Conventional Commits Skill
+
+Use this skill when applying Git workflow and commit hygiene practices.
+
+## Rules
+
+- Use Conventional Commits.
+- Prefer small, reviewable commits.
+- Commit types include `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `build`, and `ci`.
+- Do not mix unrelated changes.
+- Explain validation commands before completion.

.agents/skills/lefthook-integration/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: lefthook-integration
+description: Lefthook Git hook integration.
+---
+
+# Lefthook Integration Skill
+
+Use this skill when configuring repository-local Git hook setup.
+
+## Rules
+
+- Prefer small, fast checks in pre-commit.
+- Put slower checks in pre-push.
+- Do not block commits with network-dependent checks.
+- Keep commands cross-platform where possible.
+- Document how to install and run hooks locally.

.agents/skills/project-placement-defaults/.gitignore

@@ -0,0 +1,8 @@
+# Ignore all files
+*
+
+# Don't ignore directories, so Git can traverse them
+!*/
+
+# Keep this file
+!.gitignore

.agents/skills/sdk-configuration-reference/.gitignore

@@ -0,0 +1,8 @@
+# Ignore all files
+*
+
+# Don't ignore directories, so Git can traverse them
+!*/
+
+# Keep this file
+!.gitignore

.agents/skills/sdk-project-behavior-and-detection/.gitignore

@@ -0,0 +1,8 @@
+# Ignore all files
+*
+
+# Don't ignore directories, so Git can traverse them
+!*/
+
+# Keep this file
+!.gitignore