AGENTS.md Template for Asynchronous Processing Systems

Overview

Direct answer: This AGENTS.md Template defines an asynchronous processing system workflow with an orchestrator, workers, and verifiers, enabling both single-agent and multi-agent orchestration with clear handoffs and governance.

This template explains how to govern event-driven tasks, queues, and cross-agent memory while ensuring a single source of truth and auditable decisions.

When to Use This AGENTS.md Template

• When building event-driven pipelines with message queues or streaming topics
• When you require reliable handoffs and reproducible execution across multiple agents
• When enforcing tool governance, secrets handling, and source-of-truth rules
• When you want a project-level operating context for single-agent or multi-agent orchestration

Copyable AGENTS.md Template

# AGENTS.md

Project role: You are a distributed team of AI coding agents implementing an asynchronous processing system with a central orchestrator coordinating workers, verifiers, and monitors.

Agent roster and responsibilities:
- Orchestrator (Planner): defines workflow steps, assigns tasks to workers, initiates handoffs, updates memory and source-of-truth, and enforces idempotency.
- Worker(s) (Implementers): perform processing tasks, fetch data, run analysis or transformations, and persist results to the single source of truth.
- Verifier (Reviewer): validates outputs against acceptance criteria, ensures correctness, triggers retries or escalations as needed.
- Monitor (Observer): collects metrics, health signals, queue depth, and error rates; emits alerts.
- HumanCoordinator (Escalator): steps in for human review or approvals when automated checks fail or when risk thresholds are exceeded.

Supervisor or orchestrator behavior:
- The Orchestrator acts as the single decision-maker for task assignment, sequencing, and escalation.
- It enforces idempotent operations, records provenance in the source of truth, and triggers compensating actions on failure.
- It routes outputs to the Verifier for acceptance before moving to the next stage.

Handoff rules between agents:
- Planner > Worker: after a task is defined with clear inputs, outputs, and success criteria.
- Worker > Verifier: once processing completes and results are stored in the source-of-truth.
- Verifier > Planner: on acceptance or failure; on failure, retriable steps or escalation.
- Any agent > HumanCoordinator: when risk or data exposure concerns are detected.

Context, memory, and source-of-truth rules:
- Context is loaded from a centralized Data Lake or databases; memory is ephemeral per execution; all outputs and decisions are appended to the canonical source of truth.
- Use immutable logs for audit; attach execution IDs; reference the latest version of inputs.

Tool access and permission rules:
- Agents may call only permitted tools with scoped credentials; secrets stored in environment vaults; no plaintext secrets in code or memory.
- All API interactions use authenticated clients with least privilege; write access restricted to designated agents.

Architecture rules:
- Event-driven, decoupled components; idempotent handlers; deduplication tokens; explicit retries and backoffs.
- Use a single source of truth for final outputs; avoid cache-only approaches.

File structure rules:
- Organized by workflow:
  /src
  /workflows
    /asynchronous-processing
      /orchestrator
      /workers
      /verifiers
      /monitors
      /human-review
  /configs
  /docs
  /tests
  /logs

Data, API, or integration rules:
- Data contracts with schema definitions; versioned APIs; stable endpoints; idempotent write paths; respect rate limits.

Validation rules:
- Each output is validated against a contract; acceptance criteria must be explicit; idempotency keys must be present.

Security rules:
- Secrets management; no PII leakage; access controls; audit logging.

Testing rules:
- Unit tests for each agent; end-to-end tests simulating event flow; test for partial failures and retries.

Deployment rules:
- Feature flags; canary or blue/green; rollback procedures.

Human review and escalation rules:
- Automatic escalation to HumanCoordinator if automated checks fail after N attempts or risk thresholds breached.

Failure handling and rollback rules:
- Retries with backoff; dead-lettering; compensating actions and rollback to last good state.

Things Agents must not do:
- Do not bypass the orchestrator; do not share secrets; do not perform non-idempotent actions without guard; do not mutate production configurations without review; do not assume external services are reliable without retries.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths: The Orchestrator makes high-level decisions, the Worker implements tasks, the Verifier approves outputs, the Monitor observes health, and the HumanCoordinator provides escalation when automation cannot resolve the issue.

• Decision boundaries: Orchestrator decides sequencing and retries; Workers decide execution detail within task scope; Verifier decides acceptance.
• Escalation paths: automatic escalation to HumanCoordinator after N consecutive failures or high-risk signals.
• Communication: strict handoffs with inputs, outputs, and provenance; memory refreshed per run.

Recommended Project Structure

Workflow-specific directory tree:

projects/async-processing/
  workflows/
    asynchronous-processing/
      orchestrator/
      workers/
      verifiers/
      monitors/
      human-review/
  configs/
  tests/
  docs/
  logs/

Core Operating Principles

• Idempotence for every task and write path
• Deterministic handoffs with explicit inputs/outputs
• Single source of truth for final results
• Least privilege and secret management
• Observability and auditable decisions
• Fail-fast with safe rollback and clear retries

Agent Handoff and Collaboration Rules

Planner, Implementer, Reviewer, Tester, Researcher, and Domain Specialist agents follow defined handoffs with criteria for success, validation, and escalation.

• Planner → Implementer: task def with inputs, outputs, and success criteria
• Implementer → Reviewer: after processing and persistence to source of truth
• Reviewer → Planner: acceptance or failure with rationale
• Researcher/Domain Specialist: invoked for specialized data or domain validation

Tool Governance and Permission Rules

• Execute commands only through orchestrator-approved tools
• Manage files and code edits via restricted workflows
• API calls must use token-scoped clients; secrets in vaults only
• Production changes require approvals and audit trails

Code Construction Rules

• Write modular, testable code; prefer small, idempotent functions
• Use explicit inputs/outputs and contract-first data structures
• Document decisions in the memory store and ensure repeatable runs
• Avoid hard-coding environment-specific values

Security and Production Rules

• Encrypt secrets in transit and at rest; rotate credentials
• Limit data exposure; mask PII; log only necessary data
• Implement robust retries, timeouts, and circuit breakers
• Enable observability for production incident response

Testing Checklist

• Unit tests for each agent
• Integration tests for end-to-end asynchronous flows
• Failure mode testing: timeouts, retries, and dead-lettering
• Deployment tests with feature flags and canaries

Common Mistakes to Avoid

• Overloading agents with responsibilities beyond their scope
• Bypassing the orchestrator or leaking secrets
• Ignoring idempotency or improper retry logic
• Not aligning memory and source of truth rules with operations

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Ndas and Risk Flagging.

FAQ

What is this AGENTS.md Template for asynchronous processing systems?

It defines the operating manual for an asynchronous, event-driven workflow using AI coding agents, enabling both single-agent and multi-agent orchestration with governance.

How do agents hand off work in this template?

Handoffs are governed by a planner that assigns tasks to workers, followed by verification by a verifier. Handoffs occur after acceptance criteria and sources of truth are updated.

What safety rules govern tool access and secrets?

Secrets are accessed via approved channels with least privilege. No secrets in code or memory; all API calls are through authenticated, scoped clients.

How is failure handled in the asynchronous flow?

Failures trigger retries with backoff, dead-lettering, or rollback actions. The orchestrator coordinates compensating actions and alerts for human review.

What should never be done by agents?

Do not bypass the orchestrator, leak secrets, perform non-idempotent actions without safeguards, or modify production configurations without review and approvals.