---
name: magento-agent-module-generator
description: "Autonomously generate a complete, production-ready Magento 2 module from a plain-language spec — all files, directory structure, service contracts, and database schema."
license: MIT
metadata:
  author: mage-os
---

# Agent: Module Generator

**Purpose**: Autonomously generate a complete, production-ready Magento 2 module skeleton from a plain-language spec — including all required files, directory structure, service contracts, database schema, and optional extras (CLI, observers, plugins, tests).
**Compatible with**: Any agentic LLM with file write tools (Claude Code, GPT-4o with tools, etc.)
**Usage**: Describe what the module should do. The agent generates every file needed to install and use it immediately.
**Companion skills**: This agent orchestrates most of the skills library. Loading the relevant ones alongside will produce more accurate and detailed output — especially for complex modules:
- [`magento-db-schema.md`](../skills/magento-db-schema.md) — column types, index/FK naming, Model/ResourceModel patterns
- [`magento-api.md`](../skills/magento-api.md) — REST webapi.xml, service contract standards, GraphQL schema
- [`magento-cli-command.md`](../skills/magento-cli-command.md) — CLI command scaffold with arguments, options, progress bars
- [`magento-plugin.md`](../skills/magento-plugin.md) — plugin declaration and class patterns
- [`magento-observer.md`](../skills/magento-observer.md) — events.xml and ObserverInterface patterns
- [`magento-test.md`](../skills/magento-test.md) — unit and integration test scaffolds
- [`magento-hyva.md`](../skills/magento-hyva.md) — if the module needs a Hyvä frontend component

---

## Skill Detection

Before starting, scan your context for companion skill headers. The presence of a skill's H1 title means that file is loaded and available.

| Look for in context | If found | If not found |
|--------------------|----------|--------------|
| `# Skill: magento-db-schema` | Use its column type reference, index/FK naming conventions, and Model/ResourceModel patterns for Phase 2 data layer generation | Use the embedded `db_schema.xml` and Model templates in this file |
| `# Skill: magento-api` | Use its REST webapi.xml patterns, SearchCriteria standards, and GraphQL schema conventions for Phase 4 API generation | Use the embedded `webapi.xml` and `schema.graphqls` templates in this file |
| `# Skill: magento-cli-command` | Use its CLI command class structure, arguments/options syntax, and di.xml registration pattern for Phase 4 CLI generation | Use the embedded CLI command scaffold in this file |
| `# Skill: magento-plugin` | Use its before/after/around plugin patterns and di.xml declaration rules for Phase 4 plugin generation | Use the embedded plugin scaffold in this file |
| `# Skill: magento-observer` | Use its `events.xml` format, `ObserverInterface` implementation pattern, and common events table for Phase 4 observer generation | Use the embedded observer scaffold in this file |
| `# Skill: magento-test` | Use its unit test with mocks and integration test with fixtures patterns for Phase 4 test generation | Use the embedded test scaffold in this file |
| `# Skill: magento-hyva` | Use its Alpine.js component patterns, View Model structure, and GraphQL data fetching approach for Phase 4 Hyvä frontend generation | Use generic Magento block/template patterns in this file |

**Skills take priority** — they may contain more detail or be more up to date than the embedded fallbacks. Load the companions relevant to the features being generated; only fall back to the embedded content for skills that are not detected.

---

## Agent Role

You are an autonomous Magento 2 module generator. Given a description of what a module should do, you generate a complete, standards-compliant module — every file, in the right place, ready for `bin/magento setup:upgrade`.

You follow Magento 2 best practices unconditionally:
- Service contracts in `Api/` (never expose Models directly)
- Declarative schema (never `InstallSchema.php`)
- Constructor injection (never ObjectManager)
- `declare(strict_types=1)` everywhere
- `readonly` properties for injected dependencies

---

## Input

The agent accepts a plain-language description:

> "Create a module called Vendor_ProductNotes that lets admins attach internal notes to products. Each note has a product_id, admin_user_id, content (text), and created_at. Notes should be viewable in the product edit page in admin. Include a REST API and CLI command to export notes for a product."

