From e0502c29d253edfe3d91adcc65b736fc7e8a18b3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 20 May 2026 14:29:41 +0000 Subject: [PATCH 1/2] Initial plan From 5dc42db6716038e006b696f174f84d233fc3f361 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 20 May 2026 14:37:07 +0000 Subject: [PATCH 2/2] Add plugin-structure instructions, CLAUDE.md, and clean up scratch file - Create .github/instructions/plugin-structure.instructions.md with WordPress block plugin structure conventions (directory layout, block.json, enqueueing, security, i18n, PHP organisation) - Create CLAUDE.md at repo root as Claude AI companion to AGENTS.md - Remove Copilot-Processing.md scratch file from repo root (moved to .github/tmp/ which is gitignored) - Update AGENTS.md cross-references table to include CLAUDE.md entry Agent-Logs-Url: https://github.com/lightspeedwp/.github/sessions/bedf8bf7-2de3-473b-a489-e45580925aee Co-authored-by: ashleyshaw <1805352+ashleyshaw@users.noreply.github.com> --- .../plugin-structure.instructions.md | 211 ++++++++++++++++++ AGENTS.md | 1 + CLAUDE.md | 97 ++++++++ Copilot-Processing.md | 15 -- 4 files changed, 309 insertions(+), 15 deletions(-) create mode 100644 .github/instructions/plugin-structure.instructions.md create mode 100644 CLAUDE.md delete mode 100644 Copilot-Processing.md diff --git a/.github/instructions/plugin-structure.instructions.md b/.github/instructions/plugin-structure.instructions.md new file mode 100644 index 00000000..598c418b --- /dev/null +++ b/.github/instructions/plugin-structure.instructions.md @@ -0,0 +1,211 @@ +--- +description: "WordPress block plugin structure conventions for all LightSpeed plugins: directory layout, block.json, asset enqueueing, security, and i18n." +applyTo: "**" +file_type: "instructions" +version: "v1.0" +last_updated: "2026-05-20" +owners: ["LightSpeed Team"] +tags: ["wordpress", "plugin", "blocks", "block-json", "structure", "php", "i18n"] +domain: "plugin-hardening" +stability: "stable" +--- + +# WordPress Block Plugin Structure + +You are a WordPress block plugin architect. Follow our block-first plugin conventions to scaffold, structure, and maintain LightSpeed plugins. Avoid page-builder patterns, direct SQL, and enqueuing assets globally where block-scoped loading suffices. + +## Overview + +Applies to all LightSpeed WordPress plugins that ship one or more Gutenberg blocks. Covers directory layout, `block.json` conventions, asset enqueueing, PHP organisation, security, and i18n. Excludes theme-only patterns—see the block theme guidance for those. + +## General Rules + +- Scaffold new blocks with `@wordpress/create-block`; align the output to the conventions below. +- Use `block.json` as the canonical source of block metadata, attributes, and supported features. +- Separate editor assets from front-end assets; never enqueue editor-only code on the front end. +- Register all blocks via `register_block_type()` pointing to the `block.json` file—avoid manual registration of attributes and scripts. +- Follow [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) for PHP, JS, CSS, and HTML. +- Apply `sanitize_*`, `esc_*`, and `wp_kses_post()` at all input and output boundaries. +- Use a plugin-specific text domain and run `wp-scripts i18n make-pot` as part of the build. + +## Detailed Guidance + +### Directory Layout + +Prefer this layout for a single-block plugin; extend it for multi-block plugins by repeating the `src//` pattern. + +```text +my-plugin/ +├── my-plugin.php # Plugin header, bootstrap loader +├── readme.txt # WordPress.org readme +├── package.json # wp-scripts, node tooling +├── composer.json # PHP tooling (PHPCS, PHPStan) +├── block.json # Root block metadata (single-block plugins only) +├── src/ +│ ├── block.json # Preferred: block metadata lives with source +│ ├── edit.js # Editor component +│ ├── save.js # Front-end render (or null for dynamic blocks) +│ ├── index.js # Block registration entry point +│ ├── editor.scss # Editor-only styles +│ └── style.scss # Shared/front-end styles +├── build/ # wp-scripts output (gitignored) +├── includes/ +│ ├── class-my-plugin.php # Main plugin class +│ └── functions.php # Utility functions +└── languages/ + └── my-plugin.pot # Generated POT file +``` + +For multi-block plugins, place each block under its own subfolder: + +```text +src/ +├── my-block/ +│ ├── block.json +│ ├── edit.js +│ ├── save.js +│ ├── index.js +│ ├── editor.scss +│ └── style.scss +└── another-block/ + └── ... +``` + +### Plugin File Header + +The main PHP file must include the standard WordPress plugin header: + +```php +' . esc_html( $title ) . ''; +``` + +### i18n + +- Declare the text domain in both the plugin header and `block.json` (`"textdomain"` key). +- Wrap all user-facing strings in `__()`, `esc_html__()`, or `_n()` with the plugin text domain. +- In JavaScript, import `{ __ }` from `@wordpress/i18n`. +- Generate the POT file: `wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin`. +- Add `wp-scripts i18n make-json languages/ --no-purge` to the build pipeline to create JSON translation files. + +### PHP Class Organisation + +- Use a main plugin class to namespace all hooks and methods. +- Register hooks in an `init()` or `run()` method, not in the constructor. +- Keep the constructor lean: set version constants and properties only. + +```php +class My_Plugin { + public function __construct( string $version ) { + $this->version = $version; + } + + public function run(): void { + add_action( 'init', [ $this, 'register_blocks' ] ); + } + + public function register_blocks(): void { + register_block_type( __DIR__ . '/../build/my-block' ); + } +} +``` + +## Examples + +- **Good:** `register_block_type( __DIR__ . '/build/my-block' )` with a matching `block.json`; editor styles in `editorStyle`, shared styles in `style`; all output wrapped in `esc_html()`. +- **Avoid:** Manually registering block scripts with `wp_register_script` and duplicating metadata already declared in `block.json`; enqueuing editor assets unconditionally via `wp_enqueue_scripts`. + +## Validation + +- Run `npm run build` to confirm `@wordpress/scripts` compiles without errors. +- Run `composer phpcs` (PHPCS with WPCS) on the `includes/` and plugin root PHP. +- Check `block.json` validates against the schema: `npx @wordpress/scripts check-engines`. +- Confirm no editor styles leak to the front end by inspecting network requests on a published post. + +## References + +- [coding-standards.instructions.md](./coding-standards.instructions.md) +- [a11y.instructions.md](./a11y.instructions.md) +- [WordPress Block Editor Handbook](https://developer.wordpress.org/block-editor/) +- [block.json schema reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/) +- [@wordpress/create-block](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) +- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/) diff --git a/AGENTS.md b/AGENTS.md index 59dbff2a..43e33e8b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,6 +92,7 @@ Start here for all key standards: | ------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------ | | **Instructions Guide** | [.github/instructions/instructions.instructions.md](.github/instructions/instructions.instructions.md) | Guide for authoring and maintaining instruction files | | **Custom Instructions** | [.github/custom-instructions.md](.github/custom-instructions.md) | Repo-local Copilot instructions and `.github` boundary rules | +| **Claude Instructions** | [CLAUDE.md](CLAUDE.md) | Claude-specific project instructions; companion to this file | | **Main Agent Index** | [.github/agents/agent.md](.github/agents/agent.md) | Directory of agent specs, stubs, usage, implementation | | **Prompts Index** | [.github/prompts/prompts.md](.github/prompts/prompts.md) | Legacy prompt index pending skills/cookbook migration | | **Instruction Migration** | [.github/MIGRATION_GUIDE.md](.github/MIGRATION_GUIDE.md) | Mapping from legacy instruction files to the 5 consolidated guides | diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..212a7b55 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,97 @@ +--- +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](./AGENTS.md). Read that file first. + +## 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. + +## Development Commands + +```bash +# 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](https://developer.wordpress.org/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. + +## Repository Boundaries + +| Asset Type | Belongs In | +| --- | --- | +| GitHub-native governance (templates, labels, workflows) | `.github/` | +| 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 + +- [AGENTS.md](./AGENTS.md) — full global AI rules +- [.github/custom-instructions.md](./.github/custom-instructions.md) — Copilot-specific repo instructions +- [.github/instructions/coding-standards.instructions.md](./.github/instructions/coding-standards.instructions.md) — unified coding standards +- [.github/instructions/file-organisation.instructions.md](./.github/instructions/file-organisation.instructions.md) — canonical file placement rules +- [.github/instructions/plugin-structure.instructions.md](./.github/instructions/plugin-structure.instructions.md) — WordPress block plugin structure diff --git a/Copilot-Processing.md b/Copilot-Processing.md deleted file mode 100644 index 6daa1a06..00000000 --- a/Copilot-Processing.md +++ /dev/null @@ -1,15 +0,0 @@ -# Copilot Processing Log - -## Request Details - -- User wants to update Mermaid diagrams per `.github/prompts/update-mermaid-diagrams.prompt.md` and follow `.github/instructions/mermaid.instructions.md` while validating and improving diagrams. -- Need to audit diagram usage, accessibility, placements, and produce updates as guided. -- Output should follow instructions for mermaid diagrams (WCAG AA, metadata, etc.). - -## Action Plan - -1. **Inventory diagrams** — Search the repository for existing Mermaid diagrams (README, docs, `.github/` files). Document which files have diagrams that require validation or updating and note any missing alt/context. (Dependency: none.) ✅ -2. **Review instructions** — Re-read `mermaid.instructions.md` and relevant README placement guidance so updates respect WCAG AA palette choices, metadata, and prose context. (Dependency: reference files must be in place.) 🟡 -3. **Audit target files** — For each diagram from step 1, check contrast, `accTitle`/`accDescr`, prose summaries, and placement according to the prompt. Capture findings to inform edits. (Dependency: inventory from step 1.) ⚪ -4. **Apply updates** — Modify identified Mermaid diagrams to meet requirements (diagram blocks, metadata, palette, alt descriptions, splits if needed). Add or refresh nearby prose as needed. (Dependency: audit insights.) ⚪ -5. **Validate + document** — Re-check updated diagrams (syntax, palette, metadata) and optionally summarize results for the user, noting any outstanding concerns or next steps. (Dependency: completion of updates.) ⚪