AGENTS.md Template for Cloud Security Posture Reviews

Overview

Direct answer: This AGENTS.md Template defines a project level operating manual for cloud security posture reviews that enables AI coding agents to operate both as single agents and in multi agent orchestration patterns. It specifies roles, memory, sources of truth, tool governance and escalation paths.

What this template governs: a cloud security posture review workflow that coordinates data collection, evidence gathering, policy evaluation, remediation planning, and auditor handoffs across a planner, scanner, policy enforcer, evidence collector, and reviewer. It ensures a single source of truth and repeatable handoffs for human review.

When to Use This AGENTS.md Template

When planning a cloud security posture review for a multi account or multi cloud environment
When you need a reproducible, audit friendly workflow with clear handoffs
When you require tool governance and strict access controls
When you want to ensure evidence backed remediation decisions
When you need a documented, repeatable learning loop for AI coding agents

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Cloud Security Posture Review Lead Orchestrator
Agent roster and responsibilities:
- Planner: defines scope, timeline, and success criteria
- Scanner: runs cloud posture checks across accounts and regions
- PolicyEnforcer: translates findings into enforceable policies
- EvidenceCollector: gathers logs, findings, and screenshots as evidence
- Reviewer: validates outputs and signs off
- Auditor: performs independent checks and archival
Supervisor or orchestrator behavior:
- Orchestrator coordinates all agents, stores memory in a central workspace, and enforces source-of-truth
- All agent outputs converge to a canonical data store
Handoff rules between agents:
- Planner to Scanner: share scope and data requirements
- Scanner to PolicyEnforcer: provide structured findings and evidence
- PolicyEnforcer to EvidenceCollector: generate remediation artifacts and policy references
- EvidenceCollector to Reviewer: present evidence and remediation status
- Reviewer to Auditor: approve for archival
Context, memory, and source-of-truth rules:
- Central workspace acts as the source of truth
- Memory is append-only and versioned; outputs are timestamped
- All data sources and outputs are traceable to cloud provider APIs
Tool access and permission rules:
- Access only through approved cloud accounts and secret vaults
- Tools: cloud config, cloud trail, inventory APIs, security hub
- Do not store credentials in code or logs
Architecture rules:
- Orchestrator pattern with modular agents
- Stateless agents with shared memory in the workspace
File structure rules:
- agents/planner/
- agents/scanner/
- agents/policy_enforcer/
- agents/evidence_collector/
- agents/reviewer/
- agents/auditor/
- workflows/cloud_posture_reviews/
- data/posture_findings/
- logs/
Data, API, or integration rules when relevant:
- All findings must originate from cloud provider APIs or approved scanners
- Output formats are JSON compatible and stored in data/posture_findings
- Remediation actions are policy based and auditable
Validation rules:
- Each output must be validated against a schema and include evidence references
- Remediation suggestions must have measurable success criteria
Security rules:
- Do not print secrets or credentials
- Rotate access keys regularly and use secret vaults
- Encrypt sensitive artifacts in transit and at rest
Testing rules:
- Unit tests for each agent
- Integration tests across planner, scanner and enforcer
- End to end tests with audit log verification
Deployment rules:
- Deploy to production only after security review and approval
- Versioned releases with rollback capability
Human review and escalation rules:
- All critical findings require human review and sign off before remediation
- Escalate to security leadership if policy conflicts arise
Failure handling and rollback rules:
- If a remediation is rolled back, revert related findings and reset state
- Maintain an immutable audit trail
Things Agents must not do:
- Do not modify production resources without approval
- Do not bypass tool governance or secret management
- Do not redact evidence from audits

Recommended Agent Operating Model

The orchestrator role coordinates planning, execution and validation. The planner decides scope; the scanner gathers posture data; the policy enforcer converts findings into policies; evidence collector secures audit trails; the reviewer validates and signs off; the auditor confirms archival. Decision boundaries are strictly documented, with escalation paths to human review when confidence is below threshold.

Recommended Project Structure

projects/cloud_posture_reviews/
  planners/
  scanners/
  policy_enforcers/
  evidence_collectors/
  reviewers/
  auditors/
  workflows/
  data/
  logs/
  README.md

Core Operating Principles

Operate with a single source of truth and immutable memory
Separate planning, execution, validation, and archival concerns
Ensure evidence backed decisions and auditable trails
Enforce tool governance and access controls
Human review required for high risk or policy conflicts

Agent Handoff and Collaboration Rules

Planner hands off to Scanner with defined scope
Scanner hands off to PolicyEnforcer with structured findings
PolicyEnforcer hands off to EvidenceCollector with remediation artifacts
EvidenceCollector hands off to Reviewer with evidence bundle
Reviewer may escalate to Auditor

Tool Governance and Permission Rules

All tool calls require authorization and logging
Secrets stored in a vault; never in code
Remediation actions require policy gates
Production changes require human sign-off

Code Construction Rules

Code blocks must be readable and reproducible
Outputs must be deterministic given the input and state
Do not hard code secrets

Security and Production Rules

Zero trust access to cloud resources
Audit trails for all actions
Regular secret rotation and key management

Testing Checklist

Unit tests for each agent
Integration tests for handoffs
End to end tests including audit logs
Security and permission tests

Common Mistakes to Avoid

Skipping human review for critical findings
Bypassing tool governance or secret management
Unclear handoffs leading to state drift

FAQ

What is the purpose of this AGENTS.md Template for cloud security posture reviews?

It provides a copyable operating manual for cloud posture reviews that supports both single agent and multi-agent orchestration.

Who should use this template?

Developers, security engineers, cloud architects, and product teams implementing cloud posture reviews.

What are the default agent roles in the workflow?

Planner, Scanner, PolicyEnforcer, EvidenceCollector, Reviewer, Auditor and a supervising orchestrator.

How are handoffs governed between agents?

Handoffs are defined in the AGENTS.md and require structured outputs, evidence and clear ownership before passing to the next agent.

What constitutes a valid remediation in this workflow?

Remediation must be policy based, evidenced and auditable with measurable success criteria.

Target User

Use Cases