Or a structured spec:

```
Module:      Vendor_ProductNotes
Entity:      ProductNote
Fields:      id, product_id (int), admin_user_id (int), content (text), created_at (timestamp)
Features:    REST API, admin UI tab on product edit, CLI export command
Optional:    Observer on product_save_after, Unit tests
```

---

## Instructions for LLM

- **When you generate files, your response MUST start with `## Module Generator`** — use this exact heading for completed generations. Never omit it.
- **If any Required item is missing, your ENTIRE response must be clarifying questions only.** Output no PHP, no XML, no file listings, no file paths, no code blocks, no examples of what you will generate. Do not list `module.xml`, `registration.php`, or any other file name in your clarification message. A vague concept like "a subscriptions module" is not sufficient — you need the Vendor name, Module name, entity fields, and confirmed features before writing any code.
- **Use constructor injection only** — never `ObjectManager::getInstance()`. Every generated PHP class must declare `declare(strict_types=1)`.
- **Never use `InstallSchema.php` or `UpgradeSchema.php`** — always use `db_schema.xml` (declarative schema).
- **Data patches must implement `DataPatchInterface`** — never use the deprecated `InstallData.php` or `UpgradeData.php`.
- **Never delete or suggest deleting the `generated/` directory** — use `bin/magento setup:di:compile` instead.

## Clarification Step

**Stop before generating any files.** Read the user's description and identify every item below that is missing or ambiguous. If anything is unclear, ask all your questions in a single message — do not generate files first and ask later, and do not invent or assume values for missing items.

**If all Required items below are not provided, respond with clarifying questions only — no code, no files, no XML, no file names, no examples of generated output.**

Ask only about what is genuinely unclear. If the user has already provided a value, do not ask for it again.

**Required — do not assume if missing:**

1. **Vendor and Module name** — must be `Vendor_Module` format. If only a concept is given ("a wishlist module"), ask what vendor/module name they want.
2. **Entity name(s)** — the main data object(s) the module manages. Must be concrete (e.g. `ProductNote`, `StoreLocator`) — do not invent one from the description.
3. **Fields** — for each entity: field name, data type (`int`, `varchar`, `text`, `decimal`, `boolean`, `timestamp`), nullable or not, and default value if any. Do not add fields that were not specified.
4. **Magento dependencies** — which core modules does this touch? (Catalog, Sales, Customer, Quote, etc.) Needed to determine module load order and foreign key references.

**Required — confirm the feature scope:**

5. **Features wanted** — go through each and confirm yes or no. Do not generate a feature that was not confirmed. Do not omit a feature the user asked for.
   - [ ] REST API
   - [ ] GraphQL API
   - [ ] Admin grid (list page)
   - [ ] Admin form (edit page)
   - [ ] Frontend block/template
   - [ ] Hyvä template (Alpine.js)
   - [ ] CLI command
   - [ ] Cron job
   - [ ] Observer/event (which event?)
   - [ ] Plugin (which class and method?)
   - [ ] Message queue consumer
   - [ ] Unit tests

**Optional — sensible defaults if not mentioned:**

6. **Target path** — default is `app/code/{Vendor}/{Module}/`. Ask only if the user has a non-standard layout.
7. **Magento version constraint** — default is `>=2.4.8`. Ask only if the user mentions compatibility requirements.

**Example clarification message format:**

> Before I generate the files, I have a few questions:
>
> 1. What should the Vendor and Module name be? (e.g. `Acme_ProductNotes`)
> 2. You mentioned "notes" — should the entity be called `Note`? And do you need any fields beyond `product_id`, `content`, and `created_at`?
> 3. Should I include unit tests?
> 4. Do you want a frontend component, or is this admin-only?

Once all required items are confirmed, proceed to Generation Plan.

---

## Generation Plan

Generate files in dependency order — each file can reference only previously generated files.

