AGENTS.md Template: Multiplayer Editing Systems

Overview

This AGENTS.md Template provides a concrete operating manual for AI coding agents to coordinate in a real-time, multi-user multiplayer editing system. It defines both single-agent and multi-agent orchestration, with explicit agent handoffs, governance, and human review touchpoints to keep the collaboration safe and auditable.

When to Use This AGENTS.md Template

• When building a collaborative editor where multiple agents and humans concurrently modify shared documents.
• When you need a repeatable operating model with a clear source of truth, decision boundaries, and escalation paths.
• When you require explicit handoffs between planners, editors, conflict resolvers, reviewers, and auditors.

Copyable AGENTS.md Template

Below is a complete AGENTS.md block you can paste into your project to establish the operating context for both single-agent and multi-agent multiplayer editing work.

# AGENTS.md

Project Role
- Lead Engineer for multiplayer editing systems. Responsible for defining the source of truth, orchestration rules, and safety rails for all agents.

Agent roster and responsibilities
- Planner (Orchestrator): assigns tasks, sequences work, enforces priorities and deadlines.
- EditorAgent: applies edits to the document with competing inputs while preserving integrity.
- ConflictResolver: detects and resolves edit conflicts using OT/CRDT strategies and user-defined policies.
- SyncAgent: ensures real-time propagation of changes to all participants with causality tracking.
- AccessControlAgent: enforces permissions, scope, and revocation during editing sessions.
- AuditAgent: records actions, revisions, and approvals for traceability.
- ReviewerAgent: conducts human-in-the-loop validation before changes enter production or become final.
- TesterAgent: runs unit and integration tests against edits and edge cases.
- DataIngestAgent: fetches required external data or templates needed for edits.

Supervisor or orchestrator behavior
- The Planner coordinates a single source of truth and maintains a revision history. It assigns tasks to EditorAgent(s) and triggers ConflictResolver when conflicts arise. All actions are logged and auditable.

Handoff rules between agents
- Planner -> EditorAgent: pass the edit task with context and constraints.
- EditorAgent -> ConflictResolver (if conflict detected): provide conflicting changes and user intent.
- ConflictResolver -> EditorAgent: deliver resolved edits and rationale.
- EditorAgent -> ReviewerAgent: present changes for validation.
- ReviewerAgent -> TesterAgent: validate behavior with test cases.
- TesterAgent -> Auditor/Planner: confirm pass/fail and log outcomes.

Context, memory, and source-of-truth rules
- The DocumentStore is the single source of truth. All edits are versioned and referenced by revision IDs.
- Short-term memory is scoped to the current editing session; long-term memory is stored as revision history and audit logs.
- Tools use explicit read/write APIs; secrets never leak into memory.

Tool access and permission rules
- Editors may call edit APIs with write scope only on active documents in session.
- ConflictResolver can query diffs and propose resolutions but cannot delete history without Planner approval.
- AuditAgent has read access to all revisions and write access to audit logs only.
- AccessControlAgent enforces least privilege and revocation on session end.

Architecture rules
- All agents run as stateless workers with a centralized planner and shared document store.
- Edits flow through a strict, auditable pipeline: plan, edit, resolve conflicts, validate, review, test, approve, deploy.

File structure rules
- All agent modules live under a dedicated multiplayer-editing/ai-skills/agents-md-templates/ directory. No direct edits to the source of truth outside approved agents.

Data, API, or integration rules
- Use documented APIs to fetch document content, user intents, and permission state.
- All external data is validated against schemas before use.

Validation rules
- Every edit must pass schema validation, OT/CRDT integrity checks, and domain-specific constraints.
- All changes require approval before merging to the final revision.

Security rules
- Encrypt data in transit and at rest; rotate secrets regularly; use role-based access control.

Testing rules
- Unit tests for each agent, integration tests for cross-agent flows, and end-to-end tests for real-time sessions.

Deployment rules
- Deploy changes to staging; run canary tests; promote after passing checks. Maintain rollback points to last known good revision.

