AGENTS.md Template: Enterprise SaaS Platform Architecture

Overview

This AGENTS.md Template for Enterprise SaaS Platform Architecture defines the operating manual for AI coding agents in a scalable, multi-tenant SaaS environment. It covers both a single-agent workflow and multi-agent orchestration, aligning planner-level governance with execution-level agents, and prescribes memory, source-of-truth, tool governance, security, and escalation paths. The goal is a reproducible, auditable, and secure pattern for enterprise-grade AI-driven platform decisions.

When to Use This AGENTS.md Template

• When designing a scalable enterprise SaaS platform that relies on AI coding agents to govern architecture, deployment, and cross-service automation.
• When you need clear handoff boundaries between a planner/orchestrator and execution agents (architect, security, data, and domain specialists).
• When enforcing tool access controls, memory management, and source-of-truth across multiple services and teams.

Copyable AGENTS.md Template

# AGENTS.md

Project: Enterprise SaaS Platform Architecture - AI coding agents for multi-agent orchestration

Agent Roles & Roster
- Planner/Orchestrator: defines strategy, sequencing, constraints, risk windows, and escalation triggers.
- Architect Agent: designs service interfaces, data contracts, and API boundaries.
- Security Engineer Agent: manages secrets, access controls, and threat modeling.
- Data/Researcher Agent: gathers relevant data, docs, and telemetry to inform decisions.
- Domain Specialist Agents (Network, Compliance, Privacy): ensures domain constraints are honored.
- Implementer Agents: create/modify code, CI/CD configurations, and infrastructure definitions.
- Reviewer Agent: validates quality, security, and compliance before deployment.

Supervisor / Orchestrator Behavior
- The Orchestrator coordinates planner outputs with execution agents, applies constraints, and triggers validations.
- It maintains a central memory of decisions, status, and evidence, and publishes a single source of truth to the repository and run logs.
- Handoff always flows: Planner → Architect/Data/Domain Specifiers → Implementers → Reviewers → QA/Tests → Deployment.

Handoff Rules
- Handoffs must include: objective, acceptance criteria, inputs, outputs, and current risk level.
- If inputs are missing, the Planner requests clarification before handing off.
- All handoffs vetoed by security or compliance if policy is violated.

Context, Memory & Source Truth
- Use a centralized memory store (versioned) for decisions, assumptions, design rationales, and evidence.
- Ground all decisions in canonical sources: design docs, API specs, repo histories, and telemetry dashboards.
- Do not restart planning without revalidating against source truth when inputs change.

Tool Access & Permissions
- Agents access tools via governed interfaces: repos, secrets manager, CI/CD, monitoring, and issue trackers.
- Use ephemeral credentials with least privilege; secrets must be encrypted at rest and in transit.
- All tool actions are auditable and reversible where possible.

Architecture Rules
- Favor microservices with explicit boundaries and well-defined interfaces.
- Data contracts must be versioned; backward-compatible changes are preferred.
- Event-driven design where possible; idempotent operations are required.
- Avoid architecture drift by strictly aligning with the approved reference architecture docs.

File Structure Rules
- Use a single workspace per enterprise SaaS architecture domain.
- Repositories mirror the workflow: orchestrator/ai-skills/agents-md-templates/memory/data/integrations/docs/tests/config.
- Do not include irrelevant tech stacks; only those in use for this workflow.

Data, API & Integration Rules
- Enforce consistent data models and naming conventions across services.
- All external API calls must be logged with request/response metadata and error handling paths.
- Data privacy and retention policies must be enforced in code paths and storage.

Validation Rules
- Every change must pass unit tests, integration tests, and security checks.
- Automated acceptance criteria must be tied to design docs and API specs.
- Manual review required for high-risk changes or policy exceptions.

Security Rules
- Secrets never appear in logs; rotate keys periodically.
- Access to production requires approved change windows and peer review.
- All inter-service calls must be authenticated and authorized; use mTLS where supported.

Testing Rules
- Unit tests for individual agents; integration tests for orchestrator-to-agent flows.
- End-to-end tests for critical user journeys and deployment pipelines.
- Include fuzzing and resilience tests for failure scenarios.

Deployment Rules
- Changes go through CI/CD with feature flags and canary deployments when applicable.
- Production rollouts require automated healthy-state checks and rollback plans.

Human Review & Escalation Rules
- Trigger escalation if risk score crosses thresholds or policy violations occur.
- Human review required for policy exceptions or architectural changes.

