Governance standard

Standard scope

Applies to: all HCS-governed repos, base rules; scope overlays noted inline where applicable Domain: governance Status: Active

This document defines the project creation, naming, structure, and change management rules that apply across all HCS projects on ADO and GitHub, plus TierPoint client work on GitLab.

Platform boundary — read this before choosing a source-control platform for a new repo. GitHub is the home for every HCS-owned org, product, and internal tool — CloudGrange, Turner Legacy, ApiaryLens, Azure Local, and everything else the platform itself owns. GitLab exists for exactly one purpose: TierPoint client-facing work, under tierpoint/prodtech (see the tierpoint-prodtech scope overlay below and CI Runners / Automation for its CI specifics). Never create a new GitLab group or repo for an HCS-owned project, and never assume a GitHub-only rule elsewhere in these standards has a GitLab equivalent unless the tierpoint-prodtech overlay says so explicitly. If you are unsure which platform a repo belongs on, it is GitHub unless the work is TierPoint client delivery.

---

Naming conventions

GitHub repos

• Format: lowercase-kebab-case
• Be specific enough to distinguish the repo at a glance
• Prefix with the project family when repos are related: azurelocal-ranger, azurelocal-surveyor
• Examples: platform-engineering, azure-scout, hcs-bicep-modules

ADO projects

• Format: Title Case with spaces
• Examples: Platform Engineering, Azure Local Cloud, TierPoint Automation

ADO area paths

Every ADO project has a defined area path structure. Area paths reflect the domains of work in that project. Example for Platform Engineering:

• Standards and Governance
• Documentation
• Templates
• Integrations
• Onboarding
• Tooling

Area paths are created once per project and should not be renamed without updating all existing work items.

ADO iterations

Iterations follow a monthly cadence: 2026-05, 2026-06, etc. Sprint-based projects may use: Sprint 1, Sprint 2, etc. Establish the pattern for a project at creation time.

GitLab repos

TierPoint client work only — see the platform-boundary note above. If you're naming a repo for an HCS-owned project, this section does not apply; use the GitHub convention instead.

• Same kebab-case convention as GitHub
• Prefix group name matches the ADO project or GitHub org it mirrors

---

Required files in every new repo

Every repo that is created, regardless of size, purpose, or audience, must have these files at the root before any functional work is committed:

File	Purpose
README.md	Public-facing description: what it is, prerequisites, quick start, links to docs
CLAUDE.md / AGENTS.md	AI coding agent context. Generated from templates/CLAUDE.md.template. Required before any AI coding agent session. CLAUDE.md is read by Claude Code; AGENTS.md is the equivalent for other AI clients — commit whichever the repo's tooling uses (or both).
.gitignore	Start from templates/repo-scaffold/.gitignore.template. Customize as needed.
LICENSE	MIT by default for open-source repos. Proprietary for internal HCS tooling.

---

Repo visibility

• Private by default. A new repo is private until there is a deliberate decision to make it public.
• Public only for: published open-source tools, documentation sites, sample code intended for public reference.
• Never public: anything containing internal architecture, identity references, customer data, or unreleased product work.

---

Branch strategy

• main is the protected default branch. Direct commits to main are prohibited.
• Feature work goes on branches named feature/short-description — e.g., feature/add-kv-loader
• Bug fixes: fix/short-description
• Documentation: docs/short-description
• Chores: chore/short-description
• Branches are deleted after merge — no long-lived feature branches.

Branch protection rules (apply to every repo)

• Require at least one approval before merge (self-approval counts for solo repos)
• Require the branch to be up to date before merging
• No force pushes to main
• No deletion of main

---

Pull request requirements

Every PR must have:

1. A description — at minimum one sentence explaining what changed and why
2. A linked ADO work item — include AB#<id> in the PR title or description
3. A reviewer — at minimum self-review with deliberate sign-off; team repos require one peer review
4. Passing CI — if a pipeline is configured, it must pass before merge

PR titles follow the same commit format: type(scope): short description

---

Commit message format

type(scope): short description under 72 characters

Optional longer body explaining the why, not the what.
Link work items: AB#1234

Types:

Type	Use for
feat	New feature or capability
fix	Bug fix
docs	Documentation only
chore	Maintenance, dependency updates, config changes
refactor	Code change that neither adds a feature nor fixes a bug
test	Adding or updating tests

---

How to register a new project

When starting a new project:

1. Create the repo (GitHub or ADO) following the naming convention above
2. Copy templates/repo-scaffold/ into the repo root
3. Fill in templates/CLAUDE.md.template and commit it as the repo's AI coding agent context file (CLAUDE.md and/or AGENTS.md)
4. Create or identify the ADO project and area path for work items
5. If the project introduces new secrets or identities, register them in docs/identity/ in this repo
6. If the project introduces new standards deviations or extensions, document them in the repo's own CLAUDE.md

There is no formal registration table in this repo — the git history, ADO work items, and docs/identity/ registries collectively serve as the record.

---

New repo setup checklist

Complete these steps in order when standing up any new HCS repo. Do not skip steps — the order matters.

