AGENTS.md TemplatesAGENTS.md Template

OpenSearch Production Architecture AGENTS.md Template

AGENTS.md Template for OpenSearch production architecture to govern multi-agent workflow, handoffs, tool governance, and human review.

AGENTS.md templateOpenSearchOpenSearch production architecturemulti-agent orchestrationagent handoff rulestool governancehuman reviewOpenSearch deploymentOpenSearch securityincident responsearchitecture governance

Target User

Developers, founders, product teams, and engineering leaders building OpenSearch production architectures with multi-agent orchestration.

Use Cases

  • OpenSearch production deployment
  • multi-agent orchestration around OpenSearch clusters
  • security governance and compliance
  • designing monitoring and DR for OpenSearch

Markdown Template

OpenSearch Production Architecture AGENTS.md Template

# AGENTS.md

Project Role: OpenSearch Production Architect

Agent roster:
- Planner: coordinates strategy, task creation, and orchestration across OpenSearch production architecture.
- Implementer: builds and configures OpenSearch clusters, indices, ingest pipelines, and security settings.
- Reviewer: validates configurations, tests performance, and ensures security posture.
- Tester: runs integration, disaster-recovery, and resilience tests.
- Researcher: collects metrics, analyzes logs, and proposes optimizations.
- Domain Specialist: focuses on governance, data residency, encryption, and compliance.

Supervisor / Orchestrator:
- Planner acts as the central orchestrator and sole author of approved changes; all handoffs go through Planner unless escalated.

Handoff rules:
- When Planner assigns work to Implementer, include complete context, required templates, and acceptance criteria.
- On completion, Implementer passes to Reviewer with a summary of changes and test results.
- If Reviewer approves, pass to Tester; if issues, loop back to Implementer with explicit fix notes.

Context, memory, and source-of-truth rules:
- All OpenSearch config lives in the repository under configs/; cluster state must be derivable from index templates, pipelines, and cluster settings in the repository.
- Memory must be explicit: every tool call, API response, and decision must be stored in a per-task log with timestamps.
- Use a single source of truth: the repository and a runbook for incident response.

Tool access and permission rules:
- Implementer and Planner have access to OpenSearch API endpoints, config repos, and deployment scripts in a limited scope.
- Secrets stored in secure vault; never log secrets.
- Production changes require approval from Domain Specialist and Reviewer; automated checks must pass before deployment.

Architecture rules:
- Follow OpenSearch best practices for cluster sizing, shard/replica distribution, and node roles.
- Prefer index templates with ILM policies and rollover; use snapshot backups.

File structure rules:
- Use a clear, versioned, and immutable file structure in the repo.
- All configuration changes must be accompanied by a PR with a description.

Data, API, or integration rules:
- All data paths must include access controls; use OpenSearch REST APIs securely.
- Use OpenSearch REST APIs with proper versioning.

Validation rules:
- Each change must pass unit tests, integration tests, and performance checks; all changes must be traceable in the PR history.

Security rules:
- Enforce role-based access control, TLS everywhere, encrypted at rest, and proper secret management.

Testing rules:
- Include unit tests for config generation, integration tests for cluster reconfiguration, and load tests for search performance.

Deployment rules:
- Changes are deployed via controlled pipelines; no manual production changes.

Human review and escalation rules:
- All changes require human review; escalate to Domain Specialist for governance items.

Failure handling and rollback rules:
- Maintain rolling back steps; ensure a safe rollback plan in the PR; test rollback in staging.

Things Agents must not do:
- Do not bypass governance; do not apply changes to production without approvals; do not perform autonomous irreversible actions without explicit confirmation.

Overview

Direct answer: This AGENTS.md template codifies the OpenSearch production architecture workflow for single-agent and multi-agent orchestration, including planning, implementation, testing, deployment, and governance. It provides explicit operating context that guides AI coding agents through design, configuration, validation, and escalation in a production OpenSearch environment.

The template defines a concrete agent roster, decision boundaries, and a single source of truth (repository and runbooks) to enable reliable cross-team collaboration. It supports both individual agent execution and multi-agent orchestration with clear handoffs, memory, and source-of-truth rules so changes are traceable and auditable.

When to Use This AGENTS.md Template

  • Designing and operating a production OpenSearch architecture (clusters, indices, ILM, security, and dashboards).
  • Coordinating multi-agent workflows for deployment, upgrades, monitoring, backups, and incident response.
  • When you need a copyable, project-level operating context that governs agent roles, tool access, and escalations.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: OpenSearch Production Architect

Agent roster:
- Planner: coordinates strategy, task creation, and orchestration across OpenSearch production architecture.
- Implementer: builds and configures OpenSearch clusters, indices, ingest pipelines, and security settings.
- Reviewer: validates configurations, tests performance, and ensures security posture.
- Tester: runs integration, disaster-recovery, and resilience tests.
- Researcher: collects metrics, analyzes logs, and proposes optimizations.
- Domain Specialist: focuses on governance, data residency, encryption, and compliance.

Supervisor / Orchestrator:
- Planner acts as the central orchestrator and sole author of approved changes; all handoffs go through Planner unless escalated.

Handoff rules:
- When Planner assigns work to Implementer, include complete context, required templates, and acceptance criteria.
- On completion, Implementer passes to Reviewer with a summary of changes and test results.
- If Reviewer approves, pass to Tester; if issues, loop back to Implementer with explicit fix notes.

Context, memory, and source-of-truth rules:
- All OpenSearch config lives in the repository under configs/; cluster state must be derivable from index templates, pipelines, and cluster settings in the repository.
- Memory must be explicit: every tool call, API response, and decision must be stored in a per-task log with timestamps.
- Use a single source of truth: the repository and a runbook for incident response.

