AGENTS.md Template: Large-Scale React Architecture

Overview

AGENTS.md template for large scale React architecture is a formal operating manual for AI coding agents that govern multi-agent orchestration across a React app portfolio. It defines an agent workflow, roles, and handoffs, enabling both single-agent execution and multi-agent coordination in production-grade frontend initiatives. Direct answer: this AGENTS.md template sets the operating context, boundaries, and collaboration rules for AI coding agents managing a large React architecture, including agent handoffs and supervision at scale.

When to Use This AGENTS.md Template

• When you orchestrate multiple AI agents to design, implement, and govern a large React app ecosystem where components and UI flows must coordinate.
• When you need a formal operating manual that captures roles, handoffs, memory, and tool governance for AI coding agents.
• When compliance, reproducibility, and auditable decisions matter for frontend architecture in teams of multiple engineers and product owners.
• When you require a clear escalation path and human review for high-risk changes in UI or data contracts.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Lead AI coding agents responsible for shaping and maintaining the React architecture with multi-agent orchestration. This template defines roles, rules, and handoffs for large-scale frontend systems.

Agent roster and responsibilities:
- Planner: designs a high-level plan for UI architecture, component boundaries, data flow, and routing strategy.
- Implementer: translates plans into code, scaffolds components, hooks, and state management with accessibility in mind.
- Reviewer: validates code quality, performance, accessibility, and conformance to UI guidelines.
- Tester: creates and executes test plans, including UI tests, API mocks, and visual regression checks.
- Researcher: gathers requirements, documents edge cases, user journeys, and sources truth.
- Domain Specialist: provides domain constraints, business logic constraints, and regulatory considerations.

Supervisor or orchestrator behavior:
- The orchestrator coordinates tasks, shares memory, enforces tool access, and ensures handoffs occur per policy. It retains the plan and updates it as inputs evolve.

Handoff rules between agents:
- Planner to Implementer: handoff with a concrete task list, acceptance criteria, and memory notes.
- Implementer to Reviewer: handoff with diffs, rationale, and any design constraints.
- Reviewer to Tester: handoff with test cases and acceptance criteria.
- Researcher to Domain Specialist: handoff for domain constraints and validation.
- Domain Specialist to Planner: feedback loop to adjust the plan based on constraints.

Context, memory, and source-of-truth rules:
- Context is stored in a versioned memory store; all agents reference source-of-truth endpoints; memory is indexed by task id, agent id, and timestamp.
- Source-of-truth endpoints are the single source of decisions for external data and UI contracts.

Tool access and permission rules:
- Agents may call only permitted endpoints; secrets must be retrieved from a secrets manager; production systems require explicit approval gates; external services require scoped credentials.

Architecture rules:
- React architecture follows a modular monorepo; components are decoupled; UI data flows are unidirectional; side effects are managed via hooks and middleware; code styling follows project-wide standards.

File structure rules:
- Include only folders that contribute to the agent-guided architecture; avoid irrelevant scaffolds; maintain consistent naming and depth.

Data, API, or integration rules when relevant:
- Use typed API clients; avoid hard-coded secrets; envelope external calls; provide mocks for tests; document API contracts.

Validation rules:
- Each artifact must have unit tests, lint checks, type checks, and code reviews before handoff; acceptance criteria must be explicit.

Security rules:
- Secrets are never embedded in code; rotate keys; access to production is gated; all actions are audited; PII handled per policy.

Testing rules:
- Include unit tests for components, integration tests for data flows, and end-to-end tests for critical journeys.

Deployment rules:
- Production deployments require a review cycle; feature flags for experiments; canary releases with monitoring; rollback plan if needed.

Human review and escalation rules:
- Ambiguity triggers human review; critical failures trigger rollback and stakeholder notification.

Failure handling and rollback rules:
- On failure revert to last known good; maintain an audit log; notify stakeholders; rollback to previous release if needed.

Things Agents must not do:
- Do not access production secrets directly; do not modify infrastructure without approval; do not perform unsupervised deployments; do not ignore memory or source-of-truth.

Recommended Agent Operating Model

The recommended operating model defines clear agent roles, decision boundaries, and escalation paths. Planners propose architecture options; Implementers execute against a vetted plan; Reviewers enforce quality gates; Testers validate outcomes; Researchers provide domain and edge-case coverage; Domain Specialists ensure compliance and business constraints. Escalation paths exist for ambiguous decisions or security concerns. This model enables safe, auditable, multi-agent collaboration across UI work, data contracts, and architecture governance.

Recommended Project Structure

Workflow-aligned directory tree for large-scale React architecture.

/apps
  /react-architecture
    /src
      /components
      /containers
      /hooks
      /state
    /agents
      /planner
      /implementer
      /reviewer
      /tester
      /researcher
      /domain-specialist
    /workflows
    /config
  /shared
  /tools

Core Operating Principles

• Operate with auditable outputs and versioned decisions.
• Maintain a single source of truth for all domain data and UI contracts.
• Enforce explicit handoffs and clear memory management.
• Apply tool governance and human-in-the-loop for high-risk changes.
• Prevent context drift and architecture drift through strict boundaries.

Agent Handoff and Collaboration Rules

Concrete rules for planner, implementer, reviewer, tester, researcher, and domain specialist agents.

• Planner creates plan with acceptance criteria and memory anchors; handoff to Implementer with task list.
• Implementer completes tasks; passes to Reviewer with diffs and rationale.
• Reviewer validates and passes to Tester with test cases; unresolved blockers escalate.
• Researcher and Domain Specialist provide constraints; feedback loops back to Planner as needed.
• All handoffs must include memory references and sources of truth.

Tool Governance and Permission Rules

Rules for command execution, file edits, API calls, secrets, and production access.

• All tool actions are governed by role-based permissions and approval gates.
• Secrets retrieved from secret management; never stored in code; rotate periodically.
• Production endpoints require approved change requests; logs retained for audit.

Code Construction Rules

Concrete implementation constraints for this React workflow.

• Use TypeScript for all new React code; strict typing; explicit prop interfaces.
• Keep components small and testable; prefer composition over inheritance.
• Adopt a monorepo structure with clear package boundaries.
• UI data flow is unidirectional; avoid direct DOM manipulation in agents.
• All API interactions go through typed clients with error handling and retry policies.

Security and Production Rules

Workflow-specific security guidance and production safeguards.

• Secrets never appear in code; use a dedicated vault or secret manager.
• Production deployments require a human approval gate and monitoring.
• Access to production is restricted to predefined roles; activity is logged.

Testing Checklist

• Unit tests for components and hooks; coverage thresholds met.
• Integration tests for critical data flows and API contracts.
• UI tests for key user journeys and accessibility checks.
• End-to-end tests with canary validation where feasible.

Common Mistakes to Avoid

• Assuming agents can bypass memory or source-of-truth rules.
• Allowing plan drift without explicit re-validation.
• Unsupervised changes in production configurations.
• Overfitting to a single React pattern instead of modular design.

Related implementation resources: AI Use Case for Xero Reports and Business Performance Insights and AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is the scope of this AGENTS.md template?

The template defines roles, rules, and handoffs for AI coding agents managing a large-scale React architecture with multi-agent orchestration.

How do I adapt the template to my monorepo?

Adjust the project structure, agent roster, and workflow files to reflect your packages and domains; keep memory and source-of-truth anchors consistent.

How are agent handoffs enforced?

Handoffs include explicit acceptance criteria, memory anchors, and references to source-of-truth; the orchestrator enforces the sequence.

What about security and production changes?

Secrets are never stored in code; change approvals are required for production; all actions are audited.

How should outputs be validated?

Outputs must pass unit/integration tests, follow lint/type checks, and be reviewed for design and performance criteria before merging.

Where can I find the canonical reference for the template?

See the AGENTS.md Templates collection under AI Skills and the specific template page.