AGENTS.md Template: Leader-Follower Replication Design

Overview

This AGENTS.md template defines a leader-follower replication design workflow for AI coding agents. It governs both single-leader operation and multi-agent orchestration, providing a concrete operating manual that covers roles, handoffs, memory, tool access, architecture, and security to ensure reliable data replication and governance.

Direct answer: This template gives you a complete, paste-ready AGENTS.md block and project-level operating context for designing and governing a leader-follower replication system with AI agents.

• Leader coordinates replication and maintains the canonical log stream.
• Followers apply replication events, verify integrity, and report status.
• Auditor validates reconciliation and triggers escalations when drift occurs.
• Orchestrator coordinates multi-agent workflows, handoffs, and human review gates.

When to Use This AGENTS.md Template

• When designing a leader-follower replication design for databases or distributed stores.
• When you need clear agent handoffs between planner, implementer, reviewer, tester, researcher, and domain specialists.
• When you require tool governance, secrets handling, and secure, auditable deployment of replication tasks.
• When you want a copyable AGENTS.md template to scale replication governance across services.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Leader-Follower Replication Designer (Leader, Followers, Auditor, Orchestrator)
Agent roster and responsibilities:
- LeaderAgent: coordinates replication events, reads primary logs, issues apply commands to Followers.
- FollowerAgent-1, FollowerAgent-2: apply changes, validate apply results, maintain local state.
- AuditorAgent: performs reconciliation, checksums, data integrity checks, reports drift.
- OrchestratorAgent: coordinates multi-agent workflow, enforces timeouts, triggers handoffs and escalations.

Supervisor or orchestrator behavior:
The OrchestratorAgent maintains the replication plan, assigns tasks to Leader and Followers, aggregates progress, and enforces escalation gates when drift exceeds thresholds.

Handoff rules between agents:
1) Leader to Followers: push log positions and exact operation sequences with checkpoints.
2) Followers to Auditor: report apply results, checksums, and any mismatches.
3) Auditor to Orchestrator: escalate discrepancies and trigger rollback if needed.
4) Orchestrator to Humans: request guidance for human review when automated reconciliation fails.

Context, memory, and source-of-truth rules:
- Leader is the source of truth for replication plans, log streams, and checkpoint definitions.
- Followers store replicatedPosition and lastAppliedCheckpoint with a bounded memory window.
- Context variables and state summaries are persisted in a central memory store (e.g., vector or KV store) and synchronized via audit logs.

Tool access and permission rules:
- Leader: read primary logs, access replication APIs, perform apply actions.
- Followers: apply changes with read-only access to source of truth; no direct writes to primary; use scoped credentials.
- Auditor: read-only access to logs, state, and checksums; can request rollbacks via Orchestrator.
- Secrets: stored in a secure vault; tokens issued per task; rotate regularly and never hard-code.

Architecture rules:
- Use log-based replication with idempotent apply, checkpoint-driven progress, and TLS for transport.
- Favor eventual consistency with bounded lag; design for replayability and replay safety.
- All agents run in isolated sandboxes; no cross-service credential leakage.

File structure rules:
- replication/
  - leader/
    - plan.md
    - apply_logs.py
  - followers/
    - follower1/
      - apply_logs.py
    - follower2/
  - orchestrator/
    - orchestrate.py
  - audits/
    - checksums.md
  - docs/
  - tests/
  - scripts/

Data, API, or integration rules:
- Leader exposes /replicate endpoint and publishes events to a stream; Followers subscribe to the stream.
- Auditor consumes logs, performs reconciliation via /reconcile endpoints; Orchestrator coordinates rollbacks and escalations.

Validation rules:
- After each batch, verify checksums, row counts, and lastAppliedCheckpoint alignment with expected values.
- If mismatches exceed threshold, halt replication window and trigger auditor review.

Security rules:
- Encrypt in transit with TLS, rotate credentials, least-privilege access, secrets stored in vault with strict scoping.
- Do not bypass the orchestrator or expose primary logs to Followers.

Testing rules:
- Unit tests for apply_logs function; integration tests with simulated lag; end-to-end tests in staging.

Deployment rules:
- Canary rollout for the Leader-Follower stack; health checks and metrics before promoting to production; enable feature flags for rollback.

Human review and escalation rules:
- If drift persists after reconciliation, human review triggers data governance and SRE involvement.

Failure handling and rollback rules:
- On failure, rollback to last validated snapshot; pause follower activity; replay from known good position once approved.

Things Agents must not do:
- Do not mutate primary state from Followers; do not bypass Orchestrator; do not perform unmanaged production changes; do not expose secrets.

Recommended Agent Operating Model

Roles and decision boundaries for leader-follower replication: Leader sets plan, Followers apply changes, Auditor validates, Orchestrator coordinates and enforces gates. Escalation goes to Humans when automated checks fail.

Recommended Project Structure

Workflow-focused directory tree for leader-follower replication.

replication/
  leader/
    plan.md
    apply_logs.py
  followers/
    follower1/
      apply_logs.py
    follower2/
  orchestrator/
    orchestrate.py
  audits/
    checksums.md
  docs/
  tests/
  scripts/

Core Operating Principles

• Single source of truth is the leader's log stream and plan.
• Headless, deterministic agent actions with explicit handoffs.
• Strict access control and auditable actions for all replication tasks.
• Idempotent, replay-safe operations with rollback capabilities.

Agent Handoff and Collaboration Rules

• Planner (Orchestrator) defines plan, timeline, and checkpoints; communicates to Leader.
• Implementer (Leader and Followers) executes replication steps and validates results.
• Reviewer (Auditor) performs reconciliation and flags anomalies.
• Tester validates end-to-end replication within the staging environment.
• Researcher provides telemetry and pattern improvements without altering core replication logic.
• Domain Specialist assists with database-specific replication semantics and consistency guarantees.

Tool Governance and Permission Rules

• Commands to apply replication must go through the orchestrator; no direct single-agent side effects.
• Only Leader has write access to primary logs; Followers can only read and apply changes.
• Secrets and credentials are rotated and stored in a vault; ephemeral tokens are used for tasks.
• Automated tooling must log all actions for audit; manual actions require approvals.

Code Construction Rules

• All replication changes are idempotent and replay-safe.
• Use deterministic serialization for logs; validate integrity via checksums.
• Do not bypass the orchestrator; all actions are traceable to tasks and approvals.
• Follow a strict versioning policy for replication components.

Security and Production Rules

• Encrypt in transit with TLS; encrypt at rest where applicable.
• Least-privilege roles; rotate credentials quarterly.
• Audit trails for every replication task; alert on policy violations.

Testing Checklist

• Unit tests for apply_logs; mocks for log streams.
• Integration tests simulating lag and network partitions.
• End-to-end tests in staging with canary promotions.

Common Mistakes to Avoid

• Bypassing the orchestrator for direct changes.
• Assuming eventual consistency without validation.
• Ignoring audits, logs, and reconciliation results.

Related implementation resources: AI Agent Use Case for Defense Subcontractors Using Compliance Databases To Verify It Infrastructure Alignment with Cybersecurity Rules and AI Use Case for Construction Firms Using Procore To Extract and Categorize Safety Violation Patterns Across Job Sites.

FAQ

What is the purpose of this AGENTS.md Template for leader-follower replication?

This template defines roles, handoffs, and governance for a leader-follower replication workflow used by AI coding agents.

How should handoffs occur between the Leader and Followers?

Handoffs follow a canonical sequence: Leader plans, Followers apply, Auditor verifies, and Orchestrator enforces progress and escalates if needed.

What are the memory and source-of-truth rules?

The Leader is the source of truth for replication plans and logs; Followers maintain lastApplied and state snapshots with time-bound memory.

How is validation performed?

Validation checks include data checksums, row counts, and reconciliation between primary logs and follower state before progressing to the next window.

How do we handle failures and rollback?

On failure, restore from last validated snapshot, halt non-critical tasks, and trigger an escalation for human review if drift persists.