Kappa Architecture AGENTS.md Template

Overview

Direct answer: This AGENTS.md Template defines a Kappa architecture agent workflow with a single streaming path and a multi-agent orchestration layer. It codifies roles, memory, handoffs, tool governance, validation, and escalation so both single-agent and multi-agent runs are production-ready.

The Kappa design pattern processes all data as a stream of events, uses an append-only log for source of truth, and relies on idempotent processors. This template provides a project-level operating context for AI coding agents to work in concert, with clear policy on context, memory, and tool access.

When to Use This AGENTS.md Template

• When implementing a streaming-first data pipeline using a Kappa architecture pattern (no separate batch layer).
• When you need a repeatable operating manual for both single-agent workflows and multi-agent orchestration across events, processors, and domain specialists.
• When you require explicit governance around tool access, secrets, deployments, and escalation paths in production.
• When you must document agent handoffs between planner, implementer, reviewer, tester, and domain-specific agents.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Kappa Streaming Platform Design Lead

Agent roster and responsibilities:
- Planner: designs end-to-end orchestration for event-driven flows, ensures idempotency, and defines topic routing.
- Implementer: builds stream processors, connectors to the event store, and real-time enrichment pipelines.
- Domain Specialist: provides domain-specific event schemas, validation rules, and semantics for key events.
- Reviewer: audits processor logic, data contracts, and adherence to governance rules.
- Tester: validates end-to-end streaming behavior, fault-injection, and performance under load.
- SRE: ensures deployment, monitoring, and incident response for production streams.
- Data Engineer: maintains topic schemas, schema registry, and data quality checks.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates the planner, implementers, and reviewers. It injects new tasks, tracks progress, and enforces rules and memory scope. It surfaces escalation when risk thresholds are exceeded.

Handoff rules between agents:
- Planner → Implementer: handoff plan, data contracts, and processor dependencies.
- Implementer → Reviewer: deliver implementation artifacts and testable code; await feedback.
- Reviewer → Tester: approve test plans and data validation rules.
- Domain Specialist (as needed) → any: align schemas and semantics before implementation.
- If an agent detects a blocking issue, it escalates to the Orchestrator, which triggers a human review if needed.

Context, memory, and source-of-truth rules:
- Context is the current event schema, topic definitions, and configuration. Memory persists only within the current execution window or within structured checkpoints. Source of truth is the event store (append-only log), schema registry, and CI/CD artifacts.
- All decisions must reference the latest event schemas and runtime configuration. Cache invalidation and memory resets require explicit update events.

Tool access and permission rules:
- Tools: Git repository, CI/CD pipeline, Secrets Manager, Event Store, Monitoring dashboards, and a code execution sandbox. Access is restricted by role-based permissions and audited.
- Do not disclose secrets in logs or to non-authorized agents. Use vaults or secrets managers; rotate credentials regularly.

Architecture rules:
- Kappa architecture: a single processing layer over streaming data; no separate batch layer. All state changes are event-based and append-only.
- Idempotent processors, deterministic routing, and replayable pipelines.
- All external effects must be captured as events for traceability.

File structure rules:
- Root: kappa-architecture/
  - orchestrator/
  - planner/
  - implementer/
  - domain-specialist/
  - reviewer/
  - tester/
  - sRE/
  - configs/
  - docs/

Data, API, or integration rules when relevant:
- Use a versioned event schema; emit and consume events with topic names that include environment and version.
- All API calls should be expressed as events or idempotent requests with correlation IDs.

Validation rules:
- Validate event schemas, message formats, and end-to-end data quality before deployment.
- Regression tests must cover replay scenarios and idempotency guarantees.

Security rules:
- Secrets are never embedded in code; use a secrets manager and access controls. Encrypt data in transit and at rest.
- Production credentials are restricted to CI/CD and runtime environments with least privilege.

Testing rules:
- Unit tests for each processor, integration tests for topic pipelines, and end-to-end tests that include failure/recovery scenarios.
- Include chaos testing and simulated outages.

Deployment rules:
- Use canary or blue-green rollout for processor updates; verify event correctness before promoting to production.
- Rollback by replaying events to a known good checkpoint and revalidating downstream processors.

Human review and escalation rules:
- Any decision affecting production data schemas, routing, or security must be reviewed by a human lead when risk is high.
- If automated checks fail, escalate to the engineering manager and incident response.

