Adobe Commerce AI Toolkit

Claude Code commands, hooks, and SDLC workflow for Adobe Commerce / Magento 2 module development. Enforces a phase-gated lifecycle — requirements → structure → implementation → validation — using the adobe-commerce-mcp execution server for all scaffolding, quality checks, and bin/magento operations.

How it works

CLAUDE.md is loaded by Claude Code on every conversation. It contains all domain knowledge, coding standards, SDLC phase procedures, architecture decision rules, and skill implementations in one file — 17 numbered sections (§0–§17) that slash commands reference explicitly.

.claude/commands/ provides eight slash commands that drive the SDLC. Each command creates TodoWrite tasks, calls the right MCP tools, validates results, and gates progression to the next phase.

.claude/settings.json pre-authorizes all 24 adobe-commerce MCP tools and git commands so they run without per-call approval prompts. Three PostToolCall hooks write quality and scaffold events to an audit log. A Stop hook persists the current phase for fast status retrieval.

Slash commands

| Command | When to use | |---|---| | /commerce-init | First time on a project — detects environment, verifies MCP, shows phase status | | /commerce-status | Any time — phase dashboard, memory summary, next recommended command | | /phase1 | Start requirements gathering — creates and fills REQUIREMENTS.md | | /phase2 | Scaffold module skeleton and validate DI configuration | | /phase3 | Implement all components with per-step PHPCS + DI validation | | /phase4 | Run full quality suite (parallel) and commit on pass | | /commerce-docs <topic> | Live Adobe docs lookup + OOTB pattern reference | | /commerce-validate-quick | Fast PHPCS + DI check during Phase 3 development | | /review-before-commit | Pre-commit review — ObjectManager, typed exceptions, hardcoded IDs, commit format, App Builder response shape |

SDLC phases

/commerce-init          verify environment and MCP connectivity

Phase 0  (auto)         ensure REQUIREMENTS.md has Project Information
Phase 1  /phase1        requirements → REQUIREMENTS.md complete
Phase 2  /phase2        module skeleton + DI validation
Phase 3  /phase3        implement components, validate each
Phase 4  /phase4        quality suite (parallel) → git commit on pass
                              └── fix → re-validate loop

/commerce-status        reorient at any point
/commerce-docs          look up any Adobe Commerce pattern
/commerce-validate-quick  fast check during Phase 3

Phase gates: Each phase requires the previous one to be marked complete in REQUIREMENTS.md. No phase skipping. Completion markers written automatically by each phase command.

Natural language prompts

You don't have to use slash commands — Claude Code understands goal-based prompts and routes them to the right phase automatically. The agent proposes an approach, waits for your confirmation, then executes.

Starting a new module

I need to build a Vendor_LoyaltyPoints module that tracks customer reward
points, exposes a REST API for the storefront, and has an admin grid to
manage point balances.

Build a new Adobe Commerce module for B2B quote approvals — managers need
to approve or reject quotes above $10,000 before they can be submitted.

We need a module that listens to the order placement event, calculates
cashback based on order total, and stores it in a custom table.

Requirements phase

Let's gather requirements for the new inventory reservation module.
Start Phase 1.

I have a new module to plan — it syncs product data to an external PIM
via a REST API. Can you help me document the requirements?

Scaffolding

Requirements are done. Generate the module skeleton for Vendor_PimSync.

Set up the module structure — we need a custom table, a REST endpoint,
and an observer on catalog_product_save_after.

Implementation

Implement the data layer — Model, ResourceModel, Collection, and Repository
for the loyalty_points table.

Build the REST endpoint for /V1/loyalty/balance/:customerId. Make it
customer-authenticated and return points balance and expiry date.

I need an observer on sales_order_place_after that calculates cashback
and queues a message to process it async. Implement it.

Add a plugin on Magento\Catalog\Model\Product::getPrice that applies
a B2B tier discount for company customers.

Implement the GraphQL query for fetching loyalty point balance —
authenticated customer context, secure resolver, ACL-protected.

