Authentication and Authorization AGENTS.md Template for AI Coding Agents

Overview

Direct answer: This AGENTS.md template defines an authentication and authorization agent workflow that supports both single-agent scope and multi-agent orchestration. It codifies roles, memory, handoffs, tool governance, and human review to ensure secure, auditable authn/authz behavior across systems.

The AGENTS.md template provides the project-level operating context for AI coding agents acting in authn (identity verification) and authz (policy enforcement). It ensures consistent decision boundaries, traceability, and escalation paths for secure software delivery.

When to Use This AGENTS.md Template

• You are implementing an identity-enabled workflow where multiple agents coordinate authentication checks and policy decisions.
• You require clear handoff points between a planner, an implementer, a reviewer, and a tester for authn/authz tasks.
• You need strict tool governance, secret handling, and production safeguards across the agent network.
• You want to maintain a single source of truth for identity policy, access rules, and audit trails.

Copyable AGENTS.md Template

# AGENTS.md

Project role:
- Provide a secure, auditable authn/authz workflow with multi-agent coordination and strict governance.

Agent roster and responsibilities:
- Planner: defines the authentication and authorization strategy, policy boundaries, and data sources.
- Implementer: executes policy decisions, calls identity providers, and enforces access rules.
- Reviewer: validates outputs, security posture, and policy conformance.
- Tester: runs integration tests, simulates attack vectors, and verifies end-to-end behavior.
- Researcher: collects identity provider changes, policy updates, and potential edge cases.
- Domain Specialist: advises on industry-specific access controls and regulatory requirements.

Supervisor or orchestrator behavior:
- Orchestrator maintains canonical memory, sources of truth, and enforcement gates.
- It clips outputs, routes handoffs, and enforces escalation if outputs raise risk thresholds.

Handoff rules between agents:
- Planner ➜ Implementer: share policy decisions, data sources, and acceptance criteria.
- Implementer ➜ Reviewer: present evidence, test results, and any ambiguities.
- Reviewer ➜ Tester: hand off final validation and release criteria.

Context, memory, and source-of-truth rules:
- All decisions must reference a policy document, identity provider metadata, and a versioned policy store.
- Memory includes last decision, relevant user/session identifiers, and time stamps.
- Sources of truth are authenticated and versioned; changes require a higher-scope approval.

Tool access and permission rules:
- Agents may call identity providers, policy engines, and audit services only through approved interfaces.
- Secrets are retrieved from a protected vault with scoped permissions.
- Production systems require explicit approval gates and rollback paths.

Architecture rules:
- Stateless plan-and-execute pattern with centralized audit log.
- Clear separation between identity verification, policy evaluation, and enforcement actions.

File structure rules:
- Maintain a single AUTHZ policy file, a mapping of identity providers, and a change log.

Data, API, or integration rules:
- All API calls must be authenticated, encrypted, and logged.
- Rate limits and retry policies must be defined; avoid aggressive backoffs.

Validation rules:
- Each policy decision must pass synthetic tests, functional tests, and security checks.

Security rules:
- Secrets must never be hard-coded.
- Access must be least-privilege; every action logged.

Testing rules:
- Include unit, integration, and end-to-end tests for authn/authz scenarios.

Deployment rules:
- Staged deployments with feature flags and rollback capability.

Human review and escalation rules:
- Any anomalous decision or policy drift triggers escalation to security and product owners.

Failure handling and rollback rules:
- If authentication fails or policy evaluation is inconclusive, fail close with explicit error codes and revert to last known good state.

Things Agents must not do:
- Bypass identity checks, mutate policy without approval, or perform actions outside granted scopes.

Recommended Agent Operating Model

The operating model assigns clear decision boundaries: planners design, implementers execute, reviewers authorize, testers verify, researchers monitor changes, and domain specialists advise. Escalation paths lead to security review for potential policy drift or identity provider failures.

Recommended Project Structure

project/
└── workflows/
    └── authn-authz/
        ├── agents/
        │   ├── planner/
        │   ├── implementer/
        │   ├── reviewer/
        │   ├── tester/
        │   ├── researcher/
        │   └── domain-specialist/
        └── configs/
            └── policy.yaml

Core Operating Principles

• Operate with explicit memory and sources of truth.
• Handoffs must be explicit and auditable.
• Enforce least-privilege access for all tool calls.
• Provide deterministic, testable outputs with clear failure signals.
• Escalate promptly on security or policy anomalies.

Agent Handoff and Collaboration Rules

• Planner to Implementer: share policy decisions, data sources, and acceptance criteria.
• Implementer to Reviewer: present evidence, test results, and edge cases.
• Reviewer to Tester: provide final validation criteria and release conditions.
• Researcher to Domain Specialist: communicate policy changes and regulatory updates.

Tool Governance and Permission Rules

• Only approved interfaces may be used for identity resolution and policy evaluation.
• Secrets must be retrieved from a vault with strict access control and auditing.
• Production calls require runtime approval gates and rollback options.

Code Construction Rules

• Follow versioned policy documents and policy-as-code patterns.
• Validate policy decisions with deterministic tests; avoid non-deterministic logic.
• Document all exceptions and edge cases in the policy repo.

Security and Production Rules

• Enforce TLS, certificate pinning where applicable, and encrypted at rest.
• Audit trails for all authn/authz events; access reviews monthly.
• Fail closed on ambiguous situations with explicit user-facing error messages.

Testing Checklist

• Unit tests for policy evaluation modules.
• Integration tests with identity providers and policy engines.
• End-to-end tests for common authn/authz flows.
• Security fuzzing and negative test cases.
• Deployment verification and rollback tests.

Common Mistakes to Avoid

• Assuming identity providers are always available.
• Over-privileging agents or bypassing policy checks.
• Unversioned policy changes without auditing.
• Dropping memory context between handoffs.

FAQ

What is an AGENTS.md Template for authentication and authorization agents?

A copyable operating manual that anchors single-agent and multi-agent workflows for secure authn/authz with clear roles, handoffs, tool governance, and review processes.

Who should use this AGENTS.md Template?

Engineers, platform teams, security engineers, and product leaders implementing authentication and authorization workflows with multi-agent orchestration.

How are agent handoffs defined in this template?

Handoffs are explicit: planner to implementer, implementer to reviewer, and reviewer to tester, with sources of truth and memory context preserved.

What are the security rules and permission controls?

Access controls, secret management, role-based permissions, audit logging, and production safeguards are codified and enforced through the template.

How do I validate outputs and roll back if needed?

Validation rules, test gates, and rollback procedures are defined to ensure dependable authn/authz behavior with safe failure handling.

Where can I customize this AGENTS.md Template for my project?

Yes—adapt the code block, roles, and workflow constraints to reflect your architecture, identity providers, and policy requirements.