[Documentation] Define adoption policy

[ashleyshaw]

---

title: "[Audit] Define adoption policy"
type: "Audit"
parent_issue: 17
labels:

• "area:documentation"
• "priority:normal"
• "status:needs-triage"

---

Task Summary

Audit and define the organisation-wide adoption policy for files and defaults managed from this .github repository.

This issue should establish the decision rules maintainers need before writing the adoption guide: what must be adopted into consuming repositories, what is recommended, what is optional, and what must remain repo-local to avoid copying the wrong assets into product repositories.

This sits under #17, which is focused on creating a practical repo adoption guide for shared .github defaults. This audit issue should provide the policy baseline that guide content depends on.

Goal

Produce a clear, low-maintenance adoption policy that:

• classifies reusable .github assets by adoption level
• defines what should stay only in the control-plane .github repo
• explains the boundary between shared defaults and repo-specific customisation
• gives maintainers a safe basis for onboarding new repos and updating existing ones

Why this matters

The parent issue identifies a recurring problem: maintainers should not have to manually guess which files belong in a consuming repo, which are optional, or which should never be copied.

Without an explicit policy:

• adoption stays inconsistent across repositories
• repo-local conventions can be overwritten by mistake
• automation becomes risky because the source-of-truth boundaries are unclear
• future guide or script work becomes harder to maintain

A documented policy keeps the eventual adoption guide small, practical, and safer to follow.

Audit Scope

Review the current contents of this repository and classify assets into categories such as:

• mandatory: expected in most or all consuming repositories
• recommended: useful defaults, but not essential in every repo
• optional: situational files or configurations
• repo-local only: must remain in the .github repository or another specific repo and should not be copied generally

The audit should consider areas including, where present:

• issue templates
• pull request templates
• discussion templates
• saved replies or contributor guidance
• labels / labeler or label config
• reusable workflows versus repo-specific workflows
• governance and community-health files
• repo instruction files such as AGENTS.md and .github/custom-instructions.md
• any files that are examples, internal controls, or not intended for downstream adoption

Acceptance Criteria

• A documented adoption policy is defined for files managed in this .github repository
• The policy distinguishes mandatory, recommended, optional, and repo-local only assets
• The policy explains the reasoning for each category in terms of maintenance cost, portability, and risk
• The policy identifies any files that should explicitly not be copied into consuming repositories
• The policy notes where repo-specific override/customisation is expected
• The policy is written in UK English and aligned with existing org guidance
• Any gaps, ambiguities, or follow-up work discovered during the audit are captured
• Output is suitable to feed directly into the adoption guide work in [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17

Steps / Checklist

• Audit current reusable and non-reusable assets in this repository
• List candidate files and directories intended for downstream adoption
• Identify files that are control-plane only or otherwise repo-local
• Define classification rules for:
  • mandatory
  • recommended
  • optional
  • repo-local only
• Document the decision criteria behind each classification
• Note any areas where copying should be avoided in favour of linking, documenting, or selectively recreating
• Identify any risky or ambiguous files that need a follow-up decision
• Summarise findings in a format that can be reused by the adoption guide issue

Dependencies

• Parent issue: [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17
• Related organisation guidance in AGENTS.md
• Related repo instructions in .github/custom-instructions.md
• May inform or unblock other sub-issues under [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17 covering implementation guidance, validation, or automation boundaries

Additional Context

The parent task is intentionally aiming for the smallest maintainable solution. This audit should follow the same principle.

Prefer policy decisions that reduce ambiguity and ongoing maintenance burden. If a file or workflow is not clearly portable, the default should be to treat it as repo-local unless there is a strong reason and clear ROI for standardising it across repos.

This issue should provide the policy layer first, so later documentation or helper-script work does not have to guess the source-of-truth boundaries.

Definition of Ready (DoR)

• Scope is clear
• Parent issue linked
• Audit output format is clear enough to act on
• Any relevant existing sub-issues reviewed for overlap

Definition of Done (DoD)

• Adoption policy documented and agreed
• Reusable vs repo-local boundaries are explicit
• Follow-up issues created for any gaps or edge cases found during the audit
• Findings are ready to feed into the adoption guide in [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17
• PR uses the correct branch prefix if completed via PR

[linear-code]

LS-658