AGENTS.md Template: Full-Stack SaaS Build Agents (AGENTS.md template)

Overview

Direct answer: This AGENTS.md template defines the operating context for a full-stack SaaS build using AI coding agents. It governs both single-agent workflows and multi-agent orchestration, including planning, execution, handoffs, and governance across tools and platforms.

The template ensures a coherent, auditable trail of decisions, inputs, and outputs, enabling consistent collaboration across engineers, product managers, and site reliability teams.

When to Use This AGENTS.md Template

Use this template when you are assembling a project that uses AI coding agents to build and deploy a full-stack SaaS product. It helps teams establish roles, communication, and governance before coding begins.

• Define the agent roster and responsibilities for planning, implementation, testing, and review.
• Establish memory, source-of-truth, and tool access rules to prevent drift.
• Coordinate single-agent work or multi-agent collaboration with clear handoffs.
• Set validation, security, and deployment criteria early to guide automation.

Copyable AGENTS.md Template

Copy the block below into your AGENTS.md file.

# AGENTS.md

Project: Full-Stack SaaS Build with AI Coding Agents
Workflow: Multi-Agent Orchestration for SaaS feature development

Agent Roster and Responsibilities
- Planner/Orchestrator: defines tasks, sequencing, success criteria, and handoff points.
- Implementer Agents: draft code, integrate services, and implement features.
- Researcher: gather specs, docs, and data sources.
- Reviewer: unit/integration tests, security reviews, and quality gates.
- Domain Specialist: ensures domain constraints and regulatory compliance.

Supervisor or Orchestrator Behavior
- Maintain a single source of truth: decisions, inputs, and outputs are recorded in the AGENTS.md and linked artifacts.
- Enforce memory rules: relevant context is retained; outdated context is purged when superseded.
- Orchestrator coordinates planning, execution, validation, and handoffs with deterministic prompts.

Handoff Rules Between Agents
- Planner → Implementer: deliver defined tasks, acceptance criteria, and required inputs.
- Implementer → Reviewer: present completed code with tests and evidence of validation.
- Reviewer → Planner: request changes or approval decisions as needed.

Context, Memory, and Source-of-Truth Rules
- Context: limited to the current sprint or feature scope.
- Memory: store decisions and rationale in a shared knowledge store; do not rely on ephemeral chat history.
- Source of Truth: Git commits, CI/CD results, issue tracker, and design docs.

Tool Access and Permission Rules
- Access only to allowed tools and environments.
- Secrets are retrieved from a secure vault; never hard-code.
- All API calls are logged with request IDs and outcomes.

Architecture Rules
- Follow a layered architecture: UI -> API -> Services -> Data layer.
- Services wrap external APIs with adapters and error handling.
- Use feature flags for risky changes.

File Structure Rules
- Place code in apps/feature-name with clear module boundaries.
- Keep infrastructure as code under infra/ and configs/ for environment-specific settings.
- Tests under tests/ matching the feature scope.

Data, API, or Integration Rules
- All external calls must be auditable and retry-safe.
- Use stable API contracts; version endpoints and schemas.
- Validate all inputs and outputs with formal schemas.

Validation Rules
- Unit tests: 100% coverage for new code paths.
- Integration tests: verify end-to-end flows.
- Acceptance criteria: defined in a separate docs/acceptance.md.

Security Rules
- Encrypt secrets in transit and at rest.
- Run security scans in CI.
- Principle of least privilege for tokens and roles.

Testing Rules
- Automated tests must pass before deployment.
- Include regression tests for previous bugs.

Deployment Rules
- Deploy to staging first; require green status before production.
- Rollback plan with clear rollback steps.

Human Review and Escalation Rules
- All critical changes require human approval.
- Escalate failures to engineering manager and product owner.

Failure Handling and Rollback Rules
- If tests fail, halt deployment and revert to previous stable version.
- Maintain a changelog and release notes.

Things Agents Must Not Do
- Do not bypass test gates or skip reviews.
- Do not access production data in non-prod environments.
- Do not introduce breaking changes without feature flags.

Recommended Agent Operating Model

Roles and decision boundaries: Planner designs the roadmap with strict handoffs; Implementers execute within agreed acceptance criteria; Reviewers validate with tests and security checks; Researchers gather required data; Domain Specialists ensure compliance and domain accuracy. Escalation to the Orchestrator for blockers or resource constraints. All actions are traced to the AGENTS.md template and linked work artifacts.

Recommended Project Structure

apps/
  frontend/
  backend/
  services/
  agents/
  workflows/
infra/
configs/
tests/
docs/

Core Operating Principles

• Single source of truth for decisions and rationale.
• Deterministic prompts and outputs with explicit inputs/outputs.
• Strict handoffs with agreed acceptance criteria.
• End-to-end traceability from planning to deployment.
• Least privilege for tool access and secrets management.

Agent Handoff and Collaboration Rules

Planner coordinates with Implementer for task delivery, then passes to Reviewer, who validates and returns issues to Planner or Implementer. Researchers and Domain Specialists provide domain data and constraints at any stage. Use explicit, shareable prompts for each handoff and keep a live decision log.

Tool Governance and Permission Rules

• Commands: only allowed within allocated bots/environments.
• File edits: only in designated modules with review required.
• API calls: restricted to approved endpoints with rate limits and auditable logs.
• Secrets: stored in vault; never hard-coded.
• Production systems: changes require multi-person approvals and feature flags.

Code Construction Rules

• Follow the project’s style guides and typing requirements.
• Write idempotent functions and clear unit tests for new code paths.
• Document API contracts and data models in a central docs repo.
• Do not bypass tests or commit without passing CI.

Security and Production Rules

• Encrypt data in transit and at rest; rotate keys regularly.
• Restrict access via IAM roles and use least-privilege permissions.
• Implement robust input validation and rate-limiting for APIs.
• Monitor production artifacts and alert on anomalies.

Testing Checklist

• Unit tests cover new modules and edge cases.
• Integration tests verify cross-service interactions.
• End-to-end tests simulate real user flows.
• CI must pass with code quality gates before merge.

Common Mistakes to Avoid

• Skipping reviews or bypassing test gates.
• Drifting from the defined AGENTS.md template and handoff rules.
• Untracked memory/context leading to inconsistent decisions.

FAQ

What is AGENTS.md Template used for in a full-stack SaaS build?

This AGENTS.md Template defines the operating context for a full-stack SaaS build that uses AI coding agents, covering planning, execution, handoffs, and governance for single-agent and multi-agent workflows.

How does multi-agent orchestration work with this template?

The template specifies roles (Planner, Implementer, Reviewer, Researcher, Domain Specialist) and clear handoff points. Orchestrator coordinates prompts, memory, and artifacts to ensure end-to-end traceability and auditable decisions across agents.

Where should memory and source-of-truth be stored?

Memory and decisions should be stored in a shared knowledge store and linked back to central artifacts (AGENTS.md, design docs, and Git/CI results) to prevent drift.

How are handoffs enforced between planner, implementer, and reviewer?

Handoffs occur at defined acceptance criteria and are triggered by the orchestrator. Each handoff includes inputs, outputs, success criteria, and evidence (tests, logs, and artifacts).

What are the security and deployment constraints?

Secrets live in a vault; deployments require feature flags and multi-person approvals. Production changes are gated, auditable, and monitored for security events.