| description | version | last_updated | owners | tags | references | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Central hub for all shared GitHub templates, Copilot instructions, workflow automation, labeling systems, and community health files across the LightSpeed WordPress organisation |
3.0 |
2025-10-24 |
|
|
|
Central hub for all shared GitHub templates, Copilot instructions, workflow automation, labeling systems, and community health files across the LightSpeed WordPress organisation.
- Purpose and GitHub Template Ecosystem Overview
- Usage & Quickstart
- Validation & Testing
- Change Log / History
- FAQ / Troubleshooting
- Limitations & Notes
- Labelling and Automation
- Folder Structure and Organization Flow
- Comprehensive Workflow Integration
- Community & Q&A
- Contribution Guidelines & Instruction Index
- Related Root-Level Organisation Files
- Best Practices
- License
This repository's .github folder serves as the single source of truth for all organisation-wide community health files, automation rules, standards, and AI/Copilot instructions for LightSpeed projects. By centralising these files, we ensure consistency, discoverability, and maintainability across every repo in the organisation.
flowchart TB
subgraph "🏛️ .github Repository Hub"
A[🏠 Community Health Files]
B[📝 Issue Templates]
C[🔄 PR Templates]
D[🤖 AI Instructions]
E[⚙️ Automation Rules]
F[🔧 Workflows]
end
subgraph "📋 Template Categories"
G[🐛 Bug Reports]
H[✨ Feature Requests]
I[📚 Documentation]
J[🏗️ Architecture]
K[🔒 Security]
L[🧪 Testing]
end
subgraph "🤖 AI & Automation"
M[📊 Auto-Labeling]
N[🎯 Project Sync]
O[🔍 Quality Gates]
P[🚀 Deployment]
Q[📈 Analytics]
end
subgraph "🌐 Organization Repos"
R[Member Repository 1]
S[Member Repository 2]
T[Member Repository N]
end
A --> G
B --> H
C --> I
D --> M
E --> N
F --> O
M --> R
N --> S
O --> T
P --> R
Q --> S
style A fill:#e1f5fe
style D fill:#fce4ec
style M fill:#e8f5e8
style R fill:#fff3e0
Key goals:
- Standardise contribution, code quality, review, and labelling across all repos.
- Automate issue/PR labelling, project syncing, and governance.
- Provide a canonical set of instructions for AI agents & Copilot.
- Centralise saved replies, prompts, chatmodes, and reusable workflows.
- Enable fast onboarding and safe, scalable development.
See GitHub: About organisation-wide community health files and Creating a default community health file for your organization for more context.
Organizations can add community health files to a specially named .github repository, which then serves as the organisation-wide default for all repositories. You can include CONTRIBUTING, SUPPORT, CODE_OF_CONDUCT, ISSUE_TEMPLATE(S), or PULL_REQUEST_TEMPLATE(S) files here. If a repository does not have its own version of a given file, the org-wide default from .github will be surfaced throughout developer workflows (e.g., when opening issues or PRs, or via the Community Profile), as if it were committed directly to that repo.
While the file itself won’t appear in the file browser or Git history for each repository, it will be surfaced throughout developers’ workflows, such as when opening a new issue or when viewing the Community Profile, just as if it were committed to the repository directly.
Follow these steps to onboard and use this repository effectively across the organisation:
- Reference issue and PR templates automatically surfaced when creating new items in any repo without overrides.
- Use files in
instructions/before starting development to align with standards. - For AI-assisted workflows, load prompts from
prompts/and chat modes fromchatmodes/. - Reusable workflows in
workflows/can be invoked viauses:in member repositories. - Update labels or labeler rules only in
automation/to propagate consistency. - Add or adjust saved replies in
SAVED_REPLIES/for common maintainer responses. - Consult
AGENTS.md,GEMINI.md, orCLAUDE.mdbefore modifying AI agent behavior.
To override an org-wide template in a member repository, add a local copy there; GitHub will prefer the repo-local version.
This repository participates in organisation validation via:
- Frontmatter validation (schema enforcement for instructions, prompts, agents).
- Workflow linting (reusable Actions syntax integrity).
- Markdown linting (heading style, spacing, list formatting).
Run validation scripts (example command structure shown; adjust to actual tooling):
# Run all tests and validation (example)
./scripts/run-all-tests.sh
# Validate frontmatter across .github folders (placeholder)
node scripts/validation/validate-frontmatter.js .github/Version: 3.0 (see version frontmatter field)
Last Updated: 2025-10-24
Refer to the organisation-wide CHANGELOG.md for historical changes impacting templates, automation, or agent instructions.
Templates not appearing in a repo? Ensure the target repository does not already have local conflicting templates.
Labels didn’t auto-apply? Confirm the path/branch patterns in automation/labeler.yml match the change set and that the workflow ran.
How do I add a new chat mode? Create or update chatmodes/chatmodes.md and reference it in custom-instructions.md if globally relevant.
Agent behavior seems outdated? Check AGENTS.md and the specific agent file in agents/ for version updates; bump the frontmatter version when modifying logic.
Prompts aren’t producing expected reviews? Verify prompt file frontmatter fields and ensure correct model/tool configuration is active.
- Org-wide defaults are only applied when a member repo lacks local overrides.
- Saved replies are not automatically synced to external tooling—manual updates required.
- AI agent guidance documents rely on maintainers to enforce version discipline.
- Frontmatter validation coverage may expand; some legacy files might need retrofitting.
This repository is the canonical, organisation-wide source for:
- Labels (automation/labels.yml): Official label names, colours, and descriptions.
- Labeler Rules (automation/labeler.yml): Automation for applying labels based on file paths, branch names, or PR type.
- Issue Types (automation/issue-types.yml): Machine-readable definitions mapping issue templates, types, and automation.
sequenceDiagram
participant Dev as 👨💻 Developer
participant Repo as 📁 Member Repo
participant Hub as 🏛️ .github Hub
participant Auto as 🤖 Automation
participant PM as 📊 Project Manager
Dev->>Repo: Create Issue/PR
Repo->>Hub: Check for templates
Hub-->>Repo: Provide templates
Repo->>Auto: Trigger labeling
Auto->>Hub: Get label rules
Hub-->>Auto: Return config
Auto->>Repo: Apply labels
Auto->>PM: Sync to projects
PM-->>Dev: Notify assignment
How it works:
- Labels, labeler, and issue types from this repo are referenced by reusable workflows and automation across all LightSpeed repositories.
- If a repository does not have its own label or labeler config, the defaults from this repo apply.
- Automated labelling ensures consistent triage, prioritisation, and project management across the organisation.
- Maintainers should update labels and labeler rules here to synchronise org-wide conventions.
- For more detail, see AUTOMATION_GOVERNANCE.md and ISSUE_LABELS.md.
Quick links:
The .github folder is organised for maximum clarity and modularity, grouping related files for easy reference and automation.
graph TB
subgraph "📁 .github/ Directory Structure"
A[📋 instructions/]
B[🎯 prompts/]
C[💬 chatmodes/]
D[🤖 agents/]
E[⚙️ workflows/]
F[📝 ISSUE_TEMPLATE/]
G[🔄 PULL_REQUEST_TEMPLATE/]
H[💾 SAVED_REPLIES/]
I[🔧 automation/]
end
subgraph "📋 Instructions Ecosystem"
A1[coding-standards.instructions.md]
A2[linting.instructions.md]
A3[html-template.instructions.md]
A4[pattern-development.instructions.md]
A5[php-block.instructions.md]
A6[theme-json.instructions.md]
end
subgraph "🤖 AI Integration Hub"
B1[accessibility-review.prompt.md]
B2[code-review.prompt.md]
B3[pattern-generation.prompt.md]
C1[chatmodes.md]
D1[agent.md]
end
subgraph "⚙️ Automation Core"
I1[labels.yml]
I2[labeler.yml]
I3[issue-types.yml]
I4[AUTOMATION_GOVERNANCE.md]
E1[labels-issues-prs.yml]
E2[project-meta-sync.yml]
end
A --> A1
A --> A2
A --> A3
A --> A4
A --> A5
A --> A6
B --> B1
B --> B2
B --> B3
C --> C1
D --> D1
I --> I1
I --> I2
I --> I3
I --> I4
E --> E1
E --> E2
style A fill:#e1f5fe
style B fill:#fce4ec
style I fill:#e8f5e8
style E fill:#fff3e0
.github/
├── instructions/ # Coding, linting, template, pattern, and workflow instructions
│ ├── coding-standards.instructions.md
│ ├── linting.instructions.md
│ ├── html-template.instructions.md
│ ├── pattern-development.instructions.md
│ ├── php-block.instructions.md
│ ├── theme-json.instructions.md
│ └── ... (topic-specific instructions)
│
├── prompts/ # AI prompt templates (accessibility, code review, block patterns, etc.)
│ └── *.prompt.md
│
├── chatmodes/ # Chat mode indexes & usage guides for Copilot/agents
│ └── chatmodes.md
│
├── agents/ # Agent specs and agentic workflow documentation
│ └── agent.md
│
├── workflows/ # Reusable GitHub Actions workflows
│ ├── labels-issues-prs.yml
│ ├── project-meta-sync.yml
│ └── ... (other workflows)
│
├── ISSUE_TEMPLATE/ # Issue templates for bugs, features, docs, tasks, etc.
│ └── *.md
│
├── PULL_REQUEST_TEMPLATE/ # Pull request templates (feature, fix, docs, etc.)
│ └── *.md
│
├── SAVED_REPLIES/ # Canonical saved replies for support and triage
│ └── SAVED_REPLIES.md
│
├── automation/ # Labeler rules, automation governance, branching, etc.
│ ├── labeler.yml
│ ├── labels.yml
│ ├── issue-types.yml
│ ├── AUTOMATION_GOVERNANCE.md
│ ├── BRANCHING_STRATEGY.md
│ └── ... (automation reference files)
│
├── custom-instructions.md # Org-wide Copilot and agent instructions
├── AGENTS.md # Global agent rules and contribution principles
├── GEMINI.md # Gemini agent guidance
├── CLAUDE.md # Claude agent guidance
├── README.md # This file: folder overview and usage
└── ... (other shared files)
This diagram illustrates how all components work together to create a seamless development and governance experience across the LightSpeed organization.
flowchart LR
subgraph "👨💻 Developer Experience"
A[New Contributor]
B[Issue Creation]
C[PR Submission]
D[Code Review]
end
subgraph "🏛️ .github Hub Resources"
E[📋 Instructions]
F[📝 Templates]
G[🤖 AI Prompts]
H[💬 Chat Modes]
I[⚙️ Automation]
end
subgraph "🔄 Automated Processes"
J[🏷️ Auto-Labeling]
K[📊 Project Sync]
L[🔍 Quality Gates]
M[📈 Analytics]
end
subgraph "🎯 Quality Outcomes"
N[✅ Consistent Standards]
O[🚀 Faster Onboarding]
P[📊 Better Tracking]
Q[🛡️ Security Compliance]
end
A --> E
A --> F
B --> G
C --> H
D --> I
E --> J
F --> K
G --> L
H --> M
I --> J
J --> N
K --> O
L --> P
M --> Q
style A fill:#e1f5fe
style E fill:#f3e5f5
style J fill:#e8f5e8
style N fill:#c8e6c9
- Instructions: The
instructions/folder contains canonical, versioned standards for coding, linting, HTML templates, WordPress pattern development, PHP blocks, and theme configuration. Always reference these before starting work or reviewing code. - Prompts & Chat Modes: Modular prompt templates and chat modes designed for Copilot, Gemini, Claude, and custom agents—enabling consistent AI-assisted workflows and reviews.
- Agents: Agent specs and rules (see
AGENTS.md,GEMINI.md,CLAUDE.md) detail expected behaviour, standards, and escalation procedures for all automated or AI contributors. - Workflows & Automation: Includes reusable GitHub Actions workflows for labelling, project syncing, and more. The
automation/folder covers label rules, branching, and governance files. - Templates: Issue and PR templates standardise reporting, changelog, and review for all repos, supporting automation and reducing triage effort. Saved replies help maintainers respond consistently.
- Custom Instructions: The root-level
custom-instructions.mdand agent files define Copilot/AI behaviour org-wide, so all automated actions and suggestions follow LightSpeed rules. - Discoverability & Onboarding: All files are indexed, referenced, and cross-linked for easy discoverability. New contributors can start in this folder and be directed to relevant standards, templates, or automation docs.
Have questions, feedback, or want to propose an idea? Visit our GitHub Discussions for open conversation and community support.
For all contributors, please reference these key guidelines and indexes:
- LightSpeed General Copilot Instructions
- Coding Standards
- HTML Templates
- Pattern Development
- PHP Block Instructions
- Theme JSON
- When generating a summary for pull requests, use this pull request template.
- Always start here when onboarding, contributing, or reviewing.
- Reference instructions for standards, templates for issues/PRs, and automation docs for workflows and governance.
- Use saved replies for common support scenarios; update them as needed.
- For agent/Copilot questions, see the agent guides and custom instructions.
- Update this folder when org-wide standards, workflows, or automation rules change.
To ensure a consistent development experience and code quality, all contributors should:
- Install all recommended extensions from
.vscode/extensions.json(includes ESLint, Prettier, YAML, WordPress, PHP, AI, and GitHub workflow tools). - Use the workspace settings in
.vscode/settings.jsonfor code style, linting, and workflow automation. These settings align with.editorconfigand enforce 2-space indentation for YAML, JS, CSS, and JSON, and 4-space tabs for PHP. - Enable format-on-save and linting in your editor for best results.
- Periodically review and update your extensions to match evolving project standards.
Refer to .vscode/extensions.json and .vscode/settings.json for the authoritative list and configuration.
To ensure a consistent and standards-driven development experience, this repository includes a dedicated .vscode/ folder with:
- Recommended Extensions: See
extensions.jsonfor AI, linting, WordPress, PHP, and GitHub workflow tools. - Workspace Settings: See
settings.jsonfor formatting, linting, and file association rules that align with org standards. - Predefined Tasks: See
tasks.jsonfor running tests, linting, and E2E automation. - Debug & Automation: Includes launch configs and Model Context Protocol (MCP) server integration for advanced automation and E2E testing.
For a full overview, see
.vscode/README.md.
All contributors should open the project in VS Code to automatically apply these settings and see extension recommendations.
These files typically reside in the root of the repository for visibility but are managed from this .github folder:
- README.md — High-level overview of the organisation and community health repository.
- CONTRIBUTING.md — Full contribution guidelines (reference .github/instructions/ for standards).
- CODE_OF_CONDUCT.md — Organisation code of conduct, aligned with WordPress community standards.
- SECURITY.md — Security policy and responsible disclosure instructions.
- SUPPORT.md — Support policy and contact details.
- GOVERNANCE.md — Maintainer and contributor governance, responsibilities, and process.
- CHANGELOG.md — Keep-a-Changelog format, linking to standards and change log instructions.
- DEVELOPMENT.md — Developer setup, scripts, linting, and workflow guidance.
Reference and update these root-level files as needed, but maintain canonical instructions, templates, and workflows in .github/.
- Modularity: Reuse files as much as possible across repos; avoid duplication.
- Discoverability: Cross-link instructions, templates, and automation docs.
- Automation: Use labeler, workflows, and governance rules for consistent triage and release.
- Security & Accessibility: Adhere to WordPress standards and OWASP top 10 in every template, instruction, and workflow.
- AI/Copilot Enablement: Leverage prompts, agent rules, and custom instructions to optimise AI-powered workflows safely.
This repository and all its contents are licensed under the GNU General Public License v3.0 — see the LICENSE file.
- 🏠 Main Repository README - Organization overview and repository purpose
- 🤝 Contributing Guidelines - Complete contribution process and standards
- 🛡️ Code of Conduct - Community standards and expectations
- 🆘 Support Policy - Getting help and support resources
- 🧠 AI Agents Overview - Global AI rules and agent specifications
- 💬 Custom Instructions - Organization-wide Copilot settings
- 🎯 Prompt Library - Reusable AI prompts and templates
- 💭 Chat Modes - Specialized AI conversation modes
- 🏷️ Label Definitions - Canonical organization labels
- 🔧 Labeler Configuration - Automated labeling rules
- 📋 Issue Types - Standardized issue categorization
- ⚖️ Automation Governance - Automation standards and oversight
- 💻 Coding Standards - Unified development guidelines
- 🎨 Linting Instructions - Code quality and formatting
- 🏗️ Pattern Development - WordPress block patterns
- 🌐 HTML Templates - Semantic markup standards
🏛️ This directory is managed by the LightSpeed team. All organizational GitHub templates, automation, and AI resources are maintained here.
❓ Questions? Open an issue, start a Discussion, or contact support@lightspeedwp.agency