convez.ai
SkillDesenvolvimento WebIntermediário
muon-m2

Magento 2 Tools

muon-m2/magento2-tools

Engineering completo para Magento 2 — scaffold, review, test, fix, deploy, audit

Ver no GitHub
InicialPluginScore · de 0 a 100

Suite completa de skills para engenharia end-to-end em Magento 2, incluindo scaffolding, review, testes, correção de bugs, deployment e auditoria. Funciona como plugin Claude Code com contexto compartilhado que se adapta a qualquer projeto e ambiente.

Instalação

$npx convez-ai muon-m2/magento2-tools

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
2
Acompanhando
0
Saúde
37%
Último commit
há 1 mês
Versão
v2.4.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Scaffolding e criação de novos módulos Magento 2
  • Review automático de código com evidências de arquivo e linha
  • Diagnóstico de saúde: indexadores, caches, filas, cron
  • Correção de bugs em checkout, ordens e fluxos críticos
  • Validação e deployment seguro com approval gates

Veredito

Toolkit robusto e bem-documentado para times Magento 2, com abordagem conservadora (approval gates antes de mudanças) e excelente onboarding através de `.claude/settings.json`. Essencial para equipes que trabalham com Magento 2 em produção.

README

A tradução para o português deste README ainda está na fila.

magento2-tools

A Claude Code plugin of skills for end-to-end Magento 2 engineering: scaffolding, review, testing, bug-fixing, deployment, auditing, and more — built around a shared context-resolver so the same toolkit adapts to any project and environment.

🌐 Website: https://muon-m2.github.io/magento2-tools/

Install

/plugin marketplace add muon-m2/magento2-tools
/plugin install magento2-tools@muon-m2 --scope user

--scope user makes it available in every project. Use --scope project to pin it to one repo. Skills are then invoked namespaced, e.g. magento2-tools:fix.

Team auto-enable — commit to a project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "muon-m2": { "source": { "source": "github", "repo": "muon-m2/magento2-tools" } }
  },
  "enabledPlugins": { "magento2-tools@muon-m2": true }
}

On folder-trust, Claude Code offers to install the marketplace and enables the plugin — zero manual steps for teammates.

First steps (try it on your project)

New to the toolkit? Open any Magento 2 project in Claude Code and try these — all read-only, nothing is modified:

# 1. Let the toolkit learn your project (vendor, runner, versions, theme, tools)
Resolve the Magento 2 project context

# 2. Severity-ranked review of one of your modules, with file:line evidence
Quick review of the module app/code/<Vendor>/<Module>

# 3. One-page health snapshot: indexers, caches, queues, cron, versions
/magento2-tools:snapshot

Skills are triggered by plain language ("fix this checkout bug", "scaffold a module for order export") or invoked explicitly with flags (/magento2-tools:deploy --env=staging Acme_OrderExport). Code-writing skills always stop at an approval gate (blueprint, RCA, deploy plan, release push) before changing anything; reports land in your project's .docs/ folder. The full walkthrough lives in docs/getting-started.md.

Documentation

Developer documentation lives in docs/:

DocWhat it covers
Getting startedInstall, first run, safety model, first commands for first-time users
Daily workflowsDay-to-day recipes: bug fixes, features, reviews, tests, deploys, audits, releases
New project guideBootstrapping a new Magento 2 project with the toolkit, from CLAUDE.md to first release
Flows and scenariosArchitecture, per-skill phase flows with diagrams, approval-gate map, artifact map, end-to-end scenarios
Skills referencePer-skill quick reference: invocation, flags, phases, outputs
ConfigurationContext resolver, overrides, CLAUDE.md hints, CI integration (validate-only deploys, SARIF)

Skills

36 skills under skills/, each self-contained (SKILL.md + references/ + scripts/ + templates/). Per-skill flags, phases, and outputs are documented in docs/skills-reference.md.

