markbac · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git a/content/guidelines/ai-agent-usage.md b/content/guidelines/ai-agent-usage.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-005: AI agent usage
+# AI agent usage
 
 - **Owner:** Build and tooling lead and Security lead
 - **Applies to:** All use of AI coding agents and assistants on team repositories
@@ -113,6 +113,26 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov
 - [ ] `AGENTS.md` names CP-02, CP-16 and CP-20 (AGT-14)
 - [ ] Agent-written documentation is checked by a human against the code or design (AGT-15)
 
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] `AGENTS.md` exists at the repository root with commands, conventions, boundaries and definition of done (AGT-01, AGT-02)
+- [ ] Agent changes follow the same commit, PR, review and CI rules as human changes (AGT-03)
+- [ ] A human approves every agent-authored change, and agents never approve or merge their own work (AGT-04)
+- [ ] Agent boundaries are protected by CODEOWNERS or branch protection (AGT-05)
+- [ ] AI-assisted commits carry an `Assisted-by:` trailer (AGT-06)
+- [ ] The submitter understands and can explain every line submitted (AGT-07)
+- [ ] An approved-tools register lists each tool and the data classes it may receive (AGT-08)
+- [ ] Agents run local checks first and the PR includes the evidence (AGT-09)
+- [ ] Large agent diffs are split or accompanied by a summary of intent and risk (AGT-10)
+- [ ] Agent-generated tests are reviewed for whether they verify requirements (AGT-11)
+- [ ] Shared prompts, agent configuration and skills are versioned and reviewed (AGT-12)
+- [ ] Licence and provenance of generated code is handled under the technology guideline (AGT-13)
+- [ ] `AGENTS.md` names CP-02, CP-16 and CP-20 (AGT-14)
+- [ ] Agent-written documentation is checked by a human against the code or design (AGT-15)
+```
+
+
 ## Applying to personal projects and AI agents
 
 ### Personal projects

diff --git a/content/guidelines/architecture-principles.md b/content/guidelines/architecture-principles.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-007: Architecture principles governance
+# Architecture principles governance
 
 - **Owner:** Architecture group
 - **Applies to:** Architecture governance and decision-making across products and teams
@@ -70,3 +70,13 @@ Automated Pipeline Enforcement (CI Check / Architecture Review / ADR)
 - [ ] ADRs and RFCs cite business principle IDs (PRN-01)
 - [ ] Deviations from business principles are recorded in ADRs with trade-off rationale (PRN-02)
 - [ ] Automated architecture rules (budgets, dependency direction) run in CI pipeline (PRN-04)
+
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] Active business principles are selected from [Business Principles](business-principles.md) for the product (PRN-05)
+- [ ] ADRs and RFCs cite business principle IDs (PRN-01)
+- [ ] Deviations from business principles are recorded in ADRs with trade-off rationale (PRN-02)
+- [ ] Automated architecture rules (budgets, dependency direction) run in CI pipeline (PRN-04)
+```
+
diff --git a/content/guidelines/business-principles.md b/content/guidelines/business-principles.md
@@ -1,4 +1,8 @@
-# Business & Vertical Principles Overview
+---
+title: Business and vertical principles
+---
+
+# Business and vertical principles
 
 ## Generic Guidelines vs. Business & Vertical Principles
 

diff --git a/content/guidelines/checklists.md b/content/guidelines/checklists.md
diff --git a/content/guidelines/coding-principles.md b/content/guidelines/coding-principles.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-012: Coding principles governance
+# Coding principles governance
 
 - **Owner:** Firmware and Software lead
 - **Applies to:** Code development by human engineers and AI agents

diff --git a/content/guidelines/coding-standard.md b/content/guidelines/coding-standard.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-013: Coding standard
+# Coding standard
 
 - **Owner:** Firmware lead
 - **Applies to:** All languages used in product and tooling code
