AGENTS.md Template for Food Delivery Architecture

Overview

Direct answer: The AGENTS.md Template provides a copyable operating manual for AI coding agents that governs both single-agent execution and multi-agent orchestration within a food delivery platform architecture. It defines roles, memory, sources of truth, and governance to enable safe collaboration across order capture, payment, dispatch, routing, and last-mile delivery.

The template is designed to be pasted into a repository as project-level operating context for both individual agents and coordinated team workflows. It ensures traceability, reproducibility, and auditable handoffs across the lifecycle of food delivery operations.

When to Use This AGENTS.md Template

• When designing or extending a food delivery platform that uses AI agents for order intake, routing, and courier dispatch.
• When implementing multi-agent orchestration and explicit handoffs between planning, execution, validation, and monitoring.
• When you require tool governance, secrets management, and auditable decision history for production agents.
• When you need a repeatable operating model that can scale from a single agent to a distributed agent network.

Copyable AGENTS.md Template

Copy and paste the block below into your repository as AGENTS.md for a food delivery architecture project. It is the central operating context for both single-agent and multi-agent scenarios.

# AGENTS.md

Project Role
- Objective: orchestrate AI coding agents across order capture, payment, dispatch, routing, and delivery supervision in a food delivery platform.
- Scope: single-agent routing or a multi-agent team with planner, implementer, reviewer, tester, researcher, and domain specialist roles.

Agent roster and responsibilities
- Planner: designs end-to-end orchestration plan for a new feature (e.g., order-to-delivery flow), defines decision boundaries, and harmonizes constraints across services.
- Implementer: executes actions, makes API calls, updates state, and enforces plan steps in production-friendly modules.
- Reviewer: validates outputs, checks data integrity, and ensures compliance with governance and security rules.
- Tester: runs unit, integration, and synthetic end-to-end tests; simulates failure modes and validates resilience.
- Researcher: sources external data (traffic, weather, courier status) and tests new heuristics or data sources.
- Domain Specialist: ensures domain-specific rules (privacy, PCI, courier constraints, delivery windows) are upheld.

Supervisor or orchestrator behavior
- The Orchestrator maintains a live plan (planHash), coordinates handoffs, enforces memory constraints, and gates actions with tool governance and security checks.
- It logs decisions to the source of truth and raises escalation if memory drift or policy violations occur.

Handoff rules between agents
- Planner → Implementer when plan is ready for execution.
- Implementer → Reviewer when a task completes or a critical decision is made.
- Reviewer → Tester after validation criteria are satisfied.
- Researcher → Domain Specialist when new data sources or policy implications arise.
- Domain Specialist → Planner to update constraints or to approve policy shifts.

Context, memory, and source-of-truth rules
- Source of truth: central Order Service, Payment Gateway, Dispatch API, Routing Engine, Courier Status.
- Memory keys: orderId, planHash, lastExecutionAt, approvedChanges, dataSources.
- All decisions must cite sources; memory should be refreshed before critical decisions.

Tool access and permission rules
- Access is granted per least-privilege; secrets stored in a vault; tokens rotated every 24h.
- Agents must not log secrets or raw credentials; use secure references.
- API keys for external services must be scoped and auditable.

Architecture rules
- Event-driven microservices, idempotent operations, clear service boundaries, and eventual consistency where appropriate.
- All state transitions must be auditable and replayable.

File structure rules
- Use a single repository layout with:
  - agents/ (planner, implementer, reviewer, tester, researcher, domain-specialist)
  - workflows/
  - services/
  - data/
  - tests/
  - docs/

Data, API, or integration rules when relevant
- Data models: Order, Payment, Route, Courier, Status.
- API contracts documented and versioned; changes require approvals.

Validation rules
- All outputs validated against schemas; inputs validated for type, range, and domain constraints.

Security rules
- Encrypt sensitive data; restrict production access; maintain immutable logs; rotate credentials.

Testing rules
- Unit tests per agent, integration tests for service boundaries, and end-to-end smoke tests.
- Tests must cover failure modes, retries, and timeouts.

Deployment rules
- Use canary or blue/green deployments; feature flags for new agent logic; post-deploy validation checks.