Step	Action
1	Create the repo under the correct org (ADO or GitHub) following the naming convention
2	Clone locally and initialize with git init if not cloned from remote
3	Add required root files: README.md, the AI agent context file (CLAUDE.md / AGENTS.md), .gitignore, LICENSE
4	Add docs/ directory with index.md or equivalent landing page
5	Add mkdocs.yml if the repo will have a documentation site
6	Add .ado/ or .github/workflows/ with at minimum a CI validation pipeline
7	Add config/variables.example.yml if the repo deploys infrastructure
8	Register any new secrets or service principals in docs/identity/ in this (platform) repo
9	Set branch protection on main: require PR, require 1 approval, no force push
10	Add the repo to the ADO project board under the correct area path
11	Add required labels (see issue management section below)

Required root files

File	Purpose
README.md	What it is, prerequisites, quick start, links to full docs
CLAUDE.md / AGENTS.md	AI coding agent context, generated from templates/CLAUDE.md.template
.gitignore	Start from templates/repo-scaffold/.gitignore.template
LICENSE	MIT for open-source, proprietary for internal HCS tooling

Required docs/ structure

docs/
├── index.md                    # Landing page
├── standards/                  # If the repo has its own standards extensions
└── architecture/               # draw.io + PNG diagrams
    ├── overview.drawio
    └── overview.png

Required directory structure if deploying infrastructure

config/
├── variables.example.yml       # Template with all keys, no secret values
└── variables.yml               # Local override — gitignored, never committed

---

Issue management model

Classification — use GitHub-native types and fields, not type/*/priority/* labels

Superseded 2026-07-14. This section previously defined a type/* + priority/* label taxonomy. GitHub now ships this natively — see github-issues.md for the full standard:

• Type → GitHub's native issue type field: Bug, Feature, Task. Don't add a type/* label.
• Priority → GitHub's native issue field Priority. Don't add a priority/* label.
• Effort, Start date, Target date → also native fields, used where relevant.

Remaining reserved labels (workflow-only, not type/priority — see github-issues.md for the full set and who sets them): needs-triage, ado-tracked, in-progress, resolved, wont-fix, roadmap, ado-managed, cross-repo. Do not invent new type/*, priority/*, or status/* labels — use the native fields, or add a genuinely new workflow label to github-issues.md via a PR first.

Milestones

Milestones group issues by delivery phase within a repo. They answer "when does this land?" — not "what kind of work is this?"

Each repo defines milestones that match its delivery phases. Common pattern:

• Planning — architecture, design, pre-implementation
• Foundation — core scaffolding, required files, CI setup
• V1 — first functional release
• Post-V1 — extensions and backlog

Every issue representing planned delivery work should have a milestone. Housekeeping issues may omit one.

Tracker issues

For large workstreams, open a single tracker issue that lists sub-tasks as checkboxes. This gives a single URL to share that shows overall progress. Link child issues with AB#<id> in the body.

## Scope

This issue tracks all work for the platform engineering repo scaffold.

## Tasks

- [x] AB#101 — Scaffold required root files
- [x] AB#102 — Write identity documentation
- [ ] AB#103 — Standards documentation complete
- [ ] AB#104 — Templates finalized

---

Release model

All HCS repos that ship versioned artifacts use release-please for automated changelog generation and release management.

How it works

1. Contributors use conventional commits when merging to main.
2. Release-please reads commit messages and maintains an open release PR that updates CHANGELOG.md and bumps the version.
3. When the release PR is merged, release-please creates a release and tag.

Required files

File	Purpose
CHANGELOG.md	Maintained by release-please. Do not edit manually.
release-please-config.json	Release-please configuration.
.release-please-manifest.json	Version tracking manifest.

release-please-config.json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "simple",
  "bump-minor-pre-major": true,
  "changelog-sections": [
    { "type": "feat",     "section": "Features" },
    { "type": "fix",      "section": "Bug Fixes" },
    { "type": "docs",     "section": "Documentation" },
    { "type": "chore",    "section": "Chores", "hidden": false }
  ]
}

Exceptions

Repos that are purely documentation, experimental, or have no versioned artifact may omit release-please. Document the exception in the repo's README.md.

---

Scope overlays

The rules above are the base (hcs) governance standard and apply to every HCS-governed repo by default. Two scopes carry overlays that extend or adjust specific rules for the platform they live on. Overlays never replace the base — they add scope-specific detail on top of it, and are resolved at read time from each scope's own source (see docs/standards/_scopes/README.md for the sync model).

Scope	Overlay covers	Where it lives
azurelocal	GitHub-centric repository management: release-please release flow, org Project board, type/* + priority/* + solution/* issue labels, per-repo milestones	AzureLocal platform repo (docs/standards/repository-management.md), staged into _scopes/azurelocal/governance.md
tierpoint-prodtech	GitLab-centric repository management: GitLab Issues + Milestones, type::* + priority::* + solution::* scoped labels, GitLab group structure and permissions	prodtech docs repo (docs/.../standards/repository-management.mdx), staged into _scopes/tierpoint-prodtech/governance.md

The AB#<id> commit/PR link convention and conventional-commit format are universal — they apply in all scopes regardless of the issue-tracking surface. Do not reproduce overlay content here; each scope's specifics are authored in that scope's own repo and pulled in by the MCP.

Note (2026-07-14): the hcs base scope's own label taxonomy above was rewritten to use GitHub's native issue types/fields instead of type/*/priority/* labels (see github-issues.md). The azurelocal overlay's own label scheme (type/*/priority/*/solution/*, sourced from its own repo) is unaffected by this change — it is that scope's own choice to migrate or not, and is out of this repo's control.