AGENTS.md Template for AGENTS.md template for Cache Stampede Prevention

Overview

Direct answer: This AGENTS.md template governs a cache stampede prevention workflow by defining a multi-agent orchestration model, explicit agent handoffs, and governance rules. It supports both single-agent operations and multi-agent coordination to keep high-traffic caches healthy while maintaining safety and traceability.

The template provides a concrete operating manual that scales from a single planning agent to a planner-led orchestration flow across domain specialists, researchers, implementers, testers, and reviewers. It emphasizes a single source of truth, auditable decisions, and safe, auditable tool use.

When to Use This AGENTS.md Template

• You need a repeatable, auditable pattern to prevent cache stampede in hot-cache scenarios.
• You operate a multi-agent system where planning, execution, data gathering, and validation are performed by specialized agents.
• You require explicit handoff rules, memory and source-of-truth management, and production-grade guard rails.

Copyable AGENTS.md Template

Copy the block below into a file named AGENTS.md at the root of your project to establish project-level operating context for single-agent and multi-agent work.

# AGENTS.md

Project Role
- Owner: Platform/API team
- Orchestrator: Lead Planner
- Agents: Planner, CacheManager, DataFetcher, HandoffCoordinator, Researcher, Reviewer, Tester, Logger, Auditor, SecurityAgent

Agent Roster and Responsibilities
- Planner: defines goals, success criteria, task decomposition, and coordinates overall workflow
- CacheManager: performs cache reads/writes, manages stampede protection, and coordinates pre-warm signals
- DataFetcher: retrieves external data required for decisions and validates data freshness
- HandoffCoordinator: manages cross-agent handoffs, routing decisions, and escalation paths
- Researcher: sources external knowledge when data is incomplete or ambiguous
- Reviewer: validates outputs against quality and security requirements
- Tester: executes test scenarios and concurrency checks
- Logger: records decisions, context, and artifacts for traceability
- Auditor: maintains a SoT (Source of Truth) and ensures compliance with governance
- SecurityAgent: enforces access controls, secret handling, and rotation policies

Supervisor or Orchestrator Behavior
- The Orchestrator maintains a live plan, monitors agent states, and enforces timeouts and retry policies
- All decisions must reference a single Source of Truth (SoT) and be auditable
- Handoffs occur only through the HandoffCoordinator and are logged with rationale

Handoff Rules Between Agents
- When Planner generates a plan, pass it to Implementer/CacheManager for execution
- If CacheManager cannot complete a step, escalate to Reviewer or SecurityAgent as needed
- If external data is required, route to Researcher or DataFetcher and then back to Planner
- Handoff decisions are reversible only through explicit rollback in the orchestrator

Context, Memory, and Source-of-Truth Rules
- Context must include cache key, TTL, traffic patterns, and health signals
- Memory should reference the SoT; avoid stale or inferred data without explicit revalidation
- All decisions must be traceable to sources in SoT and linked to a unique run ID

Tool Access and Permission Rules
- Tools allowed: Cache API, DataStore, Logging/Observability, Secrets vault
- No direct edits to production systems without authorization
- Secrets must be accessed via a secure vault and rotated per policy

Architecture Rules
- Event-driven, decoupled microservices pattern
- Asynchronous messaging to decouple planners from executors
- All write operations must be idempotent and replay-safe

File Structure Rules
- Keep the repository organized around workflows; avoid unused folders

Data, API, or Integration Rules When Relevant
- Cache keys namespace per service; TTLs must reflect data criticality
- Invalidation triggers must be explicit and auditable
- Observability and health endpoints must be protected and monitored

Validation Rules
- Validate correctness, idempotence, and alignment with SoT
- Ensure decisions are reproducible and auditable through logs and run IDs

Security Rules
- Least privilege for all agents
- Secrets rotation and access controls must be enforced
- Do not log sensitive data or secrets

Testing Rules
- Unit tests for individual agents; integration tests for cross-agent flows
- Simulated high-concurrency tests for stampede scenarios

Deployment Rules
- Deploy first to staging; run chaos tests; then promote with flags
- Use feature flags to enable/disable agents

Human Review and Escalation Rules
- Escalate to a human reviewer when data quality is uncertain or risk thresholds are exceeded
- Document escalation rationale and decision outcomes

Failure Handling and Rollback Rules
- Retry with exponential backoff; if persistent, rollback to last healthy cache state
- Notify stakeholders on failure and rollback events

