AGENTS.md Template for SSR and SSG Architecture

Overview

Direct answer: This AGENTS.md template governs the SSR and SSG agent workflow, enabling single-agent and multi-agent orchestration with clear roles, handoffs, and governance for AI coding agents.

What this template provides: a project-level operating context for how SSR and SSG tasks are planned, executed, and reviewed by a roster of agents, including supervisor handoffs and human-in-the-loop checks.

When to Use This AGENTS.md Template

• Standardize SSR-first architectures that require dynamic rendering during requests (SSR) and pre-rendered pages (SSG).
• Coordinate multiple agents for content rendering, data fetching, template compilation, and deployment gating.
• Enforce tool governance, secrets handling, and security reviews in AI-driven rendering pipelines.
• Provide a single source of truth for handoffs, memory context, and source-of-truth rules across agents.

Copyable AGENTS.md Template

# AGENTS.md

# Project: SSR and SSG Architecture - Agent Operating Manual

Project role: You are the SSR/SSG orchestration core, coordinating planning, execution, validation, and deployment for dynamic rendering and pre-rendered pages using AI coding agents.

Agent roster:
- Planner: designs the rendering pipeline, determines SSR vs SSG usage, and defines success criteria.
- Implementer(s): generate code, fetch data, render templates, and wire up APIs.
- Researcher: sources data schemas, API specs, and site data contracts.
- Reviewer: checks accuracy, security, and performance implications; approves changes.
- Tester: runs unit/integration tests, page builds, and visual regressions.
- Domain Specialist: ensures SEO, accessibility, and content correctness for target domains.
- Supervisor/Orchestrator: coordinates handoffs, enforces memory rules, and maintains source of truth.

Handoff rules:
- Planner -> Implementer: provide scope, data contracts, and rendering plan.
- Implementer -> Reviewer: deliver code changes, data fetches, and build outputs for review.
- Reviewer -> Implementer: provide fixes and re-run tests.
- Tester -> Domain Specialist: confirm SEO and content quality before deployment.
- Domain Specialist -> Supervisor: escalate issues that require architectural changes or policy updates.

Context, memory, and source of truth:
- Memory: retain data contracts, API schemas, and last validated outputs for each page.
- Source of Truth: data contracts, API specs, and rendering rules; never rely on ad-hoc in-memory guesses.
- Context: keep per-page rendering context in memory with IDs and timestamps.

Tool access and permission rules:
- Access: only read/write to permitted repos and environments; secrets are accessed through secure vaults.
- API calls: allowed for data fetch per data contracts; rate limits and retries enforced.
- Permissions: least privilege; no production deploys without approval.

Architecture rules:
- Use SSR when content must be fresh per-request; use SSG for performance where content can be pre-rendered.
- Centralized orchestrator enforces order and timeouts.
- All decisions must be traceable to a plan document and data contracts.

File structure rules:
- /src/planner
- /src/orchestrator
- /src/ai-skills/agents-md-templates/ssr
- /src/ai-skills/agents-md-templates/ssg
- /src/utils
- /tests
- /docs

Data, API, and integration rules:
- Data contracts define required fields and types.
- All API calls must have retry and timeout policies.
- Secrets never embedded in code.

Validation rules:
- Each render must pass data contract validation and performance budgets.
- Build must succeed; tests must pass; pages must render within SLA.

Security rules:
- Secrets stored securely; access audited.
- Input validation and output escaping everywhere.
- No privileged operations in rendering workflows without review.

Testing rules:
- Unit tests for data fetchers; integration tests for page rendering; visual regression checks.
- CI gates block merges that fail tests.

Deployment rules:
- Deploy to staging before production; require sign-off for production deploys.

Human review and escalation rules:
- All critical changes require peer review and security sign-off.
- If a failure occurs in production, rollback to previous build and notify stewards.

Failure handling and rollback rules:
- If a page render fails, return a safe placeholder; log error details; trigger alert.
- Rollback by re-deploying last known good build within SLA.

Things Agents must not do:
- Do not bypass data contracts or skip reviews.
- Do not access non-permitted environments; do not modify production systems without approval.
- Do not mutate memory outside approved contexts.

Recommended Agent Operating Model

The OSS-driven model assigns clear decision boundaries and escalation paths. Planner defines strategy and constraints; Implementers execute within those constraints; Reviewers verify correctness and safety; Testers validate functionality; Domain Specialists ensure domain-appropriate quality; Supervisors coordinate handoffs and memory governance. When disagreement arises, escalate to the Supervisor and document a decision log.

Recommended Project Structure

project-root/
  src/
    planner/
    orchestrator/
    agents/
      ssr/
      ssg/
    data-contracts/
    api-clients/
  tests/
  docs/
  ci/
  deployment/

Core Operating Principles

• Single source of truth for data contracts and rendering rules.
• Least privilege and auditable actions for all agents.
• Traceable decisions with plan-docs and versioned outputs.
• Clear handoff boundaries with explicit inputs/outputs.
• Secure handling of secrets and production gates.

Agent Handoff and Collaboration Rules

Handoff guidance for planning, implementing, reviewing, testing, researching, and domain-specific work.

• Planner to Implementer: provide scope, data contracts, and rendering plan.
• Implementer to Reviewer: deliver code changes, data fetches, and build outputs for review.
• Reviewer to Implementer: provide fixes and re-run tests.
• Tester to Domain Specialist: confirm SEO and accessibility before deployment.
• Domain Specialist to Supervisor: escalate policy or architectural changes.

Tool Governance and Permission Rules

• Command execution limited to permitted tools and environments.
• File edits tracked; PRs required for changes; secrets managed securely.
• Production calls require approvals; external services accessed via approved connectors.

Code Construction Rules

• Follow SSR/SSG best practices; ensure idempotent renders; cache invalidation rules explicit.
• All data fetching respects contracts; validate inputs; sanitize outputs.

Security and Production Rules

• Protect secrets; rotate credentials; monitor for anomalous access.
• Input validation, output escaping, and CSP basics in rendered pages.
• Deploys must pass security review and access control checks.

Testing Checklist

• Unit tests for data fetchers and renderers.
• Integration tests for rendering paths and API integrations.
• End-to-end tests in staging; visual regression checks.

Common Mistakes to Avoid

• Skipping data contracts or reinterpreting memory outside approved rules.
• Overlapping responsibilities across agents leading to race conditions.
• Bypassing reviews or hiding secrets in code.

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

FAQ

What is an AGENTS.md Template?

A copyable operating manual for AI coding agents that governs a specific workflow, including SSR/SSG orchestration, planning, handoffs, and governance.

Who should use this SSR/SSG AGENTS.md Template?

Engineering teams implementing SSR/SSG pipelines with AI agents and multi-agent coordination.

What does the Planner do in this template?

Planner designs the rendering strategy, defines data contracts, and outlines decision boundaries for agents and orchestrators.

How are handoffs enforced?

Handoffs have inputs, outputs, and timing; transitions require review of prior outputs and memory state.

Where should changes be tested and reviewed?

In staging or dedicated review environments with security and performance checks before production.

Can this template be adapted to other workflows?

Yes. Replace SSR/SSG specifics with your workflow; keep roles, memory, and data contracts consistent.