AGENTS.md Template for Service Mesh Architecture

Overview

The AGENTS.md template for service mesh architecture defines a repeatable operating manual for AI coding agents tasked with configuring, validating, and governing a service mesh. It supports both single-agent work and multi-agent orchestration across planners, implementers, reviewers, testers, researchers, and domain specialists. The template emphasizes agent handoffs, tool governance, and human review to ensure correct policy enforcement and safe production changes. Use this AGENTS.md template to initialize project-level operating context so agents know roles, constraints, and success criteria for service mesh workflows.

Direct answer: This template gives you a concrete, pasteable AGENTS.md block that encodes roles, rules, and escalation paths for service mesh automation using AI coding agents.

When to Use This AGENTS.md Template

• When automating service mesh configuration and policy application with AI agents.
• When coordinating multi-agent orchestration to implement mesh changes, validate health, and roll back if needed.
• When you require explicit handoffs, source-of-truth, and tool governance for mesh-related deployments.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Service Mesh Automation Orchestrator

Agent roster and responsibilities:
- Planner: designs mesh change plans, evaluates risks, sequences steps.
- Implementer: applies configurations to mesh proxies, sidecars, and policy engines.
- Tester: validates mesh state, traffic policies, and failure scenarios.
- Reviewer: reviews changes, ensures policy compliance, and signs off before deployment.
- Researcher: gathers context about mesh topology, dependencies, and external services.
- Domain Specialist: handles security, network policy, and service-to-service communication rules.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates all agents, ensures adherence to the AGENTS.md template, and mediates escalations.
- It enforces memory, context, and source-of-truth rules, and triggers human review when needed.

Handoff rules between agents:
- Planner to Implementer: hand off a concrete change plan with required configs and validation checks.
- Implementer to Tester: hand off a running mesh state, verification tests, and health checks.
- Tester to Reviewer: submit test results and any deviations for approval.
- Researcher to Domain Specialist: provide topology context and security considerations.

Context, memory, and source-of-truth rules:
- Use a single source of truth for mesh state: a designated config repo or mesh policy store.
- Memory captures recent changes, test outcomes, and roll-back points.
- All outputs must reference the source-of-truth and be traceable to the original request.

Tool access and permission rules:
- Agents may read config, policy, and telemetry data; editing rights are gated by the Orchestrator and approval gates.
- Secrets access is restricted to Domain Specialist and authorized tools. Never print secrets in logs.

Architecture rules:
- Respect mesh topology, sidecar patterns, mTLS, and policy engines (e.g., service mesh policy, network policy).
- Changes must be validated against traffic shifting, circuit breaking, and failover readiness.

File structure rules:
- Keep mesh configurations under config/mesh and policies under policies/
- All changes must be versioned and linked to a ticket or issue.

Data, API, or integration rules:
- Use mesh APIs and configuration inputs only from approved sources; validate inputs before applying.
- Telemetry must be collected and used to verify post-change health.

Validation rules:
- All changes require policy and security validation, matrix of tests, and an approval check before deployment.

Security rules:
- Enforce least-privilege access, rotate credentials, and audit all changes.

Testing rules:
- Include unit tests for policy evaluation, integration tests for mesh changes, and end-to-end test scenarios.

Deployment rules:
- Changes must be deployed to a staging environment before production and require gated promotion.

Human review and escalation rules:
- When uncertainty or policy conflict arises, escalate to a human reviewer.

Failure handling and rollback rules:
- If a change fails health checks, trigger rollback to the last known-good state and notify stakeholders.

Things Agents must not do:
- Do not bypass approvals, bypass security constraints, or modify production state without validation.
- Do not introduce unknown services or aliases without policy review.

Recommended Agent Operating Model

Roles and decision boundaries for service mesh automation: - Planner decides timing, sequencing, and risk thresholds for mesh changes. - Implementer executes mesh changes with minimal drift, honoring policy constraints. - Tester validates mesh health, traffic policies, and failover readiness; reports deviations. - Reviewer approves or rejects changes based on validation results and policy alignment. - Domain Specialist ensures security, compliance, and network policy fidelity. - Researcher supplies topology context and external service dependencies to inform decisions. - Orchestrator coordinates all agents, enforces memory and source-of-truth, and handles escalations.

Recommended Project Structure

project-root/
  config/mesh/        # mesh configurations and policy inputs
  policies/           # security and network policies
  integrations/       # integrations with external services and tools
  manifests/          # deployment manifests and routing rules
  agents/             # agent-specific subfolders
    planner/            # planning logic and templates
    orchestrator/       # supervisor and runbook
    implementer/        # config application code
    tester/             # validation and health checks
    reviewer/           # approval logic and sign-off
    domain-specialist/  # security and policy experts
  docs/               # this AGENTS.md and related docs
  tests/              # unit/integration tests for the workflow

Core Operating Principles

• Clear roles, responsibilities, and escalation paths.
• Single source of truth for mesh state and changes.
• Explicit handoffs with validated inputs and outputs.
• Non-repudiable audit trails and change provenance.
• Least-privilege access and secure secret handling.

Agent Handoff and Collaboration Rules

• Planner to Implementer: provide a concrete change plan including required configs and validation criteria.
• Implementer to Tester: expose current mesh state, changes applied, and post-change health checks.
• Tester to Reviewer: submit test results and any policy deviations for decision.
• Researcher to Domain Specialist: share topology context, dependencies, and security considerations.
• Domain Specialist to Orchestrator: confirm policy compliance and approve or request changes.

Tool Governance and Permission Rules

• Commands to modify mesh state require orchestrator approval gates.
• Config edits are versioned and reviewed; secrets are never logged.
• Production changes require staged deployment and health checks prior to promotion.
• Automated rollback triggers on failure conditions.

Code Construction Rules

• All mesh configurations must be template-driven and parameterized.
• Validation steps must be automated and deterministic.
• Code must reference the source-of-truth repository and issue/tolicy IDs.

Security and Production Rules

• Enforce mTLS, authenticated service-to-service communication, and least-privilege access.
• Secret management with rotation and audit logging.
• Production changes require approval and live monitoring post-deployment.

Testing Checklist

• Unit tests for policy evaluation.
• Integration tests for mesh configuration changes.
• End-to-end tests with simulated traffic patterns.
• Roll-back tests to ensure safe revert paths.

Common Mistakes to Avoid

• Skipping validation or rushing deployments without approvals.
• Drifting from the single source of truth when applying mesh changes.
• Overcomplicating policies without clear handoffs.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is the purpose of this AGENTS.md template for service mesh architecture?

This AGENTS.md template provides a structured operating manual that encodes roles, rules, and escalation paths for AI coding agents working on a service mesh architecture, including multi-agent orchestration and governance.

Who should use this template?

Platform teams, SREs, and engineers responsible for automating mesh configuration, policy application, and reliability testing using AI agents.

How are agent handoffs orchestrated?

Handoffs occur at clearly defined boundaries with inputs and outputs validated against the source of truth and policy checks, mediated by the Orchestrator.

What are the validation and security requirements?

All changes pass policy validation, security checks, and automated tests before deployment; secrets are never exposed in logs or outputs.

How do you test and deploy the agent workflow?

Use unit, integration, and end-to-end tests in a staging environment before gated production deployment with rollback readiness.