Check, learn, write: the Bricklayer workflow before touching Magento code

Just enough workflow to stop Your AI agent from guessing about Magento.

An agent that reads only source files sees one module at a time. It does not see the plugin some other extension already put on the same method, the preference that rewrites the class, or the EAV attribute that exists only in the database. So it writes code that works on its own and breaks on the real store.

Bricklayer is built around three steps:

1. Check - look at the runtime state: check-class, plugin-list, eav-attributes, database-schema, event-list
2. Learn - load the guidelines for the task: development-context category=plugin (38 categories; category=list shows all)
3. Write - only now write code, knowing what is already there and how it should look

You do not have to drive this by hand. Every tool response nudges the agent toward the next step.

The hints

Three kinds of hint fields hold the loop together.

_skill_hint - introspection tools point to the guideline category that fits:

Tool	Points to
plugin-list	development-context category=plugin
preference-list	development-context category=preference
event-list	development-context category=observer
eav-attributes	development-context category=eav
database-schema	development-context category=model
graphql-inspect	development-context category=graphql
api-endpoints	development-context category=rest-api
layout-inspect	development-context category=frontend
ui-component-inspect	development-context category=ui-component
message-queue-inspect	development-context category=message-queue
diagnose-performance	development-context category=performance

_next_steps - development-context points back to the runtime checks:

{
  "category": "plugin",
  "_next_steps": [
    "Before writing your plugin: check-class className=TargetClass",
    "Check existing plugins and their sortOrder to avoid conflicts"
  ]
}

Categories that need no introspection (coding-standards, security, testing) return _next_steps: null.

_hint - conditional, only when something needs attention: a product with custom EAV attributes points to eav-attributes, an invalid indexer points to log, an error involving plugins points to plugin-list.

One more thing that keeps the agent efficient: only 17 tools are listed at startup. The other 67 are found with search-tools, so the agent does not read 84 tool definitions before it does anything.

Example: adding a plugin

Let’s assume we ask the agent to change the product name before it is saved. Following the loop, it should do:

1. development-context category=plugin - plugin patterns, plus _next_steps telling it to check the target class
2. check-class className=Magento\Catalog\Model\ResourceModel\Product - existing plugins with their sortOrders, preferences and rewrites, in one call
3. development-context category=coding-standards - always, for any PHP file
4. write etc/di.xml and the plugin class, with a sortOrder that does not collide with what step 2 returned

If Your agent skips straight to step 4, tell it so in the prompt or, better, add it to .bricklayer/project-context.md so it lands in the agent file for every session.

• Generated agent files (CLAUDE.md, .cursorrules…) already describe this workflow, keep them up to date with vendor/bin/bricklayer update
• Not sure which tool to call? search-tools searches by keyword or group

Start coding!

Source: GitHub · Tools overview wiki