Skip to content

Latest commit

 

History

History
340 lines (257 loc) · 15.9 KB

CLAUDE.md

File metadata and controls

340 lines (257 loc) · 15.9 KB
title LightSpeed .github — Claude Instructions
description Claude-specific project instructions for the LightSpeed .github repository.
version v1.0
last_updated 2026-05-20
file_type agents-index
maintainer LightSpeed Team

CLAUDE.md — LightSpeed .github

Full organisation-wide AI rules, coding standards, and contribution guidelines live in AGENTS.md. Read that file first.

⚠️ Branch Naming — CRITICAL (Read First)

You MUST use this pattern for ALL branches: {type}/{scope}-{title}

Examples:

  • ✅ feat/governance-audit-implementation
  • ✅ fix/pr-template-routing-bug
  • ✅ docs/branching-strategy-guide
  • ❌ claude/governance-audit-implementation — FORBIDDEN
  • ❌ copilot/fix-something — FORBIDDEN
  • ❌ feature/my-feature — WRONG (should be feat/)

Allowed Type Values (Use Exactly)

Type Purpose Example
feat New feature feat/user-preferences-panel
fix Bug fix fix/authentication-timeout
hotfix Urgent production fix hotfix/critical-security-patch
release Release branch release/v1.0.0
refactor Code refactoring refactor/api-response-structure
chore Maintenance, no code changes chore/dependency-updates
task Scoped unit of work (often project/epic-bound) task/authentication-refactor
doc Single documentation change doc/readme-typo-fix
docs Documentation docs/branching-strategy-guide
test Tests, test infrastructure test/integration-test-suite
perf Performance improvements perf/query-optimization
ci CI/CD, pipelines ci/github-actions-workflow
build Build system, package changes build/webpack-config-update
deps Dependency updates deps/upgrade-npm-packages
security Security fixes security/xss-vulnerability-fix
revert Revert previous commit revert/pr-2345-bad-merge
research Research, investigation research/performance-benchmarks
design Design system, UI design/button-component-update
a11y Accessibility a11y/wcag-compliance-audit
ux User experience ux/form-validation-feedback
i18n Internationalization i18n/german-translation-pack
ops Operations, deployment ops/database-migration-script
proto Prototype, experimental proto/new-caching-strategy
ds Design system ds/component-library-update
api API changes api/rest-endpoint-versioning
schema Data schema schema/user-model-changes
telemetry Analytics, monitoring telemetry/event-tracking-setup
content Content changes content/blog-post-updates
seo SEO optimizations seo/meta-tag-improvements
config Configuration config/environment-variables
migrate Data/schema migrations migrate/user-table-migration
qa QA processes qa/test-automation-framework
uat User acceptance testing uat/staging-validation-suite
audit Audit, compliance, review audit/security-code-review
codex Code generation, AI-assisted codex/auto-documentation-tool
aiops AI operations aiops/model-monitoring-update
automation Workflow automation automation/issue-routing-update
epic Multi-part initiative epic/platform-modernisation

FORBIDDEN Prefixes

These prefixes are NEVER allowed:

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

Why? These break PR template assignment and GitHub Actions workflows that depend on branch prefixes.

Why This Matters

Incorrect branch names cause:

  1. PR template assignment failures — PR templates route by branch prefix. Wrong prefix = wrong template
  2. GitHub Actions workflow failures — Workflows validate and act on branch names
  3. Validation check failures — Branch name validation rejects invalid prefixes
  4. Downstream automation breaks — Labeling, metrics, and release workflows depend on correct prefixes
  5. Wasted time — Humans must manually fix branches, reassign templates, and re-run workflows

Example failure chain:

  • You create branch claude/my-feature (wrong!)
  • PR template routing fails → uses default pr_feature.md (wrong template)
  • Validation workflow comments that branch is invalid
  • You must delete PR, fix branch, recreate PR
  • Result: ~5 minutes wasted, plus CI re-run credits spent

Before You Push

Always validate your branch name:

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

Expected output:

Branch '{your-branch}' matches the repository branching strategy.

More Information


What This Repository Is

