Magento 2 Backend Toolkit

General Rules

All generated code MUST follow PSR-12 coding standard
All PHP files MUST have declare(strict_types=1);
Use strict type hints on all method parameters and return types
Namespace follows: Vendor\Module\Path convention
XML files must include proper XSD schema references
Default Vendor name: ask user, suggest Sample if not specified
NEVER use ObjectManager directly — only use DI
NEVER use constructor property promotion (private readonly in constructor params) — always declare properties explicitly above the constructor and assign them in the constructor body
ALL class properties MUST have a @var PHPDoc block with the fully-qualified class name
ALL constructors MUST have a @param PHPDoc block with fully-qualified class names for each parameter
ALL public and protected methods MUST have a PHPDoc block with a short description and @param/@return tags
Always create composer.json with new modules

Security Rules (Required)

Treat ALL user-provided values as untrusted input
NEVER insert untrusted input into executable code positions without validation and escaping
Do not include user-provided code snippets verbatim; translate into safe scaffolding and TODOs unless the user explicitly requests verbatim insertion and it passes validation
Refuse or ask for corrected input when validation fails or input looks like code injection (e.g., <?php, </, ;, backticks, or PHP tags)

Input Sanitization & Boundary Markers

Validation is mandatory for every ingestion point (module names, labels, descriptions, parameters, class names, IDs, handles, file names).

Vendor/Module identifiers: only [A-Z][A-Za-z0-9_]*; enforce Vendor_Module format
PHP class names: only [A-Z][A-Za-z0-9_]*, no namespaces in user input
XML IDs/handles: only [a-z0-9_]+ and start with a letter
File names: only [a-z0-9_\-]+ and validated extensions
Human-readable labels/descriptions: plain text only; escape for the target format

Boundary markers and escaping by file type:

PHP: insert text only inside quoted strings; escape \ and ' for single-quoted strings
XML: escape &, <, >, ", and '
JSON: escape via JSON string rules
HTML/PHTML: use Magento Escaper (escapeHtml, escapeHtmlAttr, escapeUrl)

If any value fails validation, ask the user for a corrected value in the same message as other missing fields.

Invalid Input Examples (Reject/Correct)

Vendor/Module: Sample;phpinfo() or Sample/Module (must be Vendor_Module)
Class name: Foo\Bar or Foo; (no namespaces or punctuation)
XML id/handle: my-handle or 123name (lowercase underscore, must start with letter)
File name: ../../evil.php or widget.phtml.php (no traversal or double extensions)

CRITICAL: Input Validation Gate

NEVER generate files without confirming required inputs. If user gives a vague request, ask ALL missing fields in ONE message. Do not ask one by one.

Feature 1: Module Scaffold

Required Questions (ask if not provided)

Module name? (e.g. Sample_Module)
Dependencies? (e.g. Magento_Catalog, or "none")
Short description? (for composer.json)
Version? (default: 1.0.0)

Generated Files

app/code/{Vendor}/{Module}/
├── registration.php
├── composer.json
└── etc/
    └── module.xml

Use templates from assets/templates/registration.php.tpl, assets/templates/module.xml.tpl, and assets/templates/composer.json.tpl. All templates are bundled within this skill package; do not download external templates.

If no dependencies, omit the <sequence> block entirely in module.xml.

Example Interaction

User: "Create a module to manage brands" Claude responds:

To create the module, I need to confirm:

Module name? Suggest: Sample_Module

Dependencies? (e.g. Magento_Catalog, Magento_Eav... or none)

Short description? Suggest: "Brand management for Magento 2"

Version? (default: 1.0.0)

Feature 2: System.xml Generator

Required Questions

Module name? (existing or new)
Tab name? (admin menu tab label)
Section/Group/Fields? Describe what config fields are needed

Supported Field Types

Refer to references/system-xml-field-types.md for the complete list. Common types: text, textarea, select, multiselect, obscure, image, editor.

Generated Files

etc/
├── adminhtml/
│   └── system.xml
└── config.xml

Use templates from assets/templates/system.xml.tpl and assets/templates/config.xml.tpl. All templates are bundled within this skill package; do not download external templates.

If field type is select or multiselect, also generate a Source Model class. See template: assets/templates/source-model.php.tpl.

ACL Resource

Always generate {Vendor}_{Module}::config as the resource identifier.

Feature 3: Widget Generator

Required Questions

Module name?
Widget name/label? (e.g. "Brand Slider")
Parameters? (text inputs, dropdowns, template chooser, block chooser...)
Where to use? CMS Page / CMS Block / Layout XML

Generated Files