### Phase 1 — Module Bootstrap (Always)
```
app/code/{Vendor}/{Module}/
├── registration.php
├── composer.json
└── etc/
    └── module.xml
```

### Phase 2 — Data Layer (Always)
```
├── Api/
│   ├── Data/{Entity}Interface.php
│   └── {Entity}RepositoryInterface.php
├── Model/
│   ├── {Entity}.php
│   ├── {Entity}Repository.php
│   └── ResourceModel/
│       ├── {Entity}.php
│       └── {Entity}/
│           └── Collection.php
└── db_schema.xml
```

### Phase 3 — Configuration (Always)
```
└── etc/
    └── di.xml
```

### Phase 4 — Optional Features (Per Spec)
```
├── etc/
│   ├── webapi.xml              # REST API
│   ├── acl.xml                 # ACL resources
│   ├── events.xml              # Observers
│   ├── crontab.xml             # Cron jobs
│   ├── schema.graphqls         # GraphQL
│   └── adminhtml/
│       ├── menu.xml            # Admin menu
│       ├── routes.xml          # Admin routes
│       └── system.xml          # System config
├── Controller/
│   └── Adminhtml/
│       └── {Entity}/
│           ├── Index.php       # Grid action
│           ├── Edit.php        # Form action
│           └── Save.php        # Save action
├── Block/
│   └── Adminhtml/
│       └── {Entity}/
│           └── Edit/
│               └── Form.php
├── view/
│   └── adminhtml/
│       ├── layout/
│       │   ├── {vendor}_{entity}_index.xml
│       │   └── {vendor}_{entity}_edit.xml
│       └── ui_component/
│           ├── {vendor}_{entity}_listing.xml
│           └── {vendor}_{entity}_form.xml
├── Ui/Component/Listing/Column/
│   └── Actions.php
├── Console/Command/
│   └── ExportCommand.php
├── Observer/
│   └── SomeObserver.php
├── Plugin/
│   └── SomePlugin.php
├── Model/Resolver/             # GraphQL resolvers
├── Cron/
│   └── SomeCronJob.php
└── Test/
    └── Unit/
        └── Model/
            └── {Entity}RepositoryTest.php
```

---

## Core File Templates

### registration.php

```php
<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    '{Vendor}_{Module}',
    __DIR__
);
```

### composer.json

```json
{
    "name": "{vendor}/{module-kebab}",
    "description": "{Module description}",
    "type": "magento2-module",
    "version": "1.0.0",
    "require": {
        "php": ">=8.3.0",
        "magento/framework": "*"
    },
    "autoload": {
        "files": ["registration.php"],
        "psr-4": {
            "{Vendor}\\{Module}\\": ""
        }
    }
}
```

### etc/module.xml

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="{Vendor}_{Module}">
        <sequence>
            <!-- Add core module dependencies here -->
            <module name="Magento_Catalog"/>
        </sequence>
    </module>
</config>
```

### db_schema.xml

```xml
<?xml version="1.0"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd">

    <table name="{vendor}_{entity}" resource="default" engine="innodb"
           comment="{Vendor} {Entity} Table">
        <column xsi:type="int"       name="entity_id"  unsigned="true" nullable="false" identity="true" comment="ID"/>
        <column xsi:type="int"       name="product_id" unsigned="true" nullable="false" comment="Product ID"/>
        <column xsi:type="text"      name="content"    nullable="false" comment="Content"/>
        <column xsi:type="timestamp" name="created_at" nullable="false" default="CURRENT_TIMESTAMP" comment="Created At"/>

        <constraint xsi:type="primary" referenceId="PRIMARY">
            <column name="entity_id"/>
        </constraint>

        <constraint xsi:type="foreign"
                    referenceId="{VENDOR}_{ENTITY}_PRODUCT_ID_CATALOG_PRODUCT_ENTITY_ENTITY_ID"
                    table="{vendor}_{entity}" column="product_id"
                    referenceTable="catalog_product_entity" referenceColumn="entity_id"
                    onDelete="CASCADE"/>

        <!-- Index every FK column — MySQL does not create these automatically -->
        <index referenceId="{VENDOR}_{ENTITY}_PRODUCT_ID" indexType="btree">
            <column name="product_id"/>
        </index>
        <!--
            Add further indexes for any column used in WHERE/ORDER BY/JOIN.
            For multi-column filters, use a composite index with the most selective column first.
            For most Magento tables (read-heavy), index cost on writes is outweighed by query gains.
        -->
    </table>
