AGENTS.md Template: Client-Side Caching Strategy

Overview

Direct answer: This AGENTS.md Template provides a complete operating manual for AI coding agents to implement and govern a client-side caching strategy with multi-agent orchestration, clear handoffs, and governance. It supports both individual agents and multi-agent workflows for service worker caching, offline capability, and data freshness within modern web apps.

The template defines the project’s operating context, success criteria, and constraints. It ensures that AI agents collaborate deterministically, preserve context, and respect production boundaries while optimizing user experience through efficient caching.

When to Use This AGENTS.md Template

When designing a client-side caching strategy that uses AI coding agents to plan, implement, test, and deploy cache rules.
When coordinating multi-agent orchestration for service workers, HTTP cache headers, and offline support.
When you need explicit handoffs between planner, implementer, tester, reviewer, and domain experts with preserved context.
When enforcing tool governance, security, and production-guard rails around cache data, keys, and storage.

Copyable AGENTS.md Template

# AGENTS.md

Project: Client-Side Caching Strategy for Web App

Agent roster and responsibilities
- Planner: designs cache strategy, TTLs, cache keys, and invalidation rules
- Implementer: builds service worker logic, fetch handlers, and cache storage wiring
- Tester: validates performance, offline behavior, and cache correctness
- Researcher: experiments with caching patterns (LRU, stale-while-revalidate, etc)
- Reviewer: reviews changes, ensures safety and alignment with requirements
- Domain Specialist: ensures compatibility with web framework and build tooling

Supervisor / orchestrator behavior
- Orchestrator coordinates milestones, enforces handoffs, and updates the shared context
- Maintains a single source of truth for cache policy and versioning across agents

Handoff rules between agents
- Plan ready → Implementer begins code generation
- Implementer ready → Tester executes tests
- Tests pass → Reviewer approves → Deployable artifact

Context, memory, and source-of-truth rules
- Use a central memory store named CacheContext to persist policy, TTLs, and cache keys
- All agents read from and write to CacheContext with versioned updates
- Source-of-truth includes service worker scripts, caching config, and API rules

Tool access and permission rules
- Access to repository, build system, and test environment is allowed
- Secrets vault usage is restricted to approved tasks; never print secrets in messages

Architecture rules
- Service Worker must handle install, activate, fetch, and message events
- Use a conservative cache-first strategy for static assets and a network-first or hybrid for API data with proper fallbacks

File structure rules
- Only include folders relevant to this workflow
- No unrelated frameworks or databases

Data, API, or integration rules when relevant
- Cache keys must be stable and include version tags
- Invalidate caches on policy changes or resource updates

Validation rules
- Automated unit tests for fetch handlers and cache eviction
- Manual validation for offline flow and offline-first UI

Security rules
- Do not cache sensitive user data
- Isolate private caches per origin and user session where appropriate

Testing rules
- Orbit through unit, integration, and end-to-end tests; cover offline scenarios

Deployment rules
- Require passing tests and sign-off from Reviewer before deployment

Human review and escalation rules
- Escalate to Security Review for any changes impacting sensitive data
- Escalate to Product for user impact concerns

Failure handling and rollback rules
- If a deployment breaks offline flow, roll back to the previous cache version and restore network-first fallback

Things Agents must not do
- Do not cache sensitive data
- Do not bypass security controls or production safeguards
- Do not modify production configs without approval
- Do not drift from the agreed cache policy without a plan update

Recommended Agent Operating Model

The agent operating model defines roles, decision boundaries, and escalation paths for accurate, auditable client-side caching workflows. The Planner governs policy and strategy; the Implementer builds the caching code; the Tester validates behavior; the Reviewer approves changes; the Researcher and Domain Specialist refine patterns and framework compatibility. Handoffs are explicit, with preserved context via a shared CacheContext store. Escalation paths ensure security and production readiness before rollout.

Recommended Project Structure

client-side-cache-workflow/
├── planners/
├── implementers/
├── testers/
├── researchers/
├── domain-specialists/
├── src/
│   ├── sw.js
│   ├── cache-polices.json
│   ├── cache-keys.json
│   └── services/
├── tests/
│   ├── unit/
│   └── integration/
└── docs/

Core Operating Principles

Single source of truth for cache policy is maintained by the orchestrator
Clear, versioned changes to cache policy require a formal handoff
Agent actions are auditable, reversible, and reversible with rollback plans
Prefer deterministic, testable caching behaviors over speculative optimizations
Respect user privacy and avoid caching sensitive data

Agent Handoff and Collaboration Rules

Planner → Implementer: hand off policy, TTLs, and cache keys with policy context. Implementer → Tester: deliver code and test results. Tester → Reviewer: provide test report and risk assessment. Reviewer → Domain Specialist: ensure framework compatibility. Domain Specialist → Planner: feedback on architectural constraints.

Tool Governance and Permission Rules

All tool usage must be logged and auditable
Secrets must be accessed via a secure vault; never hardcode secrets
Code changes require review and approval; automated checks must pass
Production assets must not be modified by agents without deployment gates

Code Construction Rules

Code must be modular, testable, and well-documented
Service Worker scripts must be resilient to race conditions and errors
Cache eviction logic must be explicit and deterministic

Security and Production Rules

Do not cache sensitive data; segregate caches; validate origin policies; enforce HTTPS; monitor for cache poisoning risks; ensure upgrade and migration paths are safe.

Testing Checklist

Unit tests for fetch handlers and cache operations
Integration tests for offline mode
End-to-end tests for cache invalidation and update scenarios
Performance tests for cache hit/miss metrics
Security tests for data leakage and cache integrity

Common Mistakes to Avoid

Caching sensitive data or tokens
Undocumented handoffs or ambiguous ownership
Ignoring cache invalidation scenarios or version drift
Over-optimizing for cache hits at the expense of data freshness

FAQ

What is the purpose of this AGENTS.md Template for client side caching?

The template defines a clear operating manual for AI coding agents to implement a client-side caching strategy with multi-agent coordination, handoffs, and governance.

Who are the agents and their responsibilities in this workflow?

Planner designs strategy and policy; Implementer builds caching logic; Tester validates behavior; Researcher explores caching patterns; Reviewer approves changes; Domain Specialist ensures framework compatibility.

How do handoffs work between agents?

Handoffs occur at milestones: plan ready → implementer builds code → tester runs tests → reviewer approves → deployable artifact. All context is preserved via the shared CacheContext.

What are the security guidelines for client-side caching?

Avoid caching sensitive data; use private vs public caches; enforce TTLs; avoid cross-origin data; secure service worker scope; do not expose secrets in logs or code.

How is validation and rollback handled?

Run unit/integration tests, monitor live metrics, and if issues arise, rollback to previous cache version and re-run the plan with fixes.

Target User

Use Cases