AGENTS.md Template: Shopping Cart Architecture

Overview

The AGENTS.md Template: Shopping Cart Architecture defines the operating model for AI coding agents handling end-to-end cart flow. It governs a multi-agent orchestration pattern that coordinates a Planner, Inventory Agent, Pricing Agent, Checkout Agent, and Payment Agent under a central Orchestrator. It works for single-agent usage or full multi-agent handoffs with explicit steps, memory rules, and governance to maintain correctness and auditability.

Direct answer: This template provides a copyable, project-level operating manual for AI agents in a shopping cart context, covering roles, handoffs, context, tool governance, security, testing, deployment, and escalation paths.

When to Use This AGENTS.md Template

When building a shopping cart workflow that uses AI agents to manage catalog, inventory, pricing, checkout, and payments.
When you require explicit handoffs and a shared cart state to avoid context drift.
When you want a repeatable operating model across repos and teams (engineering, product, security).
When you need to enforce tool governance and security around external services and secrets.

Copyable AGENTS.md Template

# AGENTS.md
Project Role: Shopping Cart Orchestrator for AI coding agents
Agent roster and responsibilities:
- Planner: defines the workflow and task decomposition for cart lifecycle
- InventoryAgent: checks stock and reserves items
- PricingAgent: computes totals, discounts, taxes, and price updates
- CheckoutAgent: validates cart, applies promotions, and locks cart state for checkout
- PaymentAgent: processes payment through gateway and records result
- Orchestrator: coordinates agents, enforces rules, and records source of truth
Supervisor or orchestrator behavior:
The Orchestrator monitors progress, resolves conflicts, enforces memory rules, and triggers handoffs. It maintains the canonical cart state in the source of truth after each milestone.
Handoff rules between agents:
- Planner -> InventoryAgent: deliver cart items and stock status
- InventoryAgent -> PricingAgent: finalize price adjustments based on stock
- PricingAgent -> CheckoutAgent: confirm totals including discounts and taxes
- CheckoutAgent -> PaymentAgent: initiate payment and confirm success
- PaymentAgent -> Orchestrator: return payment result and finalize order
Context, memory, and source-of-truth rules:
All agents share a cart state object in memory; after each milestone, the state is persisted to a durable source of truth (e.g., database or event store). The orchestrator reconciles differences.
Tool access and permission rules:
Agents have scoped APIs to catalog, inventory, pricing, checkout, and payment services. Write access is controlled by the orchestrator with explicit approvals. Secrets are never logged.
Architecture rules:
Define clear service boundaries, idempotent operations, event-driven state transitions, and traceable decisions for auditability.
File structure rules:
Follow the repository structure described in the project structure section. Do not create unrelated folders.
Data, API, or integration rules when relevant:
Include idempotent keys on external calls; validate inputs; standardize payload shapes across services.
Validation rules:
Preconditions for each step, postconditions on success, and error propagation with structured error codes.
Security rules:
Encrypt secrets at rest and in transit; enforce least privilege; prohibit credential leakage in logs and outputs.
Testing rules:
Unit tests for each agent, integration tests for the cart workflow, end-to-end tests for multi-agent orchestration, and contract tests for API boundaries.
Deployment rules:
Support canary deployments of orchestration changes; require feature flags for new logic; rollback without data loss.
Human review and escalation rules:
Raise human review on pricing anomalies or failed payments; route escalations to product or security teams as appropriate.
Failure handling and rollback rules:
If a step fails, revert to the last known-good cart state, alert the orchestrator, and perform a safe rollback of side effects.
Things Agents must not do:
Do not bypass validation, bypass approvals, modify catalog or pricing without authorization, bypass the orchestrator, or perform unsanctioned production changes.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to support both single-agent execution and multi-agent orchestration. The Planner designs workflows and delegations; the Implementers (InventoryAgent, PricingAgent, CheckoutAgent, PaymentAgent) execute tasks with defined boundaries; the Reviewer validates decisions; the Tester confirms end-to-end functionality; Researchers and Domain Specialists address edge cases and regulatory concerns; the Orchestrator resolves conflicts and handles escalations.