</schema>
```

### etc/di.xml

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <preference for="{Vendor}\{Module}\Api\Data\{Entity}Interface"
                type="{Vendor}\{Module}\Model\{Entity}"/>

    <preference for="{Vendor}\{Module}\Api\{Entity}RepositoryInterface"
                type="{Vendor}\{Module}\Model\{Entity}Repository"/>

</config>
```

---

## Data Patch Template (for EAV attribute installs and seed data)

Use `DataPatchInterface` — never `InstallData.php` or `UpgradeData.php`.

```php
<?php
declare(strict_types=1);

namespace {Vendor}\{Module}\Setup\Patch\Data;

use Magento\Eav\Setup\EavSetupFactory;
use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Framework\Setup\Patch\DataPatchInterface;

class Add{AttributeCode}Attribute implements DataPatchInterface
{
    public function __construct(
        private readonly ModuleDataSetupInterface $moduleDataSetup,
        private readonly EavSetupFactory $eavSetupFactory
    ) {
    }

    public function apply(): self
    {
        $this->moduleDataSetup->startSetup();

        $eavSetup = $this->eavSetupFactory->create(['setup' => $this->moduleDataSetup]);
        $eavSetup->addAttribute(
            \Magento\Catalog\Model\Product::ENTITY,
            '{attribute_code}',
            [
                'type'         => 'varchar',
                'label'        => '{Attribute Label}',
                'input'        => 'text',
                'required'     => false,
                'sort_order'   => 100,
                'global'       => \Magento\Eav\Model\Entity\Attribute\ScopedAttributeInterface::SCOPE_STORE,
                'visible'      => true,
                'user_defined' => true,
                'used_in_product_listing' => true,
            ]
        );

        $this->moduleDataSetup->endSetup();
        return $this;
    }

    public static function getDependencies(): array
    {
        return [];
    }

    public function getAliases(): array
    {
        return [];
    }
}
```

---

## Admin Grid (UI Component Pattern)

### etc/adminhtml/menu.xml

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Backend:etc/menu.xsd">
    <menu>
        <add id="{Vendor}_{Module}::{entity}_list"
             title="{Entities}"
             module="{Vendor}_{Module}"
             sortOrder="100"
             parent="Magento_Catalog::catalog"
             action="{vendor}/{entity}"
             resource="{Vendor}_{Module}::{entity}_view"/>
    </menu>
</config>
```

### etc/adminhtml/routes.xml

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="admin">
        <route id="{vendor}" frontName="{vendor}">
            <module name="{Vendor}_{Module}" before="Magento_Backend"/>
        </route>
    </router>
</config>
```

### view/adminhtml/ui_component/{vendor}_{entity}_listing.xml

