AGENTS.md Template for Frontend System Design

Overview

Direct answer: This AGENTS.md Template governs a frontend system design workflow by codifying a clear agent roster, orchestrator behavior, handoff rules, memory and source-of-truth, tool governance, and escalation procedures for both single-agent and multi-agent setups.

This template describes how AI coding agents operate within a frontend system design context, covering architecture, component orchestration, design tokens, API contracts, and UI state management. It provides a project-level operating context that enables predictable agent collaboration, auditability, and safe production changes.

When to Use This AGENTS.md Template

• When defining an end-to-end frontend system design workflow that may involve multiple agents (planner, implementer, reviewer, tester, researcher, domain specialists).
• When you need explicit handoff rules between agents to prevent drift and ensure traceability of decisions.
• When you require tool governance, secrets handling, and controlled access to production endpoints in frontend projects.
• When you want a copyable operating context that can be pasted into a repo as AGENTS.md for onboarding and governance.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- Frontend System Design Agent Team: responsible for defining frontend architecture, component orchestration, and API contracts for a reliable frontend experience.

Agent roster and responsibilities
- planner: defines goals, milestones, and design decisions; outlines tasks for implementer and reviewer.
- implementer: produces code scaffolds, component wiring, and integration with API contracts.
- reviewer: validates architecture, accessibility, performance, and security implications; approves or requests changes.
- tester: executes unit, integration, and visual tests; reports findings.
- researcher: collects design patterns, libraries, and benchmarks; proposes options.
- domain specialist (frontend performance, accessibility, design system): provides expertise for domain-specific constraints.

Supervisor or orchestrator behavior
- Orchestrator maintains the multi-agent run, assigns tasks, enforces deadlines, and collects results.
- The orchestrator triggers handoffs when agents complete tasks or when dependencies change.
- All decisions and rationale are captured in memory for traceability.

Handoff rules between agents
- Planner hands off design decisions and milestones to Implementer with clear acceptance criteria.
- Implementer hands off to Reviewer when architecture decisions are complete or when code quality gates are met.
- Reviewer hands off to Tester for validation; tester reports failures back to Implementer.
- Researcher and Domain Specialist provide input during planning; their findings become part of the design rationale.

Context, memory, and source-of-truth rules
- Context is stored in a memory store indexed by task and artifact IDs.
- Source-of-truth includes design specs, API contracts, and tokenized component diagrams stored in a central repository.
- Agents must refer to the latest approved design and API contracts for changes.

Tool access and permission rules
- Agents may edit repository files, run tests, and call allowed APIs within a dedicated frontend-design namespace.
- Secrets must never be embedded in code; use secure secret storage and runtime retrieval with approvals.
- Production endpoints require explicit approval gates and can only be touched by authorized agents.

Architecture rules
- Use a modular frontend design with clear boundaries between components, services, and UI state.
- Align with design tokens, Theming, and accessibility guidelines; ensure responsive behavior.
- Prefer declarative UI states and avoid hard-coded values.

File structure rules
- Place all frontend-design artifacts under /frontend-system-design or /design-system-designer if applicable.
- Maintain a clear separation: components/, hooks/, api-contracts/, tokens/, tests/, docs/.

Data, API, or integration rules when relevant
- API contracts must be versioned; changes require planner sign-off.
- Design tokens must be versioned and exported into consistent themes.
- UI state must be serializable for debugging and replay.

Validation rules
- All changes must pass design-review criteria, accessibility checks, and performance benchmarks.
- Code must pass unit tests and integration tests for frontend flows.

Security rules
- Do not expose secrets; never call prod endpoints without approval.
- Validate inputs at every boundary and sanitize data to prevent injection threats.

Testing rules
- Unit tests cover new components and utilities; integration tests cover UI/API flows; visual regression tests where applicable.

Deployment rules
- Deploy through CI/CD with feature flags and staged rollout; ensure rollback is possible.

Human review and escalation rules
- Escalate to Tech Lead if a decision impacts core architecture or production risk.
- All escalations must be documented with rationale and expected outcomes.

Failure handling and rollback rules
- If a deployment fails, roll back to the last green state and re-run validations.
- Reproduce failures in a staging environment before re-deploying.

