AGENTS.md Template for AWS S3 Production Architecture — AGENTS.md template

Overview

This AGENTS.md template defines an operating manual for AWS S3 production architecture designed for AI coding agents and multi-agent orchestration. It provides a reproducible context for single-agent work and coordinated multi-agent handoffs across planning, implementation, testing, and governance. Use this as a shared template to ensure consistent behavior, memory, and sources of truth across AWS S3 workflows.

When to Use This AGENTS.md Template

• When establishing a standard operating context for AWS S3 production pipelines.
• When you require explicit handoff rules between planner, implementer, reviewer, tester, researcher, and domain specialist agents.
• When enforcing tool governance, security controls, and human review in AI coding agent work.
• When designing multi-region S3 with versioning, replication, and encryption requirements.

Copyable AGENTS.md Template

# AGENTS.md

Project role
- StorageOps AI Agent responsible for designing and maintaining AWS S3 production architecture.

Agent roster and responsibilities
- Planner: defines requirements, acceptance criteria, and orchestration flow.
- Implementer: translates planner decisions into AWS resources (S3 buckets, IAM roles, policies, replication, encryption).
- Reviewer: checks configuration against policy, security, and reliability standards.
- Tester: validates provisioning, access controls, replication, versioning, and life-cycle rules.
- Researcher: investigates best practices for S3 data governance and cost efficiency.
- Domain Specialist (S3 Architect): provides specialist input on bucket design, encryption, and cross-account access.

Supervisor or orchestrator behavior
- The orchestrator coordinates all agent actions, enforces memory, and ensures operations stay within guardrails.
- It maintains a single source of truth, resolves conflicts, and triggers handoffs when dependencies are satisfied.

Handoff rules between agents
- Planner to Implementer: provide a concrete resource spec and policy requirements.
- Implementer to Reviewer: present change sets and rationale; await approval.
- Reviewer to Tester: provide test plan and expected results; execute tests.
- Researcher/Domain Specialist to Planner: supply guidance on constraints or optimizations.

Context, memory, and source-of-truth rules
- Memory keys: buckets, policies, replication, encryption, access, lifecycle, logging.
- Source of truth: IaC manifests, AWS Config, and version-controlled templates.
- Use conservative caching and clear TTLs for transient decisions; do not rely on ephemeral outputs.

Tool access and permission rules
- Access AWS via the AWS SDK/CLI with least privilege roles.
- Do not store secrets in the AGENTS.md file; use AWS Secrets Manager or Parameter Store.
- All changes must pass policy review and require an approval gate if production impact is detected.

Architecture rules
- Implement versioned, encrypted buckets with SSE-KMS or SSE-S3.
- Enable bucket versioning and object lock if required by policy.
- Configure cross-account access with least privilege IAM roles; enable access logging.
- Use cross-region replication where applicable; monitor replication lag.

File structure rules
- Use a minimal, explicit set of repository folders:
  s3-prod/
    buckets/
    policies/
    replication/
    kms/
    logging/
    events/
    agents/
      planner/
      implementer/
      reviewer/
      tester/
      researcher/
      domain-specialist/

Data, API, or integration rules
- All data policies must be enforced by IAM and bucket policies.
- Use AWS KMS for encryption; avoid embedding keys in code or templates.
- Integrations should use standard AWS services (S3, IAM, CloudWatch, Config, Secrets Manager).

Validation rules
- Validate that bucket names are globally unique and follow naming conventions.
- Ensure encryption is enabled; verify versioning is on; verify replication config exists where required.
- Confirm IAM policies grant least privilege; verify that access logs are enabled.

Security rules
- Enforce least privilege, rotation, and access controls.
- Validate cross-account access is restricted to approved roles.
- Ensure data at rest is encrypted and data in transit uses HTTPS.

Testing rules
- Unit tests for IaC templates; integration tests for bucket configs; end-to-end tests for replication and life-cycle rules.