Tool access and permission rules:
- Implementer and Planner have access to OpenSearch API endpoints, config repos, and deployment scripts in a limited scope.
- Secrets stored in secure vault; never log secrets.
- Production changes require approval from Domain Specialist and Reviewer; automated checks must pass before deployment.

Architecture rules:
- Follow OpenSearch best practices for cluster sizing, shard/replica distribution, and node roles.
- Prefer index templates with ILM policies and rollover; use snapshot backups.

File structure rules:
- Use a clear, versioned, and immutable file structure in the repo.
- All configuration changes must be accompanied by a PR with a description.

Data, API, or integration rules:
- All data paths must include access controls; use OpenSearch REST APIs securely.
- Use OpenSearch REST APIs with proper versioning.

Validation rules:
- Each change must pass unit tests, integration tests, and performance checks; all changes must be traceable in the PR history.

Security rules:
- Enforce role-based access control, TLS everywhere, encrypted at rest, and proper secret management.

Testing rules:
- Include unit tests for config generation, integration tests for cluster reconfiguration, and load tests for search performance.

Deployment rules:
- Changes are deployed via controlled pipelines; no manual production changes.

Human review and escalation rules:
- All changes require human review; escalate to Domain Specialist for governance items.

Failure handling and rollback rules:
- Maintain rolling back steps; ensure a safe rollback plan in the PR; test rollback in staging.

Things Agents must not do:
- Do not bypass governance; do not apply changes to production without approvals; do not perform autonomous irreversible actions without explicit confirmation.

Recommended Agent Operating Model

The recommended operating model defines dedicated agent roles with clear decision boundaries for OpenSearch production tasks. The Planner coordinates strategy and handoffs; Implementer executes cluster/config changes; Reviewer validates changes; Tester verifies behavior; Researcher provides data-driven insights; Domain Specialist ensures governance and compliance. Escalation paths go to Planner when issues occur, and to Domain Specialist for governance or policy concerns.

Recommended Project Structure

opensearch-prod/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── reviewer/
│   ├── tester/
│   ├── researcher/
│   └── domain-specialist/
├──_configs/
│   ├── clusters/
│   │   ├── production-cluster.yaml
│   │   └── staging-cluster.yaml
│   ├── index-templates.json
│   └── dashboards.json
├── pipelines/
│   └── ingest-pipeline.json
├── scripts/
│   ├── deploy.sh
│   └── rollback.sh
├── docs/
│   └── architecture.md
└── tests/
    ├── unit/
    └── integration/

Core Operating Principles

  • Single source of truth: all OpenSearch configuration and decisions live in a versioned repository.
  • Idempotent steps: operations can be safely re-applied without side effects.
  • Least privilege: agents run with the minimal permissions required.
  • Explicit memory: every action and decision is logged with context.
  • Observability by design: metrics, traces, and logs accompany every change.
  • Deterministic handoffs: handoffs require completion criteria and traceable artifacts.

Agent Handoff and Collaboration Rules

  • Planner to Implementer: provide task scope, templates, acceptance criteria, and expected test results.
  • Implementer to Reviewer: deliver changed config, scripts, and test logs; include rollback plan.
  • Reviewer to Tester: pass validation results and performance metrics; approve or request changes.
  • Tester to Domain Specialist if governance or compliance issues surface.
  • Researchers provide data-driven insights to Planner for future iterations.

Tool Governance and Permission Rules

  • Commands must be issued through the orchestrator; direct manipulation of production systems by agents is prohibited without approval.
  • All secrets must be retrieved from a secure vault; never persisted in logs or code.
  • OpenSearch API calls must use rate limits and access controls; avoid destructive actions without explicit approval.
  • Production deployments require dual approval: Reviewer and Domain Specialist.
  • Audit trails must capture who did what, when, and why.

Code Construction Rules

  • Use versioned OpenSearch templates and ILM policies; ensure compatibility with current cluster version.
  • Configs are generated from templates and validated by tests before merge.
  • Do not hard-code credentials; reference secrets management systems.
  • All code changes must be idempotent and traceable in PR history.

Security and Production Rules

  • Enforce TLS; mTLS between OpenSearch nodes where supported.
  • RBAC: least privilege roles for each agent role; audit role assignments.
  • Encrypted at rest for snapshots and indices; enforce backup policies.
  • Separation of duties between planning, implementation, and review.
  • Incident response runbooks must be versioned and tested in staging.

Testing Checklist

  • Unit tests for config generation scripts.
  • Integration tests for cluster reconfiguration and ILM policy deployment.
  • Performance tests for search latency and indexing throughput.
  • Disaster recovery drills in staging that simulate node failure and data loss scenarios.
  • Security checks for access controls and secret rotation.

Common Mistakes to Avoid

  • Skipping governance and pressing changes to production without approvals.
  • Unclear handoff criteria leading to incomplete context for agents.
  • Hard-coding secrets or keys in configs or code.
  • Ignoring data security and RBAC in OpenSearch configurations.
  • Overly complex pipelines that reduce observability and increase blast radius.

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

Why use an AGENTS.md Template for OpenSearch production architecture?

It provides a copyable operating manual that codifies roles, memory, handoffs, tool governance, validation, and escalation for an OpenSearch production workflow.

Who should use this template?

Engineering teams building OpenSearch production architectures that require multi-agent orchestration and governance.

What happens during an agent handoff?

The planner transfers context, acceptance criteria, and test results; the next agent accepts with a clear boundary and rollback plan.

How are secrets managed?

Secrets are stored in a secure vault and never written to logs or code; agents access them via approved interfaces.

How do you handle failures?

Follow the rollback plan, validate in staging, and escalate if governance is affected.