Things Agents must not do
- Do not bypass review gates or publish to production without approvals.
- Do not introduce architectural drift without updating the design rationale.
- Do not reuse credentials or secrets in code.

Recommended Agent Operating Model

The recommended model assigns explicit roles with bounded decision spaces. Planners decide what to build and when, Implementers translate plans into code, Reviewers validate architecture and code quality, Testers ensure correctness, Researchers and Domain Specialists contribute specialized input. Escalations route issues to leadership when risk exceeds defined thresholds. Memory of design decisions and sources of truth is central to cross-agent coordination; handoffs require explicit acceptance criteria.

Recommended Project Structure

frontend-system-design/
  design-specs/           # design docs, API contracts, diagrams
  tokens/                 # design tokens and themes
  components/             # frontend components specific to the design
  services/               # frontend services and adapters
  agents/                 # agent rosters, tasks, and workflows
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  memory/                 # memory store for decisions and context
  tests/                  # unit/integration tests for frontend design artifacts
  docs/                   # onboarding and operating guidelines
  ci/                     # CI/CD configurations for frontend work

Core Operating Principles

• Operate with explicit ownership and bounded decision spaces.
• Handoff only with clear acceptance criteria and traceable rationale.
• Keep secrets out of code; use secure secret management and approvals.
• Remember and reference the current source of truth for all decisions.
• Govern tools and production endpoints with formal review gates.

Agent Handoff and Collaboration Rules

Planers, Implementers, Reviewers, Testers, Researchers, and Domain Specialists must follow these collaboration rules:

• Planner communicates milestones and constraints to Implementer with acceptance criteria.
• Implementer communicates progress and blockers to Planner and Reviewer; initiate handoffs when milestones are met.
• Reviewer validates architecture decisions and code quality; approves or requests changes with rationale.
• Tester performs validations and reports findings to Implementer with reproducible steps.
• Researcher and Domain Specialist provide input during planning and design reviews; document sources.

Tool Governance and Permission Rules

• Commands, file edits, and API calls must go through approved channels with access controls.
• Secrets must be retrieved securely; never embedded in code or prompts.
• Production system interactions require explicit gates and approvals before execution.
• All changes must be versioned and auditable in the repository.

Code Construction Rules

• Follow front-end architecture patterns and design tokens; avoid hard-coded values.
• Code must be modular, testable, and accessible; follow a11y guidelines.
• All new components must include unit tests and visual tests where applicable.

Security and Production Rules

• Secrets and credentials must never be part of the code or AGENTS.md content.
• API keys and tokens must be stored in secure vaults and retrieved at runtime as needed.
• Production changes require approval gates and rollout monitors; rollback must be possible.

Testing Checklist

• Unit tests for new components/utilities exist and pass.
• Integration tests cover frontend flows with the API contracts.
• Accessibility and performance checks pass; responsive behavior verified.
• Security checks confirm no leakage of secrets and safe data handling.
• Deployment validations and canary tests are configured.

Common Mistakes to Avoid

• Skipping design reviews or bypassing gates.
• Drifting architecture without updating the rationale in AGENTS.md.
• Storing secrets in code or prompts used by agents.
• Over-optimizing for speed at the expense of correctness and accessibility.

Related implementation resources: AI Agent Use Case for Electronics Procurement Teams Using Component Supply Alerts To Source Alternative Parts During Shortages and AI Agent Use Case for Electronics Designers Using Thermal Imagery Files To Optimize PCB Component Trace Placements.

FAQ

What is the purpose of this AGENTS.md Template for Frontend System Design?

It provides a copyable, project-level operating manual for AI coding agents to govern frontend system design workflows and multi-agent orchestration.

How do I customize the agent roster for my frontend project?

Adjust roles (planner, implementer, reviewer, tester, researcher, domain specialist) to match your design goals, keeping acceptance criteria and handoff rules explicit.

What happens if an agent violates a rule?

Violations trigger escalations to the orchestrator and, if needed, to leadership; the system records the incident and reverts to the last approved state.

How are secrets and production endpoints handled?

Secrets are retrieved securely from a vault; production endpoints require gate approvals and are never embedded in code.

How do we validate frontend architecture decisions?

Validation is conducted through the Reviewer and Tester with criteria tied to performance, accessibility, security, and API contract conformance.