JezK

Edit File: AGENTS.md

# Imagify — project instructions for AI agents Project Configuration values below override a pipeline's derived defaults. Behaviour — how agents run, dispatch, or report — belongs to the pipeline, not to this file. --- ## Project Configuration | Variable | Value | |---|---| | `REPO` | `wp-media/imagify-plugin` | | `SLUG` / `TEXT_DOMAIN` | `imagify` | | `BASE_BRANCH` | `develop` | | Protected branches | `develop`, `master` — never commit directly | | Branch naming | `<prefix>/<issue>-<slug>`; prefix `fix` (bugs), `enhancement` (features, incl. `feat` commits), `test` | | Test (full / unit / integration) | `composer run-tests` / `composer test-unit` / `composer test-integration` | | Test (one group) | `vendor/bin/phpunit --configuration Tests/Integration/phpunit.xml.dist --group <Name>` | | Lint / auto-fix | `composer phpcs` / `composer phpcbf` | | Static analysis | `composer run-stan` | | Build frontend | `npm run build` | | Local env up / down / seed | `bash bin/dev-up.sh` / `bash bin/dev-down.sh` / `bash bin/dev-seed.sh` | | E2E runner | `bash bin/test-e2e.sh` (`--headed`, `--ui`, or a spec path) | | Local URL | `http://localhost:8888` — admin `admin` / `password` | | Settings page | `/wp-admin/options-general.php?page=imagify` | | Key option | `imagify_settings` (API key + config) | | PR template | `.github/PULL_REQUEST_TEMPLATE.md` | `.env.local` at the repo root (gitignored) holds `IMAGIFY_TESTS_API_KEY=<key>`. The same value must exist as a GitHub secret for CI optimization tests. --- ## Traps Things that fail in ways you will not notice. - **Run `composer install` before any test or lint command.** Strauss namespace-prefixing is a Composer post-install hook. Without it, PHPCS and PHPUnit cannot resolve `Imagify\Dependencies\*` and fail with misleading autoload errors. - **`WordPress.Security.NonceVerification.Missing` and `.Recommended` are deliberately suppressed** in `phpcs.xml`. Do not add `phpcs:ignore` for them and do not restructure code to satisfy them. - **`assets/` is build output.** Edit `_dev/` and rebuild, or the next build discards your work. - **There is no JavaScript unit test runner** (no Jest, no Vitest). Never invent `npm test`. Frontend verification is `npm run build` plus Playwright; otherwise report JS tests as `N/A`. - **Optimization behaviour sits behind license, API-key and quota guards.** Before reporting that a feature works or is broken, run `bash bin/dev-seed.sh` and confirm the key landed: `npx @wordpress/env run cli wp option get imagify_settings --format=json | grep -c '"api_key":"[^"]\+'` Only once the key is present (result `1`) may you treat a guard as a genuine blocker. Never report a behavioural pass or failure *through* a blocked guard — report "cannot verify" with the guard's `file:line`. Guard locations are in the `e2e` skill. - **A PR's number is not its issue number.** Read it back from the `gh pr create` output. - **PHP-rendered admin UI is a frontend change.** `wp_admin_notice()`, `add_action( 'admin_notices', ... )` and `add_settings_error()` need frontend scoping and testing despite living in PHP. --- ## Architecture Single-edition plugin — no FREE/PRO split. Namespace root `Imagify\`, PSR-4 root `classes/`. - `classes/` — modern PSR-4, `declare(strict_types=1)` required. **New features go here.** - `inc/classes/` — legacy classmap, `Imagify_` prefix, migrating toward `classes/`. **Add nothing here.** In new `classes/` code: - No new singletons or `InstanceGetterTrait` usage. The trait is still used in `classes/Plugin.php`, `classes/Bulk/Bulk.php` and elsewhere — that is legacy precedent, not a pattern to copy. - No bare `add_action()` / `add_filter()`. Register hooks through a `Subscriber` implementing `SubscriberInterface`, listed in `ServiceProvider::get_subscribers()`. - Service providers live at `classes/*/ServiceProvider.php` and are registered in `config/providers.php`. - No global state, and no UI logic coupled to infrastructure logic. The legacy `inc/` layer is procedural and full of both — do not pattern-match from it. Nonce action naming: `imagify_<feature>_<action>`. DI container is Strauss-prefixed: `Imagify\Dependencies\League\Container\Container` — a plain `use League\Container\Container;` is wrong here. Async work uses ActionScheduler, not wp-cron. Frontend source is `_dev/` (Grunt, `gruntfile.js`); `_dev/` also carries its own `bud.config.js`. --- ## Coding standards Source of truth: `composer.json` scripts, `phpcs.xml`, `phpstan.neon.dist`, CI. Never hardcode PHPCS standards or invent lint commands. Imagify must stay WordPress.org-compatible ([Plugin Check](https://github.com/WordPress/plugin-check/)). Evaluate any change to public APIs, output, security, metadata, or bootstrap behaviour against it. - PHP 7.4+, strict types in all new `classes/` files. - Text domain `imagify`: `esc_html__( 'Label', 'imagify' )`. - Authorization: use the project's registered capability (`'bulk-optimize'`, `'manage'`, …) in `current_user_can()`, never the coarse `manage_options`. - No jQuery in new or modified JavaScript — native DOM APIs only, no inline handlers, no unsafe `innerHTML`. Pass nonces via `wp_localize_script`. - Remote responses from the Imagify API are untrusted input and are this plugin's main attack surface. Validate and escape everything that comes back before storing or echoing it. --- ## Testing Prefer **integration tests** (`Tests/Integration/`, annotated `@group FeatureName`) — they exercise real WordPress context, DI wiring and hook execution. Unit tests only for pure logic with no WP globals, container or hooks. Scale scope to risk: LOW = the relevant `--group`; MEDIUM = `composer test-unit` plus that group; HIGH = `composer run-tests`. Not scope violations: generated files (`*.min.js`, `*.min.css`), lockfiles, tests mirroring changed source, auto-formatter output. --- ## Commits and PRs - Conventional Commits: `type(scope): short description`. Each commit passes PHPCS and static analysis before being made. - Pipeline-authored commits carry a `Co-Authored-By: <model> <noreply@anthropic.com>` trailer so automated work stays auditable. Human-authored commits do not. - Do not squash unrelated changes. Do not amend commits already pushed. - Outside a pipeline working a specific ticket, only *suggest* commits — do not run `git commit` or `git push`. - PR title: `Closes #<N>: <short title>` — never a Conventional-Commit prefix; that is for commits. - The PR body needs a standalone `Closes #<N>` line, not buried in prose — that is what auto-closes. - Apply the `Made by AI` label to every AI-created PR and issue. - Split work vertically: each PR one complete behaviour including its tests. Never a backend PR plus a separate frontend PR for one feature, even when separate agents did the work. - Do not run large automated refactors or reorganize files without being asked. The legacy-to-modern migration is ongoing; "cleaning up while I'm here" is not in scope. --- ## On-demand references - **Browser testing** — admin URLs, page objects, environment variables, local running: [`docs/E2E_TESTING.md`](docs/E2E_TESTING.md) - **QA procedure** — tiers, spec conventions, guard locations: the `e2e` skill (`.claude/skills/e2e/`) - **Code structure** — use the installed pipeline's knowledge-graph skill if it provides one. A local builder also exists: `node bin/build-knowledge-graph.js` writes `.aiassistant/graph/` (gitignored). Do not mix the two graphs in one session; if neither is current, use grep rather than stopping. --- ## Priority order When these conflict, earlier wins: 1. Security 2. WordPress.org compliance 3. Architectural integrity 4. Backward compatibility 5. Minimal diffs 6. Performance