AGENTS.md Template: WebSocket Production Design

Overview

This AGENTS.md Template defines a production-grade WebSocket design workflow for AI coding agents. It governs both single-agent execution and multi-agent orchestration around real-time messaging, ensuring clear handoffs, tool governance, and human review gates. Answer-ready, role-driven, and shareable as project-level operating context.

When to Use This AGENTS.md Template

• Building real-time AI-enabled apps requiring WebSocket communication between clients and agents.
• Coordinating multiple AI agents (planner, implementer, tester, reviewer) around a single WebSocket session.
• Establishing strict tool access, memory, and source-of-truth rules for live messaging flows.
• Defining handoffs and escalation paths to maintain reliability and governance in production.

Copyable AGENTS.md Template

# AGENTS.md

# WebSocket Production Design - AI Coding Agents

Project role
- Orchestrator: Plan, assign tasks, validate handoffs, and monitor overall session health.
- GatewayAgent: Accepts client WebSocket connections, performs authentication, and routes messages to the internal router.
- MessageRouter: Dispatches incoming/outgoing messages to the appropriate agent(s) based on intent and domain context.
- ContextStore: Central memory and source-of-truth for per-session state, policies, and history.
- AuthService: Manages tokens, scopes, and revocation; enforces least-privilege access.
- Implementer: Executes domain-specific logic over WebSocket messages (e.g., data fetch, transform, or command execution).
- Validator/Tester: Verifies outputs against acceptance criteria and integration points.
- Researcher/Domain Specialist: Provides context, facts, and domain knowledge when needed.
- Operator: Oversees deploys, monitor dashboards, and incident response.

Supervisor or orchestrator behavior
- Maintains a live plan per session, tracks progress, and triggers handoffs.
- Enforces task boundaries, context transfer, and audit trails for every handoff.
- If a task stalls or fails, initiates escalation to Reviewer or Domain Specialist.

Handoff rules
- Handoff from Planner to Implementer must include: goals, constraints, historical messages, and a minimal reproducible artifact.
- Handoff from Implementer to Validator includes artifacts, tests, and output payloads.
- All handoffs pass a structured context object to preserve traceability.
- On failure, route back to Planner with updated context and rationale.

Context, memory, and source-of-truth rules
- All session state is stored in ContextStore with versioning and TTL.
- Context is immutable for a session; updates create a new revision.
- The single source of truth for business rules is the PolicyEngine in ContextStore.

Tool access and permission rules
- Agents may call only approved tools with per-tool scopes.
- Secrets are accessed via an external SecretsManager and never embedded in prompts.
- API calls must be logged with request IDs and audit trails.

Architecture rules
- Components: WebSocket Gateway, MessageRouter, ContextStore, AuthService, Implementer, Validator, User/Client APIs.
- All in-flight messages pass through the Gateway and Router with trace identifiers.
- Use a central event log for observability and replay safety.

File structure rules
- Only include folders relevant to WebSocket production design; do not add irrelevant tech folders.
- Example: /agents-md, /src, /tests, /config, /docs.

Data, API, or integration rules
- Handshake payloads must include session_id, client_id, and auth_token.
- Message payload must follow a defined schema: { type, id, session_id, payload }.
- All integrations must provide idempotent operations and clear error contracts.

Validation rules
- Acceptance tests verify message routing, state updates, and end-to-end flows.
- Non-functional checks: latency, throughput, and memory usage under load.

Security rules
- TLS with rotating certificates; JWT with short lifetimes.
- Secrets never in code; access controlled by RBAC.
- Production changes require review and canary deployment.

Testing rules
- Unit tests for each agent; integration tests for the WebSocket flow.
- End-to-end tests with a mock client; contract tests for payload schemas.

Deployment rules
- CI/CD with canary releases for WS gateway changes.
- Monitoring of latency, error rates, and backpressure.

Human review and escalation rules
- Human review is required for policy or security breaches.
- Escalate via incident channel if abuse or outages occur.