This is the LightSpeed organisation .github control plane. It owns:

  • GitHub community-health files (issue templates, PR templates, discussion templates, saved replies, code of conduct, security policy).
  • Organisation-wide labels, labeler rules, and issue types.
  • GitHub Actions workflows for labeling, metrics, releases, and validation.
  • Repo-local Copilot and agent instructions (.github/instructions/, .github/custom-instructions.md).
  • Reports, project artefacts, and active planning documents.

It also hosts portable AI operations assets in top-level source folders that are intended to be reusable outside this repository:

Folder Purpose
agents/ Portable agent specifications
cookbook/ Recipes, playbooks, and implementation guides
hooks/ Portable hooks and guardrails
instructions/ Portable instruction files (no .github assumptions)
plugins/ Installable plugin bundles
skills/ Self-contained skills with SKILL.md entrypoints
workflows/ Portable agentic workflows

Do not place reusable assets under .github/—use the matching top-level folder instead.

Git Workflow

Important: All development must start from the develop branch (see Branch Naming above for the required pattern).

  • main — production releases only. Never commit feature work directly to main.
  • develop — active development integration branch. All feature branches must be based on develop.

When starting work on an issue, follow the Branch Naming rules above and run:

git fetch origin develop
git checkout -B {type}/{scope}-{title} origin/develop

This ensures your branch includes all latest development work and integrates cleanly without merge conflicts from diverged histories.

Specification-First Workflow (SpecKit)

All feature work follows the specification-first process:

  1. Create branch (using correct naming convention above)
  2. Write specification (using SpecKit process) documenting user needs and acceptance criteria
  3. Create draft PR (when ready for review; not automatic, under your control)
  4. Request review from team/stakeholders
  5. Merge to develop when approved

When to Create Draft PR

Create a draft PR when:

  • ✅ Specification is complete and clarified
  • ✅ Implementation plan is solid (you understand the approach)
  • ✅ You're ready for feedback or blocked on decisions
  • ✅ Work is substantial enough to benefit from collaborative input

Do NOT create PR automatically after creating a branch. Work in your branch first, plan your approach, then create the PR when ready.

Specification Process (Recommended)

SpecKit runs as agent skills in .claude/skills/, not as npm scripts. Invoke each skill by name (for example /speckit-specify in Claude Code). Artefacts are written to .github/specs/{feature-slug}/.

For features, audits, and significant changes:

  1. Run the speckit-specify skill (creates .github/specs/{feature-slug}/spec.md)
  2. Complete spec with: User stories, Requirements, Success Criteria, Assumptions
  3. Run the speckit-clarify skill (resolve ambiguities with Q&A)
  4. Run the speckit-plan skill (generate implementation plan and research)
  5. Run the speckit-tasks skill (decompose into actionable tasks)
  6. Implement tasks, then create draft PR when ready

Quick Reference

Phase Skill Output Your Role
1. Plan speckit-specify spec.md Define requirements
2. Clarify speckit-clarify Updated spec with Q&A Answer ambiguity questions
3. Design speckit-plan plan.md, research.md Approve technical approach
4. Decompose speckit-tasks tasks.md Review task breakdown
5. Implement Your tools Branch with commits Do the work
6. PR Review gh / GitHub UI Draft PR, review, merge Collaborate with team

For Small Changes

Not all work needs a spec. Use your judgment:

  • Needs spec: New features, governance changes, architectural decisions, multi-day tasks
  • Skip spec: Small bug fixes, one-line documentation updates, routine maintenance
  • Borderline: Ask yourself: "Would this benefit from written clarification before starting?" If yes, write a spec.

Existing Specifications

Browse all active governance specifications in the centralized catalog:

  • Specification Catalog — Complete index of all 13+ specifications with status, description, and direct links
  • Maintenance Procedures — How to create, update, and archive specifications following the numbering scheme

The catalog provides quick navigation to any specification in <30 seconds. Use it as your starting point for understanding governance requirements and historical context.

Development Commands

# Install dependencies
npm ci

# Run all tests
npm test

# Lint Markdown files
npm run lint:md

# Lint JS/TS files
npm run lint:js

# Format files
npm run format

# Validate frontmatter
npm run validate:frontmatter

