AGENTS.md Template: Pessimistic Locking Strategy

Overview

Direct answer: This AGENTS.md Template defines a pessimistic locking strategy for AI coding agents and provides a clear operating manual for single-agent and multi-agent orchestration. It establishes a formal policy for serializing access to shared resources, enforcing locks, and coordinating handoffs against race conditions and deadlocks.

The template explains how a centralized LockManager, an Orchestrator, and specialized Worker agents collaborate to maintain a single source of truth (SoT) and predictable outcomes in distributed AI workflows.

When to Use This AGENTS.md Template

• When AI coding agents access shared resources that require serialization to avoid race conditions.
• When multi-agent orchestration is needed with explicit handoffs and audit trails.
• When lock state, timeouts, and deadlock detection must be governed centrally.
• When security, traceability, and rollback guarantees are required in production workflows.

Copyable AGENTS.md Template

# AGENTS.md

Project role
- Orchestrator and Locking Steward for pessimistic locking strategy

Agent roster and responsibilities
- Orchestrator: enforces locking policy, sequences agent actions, stores context, triggers handoffs
- LockManager: maintains centralized lock state, acquires/releases locks, handles timeouts
- Worker: performs business logic under a lock, respects lock ownership
- Auditor: validates lock usage and detects deadlocks

Supervisor or orchestrator behavior
- Orchestrator is the single source of truth for lock state and task order
- Validate preconditions, enforce timeouts, retries, and escalation as needed
- Log decisions to the SoT and surface anomalies for remediation

Handoff rules between agents
- On success, current agent passes updated context to the next agent and releases locks after acknowledgement
- On failure, Orchestrator rolls back, releases locks, and routes to RecoveryAgent if defined

Context, memory, and source-of-truth rules
- All decisions reference the centralized SoT
- Do not override SoT with local cache without invalidation rules
- Context must include resourceId, operationId, timestamp, and task state

Tool access and permission rules
- Agents may call DB/API endpoints only via approved interfaces
- Secrets must not be logged; tokens rotated regularly
- Workers restricted to approved tool lists

Architecture rules
- Centralized lock state with a single writer per resource
- Idempotent operations with exponential backoff on retries
- Event-driven, decoupled agents with finite state machine

File structure rules
- Root directory dedicated to pessimistic-locking workflow
- Separate orchestrator, lock-manager, and workers directories
- Do not place unrelated components in this template

Data, API, or integration rules when relevant
- Lock table schema: resource_id, locked_by, lock_ts, ttl
- API surface: /locks/acquire, /locks/release
- Persist locks in a transactional store

Validation rules
- Lock acquisition is idempotent per operationId
- No two workers modify the same resource concurrently
- Post-conditions validated against the SoT

Security rules
- Never log secrets or keys
- Enforce least privilege and audit trails
- Encrypt locks at rest

Testing rules
- Unit tests for lock state transitions
- Integration tests for worker under lock
- End-to-end tests simulating race conditions

Deployment rules
- Deploy orchestrator and lock-manager in trusted runtime
- Use feature flags and gradual rollout

Human review and escalation rules
- Deadlock or contention escalates to on-call engineer
- Quarterly review of timeout policies

Failure handling and rollback rules
- Retry with backoff on contention; otherwise rollback
- Ensure atomic state transitions

Things Agents must not do
- Do not bypass locks or modify lock state outside orchestrator control
- Do not ignore the SoT; do not drift into architecture drift
- Do not perform unsupervised production changes

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to ensure predictable behavior under pessimistic locking. The Orchestrator enforces policy, while LockManager guarantees serialized access. Workers execute only under lock ownership, with Auditors monitoring for anomalies and deadlocks. Escalation paths route failures to on-call engineers or a RecoveryAgent when configured.

Recommended Project Structure

ai-project/
  pessimistic_locking/
    orchestrator/
    lock-manager/
    workers/
    auditors/
    tests/
    docs/

Core Operating Principles

• Single source of truth for lock state
• Strict serialization of resource access
• Explicit handoffs with verifiable acknowledgments
• No bypassing the locking policy
• Deterministic, auditable decisions
• Fail-fast and recover gracefully

Agent Handoff and Collaboration Rules

• Planner defines lock acquisition order and preconditions
• Implementer respects lock ownership and completes work under lock
• Reviewer validates lock state changes and post-conditions
• Tester simulates race scenarios and deadlocks
• Researcher tests edge cases and SoT consistency
• Domain Specialist confirms domain constraints before handoffs

Tool Governance and Permission Rules

• Only approved tools and APIs may be invoked by agents
• All tool calls required to be idempotent and auditable
• Secrets never logged; access tokens rotated; least-privilege access
• Production access requires approval gates and monitoring

Code Construction Rules

• Acquire lock before performing resource-modifying operations
• Release lock only after successful handoff acknowledgement
• All operations must be idempotent and replay-safe
• Do not bypass the SoT or cache to drift state
• Code paths must be covered by unit and integration tests

Security and Production Rules

• Enforce secrets handling policies and encryption at rest
• Implement audit trails for lock acquisitions/releases
• Configure deadlock detection and automatic rollback
• Limit exposure of internal APIs to trusted networks

Testing Checklist

• Unit tests for lock state transitions
• Integration tests for orchestrator-lock-manager-worker interactions
• Race condition simulations and deadlock detection tests
• End-to-end tests under load with simulated failures

Common Mistakes to Avoid

• Bypassing locks or SoT to speed up tasks
• Ignoring deadlock scenarios and timeout policies
• Unclear handoff criteria or missing acknowledgments
• Unstructured memory without SoT references

Related implementation resources: AI Use Case for Quickbooks Reports and Management Dashboards and AI Use Case for Organic Farmers Using Historical Pest Logs To Predict When Specific Crops Will Need Organic Treatments.

FAQ

What is the purpose of this pessimistic locking AGENTS.md Template?

To define roles and rules for AI coding agents to coordinate access to shared resources using pessimistic locking and explicit handoffs, enabling safe multi-agent orchestration and governance.

Who are the key agents and what do they do?

Orchestrator coordinates locks; LockManager maintains locks; Worker performs tasks under lock; Auditor validates usage and detects deadlocks.

How are handoffs handled between agents?

Handoffs pass the updated context to the next agent and release locks after acknowledgement; failures trigger rollback and escalation.

What are the security rules and how are secrets managed?

Secrets are never logged; tokens are rotated; access is restricted to approved interfaces and audited.

What testing ensures no race conditions and deadlocks?

Unit tests for lock transitions, integration tests for lock usage, and end-to-end tests simulating race conditions and deadlocks.