Human review and escalation rules
- Critical decisions require human sign-off; escalate anomalies to on-call channels with sufficient context.

Failure handling and rollback rules
- On error, execute compensating actions, revert to last-good-state, and notify stakeholders.
- Ensure reproducibility through deterministic steps and traceability.

Things Agents must not do
- Do not bypass validation, bypass human review, copy secrets, or modify production configurations without approval.

Recommended Agent Operating Model

In a food delivery architecture, the recommended model uses a multi-agent orchestration pattern with clear decision boundaries. The Planner creates a plan aligned with service constraints and safety policies. The Implementer executes actions to achieve the plan, while the Reviewer verifies results against business rules and risk controls. The Tester validates functionality and resilience, the Researcher brings fresh data inputs, and the Domain Specialist ensures compliance with delivery, privacy, and payment constraints. Escalation paths exist for policy deviations or failures, feeding back into the Planner to adapt the operating context.

Recommended Project Structure

food-delivery-platform/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  workflows/
    order-dispatch/
  services/
    order-service/
    payment-service/
    dispatch-service/
    routing-service/
  data/
  tests/
  config/
  docs/

Core Operating Principles

• Operate with explicit handoffs and traceable context.
• Enforce least-privilege access and secret management.
• Validate outputs before state changes; require human review for risky actions.
• Maintain a single source of truth and citation for decisions.
• Favor idempotent operations and robust rollback paths.
• Document decisions, plan changes, and failure learnings.

Agent Handoff and Collaboration Rules

• Planner emits a concrete plan with success criteria and data sources; handoffs to Implementer only when the plan is approved.
• Implementer propagates operational context to Reviewer, including planHash and data citations.
• Reviewer validates outputs and, if approved, passes to Tester; if not, returns to Planner with required changes.
• Researcher supplies additional data inputs and test scenarios; Domain Specialist confirms policy alignment before any production step.
• Domain Specialist monitors regulatory constraints and triggers Planner updates when rules evolve.

Tool Governance and Permission Rules

• Only approved APIs and services may be invoked; secrets stored securely; credentials never checked into code.
• All tool calls must be auditable with planHash and source citations.
• Production actions require explicit approval when risk thresholds are exceeded.

Code Construction Rules

• Code should be modular, testable, and idempotent; avoid side effects without gating via the orchestrator.
• All data transformations must be validated against schemas; invalid inputs must be rejected gracefully.
• Use feature flags for risky changes; disable a feature if failures exceed thresholds.

Security and Production Rules

• PII and payment data must be encrypted in transit and at rest; access logged and auditable.
• Secrets are injected at runtime via a secure vault; avoid embedding secrets in code or logs.
• Production changes require code review, automated tests, and canary deployment with monitoring.

Testing Checklist

• Unit tests for each agent role and data model validations.
• Integration tests validating end-to-end order flow, including payment and dispatch integration.
• Contract tests for API boundaries between services.
• End-to-end smoke tests post-deploy; verify rollback path works.

Common Mistakes to Avoid

• Bypassing tests or human review for expediency.
• Overloading a single agent with cross-domain decisions.
• Missing sources-of-truth citations in decisions.
• Insecure handling of secrets or production keys.
• Unclear handoffs leading to data drift and repeated work.

Related implementation resources: AI Use Case for Quickbooks Invoices and Customer Payment Reminders and AI Agent Use Case for Food Processors Using Production Line Check-Sheets To Build Audit-Ready Food Safety Compliance Reports.

FAQ

What is the purpose of the AGENTS.md Template for food delivery architecture?

It provides a copyable operating manual for AI coding agents to govern single-agent and multi-agent workflows in a food delivery platform.

How does multi-agent orchestration work in this template?

The template defines roles, handoffs, memory, sources of truth, and governance so agents and the orchestrator can collaborate across order intake, payment, dispatch, routing, and delivery.

How are tool access and secrets handled?

Access is restricted by least privilege; secrets are stored securely; tokens rotate regularly and are scoped to services.

How do I validate outputs and handle failures?

Outputs are validated against schemas; tests cover failures; rollback paths revert state with audit trails.

What should agents not do according to the template?

Do not bypass validation, skip human review, log secrets, or modify production configurations without approval.