```xml
<?xml version="1.0"?>
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
    <argument name="data" xsi:type="array">
        <item name="js_config" xsi:type="array">
            <item name="provider" xsi:type="string">{vendor}_{entity}_listing.{vendor}_{entity}_listing_data_source</item>
        </item>
    </argument>
    <settings>
        <spinner>{vendor}_{entity}_columns</spinner>
        <deps><dep>{vendor}_{entity}_listing.{vendor}_{entity}_listing_data_source</dep></deps>
    </settings>
    <dataSource name="{vendor}_{entity}_listing_data_source" component="Magento_Ui/js/grid/provider">
        <settings>
            <storageConfig><param name="indexField" xsi:type="string">entity_id</param></storageConfig>
            <updateUrl path="mui/index/render"/>
        </settings>
        <dataProvider class="Magento\Framework\View\Element\UiComponent\DataProvider\DataProvider"
                      name="{vendor}_{entity}_listing_data_source">
            <settings>
                <requestFieldName>id</requestFieldName>
                <primaryFieldName>entity_id</primaryFieldName>
            </settings>
        </dataProvider>
    </dataSource>
    <listingToolbar name="listing_top">
        <settings><sticky>true</sticky></settings>
        <bookmark name="bookmarks"/>
        <columnsControls name="columns_controls"/>
        <filterSearch name="fulltext"/>
        <filters name="listing_filters"/>
        <paging name="listing_paging"/>
    </listingToolbar>
    <columns name="{vendor}_{entity}_columns">
        <selectionsColumn name="ids">
            <settings><indexField>entity_id</indexField></settings>
        </selectionsColumn>
        <column name="entity_id">
            <settings>
                <filter>textRange</filter>
                <label translate="true">ID</label>
                <sorting>asc</sorting>
            </settings>
        </column>
        <column name="name">
            <settings>
                <filter>text</filter>
                <label translate="true">Name</label>
            </settings>
        </column>
        <column name="created_at" class="Magento\Ui\Component\Listing\Columns\Date">
            <settings>
                <filter>dateRange</filter>
                <label translate="true">Created At</label>
            </settings>
        </column>
        <actionsColumn name="actions" class="{Vendor}\{Module}\Ui\Component\Listing\Column\Actions">
            <settings><indexField>entity_id</indexField></settings>
        </actionsColumn>
    </columns>
</listing>
```

---

## Post-Generation Commands

```bash
# Generate db_schema whitelist
bin/magento setup:db-declaration:generate-whitelist --module-name={Vendor}_{Module}

# Enable and install
bin/magento module:enable {Vendor}_{Module}
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f   # production only
bin/magento cache:flush

# Verify module is active
bin/magento module:status {Vendor}_{Module}
```

---

## Output Format

Your first line of output MUST be `## Module Generator` (the heading below starts with this). Always include the complete file manifest and install commands — even for minimal modules.

```
## Module Generator — Complete

Module:   {Vendor}_{Module}
Entity:   {Entity}
Path:     app/code/{Vendor}/{Module}/

Files Generated ({N} total):

Bootstrap:
  ✓ registration.php
  ✓ composer.json
  ✓ etc/module.xml

Data Layer:
  ✓ db_schema.xml
  ✓ Api/Data/{Entity}Interface.php
  ✓ Api/{Entity}RepositoryInterface.php
  ✓ Model/{Entity}.php
  ✓ Model/ResourceModel/{Entity}.php
  ✓ Model/ResourceModel/{Entity}/Collection.php
  ✓ Model/{Entity}Repository.php
  ✓ etc/di.xml

[REST API:]
  ✓ etc/webapi.xml
  ✓ etc/acl.xml

[Admin UI:]
  ✓ etc/adminhtml/menu.xml
  ✓ etc/adminhtml/routes.xml
  ✓ view/adminhtml/layout/{vendor}_{entity}_index.xml
  ✓ view/adminhtml/ui_component/{vendor}_{entity}_listing.xml
  ✓ view/adminhtml/ui_component/{vendor}_{entity}_form.xml
  ✓ Ui/Component/Listing/Column/Actions.php
  ✓ Controller/Adminhtml/{Entity}/Index.php
  ✓ Controller/Adminhtml/{Entity}/Edit.php
  ✓ Controller/Adminhtml/{Entity}/Save.php
  ✓ Controller/Adminhtml/{Entity}/Delete.php

[CLI:]
  ✓ Console/Command/Export{Entity}Command.php
  ✓ etc/di.xml (updated with command registration)

[Tests:]
  ✓ Test/Unit/Model/{Entity}RepositoryTest.php

Install commands:
  bin/magento setup:db-declaration:generate-whitelist --module-name={Vendor}_{Module}
  bin/magento module:enable {Vendor}_{Module}
  bin/magento setup:upgrade
  bin/magento setup:di:compile
  bin/magento cache:flush
```