AGENTS.md Template for Circuit Breaker Design

Overview

The AGENTS.md template is a project-level operating manual for circuit breaker design in AI coding agents. It governs single-agent and multi-agent orchestration, ensuring safe fallbacks, memory discipline, and auditable handoffs. This page is a copyable AGENTS.md template you can paste verbatim into your repository to establish the governance for resilient agent workflows and multi-agent handoffs.

Direct answer: This template defines the roles, rules, and orchestration patterns to implement a circuit breaker strategy across agents, including how inter-agent handoffs occur and how memory, context, and sources of truth are maintained.

When to Use This AGENTS.md Template

• Designing resilient AI coding workflows that require safe failure handling and fallback paths.
• Establishing clear agent roles and responsibilities for multi-agent orchestration.
• Enforcing tool governance, secrets handling, and production-systems access across agents.
• Documenting memory and context management to prevent context drift in long-running tasks.

Copyable AGENTS.md Template

# AGENTS.md

# Circuit Breaker Design for AI Coding Agents

Project role
- Establish and maintain a circuit breaker design for AI coding agent workflows.
- Define decision boundaries, escalation paths, and auditability requirements.

Agent roster and responsibilities
- Planner: designs the workflow and manages handoffs; defines success criteria.
- Implementer: builds the circuit-breaker logic and integrates with agents.
- Reviewer: validates implementation against requirements and security standards.
- Tester: executes unit/integration tests and simulates failure modes.
- Researcher: gathers failure-mode data and improvements.
- Domain Specialist: ensures domain constraints, observability, and risk controls.

Supervisor or orchestrator behavior
- Orchestrator enforces the circuit breaker policy, coordinates handoffs, and maintains memory/storage of context.
- All tool calls must go through the orchestrator; direct mutations to the truth source are prohibited.

Handoff rules between agents
- Planner ➜ Implementer: hand off design specs and wiring diagrams.
- Implementer ➜ Reviewer: hand off build and test results.
- Reviewer ➜ Tester: hand off validated features for integration testing.
- Tester ➜ Orchestrator: report pass/fail and state changes.

Context, memory, and source-of-truth rules
- Central context store holds current plan, states, and logs.
- Agents must reference the context store for any decisions related to the circuit breaker state.
- Source of truth is the production-like state repository; updates require approval gates.

Tool access and permission rules
- Implementer and Planner can access design docs; secret retrieval is restricted to approved agents.
- API calls to production endpoints require approval from the orchestrator and a failsafe path.
- No direct edits to the production database without review and rollback plan.

Architecture rules
- Use a modular design with a dedicated circuit-breaker module that exposes a small, well-documented API.
- All integration points are versioned and tested against a local simulation environment.

File structure rules
- Place all circuit-breaker related artifacts under workflows/circuit-breaker/ with clearly named subfolders.

Data, API, or integration rules when relevant
- Define circuit-breaker states, timeouts, retry policies, and fallback data paths.
- All external calls are instrumented with tracing and metrics.

Validation rules
- Cover functional, resilience, and security validations; require deterministic outcomes in tests.

Security rules
- Never log secrets; rotate credentials regularly; enforce least privilege on all agents.

Testing rules
- Unit tests for breaker logic; integration tests for end-to-end flow; contract tests for API surfaces.

Deployment rules
- Use CI gates that require tests to pass before deployment to staging and production.

Human review and escalation rules
- Escalate high-risk changes to a human reviewer; require sign-off for production deployments.

Failure handling and rollback rules
- On breaker activation, route to safe fallback; rollback changes if critical issues are detected.

Things Agents must not do
- Do not bypass the orchestrator or modify the source of truth directly.
- Do not perform unsanctioned deployments or secret leakage.
- Do not drift from agreed circuit-breaker states without approval.

# End of template

Recommended Agent Operating Model

Roles and decision boundaries: Planner designs the policy, Implementer enforces it, and Orchestrator enforces handoffs and gating. Reviewers validate code and security posture. Escalation paths connect human oversight when risk thresholds are exceeded.

Recommended Project Structure

project-root/
  workflows/
    circuit-breaker/
      planner/
      implementer/
      reviewer/
      tester/
      researcher/
      domain-specialist/
      orchestrator/
  docs/
  tests/
  infra/
  secrets/

Core Operating Principles

• Single source of truth and traceable decisions.
• Idempotent actions and deterministic state transitions.
• Clear and auditable handoffs between agents.
• Strong observability, metrics, and tracing.
• Security and access controls baked into every step.

Agent Handoff and Collaboration Rules

• Planner communicates policy, constraints, and expected outcomes to Implementer.
• Implementer provides traceable changes and test results to Reviewer.
• Reviewer approves or requests changes; Tester validates against acceptance criteria.
• Researcher adds failure mode data for future iterations; Domain Specialist audits compliance.

Tool Governance and Permission Rules

• Execution of commands must go through Orchestrator; no direct shell access by agents.
• File edits require review and sign-off; secrets stored in vault with access control.
• API calls to external services require permission gates and rate limiting.
• Production access is restricted and audited; deploy approvals required.

Code Construction Rules

• Write modular, testable components for the circuit-breaker module.
• Maintain backward compatibility and deprecation plans.
• Avoid duplicating logic; reuse existing utility functions and libraries when applicable.
• Document public interfaces and ensure type-safety where possible.

Security and Production Rules

• Never log secrets or plaintext credentials; rotate tokens periodically.
• Audit all breaker activations and ensure secure rollback paths.
• Implement input validation, output escaping, and strict schema enforcement.

Testing Checklist

• Unit tests for breaker state transitions.
• Integration tests for inter-agent handoffs and orchestrator gating.
• Security tests for secret handling and access controls.
• End-to-end tests simulating failure modes and fallback behavior.

Common Mistakes to Avoid

• Skipping required approvals for production changes.
• Assuming memory will be perfectly consistent across agents.
• Overwriting source of truth without proper rollback plans.
• Omitting explicit handoff rules and observability in multi-agent flows.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the purpose of this AGENTS.md Template?

This template defines the operating model for circuit breaker design in AI coding agents, enabling resilient single-agent and multi-agent orchestration with clear handoffs and governance.

How do I implement agent handoffs in this template?

Handoffs are defined by the Planner to Implementer, Implementer to Reviewer, Reviewer to Tester, and Tester to Orchestrator, with explicit state transfer and a shared context store.

How is memory and the source of truth managed?

All context lives in a central context store; agents read from and write to it through the orchestrator, which enforces consistency and versioning.

What are the security requirements for circuit-breaker design?

Secrets must be stored in a vault; access is role-based; production credentials require multi-person approval and audit logging.

How do I validate this circuit-breaker workflow?

Run unit tests for breaker logic, integration tests for handoffs, and end-to-end tests with simulated failures to verify fallback behavior and rollback readiness.