@@ -87,6 +87,24 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov
 - [ ] A quick reference, review checklist and agent rule list exist (COD-11)
 - [ ] Scripts and tooling code also have a proportionate standard (COD-12)
 
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] There is one coding standard per language in use, with rule IDs that cite principles (COD-01)
+- [ ] Language version, subset and compiler are specified (COD-02)
+- [ ] The standard covers every required topic or says why not (COD-03)
+- [ ] The formatter is configured in the repository and checked in CI (COD-04)
+- [ ] Static analysis is configured and pinned, warnings are errors, and suppressions are justified and audited (COD-05)
+- [ ] Rules are classified mandatory, required or advisory, with a deviation log (COD-06)
+- [ ] Each rule has a rationale, examples and a checking tool (COD-07)
+- [ ] Compiler flags are standardised and identical locally and in CI (COD-08)
+- [ ] A legacy baseline is tracked and there is no drive-by reformatting (COD-09)
+- [ ] The standard is reviewed annually through RFC (COD-10)
+- [ ] A quick reference, review checklist and agent rule list exist (COD-11)
+- [ ] Scripts and tooling code also have a proportionate standard (COD-12)
+```
+
+
 ## Applying to personal projects and AI agents
 
 ### Personal projects

diff --git a/content/guidelines/competence-tooling-and-onboarding.md b/content/guidelines/competence-tooling-and-onboarding.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-026: Competence, tooling and onboarding
+# Competence, tooling and onboarding
 
 - **Owner:** Engineering manager
 - **Applies to:** All team members, all sites, and all tools and domains used
@@ -81,6 +81,25 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov
 - [ ] The team is trained in safe and effective use of AI agents (CMP-12)
 - [ ] New tools are introduced with training and a radar update (CMP-13)
 
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] A competence matrix covers languages, RTOS, platforms, protocols, tools, domains, security and test (CMP-01)
+- [ ] Single-person areas are tracked as risks (CMP-02)
+- [ ] Expected depth per tool is defined and used in training (CMP-03)
+- [ ] Each tool and domain area has a champion and a how-to page (CMP-04)
+- [ ] Domain experts and deputies are named and primers written (CMP-05)
+- [ ] An onboarding path is documented and the environment is set up in under one day (CMP-06)
+- [ ] Environment setup is tested in CI (CMP-07)
+- [ ] An annual training plan has protected learning time (CMP-08)
+- [ ] Knowledge sharing is regular and sessions are recorded (CMP-09)
+- [ ] Rationale is captured in ADRs and docs, and a handover checklist exists for leavers (CMP-10)
+- [ ] Key areas are known at two or more sites (CMP-11)
+- [ ] The team is trained in safe and effective use of AI agents (CMP-12)
+- [ ] New tools are introduced with training and a radar update (CMP-13)
+```
+
+
 ## Applying to personal projects and AI agents
 
 ### Personal projects

diff --git a/content/guidelines/components-reuse-and-variants.md b/content/guidelines/components-reuse-and-variants.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-010: Components, reuse and variants
+# Components, reuse and variants
 
 - **Owner:** Architecture group
 - **Applies to:** Every component, whether built in the product, reused from another product, or third party
@@ -92,6 +92,25 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov
 - [ ] Transfer, deprecation and retirement are recorded and communicated (COM-12)
 - [ ] Consumers report through the owner's tracker and severity 1 and 2 defects are visible to all consumers (COM-13)
 
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] A component register lists every component with owner, repository, version, status and consumers (COM-01)
+- [ ] Every component has a named owner and deputy (COM-02)
+- [ ] Consumers depend on released, pinned versions and never on branches or unreleased commits (COM-03)
+- [ ] Interfaces follow the interface guideline and versions follow semantic versioning (COM-04)
+- [ ] The register is checked before building or copying, and forks are recorded in an ADR (COM-05)
+- [ ] Consumers do not patch components locally, and contribute changes through the owner (COM-06)
+- [ ] Changes affecting several consumers are assessed for impact, with migration guidance and deprecation notice (COM-07)
+- [ ] Each component builds and tests on its own and publishes versioned artefacts (COM-08)
+- [ ] Variation is expressed through documented variation points, and supported variants are recorded (COM-09)
+- [ ] Each product's bill of materials lists component versions (COM-10)
+- [ ] Supported combinations are tested and recorded in the compatibility matrix, and kept few (COM-11)
+- [ ] Transfer, deprecation and retirement are recorded and communicated (COM-12)
+- [ ] Consumers report through the owner's tracker and severity 1 and 2 defects are visible to all consumers (COM-13)
+```
+
+
 ## Applying to personal projects and AI agents
 
 ### Personal projects

diff --git a/content/guidelines/decision-records.md b/content/guidelines/decision-records.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-008: Decision records: RFCs and ADRs
+# Decision records: RFCs and ADRs
 
 - **Owner:** Architecture group
 - **Applies to:** All significant technical, process and guideline decisions
@@ -141,6 +141,28 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov
 - [ ] An architecture forum meets on a fixed cadence and every RFC is decided, or deferred with a reason, by its decision date (RFC-11)
 - [ ] Architecture review is limited to architecturally significant changes, and other decisions belong to component owners (RFC-12)
 
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] ADRs live in `docs/adr/`, are numbered and use the template (ADR-01, ADR-02)
+- [ ] ADRs are proposed by PR and merged as `accepted` (ADR-03)
+- [ ] Accepted ADRs are immutable apart from status and links, and superseding ADRs point back (ADR-04)
+- [ ] At least two options and the reasons for rejection are recorded (ADR-05)
+- [ ] Consequences and verification are stated (ADR-06)
+- [ ] ADRs link to requirements, principles, RFCs and PRs, and commits use the `ADR:` footer (ADR-07)
+- [ ] ADRs are written before or during implementation, and retrospective ones are marked (ADR-08)
+- [ ] A decision log index is generated (ADR-09)
+- [ ] RFCs are used for guideline changes, cross-team interfaces, major tools and release changes (RFC-01)
+- [ ] RFCs are stored in `docs/rfc/`, proposed by PR, short, and discussed in writing by default (RFC-02, RFC-09, RFC-10)
+- [ ] Each RFC names an author, sponsor, affected teams, comment period and decision date (RFC-03, RFC-04)
+- [ ] Affected teams are notified explicitly (RFC-05)
+- [ ] Each RFC covers problem, goals, proposal, alternatives, impact, risks and open questions (RFC-06)
+- [ ] Outcome and rationale are recorded and ADRs created (RFC-07, RFC-08)
+- [ ] An architecture forum meets on a fixed cadence and every RFC is decided, or deferred with a reason, by its decision date (RFC-11)
+- [ ] Architecture review is limited to architecturally significant changes, and other decisions belong to component owners (RFC-12)
+```
+
+
 ## Applying to personal projects and AI agents
 
 ### Personal projects

