AGENTS.md Template: Cache TTL Design

Overview

Direct answer: This AGENTS.md template defines a cache TTL design workflow for AI coding agents, enabling both single-agent and multi-agent orchestration with explicit handoffs, memory rules, and governance.

The template provides a project-level operating context for designing and enforcing TTL policies for cached data used by AI agents, including how to compute TTLs, when to invalidate, and how to coordinate across planners, implementers, validators, and monitors. It supports both a simple single-agent pattern and a robust multi-agent orchestration with defined handoffs and escalation paths.

When to Use This AGENTS.md Template

When you need a formal TTL strategy for a cache used by AI coding agents.
When TTL decisions require collaboration across planners, implementers, validators, and monitors.
When you must enforce tool governance, secrets handling, and production-safe changes with human review.
When you require a clear memory and source-of-truth model for TTL policies.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Cache TTL design and governance for an AI caching layer used by AI coding agents. Define TTL policies, invalidation triggers, and handoffs for single-agent and multi-agent workflows.

Agent roster and responsibilities:
- Planner: designs TTL policy, cache key patterns, and data freshness requirements.
- Implementer: encodes TTL logic in cache access, eviction, and refresh routines.
- Validator: tests TTL policies against data volatility and access patterns.
- CacheUpdater: applies TTL policy to the cache store (e.g., Redis/Memory Cache).
- Monitor: collects TTL metrics and triggers alarms for TTL drift or stale data.
- SecurityAuditor: reviews secrets handling, access to KV stores, and audit trails.
- Reviewer: approves TTL policy changes before production.

Supervisor or orchestrator behavior:
- Orchestrator sequences planning, implementation, validation, and deployment steps.
- Maintains a canonical memory of TTL policy, data sources, and approvals.
- Enforces tool governance and escalation paths when issues arise.

Handoff rules between agents:
- Planner delivers TTL policy to Implementer with explicit acceptance criteria.
- Implementer runs TTL application, then passes results to Validator.
- Validator returns pass/fail; on pass, CacheUpdater applies changes; on fail, Planner revises policy.
- Monitor and SecurityAuditor observe changes post-deploy and report anomalies.

Context, memory, and source-of-truth rules:
- Primary TTL policy source-of-truth: TTL_POLICY_STORE.
- Cache key definitions live in CACHE_SCHEMA and are versioned.
- Memory is limited to policy context and recent decision history for traceability.

Tool access and permission rules:
- Agents may read data sources and policy stores.
- Writes go through the orchestrator and require approval from Reviewer.
- Secrets must be accessed via guarded vault interfaces; no plaintext secrets in logs.

Architecture rules:
- Service: TTL Design Service → interacts with Cache Store and Data Source.
- Data flow: Planner & Implementer → Validator → CacheUpdater → Monitor.

File structure rules:
- Place TTL policy, keys, and policy docs under ttl-policy/
- Agent code under ttl-design/ai-skills/agents-md-templates/, separated by role.

Data, API, or integration rules when relevant:
- GET /cache/ttl/{key} returns TTL and last refreshed timestamp.
- POST /cache/ttl/update applies a new TTL policy with audit trail.

Validation rules:
- TTL must be positive and bounded by MAX_TTL. All changes require test coverage and staging validation.

Security rules:
- Do not log secrets or plaintext keys. Use vault-backed secrets.

Testing rules:
- Unit tests for TTL calculation; integration tests for cache refresh; end-to-end tests for handoffs.

Deployment rules:
- TTL policy changes require PR review and staged deployment.

Human review and escalation rules:
- Any TTL policy change with drift or failing tests must trigger human review.

Failure handling and rollback rules:
- If TTL update causes cache inconsistency, rollback to previous TTL and notify the team.

Things Agents must not do:
- Do not bypass orchestrator, mutate shared memory outside policy, or perform production changes without approvals.

Recommended Agent Operating Model

The agent roles form a bounded trust model with clear decision boundaries. The Planner defines policy intent; the Implementer translates policy into code paths; the Validator confirms policy correctness; the CacheUpdater enforces TTL values; the Monitor watches for drift; the SecurityAuditor ensures policy and secrets compliance; the Reviewer gates production changes. Escalations flow to a human review step when validation fails or drift is detected.

Recommended Project Structure

cache-ttl-design/
├── planner/
├── implementer/
├── validator/
├── cache-updater/
├── monitor/
├── security-auditor/
├── reviewer/
├── ttl-policies/
├── ttl-schemas/
├── data-sources/
├── configs/
├── tests/
└── docs/

Core Operating Principles

Single source of truth for TTL policies and cache key definitions.
Idempotent and auditable TTL changes with explicit approvals.
Explicit agent handoffs with defined acceptance criteria.
Tool governance, secrets handling, and production safety enforced.
Deterministic TTL computation based on data volatility and access patterns.

Agent Handoff and Collaboration Rules

Planner -> Implementer: Policy + acceptance criteria; Maintain traceable decision id.
Implementer -> Validator: Apply TTL logic and provide test data back to Verification.
Validator -> Planner: Report pass/fail and rationale; if fail, iterate policy.
Monitor -> Reviewer: Alert on drift or post-deploy anomalies; request policy tweaks if needed.
Domain specialist or Researcher: Provide data-driven inputs when volatility patterns change.

Tool Governance and Permission Rules

Actions on production data require orchestrator approval and audit trails.
Secrets and credentials must be accessed via secure vaults; avoid plaintext in logs.
API calls to cache stores must be authenticated; rate limits enforced.
All TTL changes are recorded with who, when, and why.

Code Construction Rules

TTL calculation modules must be pure and side-effect-free for deterministic testing.
Code paths must be guarded with feature flags for safe rollouts.
Tests must cover edge TTL values and drift scenarios.
Documentation must reflect current policy and decision history.

Security and Production Rules

Do not store secrets in code or logs; use vaults and encrypted storage.
Production TTL updates require staging validation and sign-off from Reviewer.
Observability: TTL metrics alert thresholds and incident response runbooks.

Testing Checklist

Unit tests for TTL calculation functions.
Integration tests for TTL application against cache store.
End-to-end tests for planner-implementer-validator handoffs.
Regression tests for TTL drift after policy changes.
CI gates enforce test passes before merge to main.

Common Mistakes to Avoid

Skipping human review for critical TTL policy changes.
Overriding TTL in production without full validation.
Ambiguous ownership of policy decisions causing drift.
Neglecting memory constraints and data-source staleness.

FAQ

How should TTL values be chosen for cache keys?

TTL values should reflect data volatility and freshness requirements, starting with conservative defaults and adjusting based on access patterns and business impact.

How do agents collaborate to recompute TTL on data changes?

Planner detects data changes, passes policy to Implementer, which updates TTL logic and reports back to Validator for approval.

What are the handoff rules between Planner and Implementer?

Planner publishes policy with criteria; Implementer implements TTL logic, provides test data back to Validator; on success, changes proceed to deployment.

How is memory and source-of-truth handled across agents?

TTL_POLICY_STORE is canonical; memory stores recent decision history; all agents read and write through governed channels to maintain consistency.

What is the rollback path if TTL design causes cache inconsistency?

Rollback to the previous TTL policy, revert cache TTLs, and trigger a human-review loop with a post-mortem.

Target User

Use Cases