originals

Imported from lightspeedwp/.github (.github/reports/governance-audit-2026-09-14/originals/AGENTS.md). Install upstream with npx skills add lightspeedwp/.github --skill originals. Copyright stays with the author (GPL-3.0).

LightSpeed – Global AI Rules (AGENTS.md)

• Use UK English; optimise for clarity, scalability, maintainability and profitable outcomes.
• Prefer minimal, modular solutions; justify heavier tools with return on investment and maintenance cost.
• Follow WordPress Coding Standards (CSS, HTML, JavaScript, PHP) and inline‑documentation standards at all times.
• All code changes must include lint fixes, relevant tests and a short rationale summarising the change.
• Before creating or pushing branch changes, verify the target branch already exists and matches the PR branch; never create a new remote branch when the work is intended for an existing pull request.
• Any new scripts, modules, or utilities must have related tests in a matching __tests__/ subtree with the smallest focused coverage that exercises the changed behaviour.
• Never output secrets. Treat production and customer data as sensitive. Follow the OWASP top 10 for web security.
• Accessibility and performance are non‑negotiable; highlight potential issues during reviews.
• Prefer theme.json and block components over bespoke code when feasible to avoid vendor lock‑in.
• When unsure, propose safe defaults and ask one focused question to clarify requirements.
• Core instructions consolidated: see instructions/{languages,documentation-formats,quality-assurance,automation,community-standards}.instructions.md (mapping in MIGRATION_GUIDE.md).

Agent Directory

• See Main Agent Index for all agent implementations and specs.
• Each agent must have both a code file (.js, .py, etc.) and a spec (.md) following the template.
• All contributors must follow the org Coding Standards.

Agent Test Status

Note: As agents are developed and tested, this table will be updated with their status. ✅ indicates passing tests, ❌ indicates failing tests, and ⏳ indicates tests pending implementation.

Repository Scripts Organisation (CRITICAL)

ALL repository scripts MUST be placed in scripts/ at the root, NOT in .github/scripts/.

Correct Script Locations

✅ scripts/automation/        - Automation and workflow scripts
✅ scripts/metrics/           - Metrics collection and analysis
✅ scripts/telemetry/         - Telemetry instrumentation
✅ scripts/release/           - Release preparation and validation
✅ scripts/validation/        - Validation and linting scripts
✅ scripts/badges/            - Badge generation scripts
✅ scripts/agents/            - Agent runner scripts
✅ scripts/workflows/         - Agentic workflow orchestration

❌ .github/scripts/           - DO NOT CREATE - Reserved for GitHub governance only

The ONLY Exceptions

• .github/website/src/scripts/ - Website browser-specific JavaScript that runs client-side
• .github/agentic-workflows/ - Agent specifications for repository governance automation

Why This Matters

• .github/ is for GitHub-native governance files (templates, workflows, configs)
• scripts/ is for executable code that powers the repository
• Mixing these creates confusion about file ownership and purpose
• Import paths become inconsistent when scripts are in the wrong location

Enforcement

When creating any new script:

1. Check the script type: Is it automation, metrics, telemetry, release, etc.?
2. Place in correct subfolder: scripts/{category}/script-name.js
3. Known exceptions: .github/website/src/scripts/ (browser), .github/agentic-workflows/ (repo governance agents)
4. Never use .github/scripts/ - This directory should not exist for new work
5. Update imports: Ensure all imports use correct paths from scripts/

Quick Reference

Branch Naming Governance (CRITICAL)

All branches MUST follow this pattern: {type}/{scope}-{title}

This is enforced globally across all LightSpeed projects. See CLAUDE.md — Branch Naming for complete details, 34 allowed type values, examples, and why this matters.

Quick Reference

✅ Correct:

• feat/governance-audit-implementation
• fix/pr-template-routing-bug
• docs/branching-strategy-guide

❌ Forbidden (never use):

• claude/something — Reserved for Claude Code internal sessions
• copilot/something — Reserved for GitHub Copilot integration
• openai/something — Reserved for OpenAI integration

Why This Matters

Incorrect branch names cause:

1. PR template assignment failures
2. GitHub Actions workflow failures
3. Validation check failures
4. Downstream automation breaks

Before You Push

npm run validate:branch-name -- --branch <your-branch>

Full Reference

• Complete guidance: CLAUDE.md — Branch Naming (34 types, examples, consequences)
• Detailed rules: .github/instructions/branch-naming.instructions.md
• Strategy doc: docs/BRANCHING_STRATEGY.md
• Copilot-specific: .github/custom-instructions.md

Contribution Guidelines & Indexes

Consolidated Instructions (5 Files):

• languages.instructions.md - JS/TS, JSON, YAML, JSDoc, linting (consolidated 4 files)
• documentation-formats.instructions.md - Markdown, frontmatter, Mermaid, A11y (consolidated 3 files)
• quality-assurance.instructions.md - Testing, Jest, coverage, CI/CD (consolidated 3 files)
• automation.instructions.md - Agents, labeling, release, metrics (consolidated 8 files)
• community-standards.instructions.md - Files, naming, README, saved replies (consolidated 4 files)

🔒 Locked Configuration Files (CRITICAL)

The following files are FINAL and manually curated. Do NOT edit these without explicit approval from @ashley:

Why These Are Locked:

1. Label synchronization: Changes must sync across .github/labels.yml, GitHub org settings, automation workflows, and AI agent rules
2. Template routing: PR templates route by branch prefix; issue templates route by issue type. Breaking routing cascades across all workflows
3. Automation dependencies: 15+ GitHub Actions workflows, scripts, and AI agents depend on these configs
4. Data integrity: Changes affect 300+ existing issues and PRs; improper changes can corrupt label history

Process for Requesting Changes:

1. Open a GitHub issue with the appropriate tag:
   • [LABEL-UPDATE-REQUEST] — To add, modify, or remove labels
   • [ISSUE-TYPE-UPDATE-REQUEST] — To add, modify, or remove issue types
   • [TEMPLATE-UPDATE-REQUEST] — To add, modify, or remove templates
2. Describe:
   • The specific change needed
   • Why it's needed (business case, issue link, user feedback)
   • Any dependent systems it affects (workflows, agents, scripts)
   • Test plan for validation
3. Link to the following projects for context:
   • issue-and-pr-template-improvements
   • openspec-labels-automation
4. Wait for explicit approval from @ashley before implementing any changes

Last Updated:

• Labels: 2026-09-09 (158 labels, 8 families, OpenSpec phases included)
• Issue Types: 2026-09-09 (24 types aligned with GitHub native types)
• Templates: 2026-09-09 (26 issue, 19 PR templates with standardized frontmatter)

Label Creation Governance (CRITICAL)

When your code creates issues via gh issue create or GitHub API:

1. Always validate labels against canonical set (.github/labels.yml)
2. All labels MUST include family prefix:
   • type:* for issue classification (bug, feature, documentation, task, design, etc.)
   • status:* for workflow state (needs-triage, ready, in-progress, blocked, done, etc.)
   • priority:* for urgency (critical, important, normal, minor)
   • area:* for domain/component (ci, docs, security, labels, tests, scripts, etc.)
   • meta:* for automation markers (needs-changelog, has-pr, duplicate, etc.)

Example: Creating an issue with correct labels

# ✅ CORRECT — All labels use required prefixes
gh issue create \
  --title "Add support for new widget configuration" \
  --body "Users need to configure widgets via JSON..." \
  --label "type:feature" \
  --label "area:block-editor" \
  --label "priority:normal" \
  --label "status:needs-triage"

# ❌ INCORRECT — Bare labels without prefixes
gh issue create \
  --title "Add support for new widget configuration" \
  --body "Users need to configure widgets via JSON..." \
  --label "feature" \
  --label "block-editor" \
  --label "normal" \
  --label "needs-triage"

Validation Checklist

Before creating any issue programmatically:

• Each label exists in .github/labels.yml
• Each label includes its family prefix (type:, status:, area:, etc.)
• No bare labels (labels without colons are invalid)

Reference: .github/scripts/validation/validate-labels-before-creation.cjs

PR Templates

• Use the default PR template: .github/PULL_REQUEST_TEMPLATE.md
• Additional PR templates are available in: .github/PULL_REQUEST_TEMPLATE/
  • Use the template most relevant to your change (e.g. feature, fix, documentation, etc.)

Core Index Instructions

Start here for all key standards:

• Coding Standards Index: Unified standards, best practices, and documentation for all LightSpeed projects.
• Linting Instructions Index: Primary index and guidance for all linting rules, tools, and file-type-specific standards.

Cross-References & Discoverability

Label Creation Governance (CRITICAL)

For Programmatic Issue and PR Creation

When your code creates issues or PRs via gh issue create, gh pr create, or GitHub API:

1. Always validate labels against the canonical set (.github/labels.yml)
2. ALL labels MUST include family prefix — never apply bare labels
3. Prefix families and examples:
   • type:* — bug, feature, documentation, task, design, security, performance, a11y
   • status:* — needs-triage, ready, in-progress, blocked, review, done
   • priority:* — critical, high, normal, low
   • area:* — ci, docs, security, labels, tests, scripts, automation, etc.
   • meta:* — needs-changelog, has-pr, duplicate, needs-audit

Example: Creating an Issue with Correct Labels

# ✅ CORRECT — All labels use required prefixes
gh issue create \
  --title "Add support for new widget configuration" \
  --body "Users need to configure widgets via JSON..." \
  --label "type:feature" \
  --label "area:core" \
  --label "priority:normal" \
  --label "status:needs-triage"

# ❌ INCORRECT — Bare labels without prefixes (DO NOT USE)
gh issue create \
  --title "Add support for new widget configuration" \
  --body "Users need to configure widgets via JSON..." \
  --label "feature" \
  --label "core" \
  --label "normal" \
  --label "needs-triage"

Pre-Creation Validation Checklist

Before creating any issue or PR programmatically:

• Each label exists in .github/labels.yml
• Each label includes its family prefix (type:, status:, area:, priority:, meta:)
• No bare labels without colons
• Canonical case (lowercase, hyphens for spaces)

References

• Canonical labels: .github/labels.yml (158 prefixed labels)
• Label taxonomy: docs/LABEL_STRATEGY.md
• Labeling guide: docs/LABELING.md
• Governance audit: Issue #1592 — Label Prefix Enforcement

References

• Contributing Guidelines - For human contributors
• Main Documentation - Project overview
• Frontmatter Schema - Schema validation

This file is the canonical reference for all AI agent rules and coding standards in LightSpeedWP projects. All contributors, agents, and AI assistants must comply with these standards.

This page brought to you by the 🦄 Magic Automation Unicorns of LightSpeedWP. Automation Docs