Create the admin grid for managing loyalty point balances — sortable,
filterable, with export to CSV.

Mid-development checks

Run a quick quality check on the current module.

Check if the DI configuration is valid after the last changes.

PHPCS is failing — show me the errors and fix them.

Validation

The implementation is done. Run the full quality suite and tests.

Phase 4 — validate everything and commit when all checks pass.

Run just the unit tests for now.

Documentation and reference

How do I implement a custom GraphQL resolver with ACL in Adobe Commerce?

Show me the OOTB pattern for declarative schema foreign keys.

What's the right approach — plugin or observer — for modifying order totals
before saving?

How does Magento handle store-scoped configuration? Show me the OOTB example.

Pre-commit review

Review my staged changes before I commit.

Check the staged files for ObjectManager usage and hardcoded store IDs.

I'm about to commit — validate the changes and suggest a commit message.

Status and reorientation

Where are we in the module development? What's left to do?

I just joined this project. What phase are we in and what's been done?

Show me the full status — all phases.

Prerequisites

• Claude Code installed
• adobe-commerce-mcp built and accessible
• Node.js ≥ 18
• An Adobe Commerce / Magento 2 project (Docker recommended: Warden or markshust/docker-magento)

Setup

# Install into your Commerce project
npm run setup:project -- --project /path/to/your/magento-project

# Developer role — Phase 3 + 4 only (for developers, not architects)
npm run setup:project -- --project /path/to/your/magento-project --role developer

# Self-setup (use this repo as the workspace)
npm run setup:project:self

After setup:

1. Copy .claude/mcp.json.example → .claude/mcp.json and fill in paths:

{
  "mcpServers": {
    "adobe-commerce": {
      "command": "node",
      "args": ["/path/to/adobe-commerce-mcp/dist/index.js"],
      "env": { "MAGENTO2_ROOT_DIR": "/path/to/magento-project" }
    }
  }
}

2. Open Claude Code in your project root and run /commerce-init.

What setup copies into your project:

| File | Behaviour | |---|---| | .claude/commands/ | Always copied (role-filtered) | | .claude/settings.json | Copied only if not already present | | .claude/mcp.json.example | Always copied | | .claude/hooks/ | Always copied | | CLAUDE.md | Copied only if not already present |

Role-based setup

| Role | Commands installed | For | |---|---|---| | full (default) | All 8 commands | Architects, tech leads, module owners | | developer | /phase3, /phase4, /commerce-status, /commerce-docs, /commerce-validate-quick | Developers implementing a pre-structured module |

Native tool equivalents by phase

| Phase | Commands used | |---|---| | Any | Environment detection from project files (§2 in CLAUDE.md) | | Phase 1 | find app/code, Read tool on module files | | Phase 2 | Claude writes skeleton from OOTB patterns; bin/magento setup:di:compile, bin/magento module:enable, bin/magento setup:upgrade | | Phase 3 | Claude writes components from OOTB patterns + skills; vendor/bin/phpcs, bin/magento setup:di:compile | | Phase 4 | vendor/bin/phpcs, vendor/bin/phpstan, vendor/bin/phpunit, vendor/bin/phpmd, bin/magento setup:upgrade | | General | bin/magento *, warden *, magento-cloud * |

The toolkit is MCP-free. Docker environment is detected by reading project files (.warden/warden-env.yml, docker-compose.yml). All CLI commands must be run inside the appropriate container when using Warden or markshust.

Claude Code-native features

| Feature | Detail | |---|---| | TodoWrite sprint board | Each phase command creates one todo per component/step — visible in real time as work progresses | | Project memory | Phase milestones (module name, environment, quality results) saved cross-conversation | | Parallel Phase 4 | Four background agents run quality checks simultaneously — ~3× faster than sequential | | Git phase commits | Phase 4 auto-commits REQUIREMENTS.md with a structured commit message on full pass | | Live docs | /commerce-docs queries developer.adobe.com via WebSearch | | Quality audit log | Every PHPCS, DI compile, and quality run appended to .claude/quality-log.jsonl |

License

MIT