AGENTS.md Template: OAuth Production Architecture

Overview

Direct answer: This AGENTS.md Template governs the OAuth production architecture workflow for AI coding agents, enabling scalable multi-agent orchestration with explicit handoffs, token handling, and tool governance for production systems.

This template provides a concrete operating manual that supports both single-agent execution and multi-agent coordination in secure OAuth environments. It defines roles, memory sources, and verification gates to prevent policy drift and architectural drift in production.

When to Use This AGENTS.md Template

You're deploying or iterating a production OAuth flow (authorization code with PKCE, client credentials, or device flow) where AI agents must coordinate token issuance, validation, and resource access.
You need explicit handoff rules between planner, implementer, reviewer, tester, researcher, and domain specialist agents to prevent drift and ensure security.
You require a centralized source of truth for policies, secrets, and architecture decisions with traceable approvals.

Copyable AGENTS.md Template

Copy the block below into your repository as AGENTS.md to establish the project-level operating context for single-agent and multi-agent workflows in OAuth production architecture.

# AGENTS.md

Project: OAuth Production Architecture

Agent roster:
- Planner: defines orchestration policy, sequencing, and risk controls for OAuth token flows
- Implementer: translates planner decisions into API calls, code changes, and automation steps
- Reviewer: validates changes against security, compliance, and architectural standards
- Tester: executes unit/integration tests for OAuth flows and token validation
- Researcher: gathers threat models, OAuth best practices, and policy requirements
- Domain Specialist: ensures domain-aligned policy, client scenarios, and regulatory constraints

Supervisor / Orchestrator:
- The Orchestrator enforces policy, coordinates handoffs, and gates production readiness. It logs decisions and maintains traceability.

Handoff rules:
- Planner → Implementer: provide concrete tasks, acceptance criteria, and risk notes
- Implementer → Reviewer: deliverables, test results, and remediation notes
- Reviewer → Tester: approved changes and test plan
- Tester → Orchestrator: validation status and risk assessment

Memory / Context / Source-of-truth:
- Central memory store for context; sources of truth include OAuth server configs, token validation rules, and policy documents
- Changes update the source of truth with a changelog and versioned configs

Tool access and permissions:
- Use only approved tools via secure agent APIs
- Secrets are retrieved from a vault; avoid plaintext storage or logging of secrets

Architecture rules:
- Modular microservices approach: authorization server, resource server, client apps, gateway, and audit/tracing layers
- Clear boundaries between identity, access management, and resource access

File structure rules:
- /ai-skills/agents-md-templates/ for agent configs and prompts
- /workflows/ for orchestrated task artifacts
- /config/ for OAuth policies and secrets references (via vault paths only)
- /infra/ for deployment and infrastructure code

Data, API, or integration rules:
- Support OAuth 2.0 / OpenID Connect flows: authorization code with PKCE, client credentials, device flow where applicable
- Validate JWKS, token introspection endpoints, and userinfo where relevant

Validation rules:
- All changes pass security policy checks, token validations, and integration tests
- Idempotent operations in integration steps

Security rules:
- Secrets never logged; enforce TLS; rotate keys; least privilege access
- Tokens must be stored and retrieved securely; never cache tokens in plaintext

Testing rules:
- Unit tests for token validation logic, integration tests for OAuth callbacks, and end-to-end tests for client scenarios
- Include security regressions tests

Deployment rules:
- Immutable artifacts; canary or blue/green deployments; full audit logging
- Rollback procedures with minimal service interruption

Human review and escalation rules:
- Trigger human review for policy drift, high-risk changes, or failed critical tests
- Escalate to security and architecture leads as needed

Failure handling and rollback rules:
- Roll back to last known good config; preserve audit logs; notify stakeholders

Things Agents must not do:
- Do not bypass approvals; do not mutate signing keys without review; do not store secrets in code or logs

Recommended Agent Operating Model

Roles and decision boundaries:

Planner: decides orchestration policy, sequencing, and gating criteria; cannot execute API calls without Implementer.
Implementer: performs concrete actions, invokes services, and updates artifacts; must present results with attestations.
Reviewer: validates for security, compliance, and architecture; can request changes before promotion.
Tester: runs tests, records outcomes, and raises issues if acceptance criteria are not met.
Researcher: analyzes threat models, new OAuth patterns, and policy implications; informs Planner.
Domain Specialist: ensures alignment with client scenarios and regulatory constraints.

Recommended Project Structure

Workflow-specific directory tree. Do not include irrelevant folders.

oauth-production-architecture/
├── agents/
│   ├── planner.md
│   ├── implementer.md
│   ├── reviewer.md
│   ├── tester.md
│   ├── researcher.md
│   └── domain-specialist.md
├── workflows/
│   └── oauth-prod-workflow.md
├── config/
│   └── oauth-policies/
├── infra/
│   ├── auth-server/
│   ├── resource-server/
│   ├── gateway/
│   └── client-app/
├── secrets/
├── docs/
│   └── agents/
└── tests/
    ├── unit/
    ├── integration/
    └── e2e/

Core Operating Principles

Operate with explicit, testable contracts between agents.
Maintain single source of truth for policy and configuration.
Require traceable approvals for every production change.
Honor security constraints for tokens, secrets, and keys.
Minimize drift between architecture and implementation.
Favor idempotent, auditable actions and deterministic results.

Agent Handoff and Collaboration Rules

Planner → Implementer: hand off concrete tasks and acceptance criteria with risk notes.
Implementer → Reviewer: deliverables, code changes, and test results with rationale.
Reviewer → Tester: approved changes and test plan; document failure modes and mitigations.
Tester → Orchestrator: final validation status and remediation recommendations.
Domain Specialist → Planner: provide policy guidance and client-specific constraints.
Researcher → Planner: threat models and best practices updates.

Tool Governance and Permission Rules

All tool calls, file edits, and API calls must pass an approval gate with justification.
Secrets access restricted to authorized agents; keys rotated regularly.
Production changes require change tickets, traceability, and rollback plans.
Access to external services must be logged and auditable.
Handoff and change summaries stored in the central memory store.

Code Construction Rules

Implement OAuth flows with secure defaults (PKCE, short-lived tokens, rotate refresh tokens).
Use feature flags for production riskier changes; validate with tests before enabling.
Do not hard-code client IDs, secrets, or keys; fetch from vaults.
Ensure deterministic outputs for token validation and scope checks.
Document API contracts and error handling in detail.

Security and Production Rules

Enforce TLS, mutual TLS where needed; enforce mTLS in service mesh if applicable.
Store all secrets in a vault and surface them only to authorized agents.
Periodic secret rotation and key rotation with rotation windows documented.
Audit logs for all access, changes, and token events must be immutable.

Testing Checklist

Unit tests for token parsing, signature validation, and claim checks.
Integration tests for OAuth flows including redirects, token exchanges, and revocation.
End-to-end tests with a sample client and resource server integration.
Security regression tests for secret leakage, misconfigurations, and policy drift.
Canary testing plan and rollback verification.

Common Mistakes to Avoid

Skipping approvals or bypassed gates.
Storing secrets in code or logs.
Drifting from defined OAuth configurations across services.
Unclear handoffs leading to duplicated work or gaps in coverage.
Assuming a single agent can cover all security and architectural decisions.

FAQ

What is the purpose of this AGENTS.md Template for OAuth production architecture?

It defines the operating context, roles, handoffs, and governance for AI coding agents coordinating a secure OAuth production architecture.

How does multi-agent orchestration work in this template?

It assigns specific responsibilities to planner, implementer, reviewer, tester, researcher, and domain specialist agents with clear handoff rules and an orchestrator that enforces policy.

What are the security constraints for handling OAuth tokens and secrets?

Tokens and secrets must be stored in a dedicated secrets vault, accessed only by approved agents, rotated on schedule, and never logged in plaintext.

How are tool access and production changes controlled?

All tool calls, file edits, and API requests go through an approval gate with justifications, automated validation, and traceability.

What happens on failure or rollback in this workflow?

Failures trigger a controlled rollback to a known good state, with a human review if needed, and comprehensive audit logs.

Target User

Use Cases