| 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 |
Full organisation-wide AI rules, coding standards, and contribution guidelines live in AGENTS.md. Read that file 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 befeat/)
| 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 |
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.
Incorrect branch names cause:
- PR template assignment failures — PR templates route by branch prefix. Wrong prefix = wrong template
- GitHub Actions workflow failures — Workflows validate and act on branch names
- Validation check failures — Branch name validation rejects invalid prefixes
- Downstream automation breaks — Labeling, metrics, and release workflows depend on correct prefixes
- 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
Always validate your branch name:
npm run validate:branch-name -- --branch <your-branch>Expected output:
Branch '{your-branch}' matches the repository branching strategy.
- Full rules: instructions/branch-naming.instructions.md
- Strategy guide: docs/BRANCHING_STRATEGY.md
- PR creation process: docs/PR_CREATION_PROCESS.md
- Copilot-specific rules: .github/custom-instructions.md
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.
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 tomain.develop— active development integration branch. All feature branches must be based ondevelop.
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/developThis ensures your branch includes all latest development work and integrates cleanly without merge conflicts from diverged histories.
All feature work follows the specification-first process:
- Create branch (using correct naming convention above)
- Write specification (using SpecKit process) documenting user needs and acceptance criteria
- Create draft PR (when ready for review; not automatic, under your control)
- Request review from team/stakeholders
- Merge to develop when approved
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.
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:
- Run the
speckit-specifyskill (creates.github/specs/{feature-slug}/spec.md) - Complete spec with: User stories, Requirements, Success Criteria, Assumptions
- Run the
speckit-clarifyskill (resolve ambiguities with Q&A) - Run the
speckit-planskill (generate implementation plan and research) - Run the
speckit-tasksskill (decompose into actionable tasks) - Implement tasks, then create draft PR when ready
| 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 |
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.
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.
# 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- 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
referencesfrontmatter 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.
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:
- Open a new GitHub issue on this repository
- Use the appropriate tag:
[LABEL-UPDATE-REQUEST],[ISSUE-TYPE-UPDATE-REQUEST], or[TEMPLATE-UPDATE-REQUEST] - Describe the specific change needed and why
- Link to any dependent projects, workflows, or agents that would be affected
- Wait for @ashley's explicit approval before implementing any changes
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.
type:bug,type:feature,type:task,type:documentation,type:security,type:designstatus:needs-triage,status:in-progress,status:done,status:blockedpriority:critical,priority:high,priority:normal,priority:lowarea:ci,area:docs,area:labels,area:security,area:testing,area:automationmeta:needs-changelog,meta:has-pr,meta:duplicate,meta:needs-audit
- ❌
bug— usetype:bug - ❌
feature— usetype:feature - ❌
urgent— usepriority:critical - ❌
ci— usearea:ci - ❌
duplicate— usemeta:duplicate
- 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
| 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/ |
- 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
referencesfrontmatter 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.
- AGENTS.md — full global AI rules
- docs/WORKFLOWS.md — workflow organisation and distribution strategy
- .github/specs/ — feature specifications and implementation planning
- .specify/ — speckit configuration for feature specification workflow
- .github/custom-instructions.md — Copilot-specific repo instructions
- instructions/coding-standards.instructions.md — unified coding standards
- .github/instructions/file-organisation.instructions.md — canonical file placement rules
- .github/instructions/plugin-structure.instructions.md — WordPress block plugin structure
Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit! Contributors