Failure handling and rollback rules
- On failure, replay last stable state from ContextStore and isolate faulty agent.
- Rollback to previous deployment if production risk exceeds threshold.

Things Agents must not do
- Do not bypass authentication or tool gates.
- Do not mutate global state without audit.
- Do not disclose secrets or tokens in prompts.
- Do not skip validations or skip handoffs.

Recommended Agent Operating Model

Roles and decision boundaries are aligned with a WebSocket production design workflow. The planner decides escalation paths and routing, while implementers perform per-message actions. Reviewers validate outputs, testers exercise end-to-end paths, researchers provide domain knowledge, and operators handle deployments and incident response. Handoffs are explicit, auditable, and triggered by session progress or failure signals.

Recommended Project Structure

websocket-prod-design/
├── services/
│   ├── gateway/
│   ├── router/
│   ├── auth/
│   └── context-store/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── validator/
│   ├── tester/
│   └── domain-specialist/
├── configs/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
└── docs/

Core Operating Principles

• Single source of truth for session context and policy decisions.
• Explicit, auditable handoffs with structured context payloads.
• Least-privilege access and secure secret management.
• Idempotent operations and clear error contracts.
• Continuous verification via automated tests and canary deployments.

Agent Handoff and Collaboration Rules

Planner to Implementer: pass goals, constraints, and history; Implementer to Validator: pass artifacts, tests, and output; Researcher to Domain Specialist: supply domain facts as needed; All handoffs must include trace IDs and context digests.

Tool Governance and Permission Rules

• Commands and API calls are allowed only through tools listed in the policy with defined scopes.
• Secrets are fetched from SecretsManager; never embedded in prompts or logs.
• Production systems require approval gates and audit trails for changes.

Code Construction Rules

• All WebSocket interactions must validate schemas and handle backpressure gracefully.
• Prompts must be deterministic given the same context to avoid nondeterministic behavior.
• Use typed payloads; include input validation, output contracts, and error handling in code templates.

Security and Production Rules

• Enforce TLS, JWT-based auth with short-lived tokens, and revocation checks.
• Audit trails for all state changes and message routing decisions.
• Canary deployments for changes to the gateway and router components.

Testing Checklist

• Unit tests for each agent role; integration tests for message routing.
• End-to-end tests with a mocked client and real WS gateway.
• Security tests for token verification and secret management.
• Performance tests focusing on latency and backpressure under load.

Common Mistakes to Avoid

• Overly broad tool access or bypassing handoffs.
• Unclear ownership of memory and source-of-truth data.
• Ignoring auditing on state changes or message routing decisions.

Related implementation resources: AI Agent Use Case for Manufacturing Buyers Using Supplier Lead Time Trends To Automatically Adjust Raw Material Reorder Dates and AI Agent Use Case for Custom Packaging Firms Using Structural Design Specs To Instantly Generate Production Cost Estimates.

FAQ

What is the purpose of this AGENTS.md Template for WebSocket production design?

To provide a copyable, project-level operating manual that governs AI coding agents in a WebSocket real-time workflow, including handoffs, governance, and security.

Which agent roles are defined in the template?

Planner, GatewayAgent, MessageRouter, ContextStore, AuthService, Implementer, Validator/Tester, Researcher/Domain Specialist, and Operator.

How are handoffs handled between agents?

Handoffs are explicit with structured context objects, including goals, history, and artifacts; routes are auditable with trace IDs.

What security controls are required?

TLS with rotating certificates, JWT-based auth with short lifetimes, secrets in SecretsManager, and RBAC with production approval gates.

How is testing and deployment managed?

Unit and integration tests for agents, end-to-end tests for the WS flow, canary deployments for gateway changes, and rollback plans if metrics breach thresholds.

What should agents not do?

Do not bypass authentication, bypass handoffs, store secrets in prompts or logs, or perform non-idempotent operations without traceability.