AGENTS.md Template: Session Management Design for AI Coding Agents

Overview

Direct answer: This AGENTS.md Template defines the session management workflow for AI coding agents, enabling both single-agent execution and multi-agent orchestration with explicit handoffs, tool governance, and human review where needed.

The AGENTS.md template provides a project-level operating context that governs how session management tasks are planned, executed, and audited by a roster of agents, including a Planner, a Session Orchestrator, and domain-specific specialists. It ensures consistent memory, a single source of truth, and governance across sessions.

When to Use This AGENTS.md Template

When designing a session management workflow for AI coding agents that require controlled handoffs and governance.
When you need to manage session state, tool access, and memory across multiple agents.
When you require formal escalation, review, and rollback procedures.
When compliance and security controls are essential.

Copyable AGENTS.md Template

Note: The template below is copyable. Copy exactly as shown to the AGENTS.md file in your project.

# AGENTS.md

Project Role: Session Management Design Lead
Agent roster:
- Planner: defines the plan to manage session lifecycle
- Orchestrator: coordinates agent actions and handoffs
- Implementer: executes coding tasks within session constraints
- AuthAgent: enforces authentication and authorization
- SessionStoreAgent: maintains session state and memory
- ValidatorAgent: validates data shapes and policy compliance
- ReviewerAgent: reviews outputs before finalization
- Researcher: gathers context and external references
Supervisor/Orchestrator: Session Management Orchestrator, ensures policy adherence and coordinated handoffs
Handoff Rules:
- Planner -> Orchestrator: provide the plan, constraints, success criteria
- Orchestrator -> Implementer: assign tasks with context
- Implementer -> Validator/Reviewer: output verification and review
- Researcher -> Planner: supply new context and references
Context, memory, source of truth:
- Context: SessionDesignContext.json, in-agent memory with expiration
- Memory: ephemeral per-session state; avoid leakage; purge on completion
- Source of Truth: Central Session Store (SessionDB) and authoritative APIs
Tool access and permissions:
- Tools: CLI, REST APIs, database connections
- Secrets: Vault/Secret Manager; never hardcode
- Permissions: least privilege per agent; no direct production writes unless approved
Architecture rules:
- Centralized session orchestrator with pluggable agents
- Stateless implementers; state stored in SessionStoreAgent
- Clear boundaries between planning, execution, and validation
File structure rules:
- Place templates and configs under sessions/ and agents/ directories
- Do not store secrets in code
Data, API, or integration rules:
- Session data must follow SessionSchema v1
- All API calls should be logged and traceable
- Use idempotent operations where possible
Validation rules:
- Contract tests for message formats
- Validation of session state transitions
- Sanity checks for memory cleanup
Security rules:
- All secrets encrypted at rest and in transit
- Access controls and audit trails
- PII handling in compliance with policy
Testing rules:
- Unit tests for each agent
- Integration tests for end-to-end session lifecycle
- End-to-end tests that simulate failure scenarios
Deployment rules:
- CI/CD with canary deployment for session-related services
- Production monitoring and alerting
Human review and escalation:
- Escalate policy violations to security lead
- Human-in-the-loop review for high-risk decisions
Failure handling and rollback:
- Retry with backoff; exponential delay
- Rollback to last known-good session state
Things Agents must not do:
- Do not bypass security or approval gates
- Do not mutate shared session state without consent
- Do not expose secrets in logs
- Do not ignore failures without reporting

Recommended Agent Operating Model

The operating model defines clear roles, decision boundaries, and escalation paths. The Planner creates the plan with constraints; the Orchestrator coordinates actions and handoffs; the Implementer executes tasks within policy; the AuthAgent and SessionStoreAgent enforce security and memory; the ValidatorAgent and ReviewerAgent ensure outputs meet quality and policy standards; the Researcher supplies necessary context. Handoffs are governed by explicit protocols and require human review for high-risk outcomes when needed.

Recommended Project Structure

sessions/           # Session management context and policies
  configs/
  data/
agents/             # Agent implementations and roles
  planner/
  orchestrator/
  implementer/
  auth_agent/
  session_store_agent/
  validator_agent/
  reviewer_agent/
  researcher_agent/
tools/
tests/
docs/

Core Operating Principles

Single source of truth for session state
Deterministic, auditable agent outputs
Explicit, documented handoffs between agents
Memory boundaries and data lifecycle controls
Observability with traceable actions and logs
Security by design with least-privilege access
Human-in-the-loop for high-risk decisions

Agent Handoff and Collaboration Rules

Planner to Orchestrator: pass plan, constraints, success criteria
Orchestrator to Implementer: assign tasks with context and state
Implementer to Validator/Reviewer: provide outputs for validation
Researcher to Planner: share new context and references
Domain Specialist handoffs: escalate specialized concerns through Reviewer

Tool Governance and Permission Rules

Only authorized tools may be invoked by agents; each action is logged
Secrets are retrieved from a centralized vault; never embedded
Production changes require an approval gate and human review
API calls must be rate-limited and retry-safe

Code Construction Rules

Code must be idempotent and auditable
Session mutations must occur via approved APIs
Validation checks run before persistence
Documentation is updated with each change

Security and Production Rules

Encrypt data in transit and at rest
Enforce access controls and maintain audit trails
Mask PII and comply with data governance policies

Testing Checklist

Unit tests for each agent behavior
Integration tests for end-to-end session lifecycle
End-to-end tests including failure and rollback scenarios
Canary and rollback checks in production

Common Mistakes to Avoid

Skipping formal handoffs between planners and implementers
Bypassing security gates or secret management
Ignoring memory cleanup after session completion
Unclear decision boundaries leading to policy drift

FAQ

What is the purpose of this AGENTS.md Template for session management?

Provides a project-wide operating manual that governs how session management tasks are planned, executed, and audited by a roster of agents in both single- and multi-agent modes.

How does multi-agent orchestration manage session state?

Session state is stored in a central SessionStoreAgent with memory boundaries per-session; the Orchestrator coordinates state transitions and ensures idempotent operations.

What are the key handoff rules between Planner, Orchestrator, and Implementer?

Planner provides plan and constraints to the Orchestrator; the Orchestrator assigns tasks to Implementers with context; Implementers pass outputs to Validator/Reviewer.

How are secrets and production credentials handled in this workflow?

Secrets are stored in a Secrets Manager; agents receive ephemeral credentials; no secrets are written to logs or memory beyond session scope.

How is testing and validation performed for session management?

Provide unit tests for agents, integration tests for the end-to-end session lifecycle, and contract tests for message formats; simulate failure scenarios.

Target User

Use Cases