diff --git a/content/guidelines/defects-and-technical-debt.md b/content/guidelines/defects-and-technical-debt.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-018: Defect and technical debt management
+# Defect and technical debt management
 
 - **Owner:** Test and quality lead
 - **Applies to:** All defects and technical debt in product and tooling
@@ -75,6 +75,25 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov
 - [ ] Suppressions and deviations are tracked as debt (DEF-12)
 - [ ] Metrics are used for improvement and not for ranking individuals (DEF-13)
 
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] All defects are in the tracker with the required fields (DEF-01)
+- [ ] Severity uses the agreed definitions, with priority set separately (DEF-02)
+- [ ] New defects are triaged within two working days (DEF-03)
+- [ ] The lifecycle is followed, verification is by someone else and closure needs a regression test (DEF-04)
+- [ ] Root cause analysis is done for severity 1 and 2 defects and escapes (DEF-05)
+- [ ] Each escape asks which gate should have caught it (DEF-06)
+- [ ] Commits reference defects and release notes list fixes and known issues (DEF-07)
+- [ ] A field defect route exists, with reproduction and release manager notification (DEF-08)
+- [ ] Technical debt is recorded with label, impact, estimate and owner (DEF-09)
+- [ ] Capacity is reserved for debt and old debt is reviewed (DEF-10)
+- [ ] Deliberate debt has a repayment plan and expiry (DEF-11)
+- [ ] Suppressions and deviations are tracked as debt (DEF-12)
+- [ ] Metrics are used for improvement and not for ranking individuals (DEF-13)
+```
+
+
 ## Applying to personal projects and AI agents
 
 ### Personal projects

diff --git a/content/guidelines/documentation-as-code.md b/content/guidelines/documentation-as-code.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-004: Documentation as code and terminology
+# Documentation as code and terminology
 
 - **Owner:** Build and tooling lead
 - **Applies to:** All documentation describing the product, its design or the way it is built
@@ -100,6 +100,26 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov
 - [ ] Approval is PR approval unless a regulation requires a signature record (DOC-14)
 - [ ] Documents are structured with headings, front matter and IDs so people and agents can navigate them (DOC-15)
 
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] Documents are plain-text Markdown in the repository and linted (DOC-01, DOC-02)
+- [ ] Documentation changes go through PR like code (DOC-03)
+- [ ] Changes to behaviour, interfaces, configuration and build steps update docs in the same PR (DOC-04)
+- [ ] Diagrams are Mermaid or PlantUML source (DOC-05)
+- [ ] Every document has front matter with owner, status and review date (DOC-06)
+- [ ] CI builds the docs, fails on broken links and lint errors, and publishes versioned docs with each release (DOC-07)
+- [ ] The minimum document set exists: README, CONTRIBUTING, `AGENTS.md`, architecture overview, build and test instructions, `docs/adr/` (DOC-08)
+- [ ] Generated docs are generated and never hand-edited (DOC-09)
+- [ ] Documents state their question and audience, and are split by purpose (DOC-10)
+- [ ] Writing is plain British English with the conclusion first (DOC-11)
+- [ ] A single glossary exists and terms are used consistently (DOC-12)
+- [ ] Naming conventions are followed for files, IDs and components (DOC-13)
+- [ ] Approval is PR approval unless a regulation requires a signature record (DOC-14)
+- [ ] Documents are structured with headings, front matter and IDs so people and agents can navigate them (DOC-15)
+```
+
+
 ## Applying to personal projects and AI agents
 
 ### Personal projects