SkillPurpose
contextResolves project context (vendor, runner, Magento root/version, tools). The hub every other skill delegates environment questions to. Owns the shared findings emitters (emit-findings.sh / emit-json.sh / emit-sarif.sh).
module-createScaffold a new module.
reviewReview a module / diff against standards. Reuses the hub's shared JSON/SARIF emitters.
featureEnd-to-end feature workflow; orchestrates most other skills.
fixReproduce → RCA → minimal TDD fix → regression test → review → deploy.
deployPre-flight validation, ordered deploy, rollback.
test-generateGenerate unit/integration/API/MFTF tests.
upgradeBC-break detection, deprecation maps.
securityCVE + secret + EQP static scan.
perf-auditN+1, caching, indexer/queue review.
debugInvestigate logs / DI graph when reproduction is hard.
eav-attributeAdd EAV attributes idempotently.
graphqlSchema-first GraphQL surfaces.
webapiContract-first REST / Web-API surfaces for an existing entity (webapi.xml routes + service contract + DTO + repository + di.xml + acl.xml + functional tests).
frontendThemes, components, email templates.
data-migrationIdempotent data patches / importers.
releaseVersion bump, changelog, tag, publish.
i18nTranslation extraction / locale management.
admin-formScaffold an adminhtml UI-component edit form (form XML + DataProvider + New/Edit/Save/Delete + button blocks).
admin-listingScaffold an adminhtml grid/listing (listing XML + DataProvider + columns + actions + mass actions), paired with admin-form.
extension-pointWire behaviour onto an existing class: plugin (before/after/around interceptor), observer (events.xml + Observer), or preference.
system-configAdd admin Stores → Configuration settings: system.xml + config.xml + ACL + optional source/backend models + typed Config reader.
cli-commandScaffold a bin/magento console command or cron job on an existing module: Symfony Command + CommandList registration, or crontab.xml + job class with a delegate service.
message-queueScaffold an async message-queue surface on an existing module: communication.xml topic + queue_topology/publisher/consumer.xml bindings + a typed message DTO + publisher + idempotent consumer.
lintRun the static-analysis gate (phpcs, phpstan, phpmd, php-cs-fixer, rector) and apply safe auto-fixes; emit residual violations as ranked findings (JSON + SARIF).
docsGenerate or refresh a module's technical documentation from its own code — public @api surface, events, plugins, REST/GraphQL, DB schema, and more. For a module with REST routes it also emits OpenAPI 3.1, a JetBrains .http file, and a Postman collection under docs/api/. Never modifies source.
indexerScaffold a custom indexer + materialized view (mview) on an existing module: indexer.xml, mview.xml subscriptions, an ActionInterface indexer class + batched action class.
widgetScaffold a CMS widget on an existing module: widget.xml declaration (parameters, containers, templates) + Magento_Widget dependency + a BlockInterface block with typed parameter accessors and a parameter-aware cache key + a theme-neutral phtml + unit/integration tests.
marketplaceAssess an existing module's Adobe Marketplace / EQP submission readiness: composer metadata, licensing, structure, MFTF tests, docs, packaging hygiene. Read-only; emits a tiered scored report (JSON + SARIF, outputKind=marketplace).
a11y-auditAudit a module's/theme's storefront templates for WCAG 2.1 Level AA issues (alt text, labels, ARIA, headings, keyboard, contrast). Static-first; optional pa11y runtime pass. Read-only; emits ranked findings (JSON + SARIF, outputKind=accessibility).
breeze-themeScaffold a Swissup Breeze (Breezefront) child theme: theme.xml Swissup/breeze-* parent + registration.php + composer.json + web/css/breeze/_default.less (@critical) + breeze-only layout.
breeze-adaptAdapt an existing module to Breeze by generating a separate companion {Vendor}_{Module}Breeze module (breeze.js JS registration + web/css/breeze LESS + Cash $.widget stubs). Never edits the target.
breeze-compatRead-only static audit of a module's Breeze compatibility (RequireJS/Knockout/jQuery-widget/mixins). Emits ranked findings (JSON + SARIF, outputKind=compatibility) + a verdict.
auditRead-only release-readiness orchestrator: fans out every findings dimension (review + security + perf-audit + lint + a11y-audit + marketplace + breeze-compat) in parallel and consolidates them into ONE deduplicated, severity-ranked report + one merged SARIF (outputKind=audit). The inspect counterpart to feature.
triageRead-only: turns a findings document into an ordered, approvable remediation plan — every finding fingerprinted, waiver-checked, confidence-gated, routed to its owning skill through the shared routing matrix, and grouped into dependency-ordered batches (outputKind=remediation). audit finds; triage decides who fixes.
remediateWrite half of the remediation cycle: executes an approved triage plan batch by batch through the skill that owns each finding — one approval per batch, one commit per finding (Closes-Finding trailer), gate: manual items reported as human actions rather than executed, then audit --compare to prove what closed. Never edits vendor/.

Dependency graph

context is the universal leaf — every other skill resolves environment through it and it depends on nothing. It also owns the shared findings emitters (emit-findings.sh → emit-json.sh / emit-sarif.sh) and the single findings engine (findings-lib.sh) that every findings-emitting skill reuses. There are two orchestrators, and they are counterparts: feature builds, audit inspects.

A ──► B means A invokes B as part of its own workflow. Callers are not listed as edges (deploy is invoked by four skills; it invokes only context), and neither is fix routing — where a read-only skill hands findings to the skill that owns the remediation. Routing is listed separately below.

context           ◄── (called by all others; depends on nothing;
                       owns the shared findings emitters + findings-lib.sh)

feature           ──► module-create, review, deploy, test-generate, docs,
                      eav-attribute, graphql, extension-point, system-config,
                      cli-command, message-queue, lint          (Phase 5 task types)
                      fix, debug, perf-audit, security, frontend,
                      data-migration                            (Phase 6B smoke-fix routing)

audit             ──► review, security, perf-audit, lint, a11y-audit,
                      marketplace, breeze-compat   (fans out, then consolidates;
                                                    reuses emit-findings.sh)

triage            ──► context                      (+ reuses route-finding.sh,
                                                    waivers-lib.sh, emit-findings.sh;
                                                    reads audit's document, writes a plan)

remediate         ──► context, triage, audit         (loads/creates the plan, then
                      fix, upgrade, extension-point,   proves closure with --compare)
                      indexer, message-queue, webapi,
                      graphql, admin-form, admin-listing,
                      system-config, data-migration,
                      frontend, breeze-adapt, i18n,
                      test-generate, lint, docs        (one batch per owner, in the
                                                        plan's dependency order)

fix               ──► context, review, deploy, data-migration, debug
module-create     ──► context, docs, review
review            ──► context                      (+ reuses emit-json/emit-sarif)
test-generate     ──► context
deploy            ──► context
upgrade           ──► context, test-generate, review
release           ──► context, deploy
i18n              ──► context
docs              ──► context

security          ──► context                      (+ reuses findings-lib.sh)
perf-audit        ──► context                      (+ reuses findings-lib.sh)
lint              ──► context                      (+ reuses findings-lib.sh)
marketplace       ──► context, security            (+ reuses findings-lib.sh)
a11y-audit        ──► context                      (+ reuses findings-lib.sh)
breeze-compat     ──► context                      (+ reuses findings-lib.sh)
debug             ──► context

eav-attribute     ──► context
data-migration    ──► context, review
graphql           ──► context, review, test-generate
webapi            ──► context, module-create, review, test-generate
frontend          ──► context, review, breeze-theme, breeze-adapt, breeze-compat
admin-form        ──► context, module-create, review, test-generate
admin-listing     ──► context, module-create, review, test-generate
system-config     ──► context, module-create, review, admin-form
cli-command       ──► context, module-create, review, system-config
extension-point   ──► context, module-create, review
message-queue     ──► context, module-create, review
indexer           ──► context, module-create, review, perf-audit
widget            ──► context, module-create, review
breeze-theme      ──► context
breeze-adapt      ──► context, breeze-compat

Fix routing (findings hand-off, not invocation): every findings skill routes each finding to the skill that owns its remediation. The mapping is a contract, not a judgement call — it lives in skills/context/references/fix-routing.md and is resolved by skills/context/scripts/route-finding.sh, which also names the specialist owners (extension-point, indexer, message-queue, webapi, graphql, admin-form, admin-listing, breeze-adapt, docs) that a prose table used to funnel into fix. triage applies it to a whole report at once and emits the ordered plan, and remediate executes that plan — the owning skills above are invoked there, which is why remediate is the one skill whose dependency line is the routing table. When review runs in diff mode on behalf of feature, fix, or upgrade, it returns findings to that caller instead of routing.

Commands

Thin slash-command shortcuts for common operations. Each forwards your arguments verbatim to the underlying skill — no behaviour changes, and the write commands keep every approval/production gate. They are always namespaced:

CommandRoutes toUse
/magento2-tools:auditauditFull release-readiness audit — every findings dimension consolidated into one ranked report + merged SARIF
/magento2-tools:bugfixfixReproduce → root-cause → minimal TDD fix → regression test → review
/magento2-tools:contextcontextResolve the Magento 2 project context — vendor, runner, versions, theme, tools
/magento2-tools:deploydeployDeploy Magento 2 module.— pre-flight, ordered deploy, rollback
/magento2-tools:docsdocsGenerate or refresh a module's technical documentation from its own code — README, guides, API references, CHANGELOG scaffold
/magento2-tools:featurefeatureEnd-to-end Magento 2 feature implementation orchestrator
/magento2-tools:i18ni18nExtract translatable strings and manage locale CSV files for a Magento 2 module
/magento2-tools:lintlintRun the static-analysis gate (phpcs, phpstan, phpmd, php-cs-fixer, rector) and apply safe auto-fixes for a Magento 2 module
/magento2-tools:perfperf-auditPerformance audit — N+1, caching, indexer/queue review
/magento2-tools:releasereleaseRelease a Magento 2 module — version bump, changelog, tag, publish
/magento2-tools:remediateremediateExecute an approved remediation plan batch by batch through the owning skills — one approval per batch, one commit per finding
/magento2-tools:reviewreviewReview a Magento 2 module or diff against standards
/magento2-tools:scaffoldmodule-createEntry point for Magento 2 code generation — routes the request to the matching generator skill (defaults to module-create for a whole new module)
/magento2-tools:securitysecuritySecurity audit — CVEs, secrets, EQP static rules, cross-module patterns
/magento2-tools:snapshotdebugOne-page Magento 2 health snapshot — indexers, caches, queues, cron, versions
/magento2-tools:testtest-generateGenerate unit, integration, API, JS, or MFTF tests for a Magento 2 module
/magento2-tools:triagetriageTurn a findings report into an ordered, approvable remediation plan — who fixes what, in what order
/magento2-tools:upgradeupgradeDetect BC breaks, deprecations, and required changes when upgrading a Magento 2 module to a new Magento/PHP version

Every command except scaffold is user-invoked only: you type /magento2-tools:<name>, and the model reaches the underlying skills directly through the Skill tool rather than through a command stub. The seven write commands (deploy, bugfix, feature, release, upgrade, lint, remediate) keep their approval/production gates. The scaffold dispatcher routes to module-create and guides generation to specialist skills. All arguments/flags are passed straight through to the skill, which is the source of truth for behaviour and gates.

Subagents or one flow — your choice. The audit/RCA commands accept --agents / --inline (or set "execution_mode" in the project's .claude/m2.json): agents fans analysis out to the read-only reviewer/explorer subagents in parallel, inline runs the same steps sequentially in the conversation. audit fans out by default; everything else defaults to auto — inline in a small conversation, subagents once the conversation is already past the context budget. Approval gates always run in the main conversation. Contract: skills/context/references/execution-modes.md.

Context budget. A run's cost scales with the conversation it starts in: every turn re-reads all of it. Start a /magento2-tools:… command in a conversation above 200k tokens and a warn-only hook recommends /clear first (MAGENTO2_TOOLS_CTX_WARN changes the threshold, 0 disables it — see docs/configuration.md).

Security scans are live, with no shipped advisory data. The security skill resolves dependency advisories at scan time (composer audit) and Adobe patch state through the store's own vendor/bin/patch-status; offline runs state "advisories were NOT checked" in scanner_errors instead of silently passing.

Per-project environment overrides

context auto-detects the runner (Docker vs bare PHP) and the Magento root. For non-standard setups, override detection (env var wins over file):

export M2_PHP_CONTAINER=my-php-container   # name of the running PHP container
export M2_MAGENTO_ROOT=src                 # Magento root (default: auto-detect "." or "src")
export M2_CACHE_TTL=86400                  # context cache TTL in seconds (0 disables; default 24h)

or commit a per-project .claude/m2.json:

{ "php_container": "my-php-container", "magento_root": "src" }

A configured container that is not running falls through to generic name-pattern detection. Changing any override busts the resolver cache automatically.

Layout

.claude-plugin/
  plugin.json        # plugin manifest
  marketplace.json   # this repo doubles as its own marketplace ("muon-m2")
skills/              # 36 skills (auto-discovered by Claude Code)
commands/            # 18 /magento2-tools:<verb> shortcut commands (auto-discovered)
agents/              # first-party read-only subagents: reviewer (per-dimension review) + explorer (code comprehension/tracing)
hooks/               # .docs/ path guard (PreToolUse) + warn-only context-budget hook (UserPromptSubmit / Skill)
tests/               # contract test harness
scripts/             # release-notes helper (used by .github/workflows/release.yml) + token-report.py (where a session's tokens went)

Bundled scripts are invoked from SKILL.md as ${CLAUDE_SKILL_DIR}/scripts/<name> (own skill) or ${CLAUDE_PLUGIN_ROOT}/skills/<skill>/scripts/<name> (cross-skill); the scripts themselves self-locate via BASH_SOURCE, so they are layout-independent.

Tests

bash tests/run-all.sh

Contract tests cover bash syntax, template lint (PHP/XML/JSON/GraphQL/CSV/JS), SKILL.md frontmatter validity, cross-reference integrity (including ${CLAUDE_SKILL_DIR} / ${CLAUDE_PLUGIN_ROOT} and <skill>/… cross-refs), context-resolver behaviour (bare/docker runner contract + src-layout/override fixtures), plugin↔marketplace version sync, skill-version-registry consistency, and golden-output snapshots of the shared findings emitters (emit-json / emit-sarif). CI additionally runs shellcheck. Tests that need a missing interpreter exit 77 (SKIP) rather than failing.

Releasing

Bump .claude-plugin/plugin.json + marketplace.json, convert the CHANGELOG [Unreleased] section to ## [X.Y.Z], commit Release vX.Y.Z, then push an annotated vX.Y.Z tag. The tag push triggers .github/workflows/release.yml, which runs the contract suite, asserts the tag matches both manifest versions, and publishes a GitHub Release with the matching CHANGELOG section as its notes (extracted by scripts/release-notes.sh). The bump, CHANGELOG, and tag stay manual.

Also bump the version badge in the landing page hero — the Claude Code plugin · vX.Y.Z string in index.html on the gh-pages branch — then commit and push the updated gh-pages branch so the published site matches the release. It is a static string with no runtime lookup, so it does not update on its own.

Versioning

Each skill's version lives in its SKILL.md frontmatter (version:) — the single source of truth. The table in skills/context/references/skill-versioning.md and the README command table are generated (gen-versions.sh / gen-routing.sh under skills/context/scripts/); contract tests fail when either is stale. The plugin itself is versioned in .claude-plugin/plugin.json; change narrative lives in CHANGELOG.md.

Ver o original no GitHub

Bom para

Relacionados