Recommended Project Structure

shopping-cart-architecture/
├── agents/
│   ├── planner/
│   │   └── planner.md
│   ├── orchestrator/
│   │   └── orchestrator.md
│   ├── inventory_agent/
│   │   └── inventory_agent.md
│   ├── pricing_agent/
│   │   └── pricing_agent.md
│   ├── checkout_agent/
│   │   └── checkout_agent.md
│   └── payment_agent/
│       └── payment_agent.md
├── memory/
│   └── cart_state.json
├── tools/
│   ├── api_clients/
│   │   ├── catalog_client.py
│   │   ├── inventory_client.py
│   │   ├── pricing_client.py
│   │   └── payment_client.py
│   └── secrets/
├── workflows/
│   └── shopping_cart_workflow.md

Core Operating Principles

Single source of truth for cart state with explicit, auditable transitions.
Idempotent and replayable steps to prevent drift and duplication.
Clear roles, responsibilities, and escalation paths for all agents.
End-to-end traceability across all handoffs and external calls.
Least privilege access and strict secrets management for all tools.
Documented decision boundaries and constraint-driven automation.

Agent Handoff and Collaboration Rules

Planner coordinates task decomposition and distributes work to Implementers.
InventoryAgent must confirm stock before prices are adjusted; pricing cannot finalize without stock validation.
PricingAgent updates totals only after inventory state is confirmed; any discount or tax rule must be validated by CheckoutAgent.
CheckoutAgent locks the cart to prevent concurrent modifications during finalization.
PaymentAgent completes gateway interaction and returns a canonical result to Orchestrator.
Domain Specialists and Researchers provide guidance on edge cases; reviewers validate policy compliance before deployment.

Tool Governance and Permission Rules

All tool calls must be mediated by the Orchestrator; direct agent calls to external services are prohibited.
Secrets are stored in a dedicated vault and never logged or surfaced in outputs.
APIs must require authentication tokens with scoped permissions; token rotation is enforced.
External payments require a formal approval gate before production use.
All data exfiltration actions require explicit authorization; audit logs are immutable.

Code Construction Rules

Use typed interfaces and explicit payload schemas for all communications between agents.
Prefer small, composable functions with clear side-effect boundaries.
Document decisions in code comments and in the AGENTS.md template at the project root.
Avoid hard-coded values; use configuration and environment-driven parameters.
Maintain idempotent write operations and deterministic ordering of state changes.

Security and Production Rules

Encrypt sensitive data in transit and at rest; use secure channels for all external calls.
Audit all agent actions and provide retrievable traces for security investigations.
Implement feature flags for orchestration changes and require authorization for production deployments.
Isolate production secrets from development environments with strict access controls.

Testing Checklist

Unit tests for each agent with deterministic inputs.
Integration tests validating end-to-end cart flow across planner, agents, and orchestrator.
Contract tests for API boundaries between services (catalog, inventory, pricing, payment).
End-to-end test scenarios including failure and rollback paths.

Common Mistakes to Avoid

Allowing context drift by skipping explicit handoffs or leaving cart state implicit.
Bypassing orchestrator controls for tool access or state changes.
Using production secrets in non-production contexts or verbose logging of sensitive data.
Overloading agents with responsibilities outside their domain (scope creep).
Neglecting rollback or failure handling in the workflow design.

FAQ

Question?

How do I use this AGENTS.md Template for a shopping cart workflow?

Question?

How should I structure the agent roster for multi-agent orchestration in this template?

Question?

What are the key handoffs between planners, inventory, pricing, checkout, and payment agents?

Question?

How are memory and source-of-truth managed across the cart lifecycle?

Question?

What security and governance rules are required for production deployments?

Target User

Use Cases