AGENTS.md Template for Container Orchestration Design

Overview

The AGENTS.md Template for Container Orchestration Design defines a formal operating manual for AI coding agents involved in container orchestration workflows. It supports both single-agent operation and multi-agent orchestration by codifying roles, handoffs, memory, source-of-truth, tool governance, and security constraints.

When to Use This AGENTS.md Template

• Design and govern AI-driven container orchestration workflows (Kubernetes, Docker-based pipelines).
• Establish clear handoffs between planner, implementer, reviewer, tester, researcher, and domain specialists.
• Enforce tool governance, secrets handling, and production change controls.
• Adopt a GitOps approach to deployment and artifact management.

Copyable AGENTS.md Template

# AGENTS.md

Project: Container orchestration design for AI coding agents managing containerized workloads across a Kubernetes cluster. Establishes operating norms for single-agent and multi-agent orchestration.

Agent roster and responsibilities:
- Planner: defines goals, scope, constraints; creates the orchestration plan.
- Orchestrator: coordinates tasks across agents, enforces rules, maintains memory/state, and triggers handoffs.
- Implementer: translates the plan into Kubernetes manifests, automation scripts, and Helm charts.
- Researcher: gathers standards, references, threat models, and best-practices for container security and networking.
- Reviewer: validates changes against standards, performs PR reviews, and ensures alignment with architecture.
- Tester: runs unit, integration, and deployment tests in staging; reports results.
- Domain Specialist (Container Security): applies security policies, network segmentation, and secret handling.

Supervisor or orchestrator behavior:
- The Orchestrator maintains a single source of truth for current goals and constraints. It orchestrates work by assigning tasks, validating progress, and triggering handoffs when criteria are met.
- It enforces constraints (resource limits, security policies, and compliance rules) and surfaces blockers to human review when needed.

Handoff rules between agents:
1) Planner & Orchestrator deliver a validated plan to Implementer.
2) Implementer produces manifests and scripts and submits for Review.
3) Reviewer approves or requests changes.
4) Tester runs tests and reports findings; if green, Orchestrator merges to staging; else loops back to Implementer.
5) Domain Specialist validates security and least-privilege policies; final sign-off by Orchestrator before production deployment.

Context, memory, and source-of-truth rules:
- Primary source-of-truth: Git repository containing manifests, Helm charts, and automation scripts.
- Cluster state is observed via the Kubernetes API and stored as read-only references in the plan history.
- Memory is derived from commit messages, PR discussions, and documented decision logs in the repository.

Tool access and permission rules:
- Allowed tools: kubectl, helm, docker, git, and CI/CD commands invoked by the Orchestrator. Secrets are retrieved from a vault and never embedded in code.
- Agents operate under least-privilege service accounts; production changes require human approval via the Orchestrator.

Architecture rules:
- Containers are composed into immutable images with explicit tags; deployments are managed via manifests with resource requests/limits, probes, and autoscaling where appropriate.
- Networking follows namespace isolation and network policy controls; sidecars used for logging, tracing, and security.
- Infrastructure as code object definitions are versioned and auditable.

File structure rules:
- manifests/: Kubernetes manifests and Helm charts
- configs/: environment-specific configurations
- scripts/: automation scripts used by agents
- docs/: design decisions and rationale
- tests/: unit and integration tests for deployment workflows

Data, API, or integration rules:
- All API calls to Kubernetes or cloud services are performed via approved clients with role-based access control.
- Secrets are never logged; use environment shortcuts to inject secrets at runtime.

Validation rules:
- YAML manifests must pass yamllint and kubeval against the target cluster schema.
- Resource requests/limits, readiness/liveness probes, and image scan results must be verified before deployment.

Security rules:
- Enforce least privilege, rotate credentials, and restrict cross-namespace access.
- Secrets management with a vault; avoid embedding credentials in code or manifests.

Testing rules:
- Unit tests for scripts, integration tests for manifests, and end-to-end tests in staging.
- Rollout tests simulate failure scenarios and validate rollback procedures.

Deployment rules:
- Follow GitOps: pull requests trigger CI, then automatic deployment to staging; production requires explicit approval.
- Tags must be immutable; avoid using the latest tag in production images.