Key Conventions

  • Language: UK English throughout (optimise, organisation, colour, behaviour).
  • Coding Standards: Follow WordPress Coding Standards for PHP, plus ESLint/Prettier for JS/TS and PHPCS/WPCS for PHP.
  • Security: Validate all input, escape all output, use nonces, never commit secrets.
  • Accessibility: WCAG 2.2 AA minimum; semantic HTML, keyboard support, sufficient contrast.
  • Performance: Avoid unnecessary JS, defer/lazy-load where possible, prefer native blocks.
  • No references frontmatter field: Use inline links or footer sections instead.
  • Instruction files: Follow the pattern in .github/instructions/instructions.instructions.md—frontmatter + role declaration + Overview + General Rules + Detailed Guidance + Examples + Validation + References.

🔒 Configuration Files — LOCKED (CRITICAL)

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

File Purpose Status Change Request
.github/labels.yml Canonical label definitions (158 labels) 🔒 LOCKED Open issue: [LABEL-UPDATE-REQUEST]
.github/issue-types.yml Org-wide issue type definitions (24 types) 🔒 LOCKED Open issue: [ISSUE-TYPE-UPDATE-REQUEST]
.github/ISSUE_TEMPLATE/*.md Issue templates (26 templates) 🔒 LOCKED Open issue: [TEMPLATE-UPDATE-REQUEST]
.github/PULL_REQUEST_TEMPLATE/*.md PR templates (19 templates) 🔒 LOCKED Open issue: [TEMPLATE-UPDATE-REQUEST]

Why these are locked:

  • Labels, issue types, and templates are the backbone of org-wide automation, labeling, and metrics
  • Uncontrolled changes break PR template routing, GitHub Actions workflows, and AI agent decision trees
  • Each change requires careful validation, testing, and coordination across dependent systems

How to request a change:

  1. Open a new GitHub issue on this repository
  2. Use the appropriate tag: [LABEL-UPDATE-REQUEST], [ISSUE-TYPE-UPDATE-REQUEST], or [TEMPLATE-UPDATE-REQUEST]
  3. Describe the specific change needed and why
  4. Link to any dependent projects, workflows, or agents that would be affected
  5. Wait for @ashley's explicit approval before implementing any changes

Label Creation Rules (CRITICAL)

When creating issues or PRs programmatically (via CLI, API, or workflow), ALL labels MUST be from the canonical set in .github/labels.yml with their required family prefix. Never apply bare labels without prefixes.

Valid Label Examples (Prefixed)

  • type:bug, type:feature, type:task, type:documentation, type:security, type:design
  • status:needs-triage, status:in-progress, status:done, status:blocked
  • priority:critical, priority:high, priority:normal, priority:low
  • area:ci, area:docs, area:labels, area:security, area:testing, area:automation
  • meta:needs-changelog, meta:has-pr, meta:duplicate, meta:needs-audit

INVALID Label Examples (Bare — DO NOT USE)

  • ❌ bug — use type:bug
  • ❌ feature — use type:feature
  • ❌ urgent — use priority:critical
  • ❌ ci — use area:ci
  • ❌ duplicate — use meta:duplicate

References

  • Source of truth: .github/labels.yml (158 canonical labels)
  • Label taxonomy: docs/LABEL_STRATEGY.md
  • Labeling guide: docs/LABELING.md
  • Root cause analysis: .github/projects/active/label-prefix-audit-2026-08-05/
  • Related issue: #1592 — Label Prefix Governance Enforcement

Repository Boundaries

Asset Type Belongs In
GitHub-native governance (templates, labels, workflows) .github/
Specification files (features, plans, research) .github/specs/
Repo-local Copilot/agent instructions .github/instructions/ or .github/custom-instructions.md
Reports, audits, metrics .github/reports/{category}/
Active project artefacts .github/projects/active/{slug}/
Temporary scratch files .github/tmp/ (clean up before PR)
Portable reusable AI assets top-level source folders above
Permanent human documentation docs/

What Not to Do

  • Do not add WordPress plugin or theme project-specific code to .github/.
  • Do not place reports or task trackers in docs/ or the repo root.
  • Do not create instruction files with a references frontmatter field.
  • Do not move existing agents, instructions, or schemas without a migration issue that records source path, target path, and validation plan.
  • Do not enqueue editor-only WordPress assets on the front end (and vice versa).
  • Do not commit node_modules/, build/, or other generated artefacts.

Related Files

Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit! Contributors