AGENTS.md Template: Weighted Load Balancing Design

Overview

This AGENTS.md template describes a weighted load balancing design workflow for AI coding agents. It governs a multi-agent orchestration pattern where a central orchestrator coordinates policy, applies weight changes, and directs agent handoffs between Planner, Implementer, Monitor, Tester, Reviewer, Researcher, and Domain Specialist. It provides clear operating context for both single-agent execution and distributed coordination, including memory, source-of-truth rules, and tool governance to ensure auditable changes.

Direct answer: Use this AGENTS.md Template to implement dynamic, policy-driven traffic distribution across services, with explicit handoffs and governance to minimize drift and risk in production.

When to Use This AGENTS.md Template

• When designing a system that routes traffic across services using weighted weights in production.
• When coordinating policy across multiple AI coding agents (Planner, Implementer, Monitor, Tester, Reviewer, Researcher, Domain Specialist).
• When you need auditable handoffs and clear escalation paths for changes to routing policy.
• When integrating with health checks, auto-scaling, and circuit-breaker patterns to adjust weights safely.

Copyable AGENTS.md Template

Please copy the block below into AGENTS.md in your project to establish the operating context for single-agent and multi-agent load-balancing work.

# AGENTS.md

Project role
- Weighted Load Balancer Orchestrator (WLO): coordinates weighted distribution policy across services and aligns multi-agent actions to a global routing objective.

Agent roster and responsibilities
- Planner: defines routing policy (relative weights, thresholds, and zones).
- Implementer: applies configuration changes to proxies and load balancers (e.g., Nginx/Envoy) and validates syntax.
- Monitor: collects latency, error rates, saturation, and health metrics; triggers reweighting when thresholds are crossed.
- Tester: simulates traffic, validates distribution, and confirms policy adherence under load.
- Reviewer: validates changes against policy and business constraints; approves before production.
- Researcher: analyzes historical data, experiments with weight scales, and recommends improvements.
- Domain Specialist: handles service-specific constraints (session affinity, sticky routing, or data locality).

Supervisor or orchestrator behavior
- The WLO acts as the single source of truth for routing policy, enforces handoffs, and ensures compliance with governance rules. It triggers escalation to human reviewers when policy cannot be resolved automatically.

Handoff rules between agents
- Planner -> Implementer: deliver policy + configuration plan; Implementer applies changes and emits a signed change record.
- Implementer -> Monitor: report applied changes and verification results.
- Monitor -> Planner: if metrics violate thresholds or drift occurs, Planner revises policy or requests Reviewer approval.
- Tester -> Reviewer: presents test results and coverage; Reviewer approves or requests adjustments.

Context, memory, and source-of-truth rules
- All policy and changes are versioned in the central config repository. Each change includes a unique change-id and rationale. Metrics are stored in a time-series store with a consistent retention window and source-of-truth tags.
- The authoritative routing policy is the latest approved policy; past policies are immutable in the change history.

Tool access and permission rules
- Agents may read all monitoring data; only Implementer and Supervisor may write to proxy/configuration endpoints after approval.
- Access to production systems requires an approval gate and a human-in-the-loop for high-risk changes.

Architecture rules
- Use a centralized orchestrator with a pluggable policy engine. Each agent operates with a scoped, read-only context where possible to minimize side effects.

File structure rules
- Only include files relevant to weighted load balancing workflows: policy, config, tests, docs, and agent templates.

Data, API, or integration rules when relevant
- Pull metrics from the monitoring stack (latency, error rate, requests/sec). Push changes to the load balancer configuration via a controlled API.

Validation rules
- All changes must pass syntax validation, policy validation, and a dry-run in staging before production.

Security rules
- Secrets and credentials are never stored in AGENTS.md. Use secret management and rotation practices; only approved agents may access production endpoints.

Testing rules
- Include unit tests for policy logic, integration tests for config application, and performance tests for reweighting under load.

Deployment rules
- Changes must pass CI with approvals before being deployed to production. Maintain a rollback plan and a tested rollback path.

Human review and escalation rules
- If the Planner cannot resolve policy conflicts, escalate to Reviewer and Domain Specialist for approval.

Failure handling and rollback rules
- On failure, revert to the previous stable policy; retain a snapshot of affected routing rules and metrics; re-run validation in staging before re-deploy.

Things Agents must not do
- Do not apply changes that violate business constraints or break service-level agreements. Do not drift from policy without a documented change and approval.

Recommended Agent Operating Model

The model defines clear boundaries for Planner, Implementer, Monitor, Tester, Reviewer, Researcher, and Domain Specialist agents. Each agent has decision boundaries, escalation paths, and a defined handoff protocol to the central orchestrator, ensuring predictable outcomes and traceability for weighted load balancing changes.

Recommended Project Structure

/weighted-load-balancing/
  /orchestrator/
    planner/
    implementer/
    monitor/
    tester/
    reviewer/
    researcher/
    domain-specialist/
  /configs/
  /policies/
  /tests/
  /docs/

Core Operating Principles

• Deterministic policy decisions with auditable change history.
• Idempotent configuration changes with explicit validation gates.
• Strict separation of read/write access across agent roles.
• Single source of truth for routing policy and metrics.
• Handoff discipline to avoid drift and duplication.

Agent Handoff and Collaboration Rules

• Planner communicates policy with rationale to Implementer via a formal change record.
• Implementer must validate syntax, run a dry-run, and emit verification results to Monitor and Planner.
• Monitor provides real-time signals to Planner; Planner may propose adjustments or triggers for Tests.
• Tester performs load tests and communicates coverage to Reviewer.
• Reviewer approves or requests changes before production deployment.
• Researcher runs experiments and reports findings to Planner and Domain Specialist.
• Domain Specialist reviews service-specific constraints prior to approval.

Tool Governance and Permission Rules

• Proxy/configuration changes require orchestrator approval unless in a predefined safe-guard window with auto-approval rules.
• All tool invocations must be logged with change-id and agent role.
• Secrets must never be embedded; use secrets vaults with rotation policies.
• Production commands are gated and require human-in-the-loop for high-risk changes.

Code Construction Rules

• Policy evaluation must be deterministic and testable; avoid hard-coded values outside config.
• Weight calculations must handle division by zero and rounding modes; log any anomalies.
• All files are version-controlled; avoid in-place edits in production config without a record.

Security and Production Rules

• Enforce least privilege for all agents; use role-based access control.
• All routes and policy changes require audit-ready traces and time-stamped records.
• Implement rate limiting on policy change endpoints; monitor for anomalous changes.

Testing Checklist

• Unit tests for weight calculation logic.
• Integration tests for policy application and config generation.
• Staging validation with live-like traffic surrogates.
• End-to-end tests for handoff sequences and rollback procedures.

Common Mistakes to Avoid

• Skipping staging validation before production changes.
• Overlapping responsibilities leading to handoff ambiguity.
• Unclear source-of-truth causing drift between policy and metrics.

FAQ

What is the purpose of this AGENTS.md Template for Weighted Load Balancing Design?

This AGENTS.md Template provides a repeatable operating manual for AI coding agents to design, validate, and operate a weighted load balancing system using multi-agent orchestration and agent handoffs with tool governance.

How do agents handle weight changes and handoffs?