Browser Caching Strategy AGENTS.md Template | Suhas Bhairav

Overview

Direct answer: This AGENTS.md Template provides a formal operating manual for browser caching strategy using AI coding agents, enabling single agent execution and multi agent orchestration with explicit handoffs, source of truth, and governance.

The AGENTS.md Template defines the agent workflow for browser caching strategy, including planning, implementing, validating, and iterating cache policies across HTTP headers, service workers, and CDN rules. It supports both a single agent and multi agent orchestration with clear handoffs and escalation paths.

When to Use This AGENTS.md Template

When you need a repeatable, auditable browser caching strategy across environments.
When coordinating multiple agents to plan, implement, test, and review cache changes.
When you require tool governance, source of truth, and explicit failure handling.
When you need a formal escalation path to human review for production changes.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Browser Caching Architect / Platform Engineer

Agent roster and responsibilities:
- Planner: defines scope, success criteria, and handoff triggers.
- Implementer: applies cache headers, service worker rules, and CDN configurations.
- Reviewer: validates correctness, performance, and security implications.
- Tester: runs automated checks, Lighthouse metrics, and regression tests.
- Researcher: gathers background on headers, caches, and modern best practices.
- Domain Specialist: provides domain-specific constraints.

Supervisor / Orchestrator behavior:
- Maintains the single source of truth for cache rules and sources.
- Issues tasks, assigns handoffs, tracks progress, and triggers escalation when outputs fail acceptance criteria.
- Enforces tool governance and secrets policies.

Handoff rules between agents:
- Planner -> Implementer: when scope, acceptance criteria, and output formats are defined.
- Implementer -> Reviewer: after implementing cache changes, code is ready for review.
- Reviewer -> Tester: once tested, to validate effect on performance.
- Tester -> Planner: summarize results and decide on rollout.
- Researcher/Domain Specialist: provide context and constraints as needed throughout.

Context, memory, and source-of-truth rules:
- Cache strategy sources (headers, service worker, CDN rules) are stored in /configs/cache.
- Memory across agents is session-scoped; no global leakage unless approved.
- All decisions reference the official performance baselines and Lighthouse reports stored in /docs/perf-baselines.

Tool access and permission rules:
- Access to code editors, CI, and deployment must be verified via approvals.
- Secrets are stored in a dedicated vault and never hard-coded.

Architecture rules:
- Client-side caching decisions must not violate privacy constraints; respect Cache-Control and ETag semantics.
- Separation of concerns between origin rules and edge rules.

File structure rules:
- Keep all cache policy files under /configs/cache/
- Each change has a corresponding test under /tests/cache/

Data, API, or integration rules:
- Pull latest origin headers from /origins, CDN rules from /cdns, and tests from /tests.
- All API calls to provision caches go through the orchestrator to ensure traceability.

Validation rules:
- Validate outputs against baseline performance metrics; require passing Lighthouse scores before rollout.

Security rules:
- Do not expose secrets; use vault; restrict production access to authorized agents.

Testing rules:
- Include unit tests for header logic and integration tests for CDN rules.
- Regression tests must pass prior to deployment.

Deployment rules:
- Rollouts done via orchestrator; no direct production edits by agents.
- If deployment fails, revert to last good state.

Human review and escalation rules:
- Any failing validation triggers human review; history is logged for audit.

Failure handling and rollback rules:
- Automatic rollback on failure with alerts to on-call.

Things Agents must not do:
- Do not bypass approvals, expose secrets, or modify production configurations without validation.

Recommended Agent Operating Model

The operating model assigns clear roles with defined decision boundaries. The Planner scopes each caching initiative, the Implementer applies changes to headers and caching layers, the Reviewer confirms correctness, the Tester validates performance, the Researcher gathers best practices, and the Domain Specialist adds constraints from edge and CDN perspectives. Escalation paths route failures to human review and a supervising orchestrator ensures traceability and rollback capability.

Recommended Project Structure

/.browser-cache-strategy/
agents/
  planner/
  implementer/
  reviewer/
  tester/
  researcher/
  domain-specialist/
configs/
docs/
tests/
scripts/

Core Operating Principles

Single source of truth for cache rules and performance baselines.
Explicit handoffs with defined outputs and acceptance criteria.
Auditable actions and traceable decisions across agents.
Guardrails for tool access, secrets, and production changes.
Continuous validation and early escalation for safety and correctness.

Agent Handoff and Collaboration Rules

Planner to Implementer: deliver scoping, success criteria, and change plan.
Implementer to Reviewer: deliver implemented cache rules and change set.
Reviewer to Tester: deliver validated changes and performance notes.
Tester to Planner: deliver results and rollout decision.
Domain Specialist to any agent: provide constraints and edge-case considerations as needed.

Tool Governance and Permission Rules

All tools accessed through the orchestrator; direct production edits are prohibited.
Secrets must be retrieved from secure vaults; never stored in code.
API calls to provision caches require explicit approval gates.
Audit logs must capture agent actions and outputs.

Code Construction Rules

Cache policy files are versioned under /configs/cache with clear naming conventions.
Changes must include tests under /tests/cache and a change note in /docs.
Headers and CDN rules must be compatible with standard HTTP caching semantics.
Do not introduce caching that leaks private data or bypasses user consent.

Security and Production Rules

Secrets are stored in vaults; never embedded in code.
Production edits require orchestration approval and role-based access control.
Monitor cache performance post rollout and rollback if anomalies are detected.

Testing Checklist

Unit tests for header logic and service worker rules.
Integration tests for origin and CDN interactions.
End-to-end performance tests and Lighthouse checks.
Regression tests to guard against performance regressions.

Common Mistakes to Avoid

Skipping validation or skipping human review for production changes.
Overly aggressive caching that violates privacy or consent.
Unclear handoffs leading to duplicated work or context drift.
Architectural drift between origin and edge caching layers.

FAQ

What is the scope of this AGENTS.md Template for browser caching?

It governs the browser caching strategy workflow with AI coding agents and supports single-agent and multi-agent orchestration with explicit handoffs, sources of truth, and governance.

Who is the agent roster and what are their responsibilities?

Roles include Planner, Implementer, Reviewer, Tester, Researcher, and Domain Specialist; each has defined responsibilities and outputs.

How are handoffs and collaboration structured?

Handoff rules specify when outputs move between Planner, Implementer, Reviewer, Tester, and Domain Specialist, with orchestrator enforcing progress and traceability.

What security and governance rules apply?

Tool access, secrets management, production change approvals, and escalation gates are enforced to prevent unsafe actions.

How is validation performed in production?

Validation includes automated tests, Lighthouse performance checks, and a rollback plan if results do not meet baseline metrics.

Browser Cache Strategy AGENTS.md Template

Target User

Use Cases