AGENTS.md Template for Optimistic Locking Strategy

Overview

Direct answer: Use this AGENTS.md template to codify an optimistic locking strategy for AI coding agents, enabling safe multi-agent orchestration with version checks, conflict handling, and auditable handoffs. It provides project-level operating context for both single-agent and multi-agent workflows.

The AGENTS.md template explains how the agent roster collaborates, what each agent is allowed to do, and how the supervisor coordinates to prevent context drift and ensure a single source of truth. It establishes memory, source-of-truth, and auditable actions for optimistic concurrency control across agents.

When to Use This AGENTS.md Template

When multiple AI coding agents access a shared resource and conflicts are possible.
When you need deterministic handoffs and explicit escalation paths.
When you require built-in conflict detection, retries, and rollback rules.
When you want a clear, auditable memory and versioning model across agents.

Copyable AGENTS.md Template

Copy the block below into AGENTS.md at the project level to establish the operating context for optimistic locking workflows.

# AGENTS.md
# Optimistic Locking - Multi-Agent Orchestration

# Project Role
- Role: Orchestrator of optimistic concurrency for a shared resource; ensures versioned updates and safe handoffs.

# Agent Roster and Responsibilities
- Planner: designs versioning strategy, decides when to retry, and defines lock/version fields.
- Implementer: executes updates with conditional writes based on expected version.
- Reviewer: validates results against business rules and constraints.
- Tester: simulates concurrency, validates no data races, and confirms rollback behavior.
- Researcher: gathers contention data, proposes improvements to the locking strategy.
- Domain Specialist: enforces domain constraints and ensures model-specific semantics are honored.

# Supervisor or Orchestrator Behavior
- The Orchestrator enforces version checks, routes handoffs, logs actions, and triggers retries or rollbacks on conflicts.

# Handoff Rules Between Agents
- Planner → Implementer: pass target resource and expected version, plus lock details.
- Implementer → Reviewer: pass update results and any conflict context.
- Reviewer → Planner (if needed): request plan adjustment on unmet constraints.
- If conflicts occur, Implementer notifies Planner to re-issue with updated version.

# Context, Memory, and Source-of-Truth Rules
- Source of Truth: VersionedResource maintained in the version store or resource API.
- Memory: Use last-known-good version, recent conflict logs, and audit trails for reproducibility.
- Context propagation: Only pass minimal necessary context to each agent; avoid stale data.

# Tool Access and Permission Rules
- Tools: Resource API, Version Store, Audit Log, and optional Concurrency Simulator.
- Permissions: Read for all, Write only for Implementer with approved plan; secrets strictly scoped and rotated.

# Architecture Rules
- Centralized version store with atomic compare-and-swap updates.
- Stateless agents; state persisted in the version store and logs.

# File Structure Rules
- /src/optimistic-locking/
- /resources/
- /tests/
- /docs/

# Data, API, or Integration Rules
- Use conditional updates: if current_version == expected_version then apply update; else fail with Conflict.
- All updates must be logged with a unique operationId.

# Validation Rules
- Validate that versions increment on success and that no data loss occurred.
- Validate that rollback occurred correctly on failure.

# Security Rules
- Do not leak secrets; store credentials in a vault; limit exposure to only necessary agents.
- All actions are auditable and reversible.

# Testing Rules
- Unit tests for version checks; integration tests for concurrency scenarios; end-to-end tests for rollback.

# Deployment Rules
- Deploy changes via feature-flag toggles; canary updates; monitor for conflicts.

# Human Review and Escalation Rules
- Escalate unresolved conflicts to engineering lead; require human approval for irreversible changes.

# Failure Handling and Rollback Rules
- On critical failure, rollback to the last stable version and re-run tests.

# Things Agents Must Not Do
- Do not bypass the version check; do not perform long-running blocking operations in the update path.
- Do not act on stale context; do not introduce new lock semantics without planner approval.

Recommended Agent Operating Model

The agent operating model defines clear roles, decision boundaries, and escalation paths for optimistic locking workflows. Planners set strategy; Implementers perform conditional writes; Reviewers validate; Testers verify; Researchers optimize; Domain Specialists enforce constraints. Handoffs are governed by the rules above, and the Orchestrator enforces version checks and retries when conflicts occur.

Recommended Project Structure

projects/
  optimistic-locking/
    agents/
      planner/
      implementer/
      reviewer/
      tester/
      researcher/
      domain-specialist/
    configs/
    resources/
    tests/
    docs/
    orchestrator/

Core Operating Principles

Deterministic version checks for all resource updates.
Idempotent operations; retries do not produce duplicate effects.
Clear ownership and auditable actions; every change is traceable.
Minimal context leakage; only necessary data is passed between agents.
Explicit handoffs with defined failure paths and escalation.
Respect for domain constraints and data integrity at all times.

Agent Handoff and Collaboration Rules

Follow these concrete rules for planner, implementer, reviewer, tester, researcher, and domain specialist agents:

Planner: creates a concrete plan with a target version and lock metadata; emits a formal handoff bundle.
Implementer: performs conditional update against current version; on conflict, reports conflict details and awaits Planner revision.
Reviewer: validates business rules and data integrity; approves or requests changes before rollout.
Tester: runs concurrency tests and verifies rollback paths; flags issues to the Orchestrator.
Researcher: analyzes conflict patterns and suggests optimization to the locking strategy.
Domain Specialist: ensures domain constraints are honored in all checks and messages.

Tool Governance and Permission Rules

Command Execution: Only the Implementer may perform updates with an approved plan; others can read or simulate locally.
File Edits: Writes are restricted to the downstream resource store; avoid direct changes to shared state from agents.
API Calls: All calls authenticated; use least privilege; log all requests with operationId.
Secrets: Stored in vault; access limited to needed agents; rotation enforced.
Production Systems: Changes require approval gates and monitoring after deployment.
External Services: Access via controlled adapters; retries must respect rate limits.
Approval Gates: Implement changes only after Planner, Reviewer, and a Human in the Loop (if required) have approved.

Code Construction Rules

Use atomic, conditional updates based on version; avoid non-deterministic reads.
Keep updates small and idempotent; break large changes into incremental steps.
Log all actions with operationId; preserve audit trails for every decision.
Do not bypass validation rules or perform direct writes when a conflict is detected.
Ensure memory usage is bounded; rely on the version store as the source of truth.

Security and Production Rules

Encrypt sensitive data in transit and at rest; use vault-backed secrets.
Enforce least privilege for all agents; rotate credentials regularly.
Maintain immutable audit logs for all state-changing events.
Monitor for anomalous retry storms or repeated conflicts and throttle as needed.

Testing Checklist

Unit tests for version comparison and conditional updates.
Integration tests simulating concurrent updates and resolution.
End-to-end tests covering planning, execution, review, and rollback.
Security tests for secret access and permission boundaries.
Performance tests for conflict-heavy workloads.

Common Mistakes to Avoid

Assuming conflicts are rare; not testing concurrency extensively.
Bypassing version checks or performing long-running transactions without observable rollback.
Overloading the orchestrator with non-deterministic logic; causing context drift.
Improper memory handling leading to stale context and cascading failures.
Neglecting auditability and missing operationId in traces.

FAQ

What is the goal of this AGENTS.md template for optimistic locking?

The goal is to provide a concrete, auditable operating manual that enforces optimistic concurrency across AI coding agents, with well-defined handoffs, conflict handling, and rollback rules.

Which agent roles are defined in this template?

Planner, Implementer, Reviewer, Tester, Researcher, and Domain Specialist, each with explicit responsibilities and handoff paths.

How are handoffs between agents managed?

Handoffs follow a fixed sequence: Planner → Implementer → Reviewer → Tester, with backchannels to Planner for plan adjustments and Orchestrator for conflict-driven retries.

What happens when a conflict occurs?

The Orchestrator detects the conflict, retries with an updated version if allowed, and logs the outcome; if unresolved, escalation to human oversight occurs.

What are the security considerations for this workflow?

Secrets are vault-backed, access is least-privilege, all actions are auditable, and no sensitive data is exposed in code or logs.

Target User

Use Cases