e-commerce-agents CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

E-Commerce Agents is a multi-agent e-commerce platform built with Microsoft Agent Framework (MAF) Python SDK. 6 specialized agents collaborate via A2A protocol to handle product discovery, orders, pricing, reviews, inventory, and customer support. Includes a marketplace layer with agent catalog, access requests, and admin approval.

Companion demo repo for the AI article series on nitinksingh.com.

Working Artifacts Location

All working artifacts live in the repo-local .claude/ folder only:

• .claude/plans/ — one consolidated plan (remaining-work.md). Finished plans are deleted rather than archived: git keeps them, and a directory of stale plans makes "what is left?" a research question every time it is asked
• .claude/agents/ — the subagent definitions and the model-strategy README
• .claude/settings.json — the session model (opusplan)

There is deliberately no .claude/memory/ or .claude/rules/: durable facts belong in this file or in AGENTS.md, and anything short-lived belongs in the one plan. Earlier revisions of this section described both directories; neither has ever existed.

Do not put these in the repo root (no top-level plans/ folder) or rely on global ~/.claude. Keeping them under the repo-local .claude/ means they are committed with the project and travel with it.

Key Commands

# Start everything from scratch (one command)
./scripts/dev.sh
./scripts/dev.ps1              # PowerShell equivalent — same flags, PascalCase
                               # (-Clean / -SeedOnly / -InfraOnly / -Dotnet)

# Clean rebuild (nuke volumes, rebuild images)
./scripts/dev.sh --clean

# Start infrastructure only (db, redis, aspire)
./scripts/dev.sh --infra-only

# Re-run seeder against existing DB
./scripts/dev.sh --seed-only

# Start everything via docker compose directly
docker compose up --build

# Run a single agent locally (for dev)
cd agents/python && uv run uvicorn product_discovery.main:app --port 8081 --reload

# Run frontend locally
cd web && pnpm dev

# Generate embeddings
cd agents/python && uv run python -m scripts.generate_embeddings

# Lint Python
cd agents/python && uv run ruff check .
cd agents/python && uv run ruff format --check .

# Run Python tests (--all-packages pulls in the MCP workspace packages, e.g. ecommerce-mcp-product)
cd agents/python && uv sync --all-packages --extra dev
cd agents/python && uv run pytest
cd agents/python && uv run pytest tests/test_specific.py -k "test_name"

# Lint frontend
cd web && pnpm lint

# Run Playwright E2E tests (requires running app at localhost:3000)
cd web && pnpm exec playwright test
cd web && pnpm exec playwright test e2e/chat-all-users.spec.ts

# Open Aspire Dashboard (telemetry visualization)
open http://localhost:18888