AGENTS.md Template for Authentication Architecture

Overview

AGENTS.md template for authentication architecture governs how AI coding agents collaborate on identity verification, token issuance, session management, and policy enforcement. It provides a project-level operating context for both single-agent execution and multi-agent orchestration, including handoffs, memory, and source-of-truth rules.

When to Use This AGENTS.md Template

• When modeling authentication workflows that require clear roles, responsibilities, and escalation paths for AI agents.
• When implementing token issuance, validation, and revocation with multiple agents and governance checks.
• When integrating policy evaluation, risk assessment, and secrets management within a reproducible template.
• When you need a copyable, auditable operating manual for human reviewers and automated agents alike.
• When ensuring strict tool governance and production-readiness with defined handoffs and failure handling.

Copyable AGENTS.md Template

# AGENTS.md

Project role
- Identity and security engineer leading the authentication workflow automation and multi-agent orchestration.

Agent roster and responsibilities
- Planner: designs authentication flow strategy, data sources, security controls, and handoffs between agents.
- Implementer: builds and wires the authentication modules, calls to token services, and policy checks.
- Reviewer: ensures policy conformance, security posture, and code quality of changes.
- Tester: validates flows (token issuance, refresh, revocation) across environments.
- Researcher: brings in threat intelligence, risk signals, and compliance considerations.
- Domain Specialist: focuses on OAuth2/OpenID Connect, SSO, SAML, and enterprise identity patterns.

Supervisor or orchestrator behavior
- The Orchestrator collects agent outputs, enforces timing, detects conflicts, and routes work to the next agent.
- Agents must pause on human-in-the-loop points and await clearance before production runs.
- The orchestrator maintains the single source of truth and ensures all agents reference the same data model.

Handoff rules between agents
- Planner to Implementer: handoff includes plan, data schemas, and required secrets access with least privilege.
- Implementer to Reviewer: handoff includes code changes, test cases, and security checks.
- Reviewer to Tester: handoff includes verification plan and acceptance criteria.
- Tester to Researcher/Domain Specialist (as needed): handoff includes risk findings and domain-specific adjustments.

Context, memory, and source-of-truth rules
- Context is the authentication domain model; memory is ephemeral cache during run; source-of-truth is the identity provider metadata store and policy store.

Tool access and permission rules
- Agents access tools via a centralized controller with scoped tokens; secrets must be retrieved from a vault and never written to local disks.
- Production tools require approval gates; access is restricted to the minimum scope.

Architecture rules
- Use a modular authentication architecture: gateway, authorization server, token service, and policy engine; all flows must be auditable.

File structure rules
- Keep files under authentication/workflows/multi-agent-auth with clear modules per agent role.

Data, API, or integration rules when relevant
- Interactions with OAuth2/OpenID Connect endpoints, token introspection, revocation, and userinfo; all API calls must be logged and signed.

Validation rules
- All changes pass unit tests for the auth flow, integration tests for token exchange, and acceptance tests for policy checks.

Security rules
- Do not embed secrets in code; rotate keys; enforce TLS; validate inputs; follow least privilege.

Testing rules
- Include positive and negative test cases for token flows, edge cases for error handling, and resilience tests.

Deployment rules
- Use staged deployments with canaries for auth changes; migrate secrets with vault rotation; monitor for anomalies.

Human review and escalation rules
- All critical changes require human review at the domain specialist level; escalate to security lead if policy violations are detected.

Failure handling and rollback rules
- If a failure occurs in the orchestration, revert to the last known-good configuration and notify stakeholders.

Things Agents must not do
- Do not leak secrets, bypass governance, perform production changes without approval, or attempt unsanctioned credential access.

Recommended Agent Operating Model

The operating model defines how each agent type participates in authentication workflows and how decisions are made. Roles are bound by explicit decision boundaries, with escalation paths for policy violations, risk signals, or security incidents. The Planner shapes the strategy; the Implementer executes the flow; the Reviewer approves changes; the Tester validates behavior; the Researcher injects threat intelligence; the Domain Specialist enforces enterprise patterns. Handoffs are governed by the policy of least privilege and traceable sources of truth. Escalations flow to the Orchestrator and, when needed, to human reviewers.

Recommended Project Structure

authentication/
  workflows/
    multi-agent-auth/
      agents/
        planner/
        implementer/
        reviewer/
        tester/
        researcher/
        domain-specialist/
      orchestrator/
      handoffs/
      policies/
  configs/
  docs/
  tests/

Core Operating Principles

• Operate with a single source of truth for identity provider metadata and policy definitions.
• Enforce least privilege for all tool access and secrets handling.
• Document decisions, handoffs, and escalation points in the AGENTS.md itself and in tests.
• Ensure auditable, testable, and reproducible authentication flows across environments.
• In multi-agent orchestration, avoid context drift and protect against policy drift.

Agent Handoff and Collaboration Rules

• Planner to Implementer: provide plan, data schemas, source-of-truth references, and required secrets access with least privilege.
• Implementer to Reviewer: provide code changes, tests, and security checks.
• Reviewer to Tester: provide verification plan and acceptance criteria.
• Tester to Researcher/Domain Specialist: provide risk findings and domain-specific adjustments.
• Domain Specialist to Planner: refine requirements based on security and enterprise patterns.

Tool Governance and Permission Rules

• All tool executions must go through a central orchestrator with scoped tokens.
• Secrets must be retrieved from a vault; never written to disk or logs in plaintext.
• API keys and tokens are ephemeral; rotate regularly and after suspicious events.
• Production access requires an approval gate; no direct production edits by agents.
• All tool actions are logged and auditable; changes require traceability.

Code Construction Rules

• Follow the authentication architecture patterns: gateway, authorization server, token service, policy engine.
• Use deterministic identifiers for flows to ensure traceability between agents.
• Write tests for token issuance, renewal, revocation, and policy evaluation.
• Avoid hard-coded secrets; use a vault for all credentials and keys.
• Document all API contracts and data models used by the auth services.

Security and Production Rules

• Enforce TLS 1.2+ for all endpoints; validate certificates; pin where appropriate.
• Regularly rotate keys and secrets; implement automated rotation plans.
• enforce strict input validation, rate limits, and anomaly detection for auth flows.
• Implement approved incident response procedures and runbooks for auth incidents.

Testing Checklist

• Unit tests for each agent’s logic and configuration.
• Integration tests for the full authentication flow (authorize, token, introspect, revoke).
• Security tests including threat scenarios, token leakage, and misconfiguration.
• End-to-end tests in staging that exercise multi-agent handoffs and escalation paths.
• Deployment tests for canary/promote workflows and secret rotations.

Common Mistakes to Avoid

• Assuming one-agent solves all security concerns; always consider multi-agent handoffs and governance.
• Hard-coding credentials or tokens in code or AGENTS.md blocks.
• Skipping human reviews for policy changes or sensitive configuration.
• Bypassing the orchestrator or creating ungoverned direct access to production services.
• Allowing context drift between agents; always reference the same source of truth.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is AGENTS.md Template in this context?

AGENTS.md Template provides a machine-readable operating manual for authentication architecture workflows, enabling single- and multi-agent orchestration with defined roles, handoffs, and governance.

How does multi-agent orchestration work in authentication architecture?

Planners define the strategy and data contracts; Implementers build the flow; Reviewers ensure security; Testers validate behavior; Researchers inject threat signals; Domain Specialists enforce enterprise patterns. An Orchestrator coordinates handoffs and enforces a single source of truth.

How are secrets and token handling governed?

Secrets are retrieved from a vault, never written to disk, and rotated regularly. Token issuance, validation, and revocation follow policy engine rules with auditable traces.

How do we perform human review and escalation?

Critical changes require domain-specialist or security-lead review. Escalation paths are defined in the AGENTS.md template and automated tests to detect policy violations.

How are failures and rollback handled?

If a failure occurs, revert to the last known-good configuration, roll back changes in orchestrator state, and notify stakeholders with the rollback plan.