[Task] Write and validate repo adoption guide with explicit checklists for shared .github files

[ashleyshaw]

---

name: "📝 Task"
about: "Document and standardise how repositories adopt shared .github defaults from the control-plane repository."
title: "[Task] Create repo adoption guide for shared .github defaults"
labels: [documentation, automation, onboarding]
assignees: [ashleyshaw]
projects: []
milestone: ""
file_type: task
type: Task

Task Summary

Create a practical adoption guide that explains how LightSpeed repositories should consume shared .github defaults from the lightspeedwp/.github control-plane repository.

The guide must reduce onboarding friction for both new and existing repositories by making it explicit:

• which files should be adopted
• which files must remain repo-local to .github
• where adopted files belong in a consuming repository
• how to update previously adopted files safely
• whether the recommended approach should be documentation only, a helper script, or a minimal combination of both

The solution should stay small, maintainable, and safe by default.

Problem Statement

Maintainers currently need to work out for themselves which .github files are reusable, which are repo-specific, and how to apply updates without overwriting local customisations.

This creates avoidable setup friction, inconsistent adoption across repositories, and a higher maintenance burden when shared defaults change.

Goals

• Provide one canonical adoption guide for shared .github defaults
• Make the reusable vs repo-local boundary explicit
• Define a low-maintenance adoption workflow for new and existing repositories
• Reduce the risk of copying the wrong files or clobbering repo-specific configuration
• Give maintainers a simple validation checklist after setup

Non-Goals

• Building a large bootstrap framework or complex automation system
• Moving existing files between top-level source folders and .github as part of this task
• Reorganising the repository structure without a separate migration issue
• Replacing repo-specific decisions with rigid global rules where local variation is expected

Acceptance Criteria

• A documented adoption guide exists for applying shared .github defaults to a new repository
• A documented adoption guide exists for applying shared .github defaults to an existing repository
• The guide clearly separates:
  • required files
  • recommended files
  • optional files
  • files that must remain only in lightspeedwp/.github
• The guide explains the purpose of each adopted file or file group
• The guide states the correct destination path for each adopted file or file group
• The guide explains how to review and apply updates without overwriting repo-specific customisations
• A recommended adoption workflow is defined and justified as one of:
  • checklist only
  • minimal helper script
  • checklist plus minimal helper script
• Any proposed script is narrow in scope, documented, and safe to run
• Validation steps are included so maintainers can confirm setup is correct
• Guidance is written in UK English and aligned with AGENTS.md and .github/custom-instructions.md
• Follow-up gaps, edge cases, or automation opportunities are captured as separate issues where needed
• Changelog entry prepared for PR if completed via PR
• Correct branch prefix for PR: chore/ or task/

Deliverables

• A canonical adoption guide in the appropriate documentation location
• A reusable file classification list covering required, recommended, optional, and repo-local-only assets
• A safe update workflow for consuming repositories
• A validation checklist for maintainers
• Optional: a minimal helper script if documentation alone is not sufficient

Implementation Tasks

1. Audit reusable and repo-local assets

• Review the current community-health and governance assets in lightspeedwp/.github
• Identify which assets are intended for reuse by consuming repositories
• Identify which assets are repo-local and must stay in the control-plane repository
• Confirm any ambiguous cases against current boundary rules in .github/custom-instructions.md

2. Define adoption scope

• Create a file inventory grouped by:
  • required
  • recommended
  • optional
  • do not copy / repo-local only
• Add a short justification for each group
• Note any exceptions or conditional adoption rules

3. Decide the smallest sustainable delivery format

• Compare:
  • documentation-only checklist
  • minimal helper script
  • checklist + helper script
• Choose the option with the lowest ongoing maintenance cost
• Document why heavier automation is not required unless there is clear ROI

4. Write the adoption guide

• Add guidance for new repositories
• Add guidance for existing repositories with partial adoption
• Add guidance for updating previously adopted files
• Explain how to preserve repo-specific customisations during updates
• Include worked examples where they improve clarity

5. Document file destinations and exclusions

• Specify target locations for key file groups such as:
  • issue templates
  • pull request templates
  • saved replies
  • labels or label configuration
  • workflows, where applicable
• Document what must not be copied into consuming repositories
• Add guardrails for repo-native vs portable assets

6. Define validation steps

• Document how maintainers confirm adoption is complete
• Document how maintainers confirm required files are in the correct paths
• Document how maintainers confirm repo-local customisations were preserved
• Document any manual verification needed for GitHub-native features

7. Review and hand-off

• Review the guide for clarity, accuracy, and maintenance cost
• Check alignment with organisation instructions and repository boundary rules
• Capture follow-up work as separate issues if needed
• Open PR with a concise rationale for the chosen approach

Validation Checklist

• Required adopted files are listed and mapped to destination paths
• Recommended and optional files are clearly distinguished
• Repo-local-only assets are explicitly marked as non-portable
• Update guidance includes a safe review step before overwriting files
• The final guidance is understandable without prior tribal knowledge
• The recommended workflow is the smallest viable solution

Dependencies

• AGENTS.md
• .github/custom-instructions.md
• Current boundary rules for reusable vs repo-local assets
• Existing issue, PR, saved reply, label, and workflow conventions in this repository

Risks / Considerations

• Reusable and repo-local boundaries may be misapplied if not documented clearly
• Over-automation could increase maintenance cost without enough ROI
• Consuming repositories may already have local conventions that should not be overwritten
• Some GitHub-native assets may need different handling from plain file copy workflows

Additional Context

This task should prefer a documentation-first solution unless a small helper script meaningfully reduces manual error without creating long-term maintenance overhead.

The output should help maintainers answer four questions quickly:

1. What should I adopt?
2. What should I leave in the control-plane repo?
3. Where do these files go?
4. How do I update them safely later?

---

Definition of Ready (DoR)

• Task described and scoped
• Relevant constraints and boundaries identified
• Estimate added if relevant

Definition of Done (DoD)

• Adoption guide completed and committed
• Reusable vs repo-local boundary documented clearly
• Any helper script is documented, scoped, and validated
• Validation steps included
• Follow-up issues created for anything out of scope
• Changelog entry prepared for PR
• PR uses correct branch prefix