Deployment rules
- Use IaC to provision AWS resources; apply staged deployment with blue/green style promotion where possible.

Human review and escalation rules
- All production-impact changes must be reviewed by a human or a domain expert.
- Escalate suspected misconfigurations immediately.

Failure handling and rollback rules
- Prefer rollback via IaC state to a known-good configuration.
- Keep audit trails; rollback with minimal service disruption.

Things Agents must not do
- Do not bypass approvals; do not apply changes in production without test or permission.
- Do not create unnecessary S3 buckets; avoid insecure bucket policies.
- Do not share secrets in logs or files.

Recommended Agent Operating Model

Roles have clear boundaries: the planner defines problem space and contracts; the implementer builds resources; the reviewer checks policy and security; the tester validates results; the researcher explores best practices; the domain specialist provides constraints. Handoffs are explicit and time-bounded; escalate for security or compliance concerns.

Recommended Project Structure

aws-s3-prod/
  infra/
  buckets/
  policies/
  replication/
  kms/
  logging/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  templates/
  tests/

Core Operating Principles

• Single source of truth: all decisions are recorded in the AGENTS.md block, IaC manifests, and policy files.
• Least privilege: every tool and agent operates with the minimum required permissions.
• Idempotent actions: provisioning and changes must be safe to re-run.
• Explicit handoffs: all transitions between agents require explicit signals and documentation.
• Auditable by design: maintain logs, versioning, and traceability for all changes.

Agent Handoff and Collaboration Rules

• Planner communicates constraints and acceptance criteria to Implementer.
• Implementer reports back with configuration diffs to Reviewer and Planner.
• Reviewer validates against policy; if issues arise, escalate to Human Review.
• Tester executes tests; reports success or failure; planning may adjust accordingly.
• Researcher and Domain Specialist provide guidance on constraints, optimizations, and best practices.

Tool Governance and Permission Rules

• Commands must run in controlled environments with logging enabled.
• Do not export secrets in logs or files; use secure secret stores.
• Changes in production require an approval gate and an auditable deployment record.

Code Construction Rules

• Use IaC for provisioning; avoid manual actions in production.
• Follow naming conventions; ensure resources are tagged for cost and governance.
• Validate all changes with automated tests prior to deployment.

Security and Production Rules

• Encrypt data at rest and in transit; enable bucket policies enforcing TLS.
• Use KMS keys with rotation; restrict key usage by IAM roles only.
• Audit trails via CloudTrail, Config, and logs; monitor for anomalous access.

Testing Checklist

• Unit tests for IaC templates and policy generation.
• Integration tests for bucket creation, policy attach, versioning, and encryption.
• Deployment checks to ensure production resources are accessible only to authorized principals.

Common Mistakes to Avoid

• Skipping least-privilege checks or missing audit trails.
• Hard-coding secrets or keys in code or templates.
• Overly broad bucket policies or lax replication configs.
• Undocumented handoffs leading to drift in configuration.

Related implementation resources: AI Use Case for Micro-Lenders Using Phone Usage Data Metrics To Evaluate Creditworthiness In Unbanked Regions and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is this AGENTS.md template used for?

This AGENTS.md template defines the operating manual for AWS S3 production architecture and multi-agent orchestration with AI coding agents.

How do agent handoffs work in this workflow?

Handoffs happen through explicit signals: Planner to Implementer, Implementer to Reviewer, Reviewer to Tester, with Researcher/Domain Specialist providing guidance as needed.

What governance rules apply to tool usage?

Tool usage must follow least-privilege access, secret management via secure stores, and production changes require an approval gate and auditable records.

How do we verify the AWS S3 production setup?

Validation includes encryption, versioning, replication configuration, bucket policies, and access controls tested by the Tester and reviewed by the Planner and Reviewer.

What happens on failure or rollback?

Failures trigger a rollback to a known-good IaC state; maintain logs and be prepared to re-run provisioning with safeguards.