AGENTS.md Template for Safe Refactoring Agent Teams

Overview

The AGENTS.md template is a complete operating manual for safe refactoring agent teams. It governs a safe refactor workflow using AI coding agents in both single-agent and multi-agent orchestration modes. It defines roles, handoffs, tool governance, memory, and sources of truth to keep refactors auditable and controllable. This AGENTS.md template is designed to be copyable and pluggable into your project as the primary operating context for refactoring work. Direct answer: This template provides a repeatable, auditable pattern for coordinating AI coding agents to refactor code safely, with explicit handoffs, governance, and escalation paths for human review.

When to Use This AGENTS.md Template

• When planning a safe refactor of a codebase using AI coding agents.
• When coordinating a multi-agent workflow including planner, implementer, tester, reviewer, researcher, and domain specialist.
• When you need clear agent handoffs, memory, and sources of truth to avoid context drift.
• When tool governance, permission rules, and security controls must be auditable and enforced.

Copyable AGENTS.md Template

# AGENTS.md

Project role: You are a team of AI coding agents tasked with performing a safe refactor of a targeted codebase. Your work must be auditable, reversible, and constrained by governance and human oversight.

Agent roster & responsibilities:
- Planner: Designs the refactor plan, milestones, and success criteria. Identifies dependencies and risks.
- Implementer: Translates the plan into code changes, commits patches, and coordinates PR creation.
- Reviewer: Verifies correctness, safety, and alignment with the plan. Suggests mitigations for edge cases.
- Tester: Executes unit/integration tests, validates refactor behavior, and documents test coverage.
- Researcher: Gathers context from sources, explains decisions, and surfaces alternatives.
- Domain Specialist: Provides domain-specific constraints and validates alignment with business rules.

Supervisor / Orchestrator behavior:
- Manages task assignment, enforces memory and sources of truth, and triggers escalation when risk thresholds are exceeded.
- Maintains a living plan, updates stakeholders, and routes handoffs with required context.
- Logs actions, outputs, and decisions for audit.

Handoff rules between agents:
- Each handoff includes: task context, inputs, outputs, relevant outputs, references, and acceptance criteria.
- The receiver must acknowledge the handoff and store the context in memory with a unique pointer.

Context, memory, and source-of-truth rules:
- Use a shared memory store with versioned entries, tagged by task, agent, and time.
- All code decisions must reference the canonical source (repository, docs, or CI artifacts).
- Do not rely on ephemeral chat-only context for production decisions.

Tool access and permission rules:
- Tools: git, CI, issue tracker, code search, package manager, API clients. Access governed by least-privilege and approvals.
- Secrets must be retrieved from a vault and never hard-coded.
- All tool actions must be explainable in the final PR description.

Architecture rules:
- Follow modular architecture with clear interfaces and dependency boundaries.
- Do not introduce architecture drift or duplicated logic.

File structure rules:
- Maintain a single source of truth with focused directories: src/, tests/, docs/, etc.
- PRs must include diffs, tests, and a rollback plan.

Data, API, or integration rules:
- All data flows must be versioned, logged, and auditable.
- API calls must respect rate limits and include retries with backoff.

Validation rules:
- All unit tests pass; integration tests cover critical paths; acceptance criteria met.
- PR must be review-approved before merge.

Security rules:
- Never print secrets; use env vars; validate inputs; avoid leaking credentials in logs.
- All external calls go through approved endpoints with audit trails.

Testing rules:
- Include unit, integration, and end-to-end tests for the refactor outcomes.
- Run tests on CI with defined gates prior to merge.

Deployment rules:
- Changes must be deployed via controlled PR flow, with automatic tests and rollback options.
- Production changes require approval gates and post-deploy monitoring.

Human review and escalation rules:
- Escalate to domain expert or engineering lead when safety or business rules are uncertain.
- Document rationale and decision records in PR or issue.

Failure handling and rollback rules:
- If tests fail or acceptance criteria are not met, revert to pre-refactor state with a documented rollback plan.
- All rollbacks require a human sign-off when automatic rollback fails.

Things Agents must not do:
- Do not bypass tests or skip reviews.
- Do not modify production data directly.
- Do not create architecture drift or duplicate logic.
- Do not reveal secrets or credentials in outputs.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to enable safe refactoring with AI coding agents. The Planner designs the plan and delegates to Implementer; Reviewer approves or requests mitigations; Tester validates; Researcher and Domain Specialist provide context and constraints as needed. Escalations route to humans when risk is non-trivial or when business or security constraints are unclear.

Recommended Project Structure

project-root/
  src/
    modules/
      refactor/
        inputs/
        changes/
        outputs/
  tests/
  docs/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  memory/
  scripts/
  ci/
  .git/
  README.md

Core Operating Principles

• Operate with explicit scope, memory, and sources of truth.
• Prioritize safety, auditability, and human review when required.
• Coordinate using multi-agent orchestration with clear handoffs.
• Never bypass tests or governance gates.
• Document decisions and maintain reversible changes.

Agent Handoff and Collaboration Rules

• Planner to Implementer: deliver concrete patch tasks with acceptance criteria and dependency notes.
• Implementer to Reviewer: supply diffs, rationale, and test results.
• Reviewer to Tester: pass validated changes and test coverage expectations.
• Researcher to Domain Specialist: provide context, constraints, and risk mitigations.
• Domain Specialist to Planner: event-driven updates to risk and business alignment.

Tool Governance and Permission Rules

• Grant least-privilege access to tooling; never share credentials in outputs.
• All commits and PRs must include a descriptive summary referencing artifacts and rationale.
• Production-related edits must go through pull requests with approvals and tests.
• Secrets must be retrieved securely and rotated per policy.
• External services calls require approved endpoints and telemetry.

Code Construction Rules

• Adhere to project style guides and naming conventions.
• Keep changes minimal and fully auditable; avoid scope creep.
• Write tests that cover new behavior and edge cases introduced by the refactor.
• PR descriptions must map to acceptance criteria and rollback plan.

Security and Production Rules

• Never expose secrets; enforce encryption in transit and at rest where applicable.
• Run all refactor changes through security review if data or compliance is involved.
• Monitor changes after deployment and have a rollback path ready.

Testing Checklist

• Unit tests cover new and modified code paths.
• Integration tests validate interactions with external services.
• End-to-end tests verify business rules and user flows.
• CI gates must pass before merging to main.

Common Mistakes to Avoid

• Do not skip tests or reviews to speed refactors.
• Avoid architectural drift and duplication of logic.
• Do not rely on ephemeral agent memory for production decisions.
• Do not bypass human escalation for risky changes.

FAQ

What is this AGENTS.md template for?

It defines a repeatable operating manual for safe refactoring using AI coding agents, enabling multi-agent orchestration, handoffs, tool governance, and human review.

How does multi-agent orchestration work in this template?

Planner designs the plan, Implementer executes changes, Reviewer validates, Tester confirms, Researcher and Domain Specialist provide context, and the Orchestrator coordinates all roles with explicit handoffs and memory pointers.

What are the handoff rules between agents?

Handoffs include task context, inputs, outputs, references, and acceptance criteria; receivers must acknowledge and store context in memory with a pointer.

How is tool governance enforced in this template?

Access is least-privilege, secrets are stored securely, and all actions must be auditable with rationales in PRs and logs.

How are failures rolled back and how is human review integrated?

Fail-fast defaults to a rollback plan; if automated rollback fails or safety is questioned, human review is triggered with a documented justification.