feat: add copilot-instructions.md for agent onboarding (#886)

* Initial plan

* feat: add comprehensive copilot-instructions.md

Co-authored-by: Luehrsen <[email protected]>

* fix: address code review feedback and remove template/boilerplate terminology

Co-authored-by: Luehrsen <[email protected]>

* fix: update title to WordPress Project to reflect plugin value

Co-authored-by: Luehrsen <[email protected]>

* fix: correct theme text domain to lhpbpt

Co-authored-by: Luehrsen <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Luehrsen <[email protected]>

Author: Copilot

.github/copilot-instructions.md

@@ -0,0 +1,185 @@
+# Copilot Instructions for WordPress Project
+
+## Overview
+WordPress project combining classic and block-based features (Gutenberg). Separates business logic (`plugin/`) from presentation (`theme/`).
+
+**Stack:** PHP 8.1+, JavaScript (ES6+), CSS, webpack 5, PostCSS, Babel, @wordpress/env (Docker), PHPUnit 10
+
+**Versions:** Node.js v20.x, npm v10.x, PHP 8.1+, Composer v2.x, Docker v20.x+
+
+## Code Modification Rules
+✅ **ALLOWED:** `plugin/` and `theme/` directories, documentation  
+❌ **FORBIDDEN:** Code outside `plugin/`/`theme/`, generated/dependency directories (`vendor/`, `node_modules/`, `dist/`)
+
+## Installation (ALWAYS follow this order)
+
+1. **npm dependencies:**
+   ```bash
+   npm ci  # ~15-20s, deprecation warnings OK
+   ```
+
+2. **Composer dependencies:**
+   ```bash
+   composer install --prefer-dist --optimize-autoloader --no-interaction
+   ```
+   **Time:** 3-5 minutes  
+   **CRITICAL:** "Could not authenticate against github.com" warnings are NORMAL due to GitHub rate limits. Composer falls back to git clone. Installation WILL succeed.
+
+3. **Build:**
+   ```bash
+   npm run build  # ~10-15s, compiles to theme/dist/, theme/admin/dist/, plugin/admin/dist/
+   ```
+   **Note:** `isModuleDeclaration` deprecation warning is safe to ignore
+
+## Build Commands
+- `npm run build` - Development (unminified)
+- `npm run release:build` - Production (minified, webpack --mode='production')
+- `npm run watch` - Watch mode with LiveReload (run AFTER `npm start`)
+
+## Linting (REQUIRED before commit)
+```bash
+npm run lint  # ~5-10s, must exit 0
+```
+Runs: PHPCS (WordPress Standards), ESLint, Stylelint
+
+**Auto-fix:**
+```bash
+npm run lint:fix     # All
+npm run fix:php      # PHPCBF
+npm run fix:js       # ESLint --fix
+npm run fix:css      # Stylelint --fix
+```
+
+**Individual:** `npm run lint:php|js|css` or `composer run lint|fix`
+
+## Testing
+```bash
+npm test  # PHPUnit for plugin + theme, requires Docker running
+```
+Individual: `npm run test:unit:env:plugin|theme`
+
+## Development Environment
+```bash
+npm start  # First run: ~5-10min, subsequent: ~30s
+```
+**Access:** http://localhost  
+**Credentials:** username=`admin`, password=`password`  
+**Prereq:** Docker running  
+**First run auto-executes:** `npm install && composer install && npm run update:schemas && npm run build`
+
+```bash
+npm stop        # Stop environment
+npm run env:clean  # Remove containers/volumes
+npm run env:reset  # Clean + reinitialize
+```
+
+## Project Structure
+
+**Root Files:** `package.json`, `composer.json`, `webpack.config.js`, `phpcs.xml`, `.eslintrc`, `.stylelintrc.json`, `postcss.config.js`, `.wp-env.json`
+
+**`plugin/` - WordPress Plugin**
+- `lhpbpp.php` - Main file (text domain: `lhpbpp`)
+- `inc/` - Business logic
+- `admin/src/{js,css}/` - Admin source → `admin/dist/` (gitignored)
+- `blocks/demo/` - Example Gutenberg block
+- `tests/` - PHPUnit tests
+- `.distignore` - Excludes `/admin/src/` from releases
+
+**`theme/` - WordPress Theme**
+- `style.css` - Main stylesheet (text domain: `lhpbpt`)
+- `functions.php`, `inc/` - Theme logic
+- `src/{js,css}/` - Frontend source → `dist/` (gitignored)
+- `admin/src/{js,css}/` - Admin source → `admin/dist/` (gitignored)
+- `template-parts/` - Template files
+- `theme.json` - Block configuration
+- `tests/` - PHPUnit tests
+- `.distignore` - Excludes `/src` and `/admin/src` from releases
+
+**`bin/`** - Build scripts: archiveProject.js, updatePluginVersion.js, updateThemeVersion.js, updateThemeJsonSchema.js, lifecycleScripts/initialize.sh
+
+**`archives/`** - Release ZIPs (generated by `npm run release`)
+
+**webpack configs:**
+1. `themeFrontend` → theme/dist/ (Babel preset-env, vanilla JS)
+2. `themeBackend` → theme/admin/dist/ (WordPress preset, dependency extraction)
+3. `pluginBackend` → plugin/admin/dist/ (WordPress preset, dependency extraction)
+
+## GitHub CI Workflows
+
+**`main.yml` - Build & Deploy** (on push/PR to main)
+1. Setup Node 20, PHP 8.1, Composer v2
+2. `composer install --prefer-dist --optimize-autoloader`
+3. `npm ci`
+4. **`npm run lint`** ← MUST PASS
+5. **`npm run release`** ← MUST BUILD
+Failure at any step stops workflow.
+
+**`release.yml` - Release Please** (on push to main)
+- Creates release PRs via release-please
+- On merge: lint → build → upload ZIP → deploy
+- **Requires:** `GH_ADMIN_TOKEN` secret
+
+**`lint-pr.yml`** - Validates PR titles follow Conventional Commits (feat:, fix:, chore:, docs:)
+
+## Commit & Branch Standards
+
+**Commits MUST follow Conventional Commits:**
+- `feat: add block`
+- `fix: resolve lint error`
+- `chore: update deps`
+- `docs: improve README`
+
+**Branches:** `add/`, `fix/`, `update/`, `try/`
+
+## Common Issues
+
+**Composer GitHub Auth Warnings**
+- "Could not authenticate" = NORMAL (rate limits)
+- Composer falls back to cloning from git
+- Installation completes successfully (just slower)
+
+**babel deprecation warning**
+- `isModuleDeclaration` warning = safe to ignore
+- Builds succeed normally
+
+**npm vulnerabilities**
+- Dev dependencies only, typically safe to ignore for development
+
+## Release Process
+```bash
+npm run release
+```
+1. Production build (`webpack --mode='production'`)
+2. Update versions in `plugin/lhpbpp.php` and `theme/style.css`
+3. Create ZIPs in `archives/` (respects .distignore)
+
+## PHP Standards Customizations (phpcs.xml)
+- **Disabled:** YodaConditions, ValidHookName.UseUnderscores, FileName
+- **Target:** PHP 8.1+ (PHPCompatibilityWP)
+- **Text domains:** Plugin=`lhpbpp`, Theme=`lhpbpt` (phpcs.xml expects `lhpbp` - may need update)
+- CI ignores warnings (`ignore_warnings_on_exit`)
+
+## Quick Checklist
+
+**Before changes:**
+1. Docker running (if using wp-env)
+2. `npm ci && composer install --no-interaction` (first time)
+3. `npm run build` works
+
+**Before commit:**
+1. **`npm run lint`** exits 0 (required)
+2. Use `npm run lint:fix` for auto-fixes
+3. `npm run build` succeeds
+4. Follow Conventional Commits
+
+**For CI to pass:**
+- Linting passes
+- Production build succeeds
+- PR title follows Conventional Commits
+
+## Additional Info
+- **i18n:** `composer run i18n-make-pot`, `composer run i18n-make-json`
+- **PostCSS:** Reads vars from `theme/src/css/vars.css`, applies preset-env stage 1, cssnano minification
+- **Config files:** `.wp-env.json` (port 80, WP_DEBUG true), `phpunit.xml` (both dirs)
+
+**Trust these instructions as a starting point.** Search the codebase when you need to understand specific implementation details, encounter undocumented errors, or find instructions incomplete.