AGENTS.md Template for Prompt Versioning Systems

Overview

AGENTS.md template for prompt versioning systems provides a formal operating manual to govern the lifecycle of prompts used by AI coding agents. It supports both single-agent scenarios and multi-agent orchestration where a Planner delegates work to Executors, Reviewers, and Domain Specialists, with a Version Guard auditing changes. This template also yields a clear source of truth and auditable handoffs in multi-agent workflows. Direct answer: This template gives you a complete, paste-ready operating manual for prompt versioning and agent governance.

When to Use This AGENTS.md Template

When you need versioned prompts and a traceable prompt history for audits
When orchestrating multiple AI agents that rely on consistent prompt formats
When you require defined handoff rules and escalation paths
When tool access, secrets, and production boundaries must be governed
When you want a copyable template you can paste into a repo immediately

Copyable AGENTS.md Template

# AGENTS.md

Project role: Orchestrator and version controller for prompt lifecycles
Agent roster and responsibilities:
- Planner: defines and versions prompts, coordinates work across agents
- VersionGuard: validates new prompt versions against criteria
- Executor: executes tasks using current, approved prompts
- Reviewer: reviews outputs and prompt fidelity
- Researcher: gathers data to improve prompts
- Domain Specialist: provides domain-accurate knowledge for prompts

Supervisor or orchestrator behavior:
- Central planner assigns work and enforces version gates
- Orchestrator maintains the canonical history and memory

Handoff rules between agents:
- Planner > Executor: provide versioned prompt and task context
- Executor > Reviewer: present results and evidence
- Reviewer > Researcher: request data to refine prompts
- Domain Specialist > Planner: update on domain-specific constraints

Context, memory, and source-of-truth rules:
- Memory store is the canonical source of truth for prompts and results
- All results are logged with version identifiers and timestamps

Tool access and permission rules:
- Executors may call only approved tools
- Secrets and API keys must be retrieved from a vault at runtime

Architecture rules:
- All prompts live under prompts/v{version}/prompts.yaml
- The orchestrator config is orchestrator.yaml in the root

File structure rules:
- prompts/v1/, prompts/v2/, etc
- orchestrator/
- tests/
- docs/

Data, API, or integration rules:
- Use stable schemas for prompts.json and prompts history

Validation rules:
- New versions must pass syntax and semantic checks
- Outputs must include traceable evidence

Security rules:
- Never print secret keys
- Rotate credentials regularly

Testing rules:
- Unit tests for version formatting
- Integration tests for multi-agent collaboration

Deployment rules:
- CI runs unit and integration tests before merge

Human review and escalation rules:
- Any failed validation triggers a human review queue

Failure handling and rollback rules:
- Roll back to last working version if a critical failure occurs

Things Agents must not do:
- Do not bypass the version gate
- Do not modify history without proper approval
# End AGENTS.md

Recommended Agent Operating Model

The recommended operating model assigns clear roles with decision boundaries and escalation paths for prompt versioning workflows. The Planner defines strategy and versions, the VersionGuard enforces gates, the Executor runs tasks with the current prompt, the Reviewer validates outputs, the Researcher improves prompts, and the Domain Specialist ensures domain fidelity. Escalation paths route anomalies to human review when needed.

Recommended Project Structure

ai-prompt-versioning/
├── prompts/
│   └── v1/
│       └── prompts.yaml
├── orchestrator/
│   ├── planner.py
│   ├── version_guard.py
│   ├── executor.py
│   ├── reviewer.py
│   └── researcher.py
├── tests/
│   ├── unit/
│   └── integration/
├── docs/
└── config/

Core Operating Principles

Versioned prompts with canonical history and audit trail
Clear handoffs and memory propagation between agents
Strict tool governance and secret management
Single source of truth for prompts and results
Deterministic, testable workflows

Agent Handoff and Collaboration Rules

Planner to Executor: transfer versioned prompt, task context, and success criteria. Executor to Reviewer: provide outputs with evidence and logs. Reviewer to Researcher: request data to refine prompts. Domain Specialist to Planner: supply domain constraints and edge cases. All handoffs include version identifiers and traceable metadata.

Tool Governance and Permission Rules

Only approved tools may be invoked by agents
Secrets retrieved from a vault; never hard-coded
API calls require explicit approvals and rate limits
Production tools require gating and rollback capabilities

Code Construction Rules

Write modular, testable units with versioned inputs
Prefer declarative configuration over hard-coded logic
Validate prompts against schema before deployment

Security and Production Rules

Secrets management and access control
Audit logging for all prompt changes and deployments
Immutable prompts in production unless approved

Testing Checklist

Unit tests for version formatting and validation
Integration tests for multi-agent collaboration
End-to-end tests of a minimal prompt version cycle
Security and access control tests

Common Mistakes to Avoid

Skipping version gates or bypassing the memory store
Unclear handoffs leading to context drift
Storing secrets in code or logs
Overly brittle prompts that break across agents

FAQ

What is the purpose of this AGENTS.md Template for prompt versioning systems?

It provides a copyable operating manual to govern versioned prompts, multi-agent orchestration, handoffs, and governance for AI coding agents.

How should agent handoffs be executed in this workflow?

Handoffs follow a planned sequence: Planner -> Executor -> Reviewer -> Researcher, with clear memory/context transfer and a single source of truth.

How is memory and source-of-truth managed?

Prompts, prompts history, and results reside in a versioned memory store under prompts/vX, with a canonical outputs log and an audit trail.

What about security and secrets within prompt versioning?

Secrets are injected via secure vaults; avoid printing tokens; access controlled by role-based permissions and short-lived credentials.

How do you validate prompts and versions in multi-agent runs?

Validation includes syntax checks, context freshness, tests for outputs, and automated checks before deployment.

Target User

Use Cases