feat(standards): seed standards/ from site + add STANDARDS.md stub (Phase 1) by kristopherjturner · Pull Request #4 · AzureLocal/platform

kristopherjturner · 2026-04-12T22:59:56Z

Summary

First commit of Phase 1 (standards consolidation). Makes platform/standards/ the canonical source per ADR-0002.

Copies 11 .mdx files from azurelocal.github.io/standards/ into standards/. Kept as-is — Docusaurus :::admonition syntax preserved (site renders it natively; GitHub fallback rendering is acceptable for stub-linked viewing).
Authors new standards/testing.mdx — the first standard covering MAPROOM contract tests, TRAILHEAD scenarios, and IIC canon. Flags open classification questions as provisional pending issue Classify & extend the centralized testing toolsets (MAPROOM / TRAILHEAD) for multi-repo coverage #3.
Authors templates/_common/STANDARDS.md — the stub that product repos will link to after their local /standards/ folders are deleted in the follow-up per-repo PRs.
Adds ADR-0003 (Proposed) describing MAPROOM/TRAILHEAD/IIC-canon centralization. Marked Proposed and blocked on Classify & extend the centralized testing toolsets (MAPROOM / TRAILHEAD) for multi-repo coverage #3.

Downstream PRs (queued)

Merging this unblocks:

azurelocal.github.io — scheduled sync workflow pulling platform/standards/*.mdx on every platform release tag.
Six product repos — delete local /standards/, add STANDARDS.md stub: azurelocal-avd, azurelocal-sofs-fslogix, azurelocal-loadtools, azurelocal-vm-conversion-toolkit, azurelocal-copilot, azurelocal-nutanix-migration. (The epic listed 7; audit found 6 — azurelocal-nutanix-migration has a single orphan file that will be flagged in its PR.)

Release

This is a feat: commit, so release-please will roll it into v0.1.0 — the Phase 1 exit criterion tag.

Test plan

Platform CI passes (Markdown lint, MkDocs build, Validate Repo Structure)
mkdocs serve locally shows testing.mdx rendering
STANDARDS.md stub link-checks (links to platform and ADR-0002 resolve)
release-please opens a v0.1.0 release PR after merge

🤖 Generated with Claude Code

…template Phase 1 of the platform rollout. Copies the 11 canonical .mdx files from azurelocal.github.io/standards/ into platform/standards/, making platform the source-of-truth per ADR-0002. Adds a new testing.mdx covering MAPROOM contract tests, TRAILHEAD scenarios, and IIC canon — referenced by every repo that ships executable code or infrastructure. Also adds the templates/_common/STANDARDS.md stub that product repos will link to in place of their deleted local /standards/ folders, and ADR-0003 (Proposed) describing MAPROOM & IIC canon centralization ahead of Phase 2. Issue #3 tracks the classification rubric that gates Phase 2 framework implementation — testing.mdx flags this so the five-class taxonomy is understood as provisional. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Seeds platform/standards/ as the canonical standards source (per ADR-0002), adds an initial Testing standard, and introduces a reusable STANDARDS.md stub template for downstream repos to link back to platform.

Changes:

Added templates/_common/STANDARDS.md stub for product repos to reference platform standards.
Seeded standards/ with the initial set of standards documents (copied from the site) and authored standards/testing.mdx.
Added ADR-0003 (Proposed) describing MAPROOM/TRAILHEAD/IIC-canon centralization.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
templates/_common/STANDARDS.md	Adds the cross-repo stub pointing consumers to `AzureLocal/platform/standards/`.
standards/index.mdx	Standards landing page/table of contents for the seeded standards set.
standards/documentation.mdx	Documentation rules and MkDocs-related conventions.
standards/repository-management.mdx	Portfolio governance + repo-management contract guidance.
standards/scripting.mdx	Script naming, config-driven patterns, logging, and Invoke-* requirements.
standards/variables.mdx	Variable registry + config/bootstrap/validation conventions.
standards/solutions.mdx	Solution-to-repo mapping + IaC parity/derivation rules.
standards/infrastructure.mdx	Infrastructure types, pipeline, state, and toolkit layout conventions.
standards/automation.mdx	Cross-tool configuration flow and interoperability rules.
standards/naming.mdx	Naming conventions for files/dirs/resources/branches/variables.
standards/examples.mdx	IIC fictional-company policy and reference card.
standards/new-repo-setup.mdx	Runbook for creating and bootstrapping new repos.
standards/testing.mdx	New testing standard defining taxonomy and MAPROOM/TRAILHEAD expectations.
decisions/0003-maproom-iic-canon.md	Proposed ADR for centralizing MAPROOM/TRAILHEAD/IIC canon under `platform/testing/`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-12T23:04:10Z

+| Documentation | [Documentation Standards](documentation) | [Full Reference](https://azurelocal.cloud/standards/documentation/documentation-standards) |
+| Repository Management | [Repository Management Standard](repository-management) | [Full Reference](https://azurelocal.cloud/standards/repository-management/) |
+| Scripting | [Scripting Standards](scripting) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-standards) |
+| Variables | [Variable Standards](variables) | [Full Reference](https://azurelocal.cloud/standards/variable-management/) |
+| Naming Conventions | [Naming Conventions](naming) | [Full Reference](https://azurelocal.cloud/standards/documentation/naming-conventions) |
+| Solutions | [Solution Standards](solutions) | [Full Reference](https://azurelocal.cloud/standards/solutions/solution-development-standard) |
+| Infrastructure | [Infrastructure Standards](infrastructure) | [Full Reference](https://azurelocal.cloud/standards/infrastructure/) |
+| Automation | [Automation Interoperability](automation) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-framework) |
+| Examples & IIC | [Examples & IIC](examples) | [Full Reference](https://azurelocal.cloud/standards/fictional-company-policy) |
+
+---
+
+## References
+
+- [Variable Reference](variables) — Per-variable catalog for this repo
+- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required file layout
+- [Repository Management Standard](repository-management) — Portfolio-level governance and repo-management contract
+
+---
+
+## Repo-Specific Conventions
+
+- **IaC tooling**: Terraform, Bicep, ARM, PowerShell, Ansible
+- **Config contract**: runtime `config/variables/variables.yml`, template `config/variables/variables.example.yml`, schema `config/variables/schema/variables.schema.json`, bootstrap policy defined in [Variable Standards](variables)
+- **Fictional company**: Infinite Improbability Corp (IIC) — see [IIC Policy](examples)


The “Local Page” links omit the .mdx extension (e.g., (documentation), (repository-management)), which breaks navigation when viewing these standards in GitHub (and ADR-0002 explicitly calls out GitHub as a consumption path). Consider linking directly to the actual files (e.g., documentation.mdx) or using absolute https://azurelocal.cloud/standards/... links consistently.

Suggested change

| Documentation | [Documentation Standards](documentation) | [Full Reference](https://azurelocal.cloud/standards/documentation/documentation-standards) |

| Repository Management | [Repository Management Standard](repository-management) | [Full Reference](https://azurelocal.cloud/standards/repository-management/) |

| Scripting | [Scripting Standards](scripting) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-standards) |

| Variables | [Variable Standards](variables) | [Full Reference](https://azurelocal.cloud/standards/variable-management/) |

| Naming Conventions | [Naming Conventions](naming) | [Full Reference](https://azurelocal.cloud/standards/documentation/naming-conventions) |

| Solutions | [Solution Standards](solutions) | [Full Reference](https://azurelocal.cloud/standards/solutions/solution-development-standard) |

| Infrastructure | [Infrastructure Standards](infrastructure) | [Full Reference](https://azurelocal.cloud/standards/infrastructure/) |

| Automation | [Automation Interoperability](automation) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-framework) |

| Examples & IIC | [Examples & IIC](examples) | [Full Reference](https://azurelocal.cloud/standards/fictional-company-policy) |

---

## References

- [Variable Reference](variables) — Per-variable catalog for this repo

- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required file layout

- [Repository Management Standard](repository-management) — Portfolio-level governance and repo-management contract

---

## Repo-Specific Conventions

- **IaC tooling**: Terraform, Bicep, ARM, PowerShell, Ansible

- **Config contract**: runtime `config/variables/variables.yml`, template `config/variables/variables.example.yml`, schema `config/variables/schema/variables.schema.json`, bootstrap policy defined in [Variable Standards](variables)

- **Fictional company**: Infinite Improbability Corp (IIC) — see [IIC Policy](examples)

| Documentation | [Documentation Standards](documentation.mdx) | [Full Reference](https://azurelocal.cloud/standards/documentation/documentation-standards) |

| Repository Management | [Repository Management Standard](repository-management.mdx) | [Full Reference](https://azurelocal.cloud/standards/repository-management/) |

| Scripting | [Scripting Standards](scripting.mdx) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-standards) |

| Variables | [Variable Standards](variables.mdx) | [Full Reference](https://azurelocal.cloud/standards/variable-management/) |

| Naming Conventions | [Naming Conventions](naming.mdx) | [Full Reference](https://azurelocal.cloud/standards/documentation/naming-conventions) |

| Solutions | [Solution Standards](solutions.mdx) | [Full Reference](https://azurelocal.cloud/standards/solutions/solution-development-standard) |

| Infrastructure | [Infrastructure Standards](infrastructure.mdx) | [Full Reference](https://azurelocal.cloud/standards/infrastructure/) |

| Automation | [Automation Interoperability](automation.mdx) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-framework) |

| Examples & IIC | [Examples & IIC](examples.mdx) | [Full Reference](https://azurelocal.cloud/standards/fictional-company-policy) |

---

## References

- [Variable Reference](variables.mdx) — Per-variable catalog for this repo

- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required file layout

- [Repository Management Standard](repository-management.mdx) — Portfolio-level governance and repo-management contract

---

## Repo-Specific Conventions

- **IaC tooling**: Terraform, Bicep, ARM, PowerShell, Ansible

- **Config contract**: runtime `config/variables/variables.yml`, template `config/variables/variables.example.yml`, schema `config/variables/schema/variables.schema.json`, bootstrap policy defined in [Variable Standards](variables.mdx)

- **Fictional company**: Infinite Improbability Corp (IIC) — see [IIC Policy](examples.mdx)

Copilot · 2026-04-12T23:04:11Z

+
+## MkDocs Material Conventions
+
+This repo uses **MkDocs Material** with the following conventions:


This standard says it “Applies to: All AzureLocal repositories” but then uses repo-specific phrasing (“This repo uses MkDocs Material…”). Since this file is now the org-wide canonical standard, please reword to something like “Repos that use MkDocs Material…” (or specify which repo types) to avoid ambiguity for consumers reading it from platform/standards/.

Suggested change

This repo uses **MkDocs Material** with the following conventions:

Repos that use **MkDocs Material** should follow these conventions:

Copilot · 2026-04-12T23:04:11Z

+Each repository is a **standalone deliverable** with its own README, issues, releases, workflows, and branch protections. At the same time, each repository participates in a shared governance model where `azurelocal.github.io` acts as the central source for standards, portfolio-level guidance, and shared repository management practices.
+


This section still states that azurelocal.github.io is the central source for standards. That conflicts with ADR-0002 in this repo, which makes AzureLocal/platform/standards/ the canonical source and the site a renderer/sync target. Please update the wording (and the repository roles table) to reflect platform as the standards source of truth.

Copilot · 2026-04-12T23:04:11Z

+## Step 11 — Add the Repository to This Standards Page
+
+Open a PR on `azurelocal.github.io` to:
+
+1. Add a row for the new repository in the [Repository Management Standard](./repository-management.mdx) portfolio table.
+2. If the solution has a dedicated page on the docs site, add a navigation entry in `docusaurus.config.js`.
+


Step 11 instructs opening a PR on azurelocal.github.io to update the Repository Management Standard table, but with ADR-0002 the canonical standards now live in AzureLocal/platform/standards/ and the site syncs from there. The repo-listing change should be made in platform/standards/... (with a separate site PR only if navigation/config needs updating).

Copilot · 2026-04-12T23:04:12Z

+1. Move MAPROOM framework → [`platform/testing/maproom/framework/`](../testing/maproom/). Ship as PowerShell module `AzureLocal.Maproom` (manifest + `.psm1`). Consumers reference by module name.
+2. Move TRAILHEAD harness + templates → [`platform/testing/trailhead/`](../testing/trailhead/). Consumers reference by path or, if module-shaped content emerges, `AzureLocal.Trailhead` sibling module.
+3. Move IIC canon → [`platform/testing/iic-canon/`](../testing/iic-canon/). Consumers reference canonical fixtures by path; additional per-domain canons (AVD, FSLogix, Nutanix) land here as they're authored, not in consumer repos.
+4. Publish schemas under [`platform/testing/maproom/schema/`](../testing/maproom/): `fixture.schema.json`, `iic-canon.schema.json`. All consumer fixtures validate against these in CI.


The link targets in items 1 and 4 don’t match the link text: platform/testing/maproom/framework/ and platform/testing/maproom/schema/ both currently point to ../testing/maproom/ (the parent folder). Please update these links to the intended subpaths so readers land on the right location.

Suggested change

1. Move MAPROOM framework → [`platform/testing/maproom/framework/`](../testing/maproom/). Ship as PowerShell module `AzureLocal.Maproom` (manifest + `.psm1`). Consumers reference by module name.

2. Move TRAILHEAD harness + templates → [`platform/testing/trailhead/`](../testing/trailhead/). Consumers reference by path or, if module-shaped content emerges, `AzureLocal.Trailhead` sibling module.

3. Move IIC canon → [`platform/testing/iic-canon/`](../testing/iic-canon/). Consumers reference canonical fixtures by path; additional per-domain canons (AVD, FSLogix, Nutanix) land here as they're authored, not in consumer repos.

4. Publish schemas under [`platform/testing/maproom/schema/`](../testing/maproom/): `fixture.schema.json`, `iic-canon.schema.json`. All consumer fixtures validate against these in CI.

1. Move MAPROOM framework → [`platform/testing/maproom/framework/`](../testing/maproom/framework/). Ship as PowerShell module `AzureLocal.Maproom` (manifest + `.psm1`). Consumers reference by module name.

2. Move TRAILHEAD harness + templates → [`platform/testing/trailhead/`](../testing/trailhead/). Consumers reference by path or, if module-shaped content emerges, `AzureLocal.Trailhead` sibling module.

3. Move IIC canon → [`platform/testing/iic-canon/`](../testing/iic-canon/). Consumers reference canonical fixtures by path; additional per-domain canons (AVD, FSLogix, Nutanix) land here as they're authored, not in consumer repos.

4. Publish schemas under [`platform/testing/maproom/schema/`](../testing/maproom/schema/): `fixture.schema.json`, `iic-canon.schema.json`. All consumer fixtures validate against these in CI.

Copilot · 2026-04-12T23:04:12Z

+| Repository Type | Role | Notes |
+|-----------------|------|-------|
+| `azurelocal.github.io` | Central standards, documentation portal, and governance source | Holds canonical standards and shared repo governance references |
+| `azurelocal-toolkit` | Reference implementation and shared automation toolkit | Primary implementation repo for deployment, validation, and automation assets |
+| Solution repositories | Standalone solution delivery repos | Must be independently usable while following org-wide standards |
+| Supporting repositories | Utilities, training, migration, demos, or experiments | May have lighter content, but still follow the governance baseline |


The repository roles table lists azurelocal.github.io as the “Central standards … source” and says it “Holds canonical standards”. With ADR-0002 accepted, azurelocal.github.io should be described as the rendering portal that syncs from platform/standards/, while platform is the canonical standards source.

release-please generates CHANGELOG.md from conventional-commit subjects and uses markdown conventions that conflict with .markdownlint.json (MD004 ul style, MD012 blank lines). Fighting the generator is a losing game; the file is machine-authored and doesn't need to match hand-authored style. Discovered during the Phase 1 seed PR — first PR after release-please cut v0.0.2 that had 10 lint errors all in CHANGELOG.md blocking CI. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings April 12, 2026 22:59

Copilot started reviewing on behalf of kristopherjturner April 12, 2026 23:00 View session

Copilot AI reviewed Apr 12, 2026

View reviewed changes

kristopherjturner merged commit 79a03a2 into main Apr 12, 2026
6 checks passed

kristopherjturner deleted the feat/phase-1-standards-seed branch April 12, 2026 23:06

github-actions Bot mentioned this pull request Apr 12, 2026

chore(main): release azurelocal-platform 0.1.0 #5

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(standards): seed standards/ from site + add STANDARDS.md stub (Phase 1)#4

feat(standards): seed standards/ from site + add STANDARDS.md stub (Phase 1)#4
kristopherjturner merged 2 commits into
mainfrom
feat/phase-1-standards-seed

kristopherjturner commented Apr 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## MkDocs Material Conventions

		This repo uses MkDocs Material with the following conventions:

	This repo uses MkDocs Material with the following conventions:
	Repos that use MkDocs Material should follow these conventions:

		Each repository is a standalone deliverable with its own README, issues, releases, workflows, and branch protections. At the same time, each repository participates in a shared governance model where `azurelocal.github.io` acts as the central source for standards, portfolio-level guidance, and shared repository management practices.

Conversation

kristopherjturner commented Apr 12, 2026

Summary

Downstream PRs (queued)

Release

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants