AGENTS.md Template for Subscription Billing System Design

Overview

Direct answer: This AGENTS.md template provides a concrete, copyable operating manual for AI coding agents governing a subscription billing system design, enabling both single-agent workflows and multi-agent orchestration with clear boundaries, governance, and escalation paths.

The AGENTS.md template defines the project context, agent roster, supervisor behavior, and the rules that ensure reliable, auditable, and secure automation. It is intended to be pasted into a project as the canonical operating model for the agent workforce and to guide handoffs between planners, implementers, reviewers, testers, researchers, and domain specialists.

When to Use This AGENTS.md Template

• Designing a subscription billing system that relies on AI coding agents for rule-based policy, pricing, proration, and invoice generation.
• Coordinating a multi-agent workflow where a central orchestrator manages handoffs and state across billing cycles.
• Establishing tool governance, permissions, and security constraints for production-grade billing automation.
• Defining a clear, auditable memory and source-of-truth model to avoid context drift in complex billing scenarios.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- Billing Automation Platform for subscription lifecycle management (billing, proration, refunds, invoicing, revenue recognition).

Agent Roster and Responsibilities
- PlannerAgent: designs the workflow, prioritizes tasks, and decomposes work for implementers.
- ImplementerAgent(s): execute actions, call APIs, modify configurations, create or update artifacts.
- ResearcherAgent: gathers external policy rules, regulatory constraints, and data from external services.
- ReviewerAgent: validates outputs, enforces quality gates, and approves changes for production.
- TesterAgent: runs unit/integration tests, simulates end-to-end scenarios, and reports results.
- DomainSpecialistAgent: provides domain-specific guidance (billing, taxation, regional compliance).
- OrchestratorAgent (Supervisor): coordinates planners, implements, reviewers, and testers; maintains global state and memory.

Supervisor/Orchestrator Behavior
- The Orchestrator maintains a single source of truth for the billing workflow state, assigns tasks, monitors SLAs, and escalates when needed.
- All handoffs follow the defined state machine: Plan → Implement → Validate → Test → Deploy → Review.
- The Orchestrator enforces idempotency, retries on transient failures, and records auditable traces.

Handoff Rules Between Agents
- Planner → Implementer: deliver task payload, acceptance criteria, and required resources.
- Implementer → Reviewer: deliver artifacts, test results, and risk notes.
- Reviewer → Implementer: return with changes or approval.
- Implementer → Tester: provide test data, environment details, and expected outcomes.
- Tester → Orchestrator: summarize test status and escalate if failures persist.

Context, Memory, and Source-of-Truth Rules
- Memory store (memory.json) persists context, decisions, and outputs with timestamps.
- Canonical data sources include billing API responses, invoices, plan metadata, and user events.
- All non-deterministic decisions must reference a grounded source of truth and include traceable citations.

Tool Access and Permission Rules
- Agents may call BillingAPI, InvoicingAPI, TaxAPI, and Auth APIs using scoped credentials via a secrets vault.
- Secrets must never be logged; credentials rotate on schedule; access limited by role-based permissions.
- All API calls must be auditable and idempotent where possible.

Architecture Rules
- Architecture uses a modular agent pool with explicit interfaces and adapters to external services.
- Maintain a single centralized orchestrator for multi-agent coordination and memory management.
- Use event-driven triggers for critical billing events (subscription creation, renewal, cancellation).

File Structure Rules
- Place agent configuration, prompts, and memory in /subscription-billing/ai-skills/agents-md-templates/
- Store policies and schemas in /subscription-billing/policies/
- Use /subscription-billing/integrations/ for external service adapters
- Do not include irrelevant folders outside the billing domain

Data, API, or Integration Rules
- Data models must include subscription_id, customer_id, plan_id, cycle_start, cycle_end, amount, currency, tax, total, status.
- Validate input schemas for all API responses; guard against partial data and retries.
- Rate limits and retry policies must be codified in adapters.

Validation Rules
- All outputs must be validated against predefined schemas before persisting.
- Outputs should be idempotent; repeat executions must not create inconsistent state.
- Critical decisions require corroboration from the canonical data sources.

Security Rules
- Do not log secrets or keys; rotate credentials; apply least privilege.
- Encrypt sensitive data at rest and in transit; monitor for anomalies.
- Require human review for production-altering changes beyond defined thresholds.

Testing Rules
- Unit tests for each agent capability; integration tests for multi-agent workflows; end-to-end tests for billing scenarios.
- Include regression tests for prorations, refunds, and tax calculations.

Deployment Rules
- CI/CD pipelines must gate changes with automated tests and a manual review consider.
- Rollback capability must exist and be tested.
- Deploy to production only after approval from a responsible reviewer and policy owner.

Human Review and Escalation Rules
- Escalate to human if: repeated failures, data discrepancies, or security concerns.
- Define an escalation path with owners and on-call rotations.

Failure Handling and Rollback Rules
- Use idempotent operations; if a step fails, roll back to the last known good state and re-run.
- Maintain a rollback log and publish it to the memory store for audit.

Things Agents Must Not Do
- Do not bypass approval gates or push changes to production without review.
- Do not hard-code secrets or credentials.
- Do not modify canonical data sources without documented justification.
- Do not drift from defined memory/state model.

Recommended Agent Operating Model

The recommended model combines a Planner-driven orchestration with specialized agents to handle policy, data, and execution. The planner designs the workflow, while implementers carry out API calls and artifact creation. Reviewers ensure correctness before deployment. Domain specialists provide regulatory and billing-specific guidance. Handoffs are governed by a strict state machine and memory persistence to ensure traceability and reproducibility. Escalation paths are clearly defined for failures and security concerns.

Recommended Project Structure

subscription-billing/
├─ agents/
│  ├─ planner/
│  ├─ implementer/
│  ├─ researcher/
│  ├─ reviewer/
│  ├─ tester/
│  └─ domain-specialist/
├─ memory/
│  └─ memory.json
├─ policies/
│  └─ billing-policies.yaml
├─ integrations/
│  ├─ BillingAPI/
│  ├─ InvoicingAPI/
│  └─ TaxAPI/
├─ configs/
│  └─ prompts/
└─ docs/

Core Operating Principles

• Clarity: each agent has a narrow, auditable remit.
• Traceability: every action is logged with a source-of-truth reference.
• Idempotency: repeated runs do not corrupt state.
• Security by design: least privilege and secrets hygiene.
• Escalation: automatic human review when thresholds are exceeded.

Agent Handoff and Collaboration Rules

Planner handles task decomposition and sequencing. Implementers perform actions and update artifacts. Reviewers validate outputs and approve changes. Researchers gather policy context. Domain specialists provide billing/regulatory guidance. Testers validate end-to-end behavior. Handoff rules emphasize data provenance, required artifacts, and success criteria. All handoffs must include memory references and sources of truth.

Tool Governance and Permission Rules

• Commands must execute within scoped environments; do not run privileged operations without approval.
• All file edits must be tracked and reversible.
• API calls require authentication, consent, and rate-limiting adherence.
• Secrets must be stored in a vault and never logged.
• Production changes require a formal approval gate with independent review.

Code Construction Rules

• Use deterministic logic and avoid side effects in agent code when possible.
• All data flows must be validated against schemas before persistence.
• Adapters must handle retries and circuit breakers for external services.
• Configuration data must be externalized and versioned.

Security and Production Rules

• Enforce encryption at rest and in transit for all sensitive data.
• Audit trails must capture who did what, when, and why.
• Automated security scans should run in CI/CD gates.
• Production deployments require manual approval for changes beyond automated policy gates.

Testing Checklist

• Unit tests for each agent’s core logic.
• Integration tests for orchestration across planner, implementer, and reviewer.
• End-to-end tests covering prorations, refunds, and invoice generation.
• Smoke tests in staging before production deployment.

Common Mistakes to Avoid

• Skipping the memory/source-of-truth model, leading to context drift.
• Overloading agents with too broad responsibilities.
• Omitting explicit handoff criteria and acceptance tests.
• Bypassing approval gates or performing non-idempotent writes in production.

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 WhatsApp Inquiries and CRM Updates.

FAQ

What is the purpose of this AGENTS.md Template for Subscription Billing System Design?

To provide a copyable, operating manual that governs how AI coding agents design, implement, and govern a subscription billing system, including multi-agent orchestration, handoffs, and governance rules.

How does multi-agent orchestration work in this template?

The Orchestrator coordinates planner, implementer, reviewer, tester, and domain-specialist agents, maintaining a single memory of truth and enforcing a strict handoff sequence with auditable outputs.

What are the handoff rules between planner, implementer, and reviewer?

Planner delivers tasks and acceptance criteria; Implementer executes and prepares artifacts; Reviewer validates and approves changes for production. Handoffs include provenance and test results.

How is data provenance and source of truth maintained?

Canonical data sources (billing API responses, invoices, plan metadata) are persisted in memory with timestamps; all decisions reference these sources and are traceable.

How are security and production risks mitigated?

Secrets are vault-stored, access is role-based, and production changes require formal approvals and validation gates with audit logging.