AGENTS.md Template: Consistent Hashing Load Balancing

Overview

AGENTS.md template for consistent hashing load balancing defines an operating manual for AI coding agents that governs single-agent and multi-agent orchestration. It codifies roles, memory, tool access, and handoffs to ensure deterministic routing of tasks across a hash-based balancer.

When to Use This AGENTS.md Template

• When you need deterministic task routing across AI coding agents using a hash-based load balancer.
• When multiple agents (planner, balancer, worker, verifier) require clear handoff rules and governance.
• When you must document memory, context propagation, and the source of truth for the hash ring and routing state.

Copyable AGENTS.md Template

Below is a copyable AGENTS.md template for the consistent hashing load balancing workflow. Paste into AGENTS.md to bootstrap your project context.

# AGENTS.md
Project: Consistent Hashing Load Balancing with AI coding agents
Agent roster & responsibilities:
- Planner: designs the decision boundary using a consistent hashing scheme and manages hash-ring updates.
- Balancer: routes tasks based on the hash and current load distribution.
- Worker: executes tasks and reports results back to the orchestrator.
- Verifier: checks results for invariants and data integrity.
- Reviewer: reviews changes and approves deployments into production.
Orchestrator/Supervisor: coordinates cycle-level handoffs and enforces governance.
Handoff rules:
- Planner -> Balancer: publish new hashing policy and ring updates.
- Balancer -> Worker: assign task to the partition indicated by the hash.
- Worker -> Verifier: provide result and logs.
- Verifier -> Reviewer: request final approval.
Context, memory, and source-of-truth:
- Use a single source of truth (SDE/DB) for the hash ring and task context.
- Agents load from memory at cycle start and persist results after success.
- All outputs are timestamped and auditable.
Tool access and permission rules:
- Each role has scoped tool access; secrets are stored in a vault with least privilege.
- API keys and credentials must be rotated and never logged.
Architecture rules:
- Stateless workers; hash-ring state is maintained by the Balancer and orchestrator.
- All state changes go through a central orchestrator with approval gates.
File structure rules:
- src/ for code, configs/ for configuration, docs/ for templates, tests/ for tests.
Data, API, or integration rules:
- All APIs require authentication; tokens are rotated; data flows are logged.
Validation rules:
- Invariants: ring membership sums, no hash misses, and no stale routing entries.
- End-to-end tests cover ring wrap, churn, and failure scenarios.
Security rules:
- Secrets must be encrypted at rest and in transit; audit trails are mandatory.
- Production changes require orchestration approval and peer review.
Testing rules:
- Unit tests for hashing logic, integration tests for routing, end-to-end tests for failures.
- CI must run before any deployment; canary deployments supported with rollback.
Deployment rules:
- Deployments require canary testing, feature flags, and rollback plans.
Human review and escalation rules:
- Any non-deterministic outcome or failed invariant requires human review and potential rollback.
Failure handling and rollback rules:
- If a mismatch or failure is detected, rollback to the previous ring state and pause traffic until validated.
Things Agents must not do:
- Do not bypass the orchestrator or mutate shared ring state outside the send/receive cycle.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to support both single-agent and multi-agent orchestration. The Orchestrator serves as the escalation point for invariants violations or failed approvals.

Recommended Project Structure

projects/consistent-hashing-load-balancer/
  agents/
    planner/
    balancer/
    worker/
    verifier/
    reviewer/
  configs/
  integrations/
  docs/
  tests/

Core Operating Principles

• Single source of truth for ring state.
• Deterministic routing via consistent hashing.
• Explicit, auditable handoffs with pre/postconditions.
• Least privilege for tools, secrets, and production access.

Agent Handoff and Collaboration Rules

Plane the handoffs clearly: Planner signals ring updates; Balancer routes tasks; Worker executes; Verifier validates; Reviewer approves. All transitions require state checks and logging. Escalate to the Orchestrator if invariants fail.

Tool Governance and Permission Rules

Commands, edits, API calls, and production actions require orchestrator consent or automated policy gates with complete audit logs.

Code Construction Rules

Implement deterministic hashing, idempotent ring updates, and safe state mutations guarded by locks. Avoid side effects in ring mutation paths and ensure reproducibility.

Security and Production Rules

Encrypt secrets, rotate credentials, monitor for anomalies, and maintain rollback capabilities with tested recovery paths.

Testing Checklist

• Unit tests for ring hashing logic.
• Integration tests for ring updates and task routing.
• End-to-end tests for failure scenarios and recovery.
• Canary deployments with rollback validation.

Common Mistakes to Avoid

• Skipping orchestrator-driven handoffs or bypassing governance.
• Unbounded memory growth in ring state or logs.
• Unsafe tool usage or secrets exposure.

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

FAQ

What is the AGENTS.md Template used for in this workflow?

The AGENTS.md Template defines a formal operating manual for a consistent hashing load balancing workflow with AI coding agents, detailing roles, handoffs, and governance.

Who are the agent roles?

Planner, Balancer, Worker, Verifier, Reviewer, and a central Orchestrator; each has a defined boundary and responsibilities.

How are handoffs between planner, balancer, and worker managed?

Handoffs are governed by preconditions, state checks, and a single source of truth; each transition requires explicit signaling and logging.

How is memory and source-of-truth handled?

Hash-ring state and task context are persisted in a central store; agents load from it at cycle start and commit on success.

What about security and approvals?

All tool usage and production actions require least-privilege access, secrets management, and orchestrator-approved changes with audit trails.