Human review and escalation rules:
- Any deviation from policy or failure in tests escalates to a human reviewer or SRE.
- If production risk is detected, pause deployment and rollback if necessary.

Failure handling and rollback rules:
- If deployment fails, roll back to the previous stable manifest; preserve a goldens image and a rollback plan.
- Record failure reasons and remediation steps in the decision log.

Things Agents must not do:
- Do not bypass approvals or secret-handling policies.
- Do not mutate production secrets in code or artifacts.
- Do not perform unsupervised production changes without orchestration sign-off.

Recommended Agent Operating Model

The recommended operating model assigns clear decision boundaries and escalation paths. The Planner defines goals and constraints; the Orchestrator enforces constraints and assigns work; Implementers produce the artifacts; Reviewers verify adherence; Testers validate outcomes; Domain Specialists ensure security and compliance. In multi-agent orchestration, the Orchestrator coordinates handoffs, maintains shared context, and ensures that state transitions occur with traceable provenance. Escalation paths route risk to a human reviewer or SRE when policy or safety thresholds are breached.

Recommended Project Structure

project-root/
  /agents
    /planner
    /orchestrator
    /implementer
    /researcher
    /tester
    /domain-security
  /manifests
  /configs
  /scripts
  /docs
  /tests
  /examples

Core Operating Principles

• Single source of truth for plan and manifests; immutable history of changes.
• Idempotent actions and repeatable deployments.
• Least privilege and secure handling of secrets.
• Clear handoffs with defined artifacts exchanged between agents.
• Human-in-the-loop for production-critical changes and risk management.
• Auditable decision logs and traceable provenance.

Agent Handoff and Collaboration Rules

• Planner & Orchestrator to Implementer: deliver goals, constraints, and initial artifact templates.
• Implementer to Reviewer: submit manifests and scripts via PR with changes annotated.
• Reviewer to Tester: approve changes for staging tests; return with feedback.
• Tester to Orchestrator: tests green or escalate failure with remediation plan.
• Domain Specialist collaborates with all roles on security-related changes and policy enforcement.

Tool Governance and Permission Rules

• Only approved tools may modify manifests or deploy to environments.
• Secrets must be sourced from a vault and never embedded in code or logs.
• Production changes require orchestrator sign-off and, if applicable, human approval gates.
• All actions are auditable and associated with a specific agent and timestamp.

Code Construction Rules

• Use versioned container images; pin exact tags and avoid latest in production.
• Define resource requests/limits, probes, and autoscaling where appropriate.
• Templates must be idempotent and refer to a stable configuration source.
• All scripts should be idempotent, deterministic, and well-logged.
• Follow consistent formatting and validation for YAML and Helm manifests.

Security and Production Rules

• Enforce namespace isolation, RBAC, and network policies for all workloads.
• Rotate credentials, use short-lived tokens, and store secrets in a vault.
• Require approval for production rollouts; implement a safe rollback path.
• Audit all changes; maintain an immutable decision log for production decisions.

Testing Checklist

• Unit tests for scripts and utilities.
• Integration tests for manifests against a staging cluster.
• End-to-end tests for GitOps deployment flows.
• Security and compliance checks for each release.

Common Mistakes to Avoid

• Drift between manifests and cluster state without a traceable path to reconciliation.
• Skipping security reviews or secrets management steps.
• Over-authorizing agents or bypassing approval gates.
• Using mutable tags or ephemeral resources without rollback planning.

Related implementation resources: AI Use Case for Rental Applications and Document Checks 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 for Container Orchestration Design?

It provides a reusable, copyable operating manual that codifies roles, handoffs, governance, and security for AI coding agents managing container orchestration workflows.

Who should use this AGENTS.md Template?

Engineering leaders, platform teams, and developers implementing or overseeing container orchestration workflows with AI agents.

How do handoffs work in multi-agent orchestration?

Plan is created by Planner, handed to Implementer to generate artifacts, reviewed by Reviewer, tested by Tester, and finally deployed after Domain Specialist validation.

What are the security considerations?

Secrets must be managed in a vault, access must be least-privilege, and production rollout requires approved changes and traceable provenance.

How is validation performed?

Through YAML/YAML-based schema validation, kubeval or similar tooling, and staged deployment tests with rollback capability.