AGENTS.md Template - Conflict Resolution System Design for AI coding agents | Suhas Bhairav

Overview

Direct answer: This AGENTS.md Template defines a conflict resolution system design for AI coding agents, enabling safe multi-agent orchestration with clear roles, state, and governance boundaries.

This AGENTS.md Template explains how the conflict resolution workflow is governed by a planner, implementer, reviewer, and escalation path, supporting both single-agent execution and multi-agent orchestration.

When to Use This AGENTS.md Template

When conflicts arise during automated coding or decision making that require cross-agent coordination
When you need a documented operating model and escalation path
When tool access, secrets, and API calls must be governed with approval gates
When you want a reusable, copyable AGENTS.md to bootstrap a project

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Conflict Resolution System Designer and Orchestrator
Agent Roster and Responsibilities:
- Planner: Detect conflicts, propose resolution plan, and coordinate handoffs.
- Implementer: Execute resolution steps, implement fixes, and apply changes.
- Reviewer: Validate outputs, ensure compliance with rules, and sign off.
- Researcher: Gather context, collect sources, and surface uncertainty.
- Domain Specialist: Provide domain constraints and guardrails.

Supervisor or Orchestrator Behavior:
The orchestrator coordinates agent actions, enforces memory and source-of-truth rules, caches context, and triggers escalations when needed. It logs decisions and prevents drift.

Handoff Rules Between Agents:
Planner → Implementer → Reviewer → Tester → Domain Specialist (as needed). Escalate to Human Review if confidence is below threshold.

Context, Memory, and Source-of-Truth Rules:
Maintain a single source of truth in the knowledge store. Memory is short-lived for each task but persisted for traceability. All decisions cite sources.

Tool Access and Permission Rules:
Only allowed to call approved APIs. Secrets are retrieved from a secure vault. Actions require approvals for production changes.

Architecture Rules:
Event-driven, idempotent, auditable, and modular to support multi-agent orchestration.

File Structure Rules:
workspace/agent-design/conflict-resolution/
- planners/
- implementers/
- reviewers/
- researchers/
- domain/
- configs/
- memory/
- tests/
- deployments/

Data, API, or Integration Rules:
All integrations must expose clear input and output schemas. Validate against contract tests.

Validation Rules:
Each step must emit a validation artifact. Validate with unit and integration tests.

Security Rules:
Do not log secrets. Use encryption at rest and in transit. Audit all escalations.

Testing Rules:
Unit tests for each agent role; integration tests for multi-agent flows; end-to-end tests in a staging environment.

Deployment Rules:
CI/CD with feature flags, blue/green deploys, and rollback hooks.

Human Review and Escalation Rules:
If automatic resolution confidence < 0.75, escalate to human review and provide a trace.

Failure Handling and Rollback Rules:
If a step fails, rollback to the last known good state and re-run with mitigations.

Things Agents Must Not Do:
Do not bypass approvals. Do not mutate shared state without consensus. Do not ignore failed validations.

Recommended Agent Operating Model

Roles and decision boundaries: Planner designs plans; Implementer executes; Reviewer validates; Researcher guides context; Domain Specialist ensures constraints. Escalations to humans for uncertain decisions. Clear handoffs and termination conditions per task.

Recommended Project Structure

workspace/
  - agent-design/
    - planners/
    - implementers/
    - reviewers/
    - researchers/
    - domain/
    - configs/
  - memory/
  - tests/
  - deployments/
  - docs/
  - tools/

Core Operating Principles

Single source of truth for decisions and sources
Idempotent and auditable agent actions
Clear escalation to human review when uncertainty is high
Strict tool governance and permission boundaries

Agent Handoff and Collaboration Rules

Planner proposes plan with confidence and required approvals
Implementer executes plan and records results
Reviewer validates outputs and confirms sources
Researcher and Domain Specialist provide context and guardrails when needed
Handoff requires state update in the knowledge store

Tool Governance and Permission Rules

All commands and API calls must pass policy checks
Secrets accessed via secure vaults with least-privilege access
Production actions require approvals and rollbacks

Code Construction Rules

Code changes applied only via orchestrator and with traceable plan
Configurations versioned and validated

Security and Production Rules

Encrypt data at rest and in transit
Log access and escalate anomalies
Limit blast radius in production by feature flags

Testing Checklist

Unit tests per agent role
Integration tests for multi-agent flows
End-to-end tests in staging with simulated conflicts

Common Mistakes to Avoid

Bypassing handoffs or approvals
Context drift across agents
Undercutting source-of-truth and memory rules

FAQ

What is the purpose of this AGENTS.md Template?

Defines a conflict resolution system design for AI coding agents, including roles, handoffs, memory, and governance.

Who should read this template?

The Planner, Implementer, Reviewer, Researcher, Domain Specialist, and engineering leads should use this to coordinate conflict resolution workflows.

How are handoffs enforced across agents?

Through a controlled state transition in the knowledge store with required approvals and traceability.

What about security and production rules?

Secrets via vault, least privilege, audited actions, and approvals for production changes.

How is failure handled?

Rollback to the last safe state and escalate to human review if needed.

AGENTS.md Template - Conflict Resolution System Design for AI coding agents

Target User

Use Cases