Skip to content

AGENTS.md

Latest commit

 

History

History
219 lines (165 loc) · 7.59 KB

AGENTS.md

File metadata and controls

219 lines (165 loc) · 7.59 KB

AGENTS.md — AI Agent Guidance

This is the primary guidance document for AI agents working in this repository. Read this file first before making any changes.

Repo Purpose

This is the LightSpeed Site Plugin repository — the canonical home for custom WordPress blocks and site-specific functionality for lightspeedwp.agency.

It is not a WordPress.org submission plugin. It is not a monorepo. It is a single plugin in a single repo.

Responsibilities:

  • Custom Gutenberg blocks for the LightSpeed website
  • Site-specific PHP functionality that does not belong in the theme
  • Shared non-theme behaviour for the LightSpeed site

Repo Structure

/
├── ls-plugin.php               Main plugin bootstrap
├── uninstall.php               Plugin uninstall stub — keep conservative
├── plugin-utils.mjs            Node CLI for validation, schema checks, and security scanning
├── package.json                Node scripts and dev dependencies
├── composer.json               PHP quality tooling
├── AGENTS.md                   This file — start here
├── CLAUDE.md                   Claude agent pointer
├── CHANGELOG.md                Version history — follow Keep a Changelog + SemVer
├── README.md                   Human-readable root documentation
├── readme.txt                  Lightweight WordPress distribution placeholder
├── inc/                        PHP include files (optional, loaded from main plugin file)
├── src/                        Source files: src/blocks/, src/css/, src/js/
├── blocks/                     Built or registered block asset directories
├── assets/                     Static assets: assets/css/, assets/js/, assets/images/, assets/icons/
├── patterns/                   WordPress block patterns (PHP files with header comments)
├── templates/                  Optional block templates and template parts
├── languages/                  Translation files (.pot, .po, .mo)
├── docs/                       End-user documentation — NOT developer reports
├── .github/                    GitHub-native workflows, Copilot instructions, prompts, tasks, reports
└── .agents/                    Portable agent skills and personas

Plugin-First Development

  • This is a plugin repo — not a theme, not a monorepo.
  • One plugin, one repo. Do not add multi-plugin infrastructure.
  • The main plugin file must maintain a valid WordPress plugin header.
  • Keep the bootstrap file lean — load includes via plugins_loaded, not inline.
  • Do not invent a plugin framework. Use WordPress core APIs.

Plugin Identity

Property Value
Plugin name LightSpeed Site Plugin
Plugin slug ls-plugin
Text domain ls-plugin
PHP function prefix ls_plugin_
PHP constant prefix LS_PLUGIN_
Composer package lightspeedwp/ls-plugin
GitHub repo lightspeedwp/ls-plugin
Plugin URI https://lightspeedwp.agency/

PHP Architecture

  • Keep PHP minimal unless there is a clear need.
  • PHP include files go in inc/.
  • Load includes from ls_plugin_init() via plugins_loaded.
  • Use WordPress coding standards (tabs for indentation in PHP).
  • Do not add a PHP autoloader unless genuinely needed.
  • Class files go in inc/ — name them class-ls-plugin-name.php.

Escaping output (required)

Always escape output before rendering:

echo esc_html( $variable );
echo esc_attr( $attribute );
echo esc_url( $url );
echo wp_kses_post( $html );

Never echo unescaped dynamic content.

Sanitising input (required)

Sanitise all user input before using it:

$value = sanitize_text_field( wp_unslash( $_POST['field'] ) );
$url   = esc_url_raw( wp_unslash( $_POST['url'] ) );
$int   = absint( $_POST['number'] );

Translation

Always wrap strings for translation:

esc_html__( 'String', 'ls-plugin' )
esc_html_e( 'String', 'ls-plugin' )

Block Development

  • Source block files go in src/blocks/{block-name}/.
  • Built block assets go in blocks/{block-name}/.
  • Each block must have a valid block.json file.
  • Register blocks using register_block_type() with the path to block.json.
  • Use @wordpress/scripts for building block assets.
  • Block editor assets should be separate from frontend assets.
  • PHP-rendered blocks must escape all dynamic output.
  • Use block.json supports and attributes rather than bespoke registration logic.

Example block registration:

register_block_type( LS_PLUGIN_PLUGIN_DIR . 'blocks/my-block' );

Asset Conventions

  • Static assets (ready-to-use CSS, JS, images, icons): assets/
  • Source files (need compilation): src/
  • Built block assets: blocks/
  • Do not mix source and built assets in the same folder.
  • Frontend CSS and editor CSS should be separate files where appropriate.

Validation and Linting Commands

Run these before committing:

# Node validation
npm run plugin:validate      # Validate plugin structure and headers
npm run schema:validate      # Validate block.json and JSON files
npm run security:scan        # Scan for risky PHP patterns
npm run lint                 # Run all JS, CSS, and JSON linters

# PHP quality
composer run phpcs           # Check coding standards
composer run phpcbf          # Auto-fix coding standards
composer run phplint         # Check PHP syntax

Changelog Expectations

  • Follow Keep a Changelog.
  • Follow Semantic Versioning.
  • Every version bump must include a CHANGELOG.md entry.
  • Keep an [Unreleased] section at the top.
  • Use sections: Added, Changed, Deprecated, Removed, Fixed, Security.

Documentation Expectations

  • docs/ is for end-user documentation — installation guides, editor guides, client notes.
  • Do not put developer reports in docs/.
  • Developer reports go in .github/reports/.
  • Task lists go in .github/tasks/.

AI Folder Conventions

Folder Purpose
.github/prompts/ GitHub Copilot prompt files for repeatable workflows
.github/reports/ Developer and AI-generated reports for this repo
.github/tasks/ Task lists and AI-maintained work tracking
.github/instructions/ File-type-specific Copilot guidance
.agents/skills/ Portable, reusable agent skills
.agents/agents/ Agent persona definitions

Rules for AI agents:

  • Store reports in .github/reports/ — never in docs/ or the repo root.
  • Store task lists in .github/tasks/ — update task-list.md when work is tracked.
  • Store GitHub prompt files in .github/prompts/.
  • Store portable skills in .agents/skills/.
  • Store agent personas in .agents/agents/.
  • Keep prompts focused and short — they are wrappers for repeatable workflows.

Code Quality Rules For AI Agents

  • Prefer small diffs — avoid large rewrites unless clearly justified.
  • Avoid adding new dependencies unless strictly necessary.
  • Do not invent a build pipeline — use @wordpress/scripts if builds are needed.
  • Keep the plugin lean — do not add infrastructure that is not used.
  • Do not add Playwright, Storybook, Docker, webpack config, or Vite unless there is a strong reason.
  • Escape all PHP output correctly.
  • Sanitise and validate all inputs.
  • Review block render callbacks and patterns carefully before modifying.
  • Do not hardcode plugin-specific values — use constants and placeholders.
  • Follow WordPress coding standards.
  • Follow accessibility best practices in blocks and templates.