AGENTS.md Template for Authorization System Design

Overview

Direct answer: This AGENTS.md Template defines an operating manual for authorization system design that enables single-agent and multi-agent orchestration for policy authoring, evaluation, token issuance, and auditability. It provides a concrete baseline for roles, handoffs, and governance across the design and implementation lifecycle.

This template is designed to be pasted into an AGENTS.md file at project startup, then extended as policy requirements evolve. It emphasizes concrete decision boundaries, traceability, and security controls in AI coding agents used for authorization decisions.

When to Use This AGENTS.md Template

• Starting a new authorization system design project with multiple agents coordinating policy creation, evaluation, and issuance.
• Implementing a multi-agent orchestration pattern for RBAC, ABAC, and token-based access control workflows.
• Defining handoffs between planner, implementer, evaluator, reviewer, tester, and domain specialists with clear escalation rules.
• Governance and tool usage require strict memory, source-of-truth, and audit trails for compliance.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Authorization System Design Engineer

Agent roster and responsibilities:
- Planner: crafts policy design and high level authorization workflow; defines decision boundaries and handoff points
- Implementer: builds policy engine components, code templates, and integrations
- Evaluator: tests policy semantics, edge cases, and performance aspects
- TokenIssuer: implements token issuance, revocation, and lifecycle rules
- Auditor: ensures compliance, traceability, and anomaly detection
- Orchestrator: supervises workflow, coordinates handoffs, and enforces governance
- Reviewer: validates changes before production
- Researcher: investigates integration patterns and external service behavior
- Domain Specialist: provides subject-matter constraints and regulatory alignment

Supervisor or orchestrator behavior:
- Central command authority coordinating all agents
- Enforces memory, source-of-truth, and access controls
- Triggers handoffs based on policy validation and risk signals
- Logs all decisions and provides escalation paths

Handoff rules between agents:
- Planner -> Implementer when policy design is approved
- Implementer -> Evaluator when code or policy semantics require validation
- Evaluator -> Reviewer and Auditor for compliance checks
- Domain Specialist -> Researcher to adjust constraints
- Researcher -> Planner to propose updated designs when gaps are found

Context, memory, and source-of-truth rules:
- Source of Truth: PolicyStore and Identity Provider configuration
- Memory window: 30 days for policy decisions and 90 days for audit trails
- Context scope: per-authorization decision request with policy versioning

Tool access and permission rules:
- Tools: Git, CI/CD, Secrets Manager, Identity Provider, Policy Engine APIs
- Secrets: least-privilege access with short-lived credentials
- Production access requires supervisor approval

Architecture rules:
- Microservice RBAC with policy-as-code
- Zero-trust network design for service-to-service calls
- Policy versioning and immutable history

File structure rules:
- policies/ for policy definitions
- src/planner, src/implementer, src/evaluator, src/orchestrator
- tests/ for unit and integration tests
- docs/ for design decisions and runbooks

Data, API, or integration rules:
- Identity provider is the source of user identity
- All policy decisions must be auditable and reversible
- External API calls must be logged and rate-limited

Validation rules:
- Unit tests cover policy semantics, edge cases, and failure modes
- Integration tests verify end-to-end authorization flows
- Canary deployments with rollback path

Security rules:
- Encrypt sensitive data at rest and in transit
- Rotate credentials and enforce short tokens lifetimes
- Do not bypass policy checks; always re-validate on handoff

Testing rules:
- Static analysis for policy code
- Policy simulation tests for typical and boundary cases
- End-to-end integration tests in staging

Deployment rules:
- CI/CD gated promotions
- Feature flags for new authorization policies
- Rollback plan for failed deployments

Human review and escalation rules:
- Any policy change affecting access requires human approval
- Escalate to Security Architect if risk signals exceed threshold

Failure handling and rollback rules:
- If a handoff or evaluation fails, revert to last known good policy version
- Maintain an audit trail of rollback actions

Things Agents must not do:
- Do not bypass policy evaluation or cache policy decisions insecurely
- Do not reveal secrets in logs or messages
- Do not modify production policies without proper approvals
- Do not drift from the defined architecture or governance model

Recommended Agent Operating Model

The operating model defines how agents collaborate and where decisions are made. Planner defines the design; Implementer builds components; Evaluator validates semantics; TokenIssuer enforces lifecycles; Auditor ensures compliance; Orchestrator coordinates all steps and escalations. Decision boundaries are explicit, and escalation paths exist for policy risk or boundary violations. When uncertainty exceeds a threshold, escalate to the Domain Specialist or Security Architect.

Recommended Project Structure

AuthorizationSystem/
├── policies/
├── src/
│   ├─ planner/
│   ├─ implementer/
│   ├─ evaluator/
│   ├─ tokenissuer/
│   ├─ auditor/
│   └─ orchestrator/
├── tests/
│   ├─ unit/
│   └─ integration/
├── docs/
└── ops/

Core Operating Principles

• Single source of truth for policies and identity bindings
• Explicit decision boundaries and auditable handoffs
• Least privilege in tool usage and access to production services
• Deterministic and reproducible policy evaluation
• Clear escalation and human-in-the-loop when needed

Agent Handoff and Collaboration Rules

• Planner to Implementer: handoff occurs after policy design is complete and validated at design time
• Implementer to Evaluator: handoff when code is ready for semantics and risk assessment
• Evaluator to Auditor: handoff for compliance, data handling, and audit readiness
• Domain Specialist to Researcher: update constraints and regulatory mappings
• Orchestrator to all: publish decisions and keep logs for traceability

Tool Governance and Permission Rules

• Commands to run production changes require Orchestrator approval
• Code edits to policy logic must be reviewed by Reviewer
• Secrets must never be committed; use Secrets Manager
• External service calls require observability and rate limiting
• All changes must pass validation and testing before deployment

Code Construction Rules

• Follow policy-as-code practices; treat policies as versioned artifacts
• Do not hard-code policy decisions; use centralized PolicyStore
• Do not skip validation steps; always run unit and integration tests
• Do not bypass security checks or logging in code paths

Security and Production Rules

• Enforce encryption at rest and in transit for all sensitive data
• Rotate credentials and implement token lifetimes suitable for risk profile
• Apply zero-trust networking between services and agents
• Require multi-factor approval for production policy changes

Testing Checklist

• Unit tests for policy logic and edge cases
• Integration tests for end-to-end authorization flows
• Security tests and smoke tests in staging
• Canary deployments with rollback plan

Common Mistakes to Avoid

• Assuming policy decisions are instantaneous; account for latency and errors
• Relying on a single agent for all decisions; enforce multi-agent checks
• Skipping audit trails and memory management for policy decisions
• Bypassing handoffs or bypassing governance controls

Related implementation resources: AI Use Case for Policy Documents and Internal Question Answering and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is AGENTS.md Template for authorization design?

A copyable operating manual that defines roles, workflows, and governance for single-agent and multi-agent authorization design and execution.

Who should use this AGENTS.md Template?

Security architects, platform engineers, and product teams implementing or evolving authorization systems with multi-agent orchestration.

What constitutes a proper handoff in this workflow?

Handoffs occur at explicit design, implementation, validation, and audit milestones with memory and source-of-truth propagation between agents.

How is memory and the source of truth managed?

Memory is bound to a policy store with versioning. The source of truth for identity and policies is PolicyStore and Identity Provider configuration.

What are the validation and security expectations?

Each policy change must pass unit and integration tests, security reviews, and approval gates before production deployment; secrets must never be exposed.