Chore/skills root folder

.config/architecture-policy.json

@@ -1,7 +1,8 @@
 {
-  "$schema": "https://raw.githubusercontent.com/purview-dev/engineering-playbook/main/.config/architecture-policy.schema.json",
+  "$schema": "https://raw.githubusercontent.com/purview-dev/build-sdk/main/architecture-policy.schema.json",
   "version": 1,
   "description": "The authoritative dependency and naming policy. The architecture tests read this file, and a test asserts the wiki tables agree with it, so there is one definition of each rule rather than one in prose and one in code.",
+  "sourceRoots": ["src"],
   "conventions": {
     "qualifiedNameSeparator": ".",
     "dependencyArrowMeaning": "A -> B means A depends on B at compile time."

AGENTS.md

@@ -28,12 +28,14 @@ implementation whose only job is to prove the conventions compile, run, and fail
 | `src/src/Infrastructure` | The in-memory adapter that implements the port |
 | `src/tests/Domain.UnitTests` | Value-object behaviour; the value-object exception to `TestBuilder` |
 | `src/tests/Application.UnitTests` | The service, against a TUnit.Mocks substitute |
-| `src/tests/Architecture.UnitTests` | Dependency-direction rules; a wrong `ProjectReference` fails the build |
+| `src/tests/Architecture.UnitTests` | Assembly dependency-direction rules and the architecture policy; a wrong `ProjectReference` fails the build |
+| `src/tests/Repository.UnitTests` | The repository itself: skill conformance and documentation checks |
 | `src/tests/SharedTestingInfra` | `TestBuilder`; referenced automatically by every test project |
 | `skills/` | Authored agent skills, installable with `npx skills add purview-dev/engineering-playbook` |
 | `templates/` | Ready-to-copy starter files for a repository adopting the playbook |
 | `src/Directory.Build.props` | `NamespacePrefix`, the SDK import, and `NamespaceRemoveSuffix` |
 | `.config/purview-build.json` | Pipeline configuration: solution, test discovery, filter |
+| `.config/architecture-policy.json` | The dependency and naming policy the architecture tests read |
 | `Justfile` | Supported local commands |
 | `package.json` | Authoritative version; the release reads it and nothing else |
 
@@ -54,7 +56,8 @@ demonstrate it.
 
 - **One page per concern**, in `docs/wiki/<Page-Name>.md`. Title case, hyphens between words.
 - **Four sections, in order:** the rule, why, how it is enforced, at your scale. A rule a build cannot check
-  is labelled a review obligation — never described as enforced.
+  is labelled a review obligation — never described as enforced. `Home.md` and `index.md` are navigation,
+  and `Engineering-Principles.md` is an index that links to the page stating each rule in full.
 - **A new page goes in `_Sidebar.md` and in the table in `Home.md`.** A page in neither does not exist.
 - **Link to the authority rather than paraphrasing it.** The SDK's own wiki is authoritative on the SDK's
   behaviour; a paraphrase here is a second source of truth that will drift.
@@ -67,12 +70,34 @@ demonstrate it.
 
 ## Skills
 
-Authored skills live in `skills/<name>/SKILL.md` at the repository root — not in `.agents/skills/`, which
-is the gitignored mirror that packages write into. The root folder is the one the skills CLI can discover
-in a git clone. A skill states when it applies in its `description`, keeps the workflow in `SKILL.md`, and
-pushes detail into `references/`. See [Agent Skills Distribution](docs/wiki/Agent-Skills-Distribution.md).
+Authored skills live in `skills/<name>/SKILL.md` at the repository root. `.agents/skills/` is the skills
+CLI's install location for skills from **other** repositories and is gitignored; this repository's own
+skills are never installed into it, because two copies drift apart. A skill states when it applies in its
+`description`, keeps the workflow in `SKILL.md`, and pushes detail into `references/`. See
+[Agent Skills Distribution](docs/wiki/Agent-Skills-Distribution.md).
 
-This repository ships no package, so its skills travel by the git route only.
+Nothing packs a skill into a NuGet package - `Purview.BuildSdk` 1.0.6 removed skill packaging and the
+build-time `.agents/` mirror outright. The skills CLI clones the git repository, and that is the only route.
+
+| Skill | Answers |
+| -- | -- |
+| `skills/purview-engineering-principles/` | the ten repository conventions, what each prevents, and whether a build or a reviewer enforces it |
+| `skills/purview-architecture/` | how many projects, which layers, where validation lives |
+| `skills/purview-architecture-testing/` | turning a boundary into a failing build |
+| `skills/purview-testing-conventions/` | TUnit, AAA, `TestBuilder`, substitutes, tiers |
+| `skills/purview-persistence/` | storage approach, EF Core abstraction, GUID key strategy |
+| `skills/purview-telemetry/` | logging, tracing, metrics, and when a project is "too small" for them |
+
+Every skill carries the `purview-` prefix: skills install into one flat directory per agent, shared with
+every skill a developer has installed from anywhere, so an unprefixed name collides and the loser is
+whichever installed second.
+
+`src/tests/Repository.UnitTests/SkillTests.cs` validates them on every test run through
+`Purview.Skills.Testing`. The `[InheritsTests]` attribute there is load-bearing - TUnit does not walk base
+types during discovery, so without it the run is green and nothing is checked.
+
+A relative link from one `SKILL.md` into another skill's folder is a rule violation: only a skill's own
+folder is installed with it. Name the other skill in prose instead.
 
 ## Code conventions
 

Directory.Packages.props

@@ -23,10 +23,15 @@
 		<MSExtensionVersion>10.10.0</MSExtensionVersion>
 	</PropertyGroup>
 	<PropertyGroup Label="Purview Versions">
-		<PurviewTelemetryVersion>5.0.3</PurviewTelemetryVersion>
+		<PurviewTelemetryVersion>5.0.4</PurviewTelemetryVersion>
+		<!--
+			The build-sdk's test-support packages ship together and track the SDK version pinned in
+			global.json, so they share one property: a bump cannot be applied to half the family.
+		-->
+		<PurviewBuildSdkTestingVersion>1.0.6</PurviewBuildSdkTestingVersion>
 	</PropertyGroup>
 	<PropertyGroup Label="Testing Versions">
-		<TUnitVersion>1.72.4</TUnitVersion>
+		<TUnitVersion>1.75.0</TUnitVersion>
 	</PropertyGroup>
 
 	<!-- Packages -->
@@ -41,24 +46,22 @@
 	<ItemGroup Label="Microsoft Extensions">
 		<PackageVersion Include="Microsoft.Extensions.Telemetry.Abstractions" Version="$(MSExtensionVersion)" />
 	</ItemGroup>
-	<ItemGroup Label="Schema">
-		<!--
-			Validates .config/architecture-policy.json against its JSON Schema in a test. The schema is
-			only worth having if something checks the policy against it; otherwise it drifts silently and
-			becomes a second, wrong description of the format. Same library the Purview.Build tool uses
-			to validate purview-build.json, so the ecosystem has one JSON Schema implementation.
-		-->
-		<PackageVersion Include="JsonSchema.Net" Version="9.4.0" />
-	</ItemGroup>
 	<ItemGroup Label="Other">
 		<!-- Injected by the SDK and added to every assembly. -->
-		<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.401" />
+		<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.402" />
 	</ItemGroup>
 	<ItemGroup Label="Testing">
 		<!-- The test packages the SDK wires into test and shared-testing projects. -->
 		<PackageVersion Include="TUnit" Version="$(TUnitVersion)" />
 		<PackageVersion Include="TUnit.Core" Version="$(TUnitVersion)" />
 		<PackageVersion Include="TUnit.Mocks" Version="$(TUnitVersion)" />
 		<PackageVersion Include="Bogus" Version="35.6.5" />
+		<!--
+			The conformance rule sets, shipped by the build-sdk so the rules are defined once rather than
+			reimplemented in every repository. Purview.Skills.Testing validates authored skills;
+			Purview.Architecture.Testing enforces the architecture policy. They move together with the SDK.
+		-->
+		<PackageVersion Include="Purview.Skills.Testing" Version="$(PurviewBuildSdkTestingVersion)" />
+		<PackageVersion Include="Purview.Architecture.Testing" Version="$(PurviewBuildSdkTestingVersion)" />
 	</ItemGroup>
 </Project>

README.md

@@ -12,15 +12,22 @@ coding agents are enabled to work in a codebase without hand-holding.
 
 | Area | Question it answers |
 | -- | -- |
-| [Engineering principles](docs/wiki/Engineering-Principles.md) | What are the non-negotiable rules, and who owns them? |
+| [Getting started](docs/wiki/Getting-Started.md) | What is the smallest repository that satisfies every rule, in the order you build it? |
+| [Engineering principles](docs/wiki/Engineering-Principles.md) | What are the non-negotiable rules, and where is each one stated in full? |
 | [Repository shape](docs/wiki/Repository-Shape.md) | Where does a file go, and what is it called? |
+| [Project responsibilities](docs/wiki/Project-Responsibilities.md) | What is each project for, how is it named, and what may it depend on? |
 | [Architecture as tests](docs/wiki/Architecture-As-Tests.md) | How does the build refuse a dependency that points the wrong way? |
 | [Verification model](docs/wiki/Verification-Model.md) | Which checks run, in which tier, for which change? |
 | [Contracts and data exchange](docs/wiki/Contracts-And-Data-Exchange.md) | How do value objects, schemas and results cross a boundary? |
 | [Testing and test data](docs/wiki/Testing-And-Test-Data.md) | How are tests written, and where does their data come from? |
 | [Agent enablement](docs/wiki/Agent-Enablement.md) | How is a repository made legible to a coding agent? |
+| [Agent skills distribution](docs/wiki/Agent-Skills-Distribution.md) | How is a skill published once and reach an agent? |
+| [Agent guidance skills](docs/wiki/Agent-Guidance-Skills.md) | Which shared guidance ships as a skill, and what context comes first? |
 | [Documentation convention](docs/wiki/Documentation-Convention.md) | How is the wiki written, structured and published? |
+| [Worked examples](docs/wiki/Worked-Examples.md) | What does the reference implementation under `src/` actually demonstrate? |
 | [Adopting this at your scale](docs/wiki/Adopting-This-At-Your-Scale.md) | Which parts apply to a small, medium or large repository? |
+| [Contributing](docs/wiki/Contributing.md) | How do I change the playbook itself? |
+| [Release flow](docs/wiki/Release-Flow.md) | How does a change become a version, and what does a release mean here? |
 
 ## Start here