Booking System Architecture AGENTS.md Template

Overview

Direct answer: This AGENTS.md Template provides a concrete, repeatable operating manual for AI coding agents to govern a booking system architecture, enabling both single-agent and multi-agent orchestration with explicit handoffs, memory rules, and tool governance. It defines roles, boundaries, and escalation paths for reliable end-to-end workflows from search to booking confirmation, inventory coordination, payments, and notifications.

Purpose: Establish a consistent operating context for AI agents across a booking workflow.
Scope: Booking, inventory, payment, and notification services with explicit data flows and memory rules.

When to Use This AGENTS.md Template

When building a complex booking system that requires multiple AI agents collaborating across services.
When you need explicit handoff rules, source of truth, and tool governance to prevent context drift.
When you require a formal operating model at project level for single-agent and multi-agent orchestration.

Copyable AGENTS.md Template

# AGENTS.md

Project role: You are an AI coding agent responsible for orchestrating the booking system architecture across services and APIs.

Agent roster and responsibilities:
- Planner: Defines end-to-end flow, decomposes tasks, and sets handoff boundaries.
- Implementer: Builds components per plan, writes code and config.
- Reviewer: Checks alignment with constraints, security, and data models.
- Tester: Creates and executes test scenarios; reports results.
- Researcher: Collects API specs, rate limits, and integration details.
- Domain Specialist: Encapsulates business rules for bookings such as inventory, pricing, and compliance.

Supervisor or orchestrator behavior:
- A supervisor maintains the master plan, enforces tool governance, memory rules, and source-of-truth alignment.
- It detects drift, escalates issues, and triggers handoffs when needed.

Handoff rules between agents:
- Planner -> Implementer: provide scope, acceptance criteria, artifacts.
- Implementer -> Reviewer: provide changes, tests, and validation criteria.
- Reviewer -> Tester: provide validation results, edge cases.
- Researcher -> Planner: request new requirements if needed.
- Domain Specialist -> Planner or Implementer as needed for domain constraints.

Context, memory, and source-of-truth rules:
- Central memory store with versioning keeps context; do not rely on ephemeral memory.
- Source of truth: Booking DB, Inventory Service, Payment Gateway, Notification Service.
- All read/write operations reference canonical IDs.

Tool access and permission rules:
- Access Booking API, Inventory API, Payment API, Notification API via secure tools.
- Secrets must be retrieved from a vault; no hard-coded secrets; rotate regularly.

Architecture rules:
- Use event-driven and API-driven integration where appropriate.
- Ensure idempotent operations and clear provenance in logs.

File structure rules:
- Keep project directory focused on the booking workflow; no unused infra.
- Use a consistent naming convention for components and agents.

Data, API, or integration rules when relevant:
- Data models: Booking, Customer, Inventory, Payment, Receipt; ensure consistent field naming and types.
- Use contracts for external service calls.

Validation rules:
- Each component has acceptance criteria; run end-to-end tests; log failures with enough context.

Security rules:
- Least privilege access; tenant-scoped data; protect PII; audit trails.

Testing rules:
- Include unit, integration, contract, and end-to-end tests.

Deployment rules:
- Support canary or blue/green releases; rollback plan in case of failures.

Human review and escalation rules:
- Trigger human review for high-risk changes or failed critical paths.

Failure handling and rollback rules:
- Idempotent workflows; rollback to previous booking state if needed; audit trail retained.

Things Agents must not do:
- Do not bypass authentication; do not modify production data without approval; do not leak secrets; do not drift from agreed architecture.

Recommended Agent Operating Model

The booking workflow requires a planner to design the end-to-end path, an implementer to execute components, a reviewer to validate outputs, and a tester to verify end-to-end behavior. A researcher provides API specs and edge-case coverage; a domain specialist enforces business rules. Escalation paths route critical issues to a human reviewer or the supervisor when confidence is low or risk is high.

Recommended Project Structure

Aim for a workflow-specific layout focused on booking orchestration.

booking-system/
  src/
    api/
      booking/
      inventory/
      payment/
      notification/
    services/
      booking-service/
      inventory-service/
      payment-service/
  agents/
    planner/
      roadmap.md
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  workflows/
    booking-orchestration/
  tests/
  infra/

Core Operating Principles

Clear ownership and accountability for every task and decision.
Strict separation of planning, implementation, and validation roles.
Reliable memory and canonical source of truth; no ephemeral context drift.
Idempotent actions with versioned artifacts and auditable traces.
Secure handling of secrets, data, and production changes.

Agent Handoff and Collaboration Rules

Planner coordinates the end-to-end flow and creates formal handoffs with acceptance criteria.
Implementer produces code or artifacts with changesets and test plans.
Reviewer signs off on compliance, data integrity, and risk controls before rollout.
Tester executes end-to-end and contract tests; reports coverage and failure modes.
Researcher maintains up-to-date API specs, limits, and integration details; escalates gaps.
Domain Specialist enforces business rules and constraints on scheduling, pricing, and inventory usage.

Tool Governance and Permission Rules

All tool calls go through a central orchestrator with access controls and audit logging.
Secrets live in a vault with rotation; do not hard-code credentials.
Production calls require approved change gates and rollback plans.
External services must be treated as contracts with explicit SLAs and retries.

Code Construction Rules

Use well-typed interfaces for cross-service calls and versioned contracts.
Maintain idempotent operations; treat repeated events safely.
Document changes in a changeset and attach tests and acceptance criteria.
Leverage versioned configurations and feature flags for deployments.

Security and Production Rules

Enforce least privilege for all agents and services.
Encrypt sensitive data at rest and in transit; audit access to PII.
Implement canary/blue-green deployment with monitoring and quick rollback.
Log security events with sufficient context for incident response.

Testing Checklist

Unit tests for each agent component and service.
Integration tests across booking, inventory, payment, and notification services.
Contract tests for API boundaries between services.
End-to-end booking flow tests with real and mocked components.
Security and privacy checks, including data minimization tests.
Deployment validation with canary or blue-green tests.

Common Mistakes to Avoid

Context drift due to untracked memory and missing state references.
Unclear ownership leading to duplicated work or gaps in the workflow.
Unsafe production changes without proper approval or rollback.
Bypassing tool governance or leaking secrets.
Ignoring edge cases in multi-agent handoffs or domain rules.

FAQ

What is the purpose of this AGENTS.md Template for a booking system architecture?

The template provides a formal operating manual to govern AI coding agents across a booking workflow, enabling reliable single-agent and multi-agent orchestration with explicit handoffs and memory rules.

Which agent roles are included and what are their responsibilities?

Roles include Planner, Implementer, Reviewer, Tester, Researcher, and Domain Specialist, each with defined responsibilities to cover planning, execution, validation, and domain constraints.

How should handoffs between agents be executed and tracked?

Handoffs are documented in the template with scope, acceptance criteria, changesets, and validation results, ensuring traceability between planner, implementer, reviewer, and tester stages.

How is data and source of truth managed across services?

Context and memory are stored in a central memory store with versioning; all services reference canonical IDs in a defined source of truth such as Booking DB, Inventory, Payments, and Notifications.

What are the security and deployment considerations for production?

Enforce least privilege, rotate secrets, guard production changes with approved gates, support canary or blue-green deployment, and implement rollback procedures.

Target User

Use Cases