Failure handling and rollback rules:
- On failure, replay input events from the last checkpoint; emit compensating events if necessary; notify the Orchestrator.
- Maintain an audit trail of all changes and rollback actions.

Things Agents must not do:
- Do not bypass tests or skip validation gates.
- Do not mutate shared memory across runs; do not perform production changes without approval.
- Do not access production dashboards or secrets outside approved, role-based contexts.

Recommended Agent Operating Model

The recommended model assigns clearly scoped roles with decision boundaries and explicit escalation paths. The Planner defines the orchestration contract; Implementers deliver processors against that contract; Domain Specialists maintain schemas and semantics; Reviewers validate correctness; Testers ensure reliability; SRE ensures production readiness and incident response. Escalations move up to the Orchestrator and, if needed, to human stakeholders when risk thresholds are crossed.

Recommended Project Structure

kappa-architecture/
  orchestrator/
  planner/
  implementer/
  domain-specialist/
  reviewer/
  tester/
  sre/
  configs/
  docs/

Core Operating Principles

• Single source of truth is the event store and schema registry.
• All changes are event-driven and replayable.
• Idempotent and deterministic processing with controlled side effects.
• Explicit, documented handoffs and escalation paths.
• Strong versioning for schemas, topics, and deployments.
• Security by default with least privilege and secrets management.

Agent Handoff and Collaboration Rules

• Planner passes plan, schemas, and routing contracts to Implementer with a defined deadline.
• Implementer delivers code, tests, and deployment artifacts to Reviewer.
• Reviewer validates against schemas, data contracts, and tests; approves or requests changes.
• Domain Specialist confirms domain semantics and event payload integrity at key boundaries.
• Tester executes end-to-end tests and reports results to Orchestrator.
• Orchestrator resolves cross-role blockers and triggers human review if needed.

Tool Governance and Permission Rules

• Code changes require PR review and CI checks; secrets are accessed via vaults, not in code.
• Production changes require approver sign-off and a documented rollback plan.
• All external service calls are audited with correlation IDs.
• Monitoring and alerting must be enabled for all processors with defined SLAs.

Code Construction Rules

• Write modular, testable processors with clear interfaces to event topics.
• Document data contracts and include schema validation at the edge.
• Avoid tight coupling to specific environment names; support environment parameterization.
• Ensure idempotency by using deterministic keys and upsert semantics where possible.
• Include comprehensive unit and integration tests; tests must cover replay scenarios.

Security and Production Rules

• Never embed secrets in code; store in a secure secrets manager.
• Limit access to production resources by role and require audit trails for changes.
• Encrypt data in transit and at rest; use TLS everywhere; rotate credentials regularly.
• Implement robust incident response and postmortem processes.

Testing Checklist

• Unit tests for all processors with deterministic inputs.
• Integration tests that simulate event flows across topics.
• End-to-end tests including failure and recovery paths.
• Performance tests under peak streaming load.
• Canary deployments with rollback capability.

Common Mistakes to Avoid

• Assuming batch semantics exist in a Kappa design; rely on streaming primitives only.
• Overloading the Orchestrator with too many simultaneous handoffs without clear SLAs.
• Exposing secrets or credentials in logs or code.
• Skipping schema evolution discipline and not versioning events.
• Neglecting end-to-end testing of replay and fault tolerance.

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 Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is the purpose of this AGENTS.md Template for Kappa architecture?

This AGENTS.md Template provides a complete operating manual for a Kappa architecture design, detailing agent roles, handoffs, tool governance, and security for single-agent and multi-agent workflows.

How many agents are typically required for Kappa orchestration?

In production scenarios, a minimal set includes Planner, Implementer, Reviewer, Tester, Domain Specialist, and SRE, with possible Domain Sub-specialists as needed.

How are handoffs managed between planner and implementer?

The Planner delivers a formal plan, data contracts, and topic routing; the Implementer delivers working code, tests, and deployment artifacts; escalations occur if deadlines or quality gates are missed.

What about memory and source-of-truth in this workflow?

Context comes from the latest schemas and configuration; memory is scoped to the current execution window and checkpointed where appropriate; the source of truth is the event store and schema registry.

How is security enforced in production deployments?

Secrets are stored in a vault, access is role-based, and production changes require approvals with a clear rollback plan and audit logging.