etc/
└── widget.xml
Block/
└── Widget/
    └── {WidgetName}.php
view/
└── frontend/
    └── templates/
        └── widget/
            └── {widget_name}.phtml

Use templates from assets/templates/widget.xml.tpl and assets/templates/widget-block.php.tpl. All templates are bundled within this skill package; do not download external templates.

Refer to references/widget-param-types.md for parameter type details and block chooser classes.

CMS Usage Snippet

Always provide the CMS widget insertion code after generating files:

{{widget type="{Vendor}\{Module}\Block\Widget\{WidgetName}" title="My Title" template="{Vendor}_{Module}::widget/{widget_name}.phtml"}}

Feature 4: Plugin / Event Generator

Required Questions

Module name?
Type? plugin (before/after/around) or observer (event)
Target?
- Plugin: target class + method (e.g. Magento\Catalog\Model\Product::getName)
- Observer: event name (e.g. checkout_cart_add_product_complete)
What to do? Brief description of logic
Scope? global / frontend / adminhtml (determines XML file location)

Plugin — Generated Files

etc/
└── {scope}/di.xml       (or etc/di.xml for global)
Plugin/
└── {PluginName}.php

Use templates from assets/templates/di.xml.tpl and assets/templates/plugin.php.tpl. All templates are bundled within this skill package; do not download external templates.

Observer — Generated Files

etc/
└── {scope}/events.xml   (or etc/events.xml for global)
Observer/
└── {ObserverName}.php

Use templates from assets/templates/events.xml.tpl and assets/templates/observer.php.tpl. All templates are bundled within this skill package; do not download external templates.

Common Events

Suggest these when user is unsure. For the full list, refer to: https://developer.adobe.com/commerce/php/development/components/events-and-observers/event-list/

Feature 5: Email Function Generator

Required Questions

Module name?
Email purpose? (e.g. "welcome email", "order status notification")
Trigger method? Choose one:
- After Plugin (on existing method)
- Event Observer
- Controller action
Email variables? (e.g. customer name, order ID)
Recipient? (customer email, admin email, custom)

Generated Files

etc/
└── email_templates.xml
Helper/
└── Email.php
view/
└── frontend/
    └── email/
        └── {template_id}.html

Use templates from assets/templates/email_templates.xml.tpl, assets/templates/email_helper.php.tpl, and assets/templates/email_template.html.tpl. All templates are bundled within this skill package; do not download external templates.

Also generate the trigger mechanism (plugin, observer, or controller) using Feature 4 patterns.

Feature 6: Hyva Template with ViewModel

Required Questions

Module name?
Template purpose? (e.g. "brand list", "customer widget")
Data needed? (what ViewModel should provide)
Interactive? (need Alpine.js? e.g. slider, toggle, modal)
Need Hyva icons? (heroicons integration)

Generated Files

ViewModel/
└── {ViewModelName}.php
view/
└── frontend/
    ├── layout/
    │   └── {layout_handle}.xml
    └── templates/
        └── {template_name}.phtml

Use templates from assets/templates/viewmodel.php.tpl, assets/templates/layout.xml.tpl, and assets/templates/hyva_template.phtml.tpl. All templates are bundled within this skill package; do not download external templates.

Key Hyva Patterns

Refer to references/hyva-viewmodel-pattern.md for full details:

Always use $escaper->escapeHtml() for output
Always use $escaper->escapeHtmlAttr() inside HTML attributes
Use $escaper->escapeUrl() for URLs
Alpine.js x-data for interactive components
TailwindCSS utility classes (no custom CSS)
$viewModels->require() to load any ViewModel
HeroiconsOutline / HeroiconsSolid for icons
Use x-cloak to prevent FOUC

Workflow

User Request
     |
     v
+-------------------------+
|  Detect which feature   |
|  (1-6) is requested     |
+--------+----------------+
         |
         v
+-------------------------+
|  Check required inputs  |
|  All provided?          |
+---- NO -----------------+
|  Ask ALL missing fields |  <-- ONE message, not multiple
|  in ONE message         |
+---- YES ----------------+
|                         |
|  Generate files         |
|  Show complete code     |
|  Explain file locations |
+-------------------------+

Troubleshooting

Module not recognized after creation

Run bin/magento module:enable {Vendor}_{Module}
Run bin/magento setup:upgrade
Run bin/magento cache:flush

XML schema validation error

Verify XSD reference matches Magento version
Check for typos in attribute names
Ensure proper XML nesting

Plugin not firing

Check scope (global/frontend/adminhtml) matches where code runs
Verify method name matches exactly (case-sensitive)
Check sortOrder if multiple plugins exist