Saga Pattern Architecture AGENTS.md Template for Multi-Agent Orchestration

Overview

Direct answer: This AGENTS.md template governs a saga-pattern architecture for orchestrating AI coding agents in distributed workflows. It supports both a single-agent mode and multi-agent orchestration with supervisor coordination, compensation actions, and human review where needed.

The Saga pattern coordinates long-running transactions across services by using compensating actions when failures occur. This AGENTS.md template is designed as a project-level operating context that defines agent roles, handoffs, memory, and governance rules for both single-agent and multi-agent executions.

When to Use This AGENTS.md Template

When designing multi-service workflows requiring distributed transaction patterns with compensating actions.
When you need explicit agent handoffs and escalation paths across planner, implementer, tester, and reviewer roles.
When tool governance, secrets access, and production safety are required for AI coding agents.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Saga Pattern Architect
Agent roster and responsibilities:
- Planner: Define saga steps, orchestration, and compensation strategy.
- Implementer: Implement service calls and agent actions per saga step.
- Validator: Validate outputs and keep memory/state in the source of truth.
- Tester: Execute test scenarios for happy and failing paths.
- Monitor: Observe runtime health, retry behavior, and alert on failures.
- Reviewer: Review changes to orchestration and compensation logic.

Supervisor or orchestrator behavior:
- Maintain a canonical plan of steps and compensations.
- Route handoffs between agents; enforce memory and memory refresh rules.
- Trigger compensating actions on failure and orchestrate rollback when needed.

Handoff rules between agents:
- Planner -> Implementer: hand off step details, inputs, and expected outputs.
- Implementer -> Validator: hand off results and evidence for acceptance.
- Validator -> Monitor: hand off health status and any anomalies.
- Monitor -> Reviewer: hand off escalation when manual review is required.

Context, memory, and source-of-truth rules:
- All state lives in a central source of truth (SoT).
- Agents should read and write to SoT; avoid caching decisions in short-lived memory unless necessary.
- All decisions and outputs must be traceable to inputs in the SoT.

Tool access and permission rules:
- Use read/write access to approved APIs and services only.
- Secrets must be retrieved via a secure vault and never logged in plaintext.
- Production system calls require approval gates and audit trails.

Architecture rules:
- Use event-driven or request-driven choreography with a central orchestrator.
- Each saga step should have a compensating action.
- Idempotency and retry semantics must be explicit.

File structure rules:
- Keep all saga-related artifacts under /workflows/saga-pattern/
- Use clear naming conventions for steps and compensations.

Data, API, or integration rules when relevant:
- Validate inputs against schemas; reject unexpected fields.
- Respect rate limits and backoff policies.

Validation rules:
- All outputs must be verifiable against the SoT.
- Tests must cover both success and compensation paths.

Security rules:
- Principle of least privilege for all agents.
- Secrets must be rotated and stored securely.
- Production secrets must never be logged.

Testing rules:
- Include unit, integration, end-to-end, and regression tests.
- Tests must be deterministic and isolated.

Deployment rules:
- Deploy saga orchestration with version tagging and rollbacks.
- Require canary checks for new runners.

Human review and escalation rules:
- Escalate edge cases to humans when risk exceeds threshold.
- Log all decisions for audit.

Failure handling and rollback rules:
- On failure, trigger compensating actions in reverse order.
- If rollback fails, escalate and halt production with a rollback plan.

Things Agents must not do:
- Do not bypass the source of truth.
- Do not execute unsupported API calls without approval.
- Do not perform unsupervised production changes.

Recommended Agent Operating Model

The Saga pattern operating model assigns clear decision boundaries and escalation paths. The Planner designs the steps and compensations; the Implementer performs actions; the Validator checks outcomes against the canonical SoT; the Monitor watches for failures; and the Reviewer approves changes to the orchestration logic. In multi-agent runs, a central Orchestrator coordinates handoffs, ensures memory consistency, and triggers compensations when needed. If a failure occurs beyond automatic recovery, human review is invoked per escalation rules.

Recommended Project Structure

workflows/saga-pattern/
├── planning/
├── implementation/
├── validation/
├── compensation/
├── tests/
├── docs/
└── config/

Core Operating Principles

Single source of truth for all saga state.
Idempotent steps and explicit compensations.
Clear handoffs and no silent state drift.
Auditable decisions and human review on escalation.
Secure access to tools and secrets with least privilege.

Agent Handoff and Collaboration Rules

Planner defines steps and handoffs; Implementer executes steps and logs evidence.
Validator validates outputs; if invalid, trigger remediation or compensate.
Monitor alerts on failure; escalate to Reviewer if manual intervention is required.
Researchers and Domain Specialists provide inputs at decision points; maintain traceability.

Tool Governance and Permission Rules

All tool calls are subject to approval gates and logging.
Secrets retrieved from vault; never hard-coded or logged.
Production changes require review and rollback plans.

Code Construction Rules

Prefer declarative configurations for saga steps and compensations.
All actions must be idempotent and retry-safe.
Keep dependencies minimal and well-scoped to the saga.

Security and Production Rules

Follow least privilege across all agents and services.
Enable logging, audit trails, and anomaly detection.
Implement secure error handling that does not leak secrets.

Testing Checklist

Unit tests for each step and compensation.
Integration tests across services involved in the saga.
End-to-end tests simulating success and failures with rollback.
Canary and rollout tests for new orchestrations.

Common Mistakes to Avoid

Ignoring the source of truth and drifting state between agents.
Skipping compensating actions or making them non-idempotent.
Bypassing escalation paths or performing production changes without review.

FAQ

How does this AGENTS.md template support the Saga pattern orchestration?

The template defines roles, handoffs, and governance for multi-agent coordination with compensations and human review when needed.

What outputs should I expect from this AGENTS.md template?

A copyable AGENTS.md block and operating context to paste into your project.

How are failure and rollback handled in this workflow?

Failures trigger compensating actions in reverse order; escalation rules trigger human review if needed.

How is memory/SoT maintained across agents?

All state is stored in a central source of truth; agents read/write to it and avoid stale caches.

When is human review required?

At escalation points or when risk thresholds are exceeded, with audit logging.

Target User

Use Cases