diff --git a/content/guidelines/guidelines-governance.md b/content/guidelines/guidelines-governance.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-001: Guidelines governance
+# Guidelines governance
 
 - **Owner:** Architecture group
 - **Applies to:** All engineering teams, sites and agents
@@ -96,6 +96,26 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov
 - [ ] Core rules are marked and applied identically across products, and all other rules are tailored only through the product profile (GOV-15)
 - [ ] Each product has a conformance profile recording applicability, thresholds, exceptions, components and toolchain (GOV-16)
 
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] Guidelines live in `docs/guidelines/`, one file per guideline, named `eg-nnn-short-title.md` (GOV-13)
+- [ ] Every guideline has front matter with id, title, status, owner, version and review-by (GOV-01)
+- [ ] Every guideline follows the standard template and states how compliance is checked (GOV-02, GOV-04)
+- [ ] Rules have stable IDs and RFC 2119 keywords, with a rationale where it is not obvious (GOV-03)
+- [ ] Each guideline is short enough to read in one sitting, with examples where they help (GOV-05, GOV-11)
+- [ ] Changes are made by PR with owner and practitioner approval, and by RFC when material (GOV-06, GOV-07)
+- [ ] Review-by dates are checked by CI and no guideline is overdue (GOV-08)
+- [ ] Exceptions are recorded with owner, scope, reason and expiry (GOV-09)
+- [ ] Deprecated guidelines are kept with a pointer to their replacement (GOV-10)
+- [ ] Guideline versions follow semantic versioning (GOV-12)
+- [ ] The index is generated from front matter (GOV-13)
+- [ ] Each guideline has an accountable owner who handles questions and exception requests (GOV-14)
+- [ ] Core rules are marked and applied identically across products, and all other rules are tailored only through the product profile (GOV-15)
+- [ ] Each product has a conformance profile recording applicability, thresholds, exceptions, components and toolchain (GOV-16)
+```
+
+
 ## Applying to personal projects and AI agents
 
 ### Personal projects

diff --git a/content/guidelines/interfaces-and-co-design.md b/content/guidelines/interfaces-and-co-design.md
@@ -10,7 +10,7 @@ review-by: 2027-09-30
 supersedes:
 ---
 
-# EG-009: Interfaces and hardware and software co-design
+# Interfaces and hardware and software co-design
 
 - **Owner:** Architecture group
 - **Applies to:** All software, protocol, hardware and cross-site interfaces
@@ -78,6 +78,22 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov
 - [ ] Cross-site interface changes are announced with lead time (INT-10)
 - [ ] Vendor documents are version-controlled or cited by exact version (INT-11)
 
+**As Markdown.** To copy it into an issue, a pull request or a review record:
+
+```markdown
+- [ ] Every interface has an owner and a specification in the repository (INT-01, INT-02)
+- [ ] Machine-readable definitions generate code and docs, with no hand-maintained copies (INT-03)
+- [ ] Interfaces are versioned, a compatibility matrix is kept, and breaking changes go through RFC (INT-04)
+- [ ] Contract tests run on both sides in CI (INT-05)
+- [ ] The hardware interface agreement is versioned and firmware headers are generated where possible (INT-06)
+- [ ] Hardware changes are reviewed for firmware impact and recorded in the bill of materials (INT-07)
+- [ ] An errata register is maintained (INT-08)
+- [ ] A bring-up plan and emulation exist for new hardware (INT-09)
+- [ ] Cross-site interface changes are announced with lead time (INT-10)
+- [ ] Vendor documents are version-controlled or cited by exact version (INT-11)
+```
+
+
 ## Applying to personal projects and AI agents
 
 ### Personal projects