AGENTS.md Template for Event Streaming Platform Design

Overview

Direct answer: This AGENTS.md Template defines the event streaming platform design operating model, enabling both single-agent execution and multi-agent orchestration across producers, processors, and consumers with clear handoffs and governance.

This AGENTS.md template provides a copyable project-level operating context for AI coding agents acting as event-streaming specialists. It codifies roles, memory, source-of-truth, tool access, and architecture constraints to ensure consistent, auditable decisions across single-agent and multi-agent workflows.

When to Use This AGENTS.md Template

• When designing an end-to-end event streaming platform (producers, topics, schemas, processors, sinks) and you want a codified agent operating model.
• When you require coordinated multi-agent orchestration with explicit handoffs and escalation paths.
• When you need governance around tool access, secrets, production changes, and policy compliance.
• When you want a reusable, copyable template to anchor project-level agent behavior for streaming pipelines.

Copyable AGENTS.md Template

# AGENTS.md

Project: Event Streaming Platform Design
Role: Architecting an end-to-end streaming data pipeline with producer -> topic -> stream processor -> sink

Agent roster and responsibilities:
- Planner: designs streaming topology, data contracts, and topic schemas.
- Implementer: builds producers, processors, and consumers according to specs.
- Orchestrator: coordinates agent work, retries, and lifecycle of tasks.
- Reviewer: validates architecture decisions, code quality, and security controls.
- Tester: runs end-to-end tests, data quality checks, and performance tests.
- Researcher: gathers best practices, benchmarks, and references.
- Domain Specialist: ensures compliance, security, and domain-specific requirements.

Supervisor / Orchestrator behavior:
- Maintains plan, decision log, and versioned design artifacts.
- Issues prompts, assigns tasks, and tracks progress.
- Enforces handoffs rules and escalation paths.

Handoff rules between agents:
- Planner -> Implementer: provides topology, data contracts, and required schemas.
- Implementer -> Tester: delivers runnable pipelines and test data.
- Tester -> Reviewer: presents test results and remediation tasks.
- Researcher / Domain Specialist -> Planner: feeds design constraints and policy requirements.
- If issues arise, Orchestrator routes to Domain Specialist for decision.

Context, memory, and source-of-truth rules:
- All decisions and artifacts are stored in the project memory store (design.md, contracts.json, runbooks).
- Source of truth: data contracts, topic schemas, and security policies; accessed via read-only tooling when possible.

Tool access and permission rules:
- Agents may invoke: git, CI/CD pipelines, Kafka/Kafka-like tooling, schema registry, monitoring dashboards.
- Secrets must never be logged; use vault/repo secret stores.
- Production changes require explicit approvals and audit trails.

Architecture rules:
- Use a producer -> topic -> processor -> sink pattern with idempotent processors.
- Define exactly-once or at-least-once semantics per topic.
- Enforce schema versioning and backward compatibility.

File structure rules:
- Keep a single repository with folders: planners/, implementers/, testers/, reviewers/, researchers/, domain-specialists/, orchestrator/, pipelines/, configs/, docs/.
- No unrelated tech debt files or deprecated artifacts.

Data, API, or integration rules:
- Use data contracts for message schemas; schemas registered in a central registry.
- APIs should be versioned and authenticated; avoid breaking changes mid-flight.

Validation rules:
- End-to-end tests must pass before deployment; data quality checks must pass with defined SLAs.
- Validation logs saved for audit.

Security rules:
- Apply least privilege and rotate credentials; secrets never appear in code or logs.
- Access to production topics is restricted to approved agents only.

Testing rules:
- Include unit tests for producers/processors/consumers; integration tests for end-to-end pipelines.
- Run tests in CI before merges; performance tests for throughput and latency.

Deployment rules:
- Use canary or blue/green deployments for changes to streaming topology.
- Rollback plan and incident response documented.

Human review and escalation rules:
- All design changes require domain specialist sign-off and reviewer confirmation.
- Human in the loop for security or compliance triggers.

Failure handling and rollback rules:
- If a deployment fails, revert to last stable version and re-run tests.
- Keep failed messages in a quarantine area for analysis.

Things Agents must not do:
- Do not bypass approvals or push production changes without oversight.
- Do not leak credentials or sensitive data in logs or outputs.
- Do not ignore schema changes or data contracts.

Recommended Agent Operating Model

The recommended operating model defines clear roles and boundaries for planners, implementers, testers, reviewers, and domain specialists. Decision points are auditable, and escalation paths are explicit. In multi-agent orchestration, the Orchestrator enforces handoffs, tracks progress, and ensures alignment with data contracts and security policies.

Recommended Project Structure

event-streaming-platform/
├── planners/
├── implementers/
├── testers/
├── reviewers/
├── researchers/
├── domain-specialists/
├── orchestrator/
├── pipelines/
├── configs/
├── docs/
└── tests/

Core Operating Principles

• Single source of truth for data contracts and topic schemas.
• Explicit, logged handoffs between agents and a defined escalation path.
• Least privilege for tool access with auditable traces.
• Idempotent design and clear rollback procedures.
• Continuous validation through end-to-end and performance tests.

Agent Handoff and Collaboration Rules

• Planner to Implementer: share topology, contracts, and schemas.
• Implementer to Tester: provide runnable pipelines and test data.
• Tester to Reviewer: present results and remediation tasks.
• Researcher/Domain Specialist to Planner: provide constraints and policies.
• Orchestrator: enforce the flow and escalate blockers to appropriate roles.

Tool Governance and Permission Rules

• CI/CD, code repos, and streaming clusters require authenticated access with audit trails.
• Secrets must be stored securely; never logged or committed.
• Production changes require approvals and change records.

Code Construction Rules

• Follow project-specific conventions for producers, processors, and consumers.
• Use idempotent operations and well-defined error handling.
• Validate data contracts against the registry before deployment.

Security and Production Rules

• Enforce least privilege, rotation of credentials, and encrypted transport.
• Separate staging vs. production environments; monitor for anomalies.

Testing Checklist

• Unit tests for each component; integration tests for end-to-end pipelines.
• Data quality checks and schema compatibility tests.
• Performance tests for throughput and latency under load.
• Publish and rollback tests in CI/CD.

Common Mistakes to Avoid

• Skipping canonical data contracts or ignoring schema evolution.
• Bypassing approvals or introducing changes directly in production.
• Neglecting memory/context persistence across agent runs.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is this AGENTS.md Template used for in event streaming platform design?

This AGENTS.md Template codifies the operating model, handoffs, and governance for single- or multi-agent execution of event streaming pipelines (producers, processors, consumers, and orchestrators).

How does multi-agent orchestration apply to event streaming pipelines?

It coordinates specialized agents to design, implement, test, and validate streaming topology, data contracts, and processing logic with clear handoffs and shared memory.

What are the agent handoff rules?

Handoffs are explicit: Planner -> Implementer; Implementer -> Tester; Tester -> Reviewer; Researcher/Domain Specialist provide constraints to Planner; Orchestrator enforces escalation when blockers occur.

What safety and security rules govern access to streaming systems?

Secrets are stored in vaults, access is least-privilege, production changes require approvals, and no secrets appear in code or logs.

How is memory and source-of-truth managed?

Decisions and artifacts are stored in a shared memory store (design docs, contracts, runbooks). The source of truth is canonical data contracts, topic schemas, and policy documents.