Presence Service Architecture AGENTS.md Template

Overview

Direct answer: This AGENTS.md template provides a comprehensive operating manual for a presence service architecture, enabling both single agent execution and multi agent orchestration with clear handoffs and governance.

It describes an agent workflow that includes a planner, implementer, reviewer, tester, researcher, and domain specialist, coordinated by a supervisor orchestrator to maintain a single source of truth and controlled tool access.

When to Use This AGENTS.md Template

• When designing a presence service that must coordinate multiple AI coding agents.
• When you need explicit handoff rules and governance between agents.
• When enforcing memory state management and auditable decisions.
• When integrating external services or data sources with strong security controls.

Copyable AGENTS.md Template

Copy the block below into your repository to define the project level operating context for presence service architecture.

# AGENTS.md

Project: Presence Service Architecture

Agent roster and responsibilities:
- Planner: define orchestration plan, task boundaries, and success criteria
- Implementer: execute tasks via AI agents and make changes to state
- Reviewer: validate outputs, ensure compliance with rules
- Tester: perform unit integration tests and trigger end to end checks
- Researcher: collect data and external signals
- Domain Specialist: provide domain specific guidance on presence semantics

Supervisor or orchestrator behavior:
- Coordinate all agents, assign tasks, enforce boundaries, and maintain a single source of truth
- Detect plan drift and replan when necessary
- Enforce memory limits and context transfer rules during handoffs

Handoff rules between agents:
- Transfer complete context including inputs, state, last decision, and evidence
- Require explicit confirmation from the next actor before actioning
- Maintain idempotency: repeatable, no unintended side effects

Context, memory, and source of truth rules:
- All decisions reference the canonical state store
- Memory caches are bounded and cleared after use
- Changes must be logged to the events log and traceable to a trusted source

Tool access and permission rules:
- Agents may access read write to the state store and to the events stream
- Secrets and production credentials must be retrieved from a secure vault and never hard coded

Architecture rules:
- Use a modular event driven architecture with clear boundaries between components
- Each agent must be stateless where possible and rely on the canonical state store

File structure rules:
- Place all agent templates config and documentation under a dedicated presence service folder
- Do not mutate shared code outside approved repositories without reviews

Data API or integration rules when relevant:
- Define strict input output schemas for all integrations
- Validate external data before use and sanitize all inputs

Validation rules:
- Every agent action must produce idempotent results and verifiable evidence
- All changes must be auditable

Security rules:
- Secrets must be retrieved at runtime from a vault
- Access controls must enforce least privilege

Testing rules:
- Include unit tests for each agent integration
- Integration tests for the presence workflow
- End to end tests for multi agent orchestration

Deployment rules:
- Trigger deployments via CI CD with staged approvals
- Rollback to a known good state on failure

Human review and escalation rules:
- Escalate anomalies to a human reviewer and provide a complete evidence trail
- Allow revert option and rollback to prior state if required

Failure handling and rollback rules:
- Graceful degradation and state rollback on failures
- Do not continue with partial updates that leave the system in an inconsistent state

Things Agents must not do:
- Do not access secrets directly in code
- Do not bypass orchestrator handoffs
- Do not operate in production without approvals

Recommended Agent Operating Model

Roles and decision boundaries: Planner designs orchestration with strict task boundaries; Implementer acts within those boundaries; Reviewer verifies; Tester validates; Researcher feeds data; Domain Specialist provides domain constraints. Escalation paths: if a critical check fails, escalate to human review and halt further automation until approved.

Recommended Project Structure

presence-service/
├── orchestrator/
│   └── orchestrator.md
├── agents/
│   ├── planner/
│   │   └── planner.md
│   ├── implementer/
│   ├── reviewer/
│   ├── tester/
│   ├── researcher/
│   └── domain/
├── state/
│   └── presence_state.json
├── detectors/
│   └── presence_detector.py
├── events/
│   └── presence_events.json
├── policies/
│   └── governance.md
└── tests/
    ├── unit/
    ├── integration/
    └── e2e/

Core Operating Principles

• Single source of truth for presence state
• Explicit, auditable agent handoffs
• Idempotent agent actions
• End to end observability and tracing
• Deterministic decision bounds
• Security by default and least privilege

Agent Handoff and Collaboration Rules

• Planner to Implementer handoffs include task inputs state and success criteria
• Implementer to Reviewer handoffs include outputs rationale and validation evidence
• Researcher provides data to Implementer with clear provenance
• Domain Specialist approves domain sensitive decisions before execution
• All handoffs require a confirmation signal from the receiving agent

Tool Governance and Permission Rules

• Commands to state store or services require authorization tokens from vaults
• Files edits must be tracked and require review
• APIs require rate limits retries and input validation
• Secrets must never be logged or exposed
• Production changes require double checked approvals

Code Construction Rules

• Use defined data models and schemas for all inputs outputs
• All code must be linted and typed
• Agent actions must be idempotent and replayable
• State mutations must go through the orchestrator and event log
• Include unit tests for each agent

Security and Production Rules

• Store secrets in a vault never in code
• Audit trails for all state changes
• Use TLS rotate credentials and enforce least privilege
• Disable automated production changes without approvals

Testing Checklist

• Unit tests for all agents
• Integration tests for the presence workflow
• End to end tests of multi agent orchestration
• Security and access tests

Common Mistakes to Avoid

• Skip handoffs or mutate state outside orchestrator
• Overload agents with non deterministic actions
• Expose secrets in logs or artifacts
• Ignore edge cases in presence semantics

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Policy Documents and Internal Question Answering.

FAQ

What is the purpose of this AGENTS.md Template for Presence Service Architecture?

It defines a repeatable, auditable operating manual for AI coding agents handling presence service workloads, including multi-agent orchestration, handoffs, memory and source of truth, tool governance, and human review.

Who is the intended audience for this AGENTS.md Template?

Developers, product teams, engineering leaders, and AI operators building presence services with AI coding agents.

How do agents handle handoffs in presence service orchestration?

Handoffs are triggered by the orchestrator based on task boundaries, with explicit context transferred and freshness checks to avoid context drift.

What security and governance rules apply to the presence service AGENTS.md Template?

Hardened access, secrets management, auditable changes, and enforced approvals for production changes.

How should I validate and test the presence service workflow with this template?

Follow unit, integration, and end-to-end tests, plus manual reviews for edge cases and performance under load.