Domain context generator

PrestaShop Domain CONTEXT.md Generator

Purpose

Generate a minimal, accurate CONTEXT.md for a PrestaShop business domain (src/Core/Domain/{Name}/). The goal is the smallest file that gives an AI agent enough orientation to work in the domain — not an inventory of every class.

Output format

# {Domain} Domain

> **Status:** Draft — this context file is a starting point and should be refined by domain experts.

## Purpose

{1–2 sentences: what this domain does and what it does NOT do}

## Layers

| Layer | Path |
|-------|------|
| Core CQRS | `src/Core/Domain/{Name}/` — Commands, Queries, QueryResults, ValueObjects, Exceptions |
| Adapter | `src/Adapter/{Name}/` — handler implementations, repositories |
| Legacy ObjectModel | `classes/{Name}.php` ({N} lines) — do not add logic here |
| Back-office UI | controller path, grid factory name, TS frontend path |

## Non-obvious patterns

- {Things that aren't discoverable by reading the directory structure}
- {Surprising abstractions, delegation chains, cross-domain flows, legacy gotchas}

## Canonical examples

- `path/to/Command.php` + `path/to/Handler.php`
- `path/to/Query.php` + `path/to/ResultDTO.php`

## Skills

- [`skill-name`](../../skills/skill-name/SKILL.md) — one-line description

## Related

- [Component/Domain](path) — one-line reason

## Skills is optional — only include it if a skill in .ai/skills/ targets this domain. Omit the section entirely if no relevant skill exists.

Do NOT include: class name inventories (command names, exception names, value object names, handler names). These are greppable on demand and waste context tokens.

Do NOT include: ## Coding standards, ## Do, ## Don't, ## Testing expectations — project-wide, live in .ai/CONTEXT.md.

---

Step-by-step process

0. Confirm the target is a Domain, not a Component

Check that src/Core/Domain/{Name}/ exists and contains a CQRS structure (Command/, Query/, or handler interfaces). If you don't find a dedicated CQRS layer or a Controller for this domain, it is probably a Component — use the component-context-generator skill instead.

1. Explore the codebase

Use the Explore agent to map:

• src/Core/Domain/{Name}/ — subdirectory names (Command/, Query/, ValueObject/, Exception/, sub-domains)
• src/Adapter/{Name}/ — subdirectory names (CommandHandler/, QueryHandler/, Repository/, any unusual patterns)
• classes/{Name}.php — does it exist? approximate line count
• src/PrestaShopBundle/Controller/Admin/**/{Name}Controller.php — exists?
• Any sub-domains under src/Core/Domain/{Name}/ with their own CQRS structure
• Other domains that reference this domain (grep for {Name}Id or {Name}Command)

Do NOT enumerate every file — just note what layers/patterns exist and what's non-obvious.

2. Write the Layers table

One row per layer that actually exists. Path only — no class names.

3. Write Non-obvious patterns

Ask: what would surprise a developer reading this domain for the first time?

• Separate calculation/engine layer (like Cart's src/Core/Cart/)
• Delegation chains (like Product's filler pattern)
• Sub-domains with their own full CQRS structure
• Legacy class size and usage warning
• Cross-domain flows (which other domain consumes this one)

Skip anything obvious from the directory structure.

4. Write Canonical examples

2 file path pairs maximum:

• One Command + its Handler
• One Query + its result DTO

5. Check for relevant skills

List the contents of .ai/skills/ and check if any skill targets this domain (e.g. a create-{entity} or add-{domain}-form skill). If one exists, include a ## Skills section before ## Related linking to it.

6. Write Related (use sparingly)

Every cross-reference is a potential cascade: an AI agent reads domain A, follows a link to domain B, follows B's link to component C... and loads everything. This defeats the purpose of the split.

Include a link when:

• The cross-domain flow is non-obvious and would surprise a developer (e.g. Cart → Order conversion happens in the Order domain, not Cart)
• A DevDocs URL exists for this domain

Do NOT include a link when:

• The relationship is obvious from imports (e.g. "this domain uses CQRS" — they all do)
• You're linking to a component just because the domain consumes it (Controller, Forms, Grid are consumed by every migrated domain)
• The link would create a bidirectional reference (A → B and B → A)

When in doubt, omit the link. An agent can always find related contexts via the index in .ai/CONTEXT.md.

---

Reference: Cart domain (canonical lean example)

# Cart Domain

> **Status:** Draft — this context file is a starting point and should be refined by domain experts.

## Purpose

Manages the shopping cart lifecycle: creation, product additions/removals, quantity updates,
cart rule application, address/carrier/currency settings, and price computation.
Does not handle order creation — that is the Order domain's responsibility.

## Layers

| Layer | Path |
|-------|------|
| Core CQRS | `src/Core/Domain/Cart/` — Commands, Queries, QueryResults, ValueObjects, Exceptions |
| Adapter | `src/Adapter/Cart/` — handler implementations, `CartRepository`, `CartProductsComparator` |
| Calculation engine | `src/Core/Cart/` — pure price/tax/discount computation, independent of persistence |
| Legacy ObjectModel | `classes/Cart.php` (5 000+ lines), `classes/CartRule.php` — do not add logic here |
| Presenter | `src/Adapter/Presenter/Cart/` — lazy-loading Smarty presentation layer |
| Back-office UI | `CartController.php`, `CartGridDefinitionFactory`, `CartSummaryType`, `cart-editor.ts` |

## Non-obvious patterns

- The **calculation engine** (`src/Core/Cart/`) is separate from the CQRS domain layer —
  `Calculator` orchestrates totals purely in memory; adapter handlers call it before persisting
- Cart→Order conversion happens via `AddOrderFromBackOfficeCommand` in the **Order domain**,
  which takes a `CartId`; the Cart domain has no knowledge of this
- `AbstractCartHandler` in Adapter provides shared cart-loading and validation used by all handlers

## Canonical examples

- `src/Core/Domain/Cart/Command/AddProductToCartCommand.php` + `src/Adapter/Cart/CommandHandler/AddProductToCartHandler.php`
- `src/Core/Cart/Calculator.php` — calculation engine entry point

## Related

- [Order Domain](../Order/CONTEXT.md) — Cart→Order conversion happens in the Order domain via `AddOrderFromBackOfficeCommand`
- [DevDocs](https://devdocs.prestashop-project.org/9/development/architecture/domain/references/cart/#cart-domain/)

---

Output

Write to .ai/Domain/{Name}/CONTEXT.md. Create the directory if needed. Confirm the file path to the user when done.