Authoring standards

Standard scope

Applies to: Anyone proposing a new standard or changing an existing one, in any scope Domain: authoring-standards Status: Active

This document defines how to author, propose, and version a standard in the HCS standards system. It merges what used to be two separate documents in the AzureLocal platform repo — an authoring guide and a contributing guide — into one, generalized so it applies to anyone proposing a standard in any scope (hcs, azurelocal, or tierpoint-prodtech), not just AzureLocal.

---

Where standards live

The authoritative source for HCS-governed standards is docs/standards/*.md in this repository (platform). This is the single base library. Scope-specific deviations live as overlays under docs/standards/_scopes/, resolved at read time by the HCS Governance MCP — see _scopes/README.md for how the overlay mechanism works.

Scope-owned content that genuinely belongs to another repo is authored in its own source repo, not copied into this one:

• tierpoint-prodtech overlays are authored in tp-docs-docs (GitLab) and staged into the MCP build by scripts/Sync-ProdTechStandards.ps1. This sync script does not commit scope content into this repo's git history — the staged files exist only at MCP build time.

NOTE

azurelocal overlays were previously synced from an external repository. That repository was sunsetted during the platform federation, and the overlays are now authored directly within this repository under docs/standards/_scopes/azurelocal/.

---

How a new domain gets proposed

1. Check it doesn't already exist. Read the governance standard's PR rules and skim the existing docs/standards/*.md files — a similar rule may already exist under a different name.
2. Open a PR against this repo (platform) with the new or changed standards file. Follow the governance standard's PR requirements: a description, a linked ADO work item (AB#<id>), and passing CI.
3. Get it reviewed. The repo owner (Kris Turner) reviews standards PRs. Comments get resolved before merge.
4. Merge. Once merged, the standard is live in the base library immediately for hcs-scope repos. If the change also needs a scope overlay, open the corresponding PR in the owning scope's repo (see above).

There is no separate approval body beyond the PR review described in governance.md — standards changes follow the same PR process as any other change to this repo.

---

Base vs. overlay: when to split

Not every difference between scopes warrants a scope overlay. Use this test:

Question	If yes →	If no →
Is this a genuinely different rule (a different tool, a different mandatory pattern, a different lifecycle), not just different phrasing of the same rule?	Overlay candidate	Keep it one base rule; fix the phrasing
Would forcing one scope to adopt the other's rule break live, working automation or infrastructure?	Overlay	Converge on one rule
Is the difference a rendering/format concern (e.g. .md vs .mdx) rather than a governance rule?	Not an overlay — handle via docs_platform, not a forked standard	—
Does the content only make sense for one scope at all (no equivalent exists elsewhere)?	New scope-only domain (e.g. provisioning.md for tierpoint-prodtech)	—

Worked examples from this repo's own consolidation effort:

• Overlay, correctly split: Azure resource naming pattern. HCS uses <type>-<org>-<env>-<region>-<instance>; azurelocal uses a purpose-based short form with no region; tierpoint-prodtech uses a full CAF pattern plus a large multi-platform matrix. These are genuinely different rules serving genuinely different estates — see naming.md.
• Not an overlay, merged instead: Documentation format. .md vs .mdx is a generator/rendering difference, not a governance difference — the underlying Markdown, diagram, and commit-message rules are ~identical across scopes. Format lives in docs-platforms.md; prose rules stay merged in documentation.md.
• Deliberately not forced to converge: IaC tool default. HCS is Bicep-first; tierpoint-prodtech is Terraform-first (matches its live tp-tf-module-* repos and GitLab state backend); azurelocal requires multi-tool parity. Forcing convergence here would break real, working pipelines for no governance benefit.

When in doubt, prefer one base rule over an overlay. Overlays are for genuine, load-bearing divergence — not a shortcut around reconciling two similar-but-differently-worded rules.

---

Link-not-copy principle

Never vendor or copy standards content into a consuming repo. A repo that must follow a standard resolves it live — via the MCP (get_standard(domain, scope)) or by linking to the public site (platform.hybridsolutions.cloud) — rather than pasting a copy of the standard into its own docs/ folder.

This principle is inherited from AzureLocal's earlier propagation model, which used a STANDARDS.md breadcrumb file in each consumer repo pointing back at the platform repo, kept in sync by a scheduled job. That specific mechanism (the breadcrumb + scheduled sync) is now deprecated — the MCP and the public site supersede it. But the underlying principle survives unchanged: standards have exactly one authoritative copy, and every consumer resolves against that copy rather than maintaining its own.

In practice this means:

• Every HCS-governed repo carries an AGENTS.md (or equivalent) that references the platform repo and the public site as the source of truth — it does not restate the standards themselves.
• A repo's own CLAUDE.md documents repo-specific context and deviations, not a copy of the base standard.
• If a standard changes here, every consuming repo picks up the change automatically the next time an AI client or human resolves it — there is nothing to manually propagate.

---

Structure of a standards document

Every file in docs/standards/ should open with the scope-header admonition:

::: info Standard scope
**Applies to:** <who/what this governs>
**Domain:** <domain-name>
**Status:** Active
:::

Beyond that, use whatever structure best serves the content — a rule-heavy document (like keyvault.md) benefits from tables and worked examples; a policy document (like this one) benefits from prose and a decision table. There is no rigid mandatory skeleton, but every standard should make clear:

• What it covers and what it doesn't (scope)
• The rule itself, stated plainly enough to follow without interpretation
• Why the rule exists, when the reason isn't self-evident
• How it's enforced (CI check, PR review, manual audit) — even if enforcement is "manual review"

---

Voice

• Imperative, not descriptive. "Use PowerShell 7+ for all scripts," not "PowerShell 7+ is used for scripts."
• Specific, not aspirational. Don't say "keep documentation clean" — define what clean means in context.
• Lead with the rule. Rationale comes after the rule, not before.
• Write for an outside reader. Standards on the public site are read by people with no session context and no internal shorthand. Spell out acronyms on first use (see documentation.md's abbreviation rule).

---

Testing a standards change locally

mkdocs serve

Navigate to the changed page and verify rendering and links before opening the PR.

---

Related

• Governance standard — PR rules, branch strategy, commit format that apply to every change including standards changes
• _scopes/README.md — the three-way scope reconciliation matrix and overlay resolution mechanism
• Documentation standard — Markdown, admonition, and prose conventions used when writing a standard