Layer 4 LB Design AGENTS.md Template | Suhas Bhairav

Overview

Direct answer style summary: This AGENTS.md Template defines the operating model and governance for layer 4 load balancer design using AI coding agents, enabling clear roles, handoffs, and validation gates for reliable multi agent orchestration. It supports both single agent and multi agent workflows by codifying roles, memory, and source of truth rules in a copyable block that teams can paste into a repository to bootstrap their project level operating context.

When to Use This AGENTS.md Template

When designing a Layer 4 load balancer with distributed automation and policy enforcement
When multiple AI coding agents must collaborate on config generation, health checks, and failover rules
When you need explicit handoff rules between planner, implementer, reviewer, and tester
When you require tool governance, secrets handling, and production safe-guards
When you want a ready to paste copyable AGENTS.md block for project level context

Copyable AGENTS.md Template

# AGENTS.md

Project role
  Platform Engineering Lead for Layer 4 LB orchestration

Agent roster and responsibilities
  - Planner: designs overall LB4 topology, policies, and sequencing of actions
  - Implementer: translates planner output into infrastructure changes and scripts
  - Reviewer: validates design and changes against policies and risk criteria
  - Tester: executes simulated runs, validates outputs, and reports gaps
  - Researcher: gathers LB4 best practices and checks compatibility with existing tooling
  - Domain Specialist (LB4): validates layer 4 specifics such as TCP/UDP rules, NAT, and health checks

Supervisor or orchestrator behavior
  The Orchestrator coordinates the planner output, assigns tasks to agents, and enforces memory and source of truth rules. It validates inputs, sequences handoffs, and triggers human review for high risk changes.

Handoff rules between agents
  Planner -> Implementer: provide concrete config or script plan with identifiers
  Implementer -> Reviewer: deliver changes with validation results and rationale
  Reviewer -> Tester: hand off validated changes for test execution
  Tester -> Orchestrator: report results and pass/fail status
  Researcher/Domain Specialist -> Planner: update constraints or new policies based on findings

Context, memory, and source-of-truth rules
  Context stored in a central state file at /infra/lb4/state.json and in versioned configuration repository
  All agents reference the state, policy documents, and canonical configs as the single source of truth
  Changes are recorded with timestamps and agent identifiers

Tool access and permission rules
  Agents may use curl, HTTP calls, and local scripting to fetch configs
  Secrets must be retrieved from a secrets vault; do not hard code
  No access to production secrets without approval gated processes

Architecture rules
  Design is modular and stateless per agent, with idempotent operations
  All changes are auditable and reversible

File structure rules
  /infra/lb4/configs
  /infra/lb4/scripts
  /infra/lb4/state.json
  /ai-skills/agents-md-templates/md
  /policies

Data, API, or integration rules when relevant
  Interact with LB4 API for config and health checks
  Use standard RBAC for all API calls
  All integrations must return idempotent results and log outcomes

Validation rules
  Validate syntax of new configs, topology constraints, and policy conformance before apply
  Run dry runs before real deployment

Security rules
  Do not expose secrets in code or logs
  Enforce least privilege for each agent
  Gate production changes with human approval when risk thresholds are exceeded

Testing rules
  Unit tests for generated configs
  Integration tests for LB4 API calls
  End-to-end tests for typical failover scenarios

Deployment rules
  Changes deployed via CI/CD with staged environments
  Rollback plan ready for each deployment step

Human review and escalation rules
  Any config changing core LB4 behavior or security policies requires human review
  Escalate to SRE on production anomalies beyond threshold

Failure handling and rollback rules
  If a deployment fails, rollback to the previous known good state with a rapid revert procedure
  Maintain an incident log and postmortem within 48 hours

Things Agents must not do
  Do not bypass approvals or security controls
  Do not modify production secrets directly
  Do not perform unsanctioned changes to topology without tests and rollback plan
  Do not drift from the architecture constraints or policy documents

Recommended Agent Operating Model

Roles and boundaries: Planner defines desired LB4 topology and policy constraints; Implementer applies changes; Reviewer checks adherence; Tester verifies behavior; Researcher keeps up with LB4 practices; Domain Specialist validates LB specifics. Decision boundaries: Planner decides what to implement, Implementer performs, Reviewer approves, Tester validates, Domain Specialist conditions the constraints. Escalation: If risks exceed thresholds, escalate to human review and SRE. Handoffs are strict and traceable with context and rationale.

Recommended Project Structure

infra/
  lb4/
    configs/
      lb4_config.yaml
      health_checks.yaml
    scripts/
      apply_lb4.sh
      validate_lb4.sh
    state.json
agents/
  md/
    layer-4-lb-design-agents-md-template/
      AGENTS.md
policies/
  lb4_policies.md

Core Operating Principles

Single source of truth for LB4 design and state
Idempotent operations and auditable changes
Explicit, documented handoffs among planner, implementer, reviewer, tester
Robust validation before production changes
Respect security and secrets handling policies

Agent Handoff and Collaboration Rules

The planner crafts a concrete plan; the implementer executes; the reviewer validates; the tester tests; researchers refine constraints; domain specialists ensure LB4 correctness. All handoffs must include state context, rationale, and expected outcomes.

Tool Governance and Permission Rules

All tool usage must be auditable and restricted by role
Secrets must be retrieved from a vault; never stored in code
Only approved API calls are allowed in production changes
All commands must be logged; any destructive commands require explicit confirmation

Code Construction Rules

All configs are generated declaratively and validated against policy
Scripts are idempotent and have dry run modes
Changes are modular and testable in isolated LB4 scenarios
No hard coded values for secrets or credentials

Security and Production Rules

Least privilege access for all agents
Secrets vault integration for credentials
Production changes require human approval and testing gates
Logging and monitoring enabled for all production changes

Testing Checklist

Unit tests for generated LB4 configs
Integration tests for LB4 API endpoints
Dry runs and simulated failover tests
End-to-end validation in staging environment

Common Mistakes to Avoid

Skipping validation gates or human review
Unsafe shortcuts that bypass secrets management
Context drift from the planner to implementation
Architecture drift and undisclosed topology changes

FAQ

What is an AGENTS.md Template?

A copyable operating manual for AI coding agents that governs the layer 4 LB design workflow, including roles, handoffs, and governance.

Who should use this template?

Engineering leaders, platform teams, and developers building multi agent orchestration for LB4 configuration and policy enforcement.

How are agent handoffs managed in this workflow?

Handoffs follow a strict sequence with rationale and validation; planner to implementer, implementer to reviewer, reviewer to tester, and tester back to orchestrator with results.

What security rules apply to this workflow?

Secrets must be sourced from a vault, permissions are least privilege, and production changes require explicit approvals and testing gates.

How is multi agent orchestration validated?

Through dry runs, simulated failovers, and end to end tests in staging before any production deployment.

Layer 4 Load Balancer Design AGENTS.md Template

Target User

Use Cases