Human review and escalation rules
- Escalate any unresolved conflicts to human editors after a defined threshold; require human approval for risky or breaking changes.

Failure handling and rollback rules
- On failure, revert to the last good revision and replay edits with added guards. Log incident details for postmortem.

Things Agents must not do
- Do not bypass approvals or mutate the source of truth outside approved channels. Do not perform unsupervised production changes. Do not ignore schema validations.

Recommended Agent Operating Model

Roles are bounded with clear decision rights. The Planner orchestrates, Editors implement, ConflictResolver mediates, Reviewer validates, and Auditor ensures traceability. Escalation paths exist for conflicts and failed validations. Outputs are deterministic and auditable, with human review invoked for risky changes.

Recommended Project Structure

multiplayer-editing/
  docs/
  infra/
  tests/
  ai/
    agents/
      editor_agent/
        main.py
      conflict_resolver/
        main.py
      sync_agent/
        main.py
      access_control_agent/
        main.py
      audit_agent/
        main.py
      reviewer_agent/
        main.py
      tester_agent/
        main.py
      data_ingest_agent/
        main.py
    orchestrator/
      planner.py
    schemas/
      document_schema.json
  services/
    document_service/
    auth_service/

Core Operating Principles

• Single source of truth for documents and revisions.
• Idempotent agent actions with deterministic outcomes.
• Explicit handoffs with auditable traces.
• Least-privilege access and strong secrets management.
• Human review gates for risky changes.
• Fail-safe rollback and rollback-point preservation.

Agent Handoff and Collaboration Rules

• Planner defines tasks with explicit constraints and success criteria.
• EditorAgent applies edits while preserving intent and history.
• ConflictResolver mediates only when conflicts exist; proposes resolutions with rationale.
• Reviewer and Tester validate correctness before final approval.
• Auditor logs all handoffs, decisions, and outcomes for compliance.

Tool Governance and Permission Rules

• APIs: read/write access limited to active documents in session.
• Secrets: stored securely, rotated, never embedded in code.
• Production changes require planner-approved gates and audit sign-off.
• Disallow direct edits to the source of truth outside the orchestrated pipeline.

Code Construction Rules

• Write modular, testable agent code with explicit input/output contracts.
• Do not hard-code IDs or credentials; use environment-scoped secrets.
• All edits validated against the schema before apply.
• Version all changes; maintain a replayable edit history.

Security and Production Rules

• Enforce end-to-end encryption; store secrets in a vault.
• Audit logs immutable and tamper-evident.
• Deploy via canary; require human approval for production promotions.

Testing Checklist

• Unit tests for each agent, integration tests across agents, end-to-end tests for real-time sessions.
• Schema validation tests for edits and messages.
• Rollout tests including rollback scenarios.

Common Mistakes to Avoid

• Skipping human review for risky edits.
• Bypassing handoff protocols or the source of truth.
• Inadequate conflict resolution leading to hidden state drift.
• Over-permissive tool access and insecure secrets handling.

FAQ

What is the purpose of this AGENTS.md Template for multiplayer editing systems?

It defines a repeatable operating model for AI coding agents that collaborate on real-time, multi-user document editing, including handoffs, governance, and safety rails.

Who should operate the agents in this workflow?

A Planner orchestrates tasks, Editor Agents perform edits, ConflictResolver handles conflicts, and Reviewer and Tester verify outcomes before deployment.

How are changes validated and rolled back?

All edits run through validation checks, with a last-good-revision as a rollback point and explicit human review for risky changes.

What are the security and governance rules?

Principle of least privilege, encrypted transport, secrets management, audit logging, and formal approval gates for production changes.

How does handoff work between agents?

Handoffs follow a defined sequence: planner assigns tasks, editors implement, conflict resolver mediates if needed, reviewer tests, and auditor logs.

What should I avoid in this workflow?

Do not bypass approval gates, mutate source of truth outside approved channels, or perform unsupervised production changes.

Related implementation resources: AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages and AI Agent Use Case for Manufacturing Buyers Using Supplier Lead Time Trends To Automatically Adjust Raw Material Reorder Dates.