AGENTS.md Template for Concurrency Control Reviews

Overview

This AGENTS.md template governs a concurrency control review workflow for AI coding agents. It supports both single-agent review cycles and multi-agent orchestration, ensuring safe, auditable changes to concurrent code paths, race-condition mitigations, and deterministic outcomes across tools and APIs involved in the workflow.

Direct answer: This AGENTS.md template defines roles, governance, handoffs and validation rules to enable safe concurrency reviews across agents, with clear escalation paths and memory you can persist in a knowledge base.

When to Use This AGENTS.md Template

• When introducing new concurrency checks in an AI coding agent workflow
• When coordinating planner, implementer, reviewer, and researcher roles for race-condition audits
• When you need explicit handoff rules and source-of-truth for multi-agent review cycles
• When tool governance and secrets management must be enforced during reviews
• When you require a repeatable project structure and validation gates before deployment

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Concurrency Control Review Agent

Agent roster and responsibilities:
- Planner: orchestrates the review flow, assigns tasks, and tracks dependencies across agents
- Implementer: makes code or workflow changes to address concurrency issues
- Reviewer: validates correctness of changes, detects race conditions, and enforces safety constraints
- Researcher: gathers data on potential contention scenarios and proposes mitigations
- Domain Specialist: ensures domain rules and data integrity are preserved during concurrency changes
- Orchestrator: supervisor that triggers handoffs, enforces memory rules, and ensures auditable state

Supervisor or orchestrator behavior:
- Enforce explicit handoffs with status signals
- Maintain a single source of truth for decisions and outputs
- Persist essential memory to a knowledge base; do not rely on short-term ephemeral context
- Gate changes through validation and human review as defined in this template

Handoff rules between agents:
- Planner -> Implementer: deliver clear task brief with acceptance criteria
- Implementer -> Reviewer: publish changes and a brief summary of reasoning
- Reviewer -> Researcher/Domain Specialist: request deeper analysis if edge cases are found
- Researcher/Domain Specialist -> Planner: provide findings and mitigations for inclusion in the next cycle

Context, memory, and source-of-truth rules:
- All decisions must be anchored to a repository state, CI results, and test artifacts
- Memory is stored in a dedicated knowledge base; avoid relying on ephemeral tokens
- Use PRs and CI checks as the canonical source of truth for changes

Tool access and permission rules:
- Only approved tools and scopes permitted by the orchestrator
- Secrets stored in a secure vault; never exposed in logs or agent messages
- Produce minimal, auditable outputs for tool usage and access requests

Architecture rules:
- Concurrency concerns must be modeled with deterministic, idempotent actions where possible
- Changes must be traceable end-to-end from planning to deployment
- Avoid non-idempotent steps in automated flows

File structure rules:
- All concurrency-related changes live under a dedicated workspace: concurrency-review/
- Subfolders: planner/, implementer/, reviewer/, researcher/, domain-specialist/, orchestrator/
- Include a shared knowledge_base/ for memory and decisions

Data, API, or integration rules when relevant:
- Use structured inputs for race-condition scenarios; log inputs and outcomes
- Validate API contracts and data ownership during concurrency checks
- Do not perform live operations against production datasets during reviews

Validation rules:
- All changes must pass unit tests for concurrency scenarios
- Integration tests must cover at least one race-condition mitigation path
- Validate that no non-idempotent operations occur in the review path

Security rules:
- Do not expose secrets in agent messages or logs
- Encrypt sensitive artifacts in transit and at rest
- Enforce least privilege for tool access

Testing rules:
- Include unit, integration, and end-to-end tests focused on concurrency behavior
- Use simulated race conditions to validate safeguards

Deployment rules:
- Do not auto-deploy from the review branch without explicit approval
- Deploy only after all validations pass and human review is complete

Human review and escalation rules:
- Trigger human escalation for ambiguous concurrency patterns or policy violations
- Escalate to domain experts when edge-case data conditions are unidentified

Failure handling and rollback rules:
- If race conditions or nondeterministic outputs are detected, revert to the last known good state
- Apply a rollback PR and re-run the review with updated mitigations

Things Agents must not do:
- Do not bypass approvals or skimp on tests
- Do not mutate production data
- Do not leak secrets or credentials in messages
- Do not ignore established handoff protocols

Recommended Agent Operating Model

• Planner defines scope, success criteria, and sequencing for concurrency reviews
• Implementer executes changes with clear, testable outcomes
• Reviewer validates correctness, tests, and guardrails for race conditions
• Researcher provides data-driven mitigations and scenario analysis
• Domain Specialist ensures business rules and data integrity
• Orchestrator coordinates all roles, enforces memory rules, and ensures auditable outputs

Recommended Project Structure

concurrency-review/
├─ planner/
├─ implementer/
├─ reviewer/
├─ researcher/
├─ domain-specialist/
├─ orchestrator/
└─ shared_kb/

Core Operating Principles

• Operate with deterministic and idempotent actions where possible
• Enforce clear handoffs and audit trails for every decision
• Keep secrets out of messages; use secure vaults and access controls
• Validate changes with targeted concurrency tests before adoption
• Escalate to humans for ambiguous decisions or policy violations

Agent Handoff and Collaboration Rules

• Planner issues a task brief; Implementer delivers changes with a summary
• Reviewer validates, logs rationale, and asks for clarifications if needed
• Researcher and Domain Specialist provide mitigation data when gaps exist
• Orchestrator ensures all steps completed and stores final state

Tool Governance and Permission Rules

• Only approved tools with scoped permissions may be used
• Secrets must be retrieved from a vault; never written to logs
• All API calls and tool usage must be auditable
• Approval gates must be honored before any deployment action

Code Construction Rules

• Write deterministic, testable code paths for concurrency review steps
• Document changes with rationale and test outcomes
• Avoid duplicating work across agents

Security and Production Rules

• Protect production systems; never perform review actions in production without explicit approval
• Review access controls for all tools invoked during concurrency tests
• Ensure data minimization in test scenarios

Testing Checklist

• Unit tests for each concurrency mitigation path
• Integration tests simulating race conditions
• End-to-end tests that validate the entire review orchestration

Common Mistakes to Avoid

• Skipping tests for concurrency scenarios
• Relying on ephemeral context instead of a persistent memory store
• Bypassing handoffs or skipping approvals

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Agent Use Case for Intermodal Transport Providers Using Rail Schedules To Coordinate Seamless Truck-To-Train Transfers.

FAQ

How do concurrency control reviews ensure safe multi-agent orchestration?

They define roles, handoffs, sources of truth, and gating rules to prevent race conditions and ensure deterministic outcomes.

What happens when a potential race condition is detected during a review?

The orchestrator flags the issue, rolls back non-idempotent actions, and routes the task to researchers and domain experts for analysis before re-trying with mitigations.

How is tool access and secrets managed during concurrency reviews?

Only approved tools are used; secrets are stored in a secure vault and never exposed in logs or agent messages.

How are agent handoffs enforced between planner, implementer, and reviewer?

Handoffs are triggered by status signals from the orchestrator; outputs include a concise summary, and missing signals trigger escalation.

What coverage is required for validation and rollback?

Include unit tests for concurrency paths, integration tests for race conditions, and a rollback plan to revert commits if issues are found.