Things Agents Must Not Do
- Do not modify production code without approval
- Do not bypass security controls or log secrets
- Do not perform unsanctioned data exfiltration or cache bypasses

Recommended Agent Operating Model

Roles and decision boundaries for a cache-stampede workflow:

• Planner: defines the optimization objective (prevent stampede, minimize latency) and approves the plan with acceptance criteria.
• CacheManager: implements the plan via safe cache operations and locks; ensures idempotence.
• DataFetcher/Researcher: sources required data; signals if data is missing or stale.
• HandoffCoordinator: routes tasks between agents and handles escalation paths.
• Reviewer: validates outputs, data quality, and adherence to SoT.
• Tester: exercises concurrency, failure modes, and rollback behaviors.
• SecurityAgent: enforces access, secrets, and production safety gates.

Recommended Project Structure

Workflow-specific directory tree:

ai-project/
├─ workflows/
│  └─ cache_stampede/
│     ├─ configs/
│     │  └─ cache_config.yaml
│     ├─ prompts/
│     │  └─ planner_prompts.md
│     ├─ tests/
│     │  ├─ unit/
│     │  └─ integration/
│     └─ logs/
├─ agents/
│  ├─ planner/
│  │  └─ plan.py
│  ├─ cache-manager/
│  │  └─ cache.py
│  ├─ data-fetcher/
│  │  └─ fetch.py
│  ├─ handoff-coordinator/
│  │  └─ route.py
│  ├─ researcher/
│  │  └─ sources.py
│  ├─ reviewer/
│  │  └─ validate.py
│  ├─ tester/
│  │  └─ test_flow.py
│  └─ security/
│     └─ vault.py
├─ configs/
├─ docs/
└─ tests/

Core Operating Principles

• Single source of truth (SoT) for decisions and data.
• Idempotent, replay-safe operations across all agents.
• Explicit, auditable agent handoffs with rationale.
• Controlled tool access with least privilege and secret rotation.
• Observability and traceability across the entire workflow.

Agent Handoff and Collaboration Rules

• Planner to CacheManager handoffs must include a plan, success criteria, and expected data sources.
• CacheManager to Researcher/DataFetcher when external data is required; results must be validated before handoff.
• Researcher to Planner for replanning if data quality is insufficient.
• Reviewer to Tester for validation scenarios; Tester must report all failure modes.
• HandoffCoordinator enforces order, timeouts, and logging of handshake rationale.

Tool Governance and Permission Rules

• Only allowed tools: Cache API, DataStore, Monitoring/Observability, Secrets vault.
• Do not bypass authentication or secret rotation policies.
• All tool interactions must be auditable with run IDs and traceability.

Code Construction Rules

• Use idempotent and deterministic cache operations.
• Validate inputs using schema validation and explicit type checks.
• Isolate side effects to permitted tools and guard rails.

Security and Production Rules

• Principle of least privilege for all agents.
• Secret rotation every 90 days and access audited.
• Do not log secrets; redact sensitive fields in logs.

Testing Checklist

• Unit tests for each agent cover edge cases and idempotence.
• Integration tests simulate high concurrency and cache stampede scenarios.
• End-to-end tests validate handoffs, data flows, and rollback paths.
• Security and access-control tests for vaults and tokens.

Common Mistakes to Avoid

• Omitting a single source of truth and losing traceability.
• Skipping explicit handoffs or bypassing escalation paths.
• Allowing hidden or unsupervised production changes by agents.

Related implementation resources: AI Use Case for Xero Reports and Business Performance Insights and AI Use Case for Visa Consultants Using Government Portals To Check Application Documents for Missing Requirements.

FAQ

What is this AGENTS.md Template for Cache Stampede Prevention?

This template defines a formal operating model for AI coding agents to prevent cache stampede using multi-agent orchestration, explicit handoffs, and governance rules.

Which agent roles are defined in this template?

Planner, CacheManager, DataFetcher, Researcher, HandoffCoordinator, Reviewer, Tester, Logger, Auditor, SecurityAgent.

How are cache keys and TTLs managed to prevent stampede?

Keys are namespaced per service; TTLs reflect data criticality; CacheManager implements safe locking and pre-warm signals to avoid concurrent eviction storms.

How do handoffs work between planner, implementer, and reviewer?

Handoffs are routed through the HandoffCoordinator with run IDs, rationale, and acceptance criteria; failures trigger escalation to Reviewer or SecurityAgent.

What are the escalation and rollback procedures?

On failure, retry with backoff; if persistent, rollback to last healthy cache state and notify stakeholders; all actions are logged.