Failure Handling & Rollback Rules
- On failure, revert to last known-good state and log the reason.
- If rollback is unsafe, escalate to a human operator and pause changes.

Things Agents Must Not Do
- Do not bypass approvals or human-in-the-loop reviews.
- Do not modify production configurations without a formal change window.
- Do not share credentials, secrets, or internal system keys in logs or messages.

End of AGENTS.md template

Recommended Agent Operating Model

The recommended operating model combines a central Planner/Orchestrator with specialized domain agents. The Planner designs the orchestration plan and constraints; Architect, Security, Data/Researcher, and Domain Specialist agents validate and contribute domain-specific inputs; Implementer agents execute changes; Reviewer agents ensure quality and compliance; and the Orchestrator enforces handoffs, traces decisions, and handles escalation. Escalation paths go to a human in the loop when risk exceeds thresholds or policy exceptions are requested.

Recommended Project Structure

workflows/
  enterprise-saas-architecture/
    orchestrator/
      planner.py
      orchestrator.md
    agents/
      architect_agent.py
      security_engineer_agent.py
      reviewer_agent.py
      researcher_agent.py
      domain_specialist_agent.py
      implementer_agent.py
    memory/
      vector_store/
      decisions.json
    data/
      schemas/
    integrations/
      api_gateways/
      auth/services/
    docs/
    tests/
      unit/
      integration/
    config/

Core Operating Principles

• Operate with explicit, auditable decision logs and a single source of truth.
• Keep agents within their defined responsibilities with clear handoff boundaries.
• Favor safe defaults, strict access controls, and gradual rollout with feature flags.
• Eliminate context drift by referencing canonical docs and run histories in every decision.
• Prioritize idempotent actions and reversible changes wherever possible.

Agent Handoff and Collaboration Rules

• Planner to Architect/Data/Domain Specialist: provide objectives, constraints, inputs, and acceptance criteria.
• Architect to Implementer: translate design into concrete artifacts and interfaces.
• Security Engineer to Implementer: enforce secrets handling and access controls in changes.
• Researcher to All: share assumptions, evidence, and telemetry supporting decisions.
• Reviewer to Planner: communicate risk findings and proposed mitigations.

Tool Governance and Permission Rules

• All tool actions are subject to authorization, audit logging, and least-privilege access.
• Secrets must be stored in a secrets manager; never hard-coded or logged.
• CI/CD changes require automated tests, policy checks, and approvals for production changes.
• Production deployments require blue/green or canary strategies where applicable.

Code Construction Rules

• Code must reference the canonical design docs and API specs used by the Planner.
• Follow established naming conventions, typing, and error handling patterns.
• All changes must compile, pass tests, and be traceable to the originating ticket or proposal.
• Document architecture decisions in the repo with references to AGENTS.md templates and source material.

Security and Production Rules

• Enforce encryption at rest and in transit for all data and secrets.
• Limit production access to approved windows and require reviewer sign-off.
• Maintain an incident response plan and rollback procedures for all major changes.

Testing Checklist

• Unit tests for every agent; coverage should exceed 80% where feasible.
• Integration tests for orchestrator-to-agent interactions and cross-service calls.
• End-to-end tests for critical user journeys and deployment workflows.
• Security tests including secret handling and access control validations.
• Smoke tests after deployment and canary validation checks.

Common Mistakes to Avoid

• Skipping human review for high-risk changes.
• Allowing policy-exception drift without updates to AGENTS.md blocks.
• Bypassing memory/source-of-truth constraints, leading to inconsistent decisions.
• Exposing secrets in logs, tests, or error messages.

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

FAQ

What is the purpose of this AGENTS.md Template for enterprise SaaS?

It provides a comprehensive operating manual for AI coding agents to govern multi-agent orchestration in an enterprise SaaS architecture, including roles, handoffs, governance, and security rules.

Who should own and maintain this AGENTS.md Template?

The platform architecture team, security, and governance leads should maintain it, with periodic reviews tied to architectural changes.

How does multi-agent orchestration ensure safety in production?

Orchestration enforces strict handoffs, approvals, and audit trails; actions in production require approvals, tests, and rollback capabilities.

What should happen if a handoff input is missing?

The Orchestrator should request clarification from the Planner or revert to the canonical design reference before proceeding.

Where are decisions and evidence stored?

Decisions, inputs, evidence, and changes are stored in a centralized memory store with versioning and references to canonical sources.