AGENTS.md Template for Payment and Billing System Agents

Overview

Direct answer: This AGENTS.md template defines the operating model, governance, and orchestration pattern for AI coding agents in payment and billing systems, enabling both single-agent execution and multi-agent orchestration with clear handoffs, tool governance, and human review workflows.

This template governs an end-to-end payment and billing workflow, including gateway interactions, ledger updates, reconciliation, and refunds. It emphasizes multi-agent orchestration where multiple agents collaborate under a supervisor, share context, and hand off tasks with explicit rules. It also documents how to maintain a single source of truth, enforce security, and enable human review when needed.

When to Use This AGENTS.md Template

• Model complex payment and billing processes that involve gateway calls, ledger updates, and reconciliation across services.
• Coordinate multiple agents (planner, implementer, verifier, data integrator, compliance reviewer) to reduce drift and improve accountability.
• Define governance, approval gates, and escalation paths for changes that affect financial data or external payments.
• Document tool access, secrets handling, and source-of-truth rules to prevent context drift.
• Prepare for PCI-DSS, data minimization, and auditable change control in production workflows.

Copyable AGENTS.md Template

# AGENTS.md

Project: Payments and Billing Automation

Overview:
- Purpose: Define the operating model for AI coding agents managing payments and billing workflows.
- Scope: Single-agent and multi-agent orchestration for gateway interactions, ledger updates, invoicing, and refunds.

Agent roster and responsibilities:
- Planner: designs the end-to-end multi-agent workflow, milestones, and expected outputs.
- Implementer: integrates with Payment Gateway, Billing API, and Ledger; implements code to perform tasks.
- Verifier: validates outputs, checks data integrity, and enforces business rules.
- DataIntegrator: maps data between systems, normalizes schemas, and ensures compatibility.
- ComplianceReviewer: validates PCI-DSS, data privacy, and regulatory constraints.
- Orchestrator (Supervisor): coordinates agents, enforces policy, triggers handoffs, monitors progress.
- Auditor: records actions and maintains a complete audit trail.
- DomainExpert: applies payments domain knowledge (tax, refunds, chargebacks, proration).

Supervisor or orchestrator behavior:
- The Orchestrator maintains task state, context, and a live view of workflow health.
- It enforces decision boundaries and triggers retries or escalations when outcomes deviate from expectations.
- It coordinates handoffs using explicit context transfer and validates pre/post-conditions at each handoff.

Handoff rules between agents:
- Planner → Implementer: after design approval and task breakdown.
- Implementer → Verifier: after code and API changes are implemented.
- Verifier → DataIntegrator / DomainExpert: after validation against business rules.
- DomainExpert → ComplianceReviewer: for regulatory and privacy checks.
- Auditor → Orchestrator: for traceability and continuous improvement.

Context, memory, and source-of-truth rules:
- Source-of-truth: Billing DB, Payment Gateway responses, Ledger API.
- Context memory: per-run context stored in a central store; memory persists across tasks in a session when allowed by policy.
- All outputs must be traceable to source data with immutable references.

Tool access and permission rules:
- Agents may call Payment Gateway, Billing API, Ledger API under scoped credentials.
- Secrets are retrieved from a vault; do not hard-code credentials.
- Access to production systems requires approval gates and audit logging.

Architecture rules:
- Use API wrappers and clear interfaces; agents should be stateless; state stored externally.
- Prefer idempotent operations and deterministic outputs.

File structure rules:
- Organize by role and workflow: /ai-skills/agents-md-templates/planner, /ai-skills/agents-md-templates/implementer, /ai-skills/agents-md-templates/verifier, /ai-skills/agents-md-templates/data-integrator, /ai-skills/agents-md-templates/compliance, /orchestrator, /auditor.
- Keep workflow-specific code under /workflows/payments_billing/.

Data, API, or integration rules when relevant:
- Normalize data to a canonical schema before cross-service usage.
- Validate data types, timezones, and currency codes prior to ledger updates.

Validation rules:
- Each agent must emit pre/post-conditions; validation gates must pass before handoffs.
- End-to-end tests must cover gateway success, ledger update, and reconciliation edges.

Security rules:
- Do not log full PAN or CVV; mask sensitive fields in all logs.
- Enforce TLS 1.2+ for all external calls; rotate and audit secrets.

Testing rules:
- Include unit tests for individual agents and integration tests for inter-agent interactions.
- Run end-to-end tests with mocks and real services in staging before production.

Deployment rules:
- CI/CD with staged rollouts; feature flags for riskier changes.
- Maintain rollback procedures for failed payments or refunds.

Human review and escalation rules:
- Escalate high-risk financial changes to ComplianceReviewer and a required human sign-off when required by policy.
- Provide human-readable run logs for review in case of disputes.

Failure handling and rollback rules:
- On payment gateway failure, rollback ledger writes and revert any provisional changes; alert Orchestrator.
- If a handoff fails, revert to the previous stable state and retry with backoff.

Things Agents must not do:
- Do not bypass approvals or change policies without approval.
- Do not store secrets in code; do not leak PII; do not make irreversible changes without a confirm step.

Recommended Agent Operating Model

The operating model defines roles, decision boundaries, and escalation paths for payment and billing automation. Planner defines scope and milestones; Implementer delivers integrations; Verifier enforces correctness; DataIntegrator ensures data hygiene; ComplianceReviewer enforces security and regulation; Orchestrator coordinates handoffs; DomainExpert provides domain insight; Human reviewer steps in for sensitive changes. Escalation follows a predefined path when thresholds or policy violations occur.

Recommended Project Structure

/payments-billing-agents/
  /ai-skills/agents-md-templates/
    planner/
    implementer/
    verifier/
    data-integrator/
    compliance/
    domain-expert/
    auditor/
  /orchestrator/
  /integrations/
    payment_gateway/
    billing_api/
    ledger_api/
  /workflows/
    payments_billing/
      tasks/
      handoffs/
  /config/
  /tests/
  /docs/

Core Operating Principles

• Single source of truth: rely on canonical data from the Billing DB and Gateway responses.
• Deterministic and idempotent actions: do not perform irreversible operations without confirmation.
• Clear ownership and auditable decisions: every handoff logs rationale and identifiers.
• Security-first: mask sensitive data, enforce least privilege, and audit secrets usage.
• Fail fast with graceful degradation and explicit rollback paths.

Agent Handoff and Collaboration Rules

• Planner to Implementer: hand off design artifacts, interfaces, and task breakdown with acceptance criteria.
• Implementer to Verifier: hand off code, API changes, test results, and validation checks.
• Verifier to DataIntegrator/DomainExpert: hand off data schemas, mapping rules, and domain constraints.
• DomainExpert to ComplianceReviewer: hand off domain-specific risk and regulatory concerns.
• Auditor to Orchestrator: hand off trace logs for traceability and continuous improvement.

Tool Governance and Permission Rules

• Commands to external services must be mediated by the Orchestrator with an approval gate for sensitive actions.
• File edits require review and commit hooks; secrets never stored in code.
• API calls must use scoped credentials and be rate-limited; sensitive scopes require extra approvals.
• Production changes require human sign-off for high-risk flows (refunds, large settlements, tax adjustments).

Code Construction Rules

• All business logic must be modular and tested; wrap external calls with retry/backoff strategies.
• Use typed data contracts; validate inputs/outputs against schemas before use.
• Do not hard-code credentials; pull from vaults or secret managers.
• Document interfaces and side effects for each integration.

Security and Production Rules

• Mask PII and payment data in logs; never expose PAN, CVV, or full account numbers.
• Apply PCI-DSS and data-minimization practices; implement least-privilege access controls.
• Maintain audit trails for all financial changes and approvals.
• Enforce encrypted transport (TLS) and secure storage of secrets.

Testing Checklist

• Unit tests for each agent with deterministic inputs.
• Integration tests for gateway, ledger, and billing APIs with mocks/stubs.
• End-to-end tests for payments, refunds, and reconciliation in staging.
• Security tests for data masking and access controls.
• Canary/blue-green tests for production deployments of payment flows.

Common Mistakes to Avoid

• Skipping explicit handoff criteria and relying on implicit handoffs.
• Storing secrets in code or logs; not enforcing vault-based secret retrieval.
• Bypassing approvals for high-risk financial changes.
• Ignoring data lineage and source-of-truth drift between systems.
• Unbounded escalation without clear escalation paths or SLAs.

FAQ

What is the purpose of this AGENTS.md Template for payment and billing?

It codifies the operating model, roles, handoffs, and governance for AI coding agents in payment and billing workflows, enabling reliable single-agent and multi-agent orchestration.

Who should use this template?

Developers, platform engineers, and engineering leaders building automated payments, invoicing, refunds, and reconciliation workflows.

What are the main agent roles?

Planner, Implementer, Verifier, DataIntegrator, ComplianceReviewer, Orchestrator, Auditor, and DomainExpert for payments.

How are tool access and secrets managed?

Agents access only required APIs with scoped credentials; secrets live in a vault and are never embedded in code.

How is production security enforced?

PCI-DSS alignment, data minimization, masking of sensitive data, and mandatory audit trails for changes.