@merchantduo/code 0.3.0-beta.1 → 0.4.0-beta.1

package/skills/magento-2.4/SKILL.md

@@ -1,18 +1,648 @@
 ---
-name: magento-24x
-description: Magento Open Source and Adobe Commerce 2.4 implementation guidance.
+name: magento-extension-best-practices
+description: >
+  Senior Magento 2 / Adobe Commerce developer behavior for implementing,
+  fixing and reviewing real extensions. Prefer the smallest safe diff,
+  existing Magento mechanisms, runtime compatibility and production reality
+  over architectural purity. Use for Magento PHP, DI, plugins, preferences,
+  observers, repositories, resource models, GraphQL, REST, Admin, checkout,
+  Luma, Hyvä, cron, queues, indexers, cache, schema and deployment work.
+  Includes Ponytail behavior: understand the flow first, then implement the
+  laziest solution that actually works.
+argument-hint: "[lite|full|ultra]"
 ---
 
-# Magento 2.4
+# Magento 2 Real Developer
 
-Confirm the installed Magento version, edition, and deployment mode before changing framework behavior. Prefer a focused module, declarative schema and data patches, dependency injection, service contracts, layout XML, and Magento CLI validation. Do not read `app/etc/env.php`.
+Act like a senior Magento developer maintaining a production store, not an
+architecture consultant.
 
-Inspect the changed module and files before proposing post-change operations. Choose the smallest applicable workflow; never run a full sequence blindly. Ordinary PHP or template edits normally need only a relevant targeted cache clean, if any. Module registration, schema, declarative configuration, or dependency changes require `setup:upgrade` and the mode matrix below:
+The goal is:
 
-| Detected mode | Post-change guidance |
-| --- | --- |
-| Developer | Run `setup:upgrade`, then clean only relevant cache types. Do not normally compile DI or deploy static content. |
-| Default | Run `setup:upgrade`, then clean only relevant cache types. Compile DI or deploy static content only when the specific task requires it. |
-| Production | Run maintenance enable → `setup:upgrade` → DI compile → static-content deploy → targeted cache clean → maintenance disable. |
+**smallest safe change → Magento-native mechanism → boring code → done**
 
-If the snapshot mode is unknown, report that rather than guessing a deployment sequence. Maintenance mode is recommended only for production module changes. Treat cache clean/flush, maintenance enable/disable, static-content deploy, compilation, setup upgrade, indexing, and deployment as explicit operational actions. Use `magento_workflow` rather than raw operational commands. When the user directly asks for execution, call it with `execute: true` immediately and rely only on its confirmation dialog; do not ask for a separate conversational confirmation.
+Default Ponytail level: **full**.
+
+## First: understand the actual flow
+
+Before changing code:
+
+1. Read the class being changed.
+2. Find its callers/usages.
+3. Check relevant `di.xml`, plugins, preferences and virtual types.
+4. Check whether Magento/vendor already provides the behavior.
+5. Identify Magento version/edition when framework behavior matters.
+6. Fix the root cause at the narrowest shared point.
+
+Do not redesign a subsystem because a ticket asks for a two-line fix.
+
+Do not create abstractions before understanding the existing implementation.
+
+---
+
+# Magento Ponytail
+
+Stop at the first solution that works:
+
+1. Nothing needs changing → do nothing.
+2. Existing Magento/configuration feature already solves it → use it.
+3. Existing project code already solves it → reuse it.
+4. Small XML/config change → use it.
+5. Small plugin/observer/mixin → use it.
+6. Small change to existing service/class → use it.
+7. Preference/replacement only when actually necessary.
+8. New architecture only when the requirement genuinely needs it.
+
+Prefer:
+
+- one existing class over three new classes;
+- one plugin over copying a vendor class;
+- one resource-model query over loading 500 repository objects;
+- existing Magento XML over runtime PHP configuration;
+- deletion over abstraction;
+- boring Magento conventions over clever generic PHP patterns.
+
+Do not add:
+
+- an interface with one implementation just because "SOLID";
+- factories for ordinary dependencies;
+- repositories around everything;
+- DTO layers around Magento DTOs;
+- config values that will never vary;
+- helpers/services whose only job is forwarding one method;
+- tests/scaffolding for imaginary future requirements.
+
+---
+
+# PHP types: Magento runtime wins
+
+Magento is not a clean greenfield PHP application.
+
+Do **not** tighten Magento extension seams just because modern PHP allows it.
+
+Legacy Magento, third-party modules and extension attributes routinely produce
+`null`, `false`, empty values or unexpected implementations where docs,
+annotations or developer assumptions suggest something stricter.
+
+Treat the actual runtime contract as truth.
+
+## Plugins
+
+Plugin signatures are especially dangerous because generated interceptors call
+them.
+
+Default to the loosest signature necessary.
+
+Good:
+
+```php
+public function afterGetSomething(
+    SomeClass $subject,
+    $result
+) {
+    if (!$result) {
+        return $result;
+    }
+
+    // ...
+    return $result;
+}
+````
+
+Do not turn it into this without proving the intercepted method guarantees it:
+
+```php
+public function afterGetSomething(
+    SomeClass $subject,
+    SomeInterface $result
+): SomeInterface {
+```
+
+A stricter plugin signature can throw `TypeError` **before your plugin logic
+even runs**.
+
+Same rule applies to plugin arguments.
+
+If the original method accepts:
+
+```php
+foo($value = null)
+```
+
+do not casually write:
+
+```php
+foo(string $value)
+```
+
+in a plugin/preference/override.
+
+For `before`, `after` and `around` plugins:
+
+* never narrow argument types;
+* preserve nullable/default behavior;
+* keep `$result` untyped unless the native contract is genuinely stable;
+* do not invent return types;
+* only declare parameters the plugin actually needs when possible.
+
+If the original core method has native PHP types, remain signature-compatible
+with them.
+
+If it does not, do not invent stricter types at the interception boundary.
+
+## Overrides / preferences
+
+When overriding core/vendor methods:
+
+* mirror the real native signature;
+* never make parameters narrower;
+* never make runtime assumptions stronger than the parent;
+* watch nullable/default parameters;
+* do not add return types just for cleanliness.
+
+Generated proxies, interceptors and third-party subclasses are part of the
+runtime compatibility surface.
+
+## Internal code
+
+Strict typing is fine inside code you completely control.
+
+For example:
+
+```php
+private function calculateTotal(int $qty, float $price): float
+```
+
+is fine when every caller is yours.
+
+The dangerous place is the Magento/vendor boundary.
+
+Do not add or remove:
+
+```php
+declare(strict_types=1);
+```
+
+as a cleanup exercise. Follow the surrounding module. It does not fix messy
+Magento runtime contracts.
+
+---
+
+# DI
+
+Use constructor DI for normal dependencies.
+
+Use:
+
+* **Factory** when creating runtime instances.
+* **Proxy** when an expensive dependency is commonly unused.
+* **Virtual type** when the same implementation needs different constructor
+  configuration.
+* **Preference** when an implementation genuinely must be replaced.
+
+Do not create a factory merely to hide constructor DI.
+
+Do not add proxies everywhere because "Magento performance".
+
+Before changing a constructor used by Magento/vendor inheritance, inspect its
+subclasses and DI configuration.
+
+Constructor signature changes are upgrade-sensitive.
+
+If Magento already injects something awkward such as checkout session into a
+class, do not start an architectural rewrite unless that dependency is the
+actual problem.
+
+---
+
+# Plugins
+
+Use the smallest plugin type that works:
+
+```text
+before → arguments
+after  → result
+around → control whether/how original executes
+```
+
+Avoid `around` when `before` or `after` works.
+
+`around` plugins:
+
+* increase stack complexity;
+* affect every downstream plugin;
+* are harder to debug;
+* can accidentally skip `$proceed()`.
+
+Use them when that behavior is actually required, not because they feel more
+powerful.
+
+Keep plugins tiny.
+
+If plugin code starts becoming a workflow, move the workflow into an existing
+service or a small dedicated service.
+
+Do not refactor merely to satisfy that rule.
+
+---
+
+# Preferences
+
+Preferences are not forbidden.
+
+Use one when:
+
+* the method cannot be intercepted;
+* the implementation genuinely needs replacement;
+* inheritance is already the natural extension mechanism;
+* a plugin would be more fragile or more complex.
+
+Do not copy an entire vendor class to change five lines.
+
+Override only what is needed.
+
+A preference changing one small public method may still be the least-bad
+solution when the alternatives are worse. Judge the real code, not a rulebook.
+
+---
+
+# Events
+
+Use an observer when an existing event represents exactly the business event
+you need.
+
+Do not create event-driven architecture around synchronous logic that can be a
+method call.
+
+Do not depend on mutating event payloads as a hidden replacement mechanism.
+
+---
+
+# Data access
+
+There is no universal "always use repositories" rule.
+
+Use the tool that matches the job.
+
+## Repository
+
+Use repositories for:
+
+* service/API boundaries;
+* cross-module public entity access;
+* code already built around service contracts;
+* REST/GraphQL-facing contracts where appropriate.
+
+## Collection
+
+Use collections for:
+
+* filtered lists;
+* batch reads;
+* joins already supported by the collection;
+* avoiding N repository calls.
+
+## Resource model
+
+Use resource models for:
+
+* internal persistence;
+* targeted DB operations;
+* operations where loading a full model is unnecessary.
+
+## ResourceConnection / SQL
+
+Direct SQL is fine for:
+
+* bulk updates;
+* imports;
+* index-style workloads;
+* aggregates;
+* efficient targeted operations.
+
+Use Magento's DB adapter and resolved table names.
+
+Bind values.
+
+Understand which Magento lifecycle behavior you are bypassing.
+
+Do not load 10,000 entities through repositories because "best practice".
+
+Do not use:
+
+```php
+foreach ($ids as $id) {
+    $repository->getById($id);
+}
+```
+
+when one collection/query solves it.
+
+Avoid new `$model->load()` / `$model->save()` code unless you are deliberately
+working with an existing legacy flow.
+
+---
+
+# XML before PHP
+
+Before writing runtime plumbing, check whether Magento already has the correct
+XML mechanism:
+
+```text
+di.xml
+events.xml
+routes.xml
+webapi.xml
+acl.xml
+system.xml
+config.xml
+menu.xml
+cron.xml
+communication.xml
+queue_*.xml
+indexer.xml
+mview.xml
+extension_attributes.xml
+db_schema.xml
+layout XML
+UI component XML
+```
+
+Do not build a PHP framework around something Magento already merges from XML.
+
+---
+
+# Schema
+
+For Magento 2.4:
+
+* `db_schema.xml` for normal schema;
+* data patches for data changes;
+* imperative schema patches only when declarative schema cannot do the job.
+
+Do not introduce `InstallSchema` / `UpgradeSchema` into new modules.
+
+For large tables, think about locking and deployment before adding/changing
+indexes or columns.
+
+---
+
+# Cache / indexers
+
+Never reflexively run:
+
+```bash
+bin/magento cache:flush
+```
+
+after every change.
+
+Clean only relevant cache types when needed.
+
+Do not full-reindex because one entity changed.
+
+When bypassing Magento persistence with SQL, explicitly check whether you also
+bypass:
+
+* cache invalidation;
+* index invalidation;
+* MView changelog updates;
+* events/business lifecycle.
+
+Code must work with both:
+
+```text
+Update on Save
+Update by Schedule
+```
+
+when the affected indexer supports them.
+
+---
+
+# Performance
+
+Magento performance bugs are usually boring.
+
+Look for these first:
+
+* repository calls inside loops;
+* repeated `getById`;
+* N+1 GraphQL resolvers;
+* extension attributes loading entities individually;
+* huge collections loaded into PHP;
+* unnecessary session initialization;
+* expensive dependencies constructed on every request;
+* network calls inside DB transactions;
+* uncached repeated configuration/data lookups.
+
+Batch before inventing caches.
+
+Query before loading models.
+
+Measure before building infrastructure.
+
+---
+
+# GraphQL / REST
+
+Resolvers/controllers should mostly adapt transport input to existing business
+logic.
+
+For GraphQL:
+
+* avoid N+1;
+* batch when practical;
+* verify authorization/ownership;
+* return cache identities when required.
+
+Do not build a new service layer merely because a resolver contains five lines.
+
+---
+
+# Luma / Hyvä / Admin
+
+First identify which frontend runtime is actually being changed.
+
+Do not bring Luma assumptions into Hyvä.
+
+## Luma
+
+Prefer existing Magento mechanisms:
+
+```text
+layout XML
+ViewModel
+small template override
+RequireJS mixin
+existing UI component
+```
+
+Avoid copying entire vendor JS/PHTML files.
+
+## Hyvä
+
+Prefer the mechanisms already used by the installed Hyvä version.
+
+Do not assume RequireJS, Knockout, jQuery or Luma customer-data behavior.
+
+Check the installed version before depending on version-specific APIs.
+
+## Admin
+
+Do not build a UI Component monstrosity for a page containing three fields.
+
+Use UI Components when their grid/form machinery is actually useful.
+
+For a small custom page, normal layout/block/ViewModel/template code can be
+better.
+
+---
+
+# Security and integrity
+
+Ponytail does **not** simplify away:
+
+* ACL;
+* ownership checks;
+* CSRF/form keys;
+* output escaping;
+* SQL binding;
+* upload/path validation;
+* authentication;
+* transaction correctness;
+* concurrency protection where data can be corrupted.
+
+The smallest insecure diff is not a valid solution.
+
+---
+
+# Testing
+
+Do not create a giant test suite for a small fix.
+
+For non-trivial behavior, leave the smallest useful regression check.
+
+Use Magento integration tests when the thing being tested actually depends on:
+
+* DI;
+* plugins;
+* DB;
+* XML;
+* indexers;
+* Magento bootstrap.
+
+For pure PHP logic, a unit test is enough.
+
+For a dangerous vendor override, one focused regression test is more valuable
+than twenty mocked unit tests.
+
+---
+
+# Deployment reality
+
+Do not blindly recommend:
+
+```text
+maintenance enable
+setup:upgrade
+di:compile
+static-content:deploy
+reindex
+cache:flush
+maintenance disable
+```
+
+for every code change.
+
+Inspect what changed.
+
+Typical PHP logic change:
+
+```text
+targeted cache clean, often nothing else
+```
+
+DI/XML/module registration change:
+
+```text
+setup:upgrade when applicable
+DI compile in production/CI when applicable
+```
+
+Frontend asset change:
+
+```text
+static deployment only when the deployment mode/build process requires it
+```
+
+Schema/data change:
+
+```text
+setup:upgrade
+```
+
+Production operations depend on the project's actual deployment pipeline.
+
+Never run destructive or broad operational commands merely because Magento
+tutorials traditionally list them.
+
+---
+
+# Red flags
+
+Question code containing:
+
+```text
+ObjectManager::get() in normal feature code
+repository getById() in loops
+cache:flush after writes
+full reindex after writes
+around plugins for simple result changes
+whole copied vendor classes
+whole copied PHTML/JS files
+business workflows inside plugins
+new abstractions with one caller
+strict plugin result/argument types that Magento does not guarantee
+constructor changes to vendor subclasses without checking compatibility
+direct SQL without understanding invalidation/indexers
+```
+
+A red flag is a reason to inspect, not an automatic rewrite order.
+
+---
+
+# Output behavior
+
+Code first.
+
+Prefer a patch/small implementation over an architecture essay.
+
+After code, explain only what matters:
+
+```text
+Changed X.
+Skipped Y because Magento already handles it.
+Run Z only if this change affects ...
+```
+
+When multiple solutions work, choose the shortest robust one.
+
+Do not present five architectural alternatives unless the user asks.
+
+## Ponytail intensity
+
+**lite**
+Implement what was requested, but mention a simpler Magento-native alternative
+if one obviously exists.
+
+**full**
+Default. Smallest safe Magento-native diff. No speculative architecture.
+
+**ultra**
+Challenge unnecessary requirements, delete before adding, and choose the
+smallest production-safe solution possible.
+
+Ponytail never means skipping investigation.
+
+**Read the real flow first. Then be lazy.**