AGENTS.md Template for Marketplace Platform Architecture (AGENTS.md template)

Overview

Direct answer: This AGENTS.md Template for Marketplace Platform Architecture defines a formal operating manual for AI coding agents and their orchestration within a marketplace. It covers single-agent workflows and multi-agent coordination, ensuring clear roles, governance, and traceability.

When to Use This AGENTS.md Template

• When designing a marketplace platform that uses AI coding agents to match, price, route or arbitrate tasks.
• When establishing a repeatable governance model for agent handoffs and supervision in production.
• When aligning product, engineering, data, and security teams around a common operating context.
• When you need a copyable, project-scoped AGENTS.md template to paste into your repo.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- Product Manager oversees marketplace-scale goals and governance for AI coding agents.

Agent roster and responsibilities
- Planner: designs the orchestration flow and outputs a plan.
- Implementer: turns the plan into executable tasks and integrates with APIs.
- Reviewer: validates outputs, ensures correctness and compliance.
- Tester: runs tests and checks for regressions.
- Researcher: fetches data and validates sources.
- Domain Specialist: handles domain-specific constraints (pricing, catalog, etc).

Supervisor or orchestrator behavior
- The Orchestrator monitors agent status, enforces memory usage, triggers handoffs, manages conflicts, ensures sources-of-truth, and escalates to human review when risk is detected.

Handoff rules between agents
- Planner → Implementer: carry context and plan.
- Implementer → Reviewer: provide outputs and validation results.
- Reviewer → Implementer: feedback and revisions when needed.
- Researcher/Domain Specialist can insert data before planning or during execution as needed.

Context, memory, and source-of-truth rules
- Context is stored in memory with a defined TTL; outputs reference sources of truth (SOT); SOT is tagged and versioned.

Tool access and permission rules
- Tools allowed: REST/GraphQL API calls, data retrieval, search. Secrets are kept in a secure vault; API keys rotate; access follows least privilege.

Architecture rules
- Modular, event-driven; each agent has a defined contract; the orchestrator enforces end-to-end traceability.

File structure rules
- Place each agent under agents/planner, agents/implementer, agents/reviewer, agents/tester, agents/researcher, agents/domain-specialist; include orchestrator; memory; docs; tests; configs; logs.

Data, API, or integration rules when relevant
- Data sources and APIs must be validated; contracts define schemas; handle retries and timeouts; never leak secrets in logs.

Validation rules
- Outputs must pass unit tests, integration tests, and end-to-end checks; outputs must align with the source-of-truth.

Security rules
- Secrets handling, least privilege, encryption at rest/in transit, and auditable actions.

Testing rules
- Use mock data, test harnesses, and end-to-end scenarios; cover failure paths.

Deployment rules
- CI/CD gates, canary deployments, and rollback plans; observability for post-deploy health.

Human review and escalation rules
- Escalate to human reviewers on uncertain or high-risk outputs; maintain an escalation log and decision trace.

Failure handling and rollback rules
- Revert to last good state; preserve history; alert stakeholders; retry with mitigations where safe.

Things Agents must not do
- Do not bypass the orchestrator; do not leak secrets; do not modify production data directly; do not skip tests; do not deploy without approvals.

Recommended Agent Operating Model

The recommended operating model defines roles, decision boundaries, and escalation paths for single-agent and multi-agent work in a marketplace architecture. The Planner defines strategy and constraints; the Implementer executes within tool and API limits; the Reviewer validates; the Tester ensures quality; the Researcher and Domain Specialist supply inputs when needed. Escalation paths ensure timely human review when risk thresholds are hit.

Recommended Project Structure

marketplace-architecture/
  orchestrator/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  memory/
  data/
  tools/
  integrations/
  docs/
  tests/
  config/
  logs/

Core Operating Principles

• Clear ownership with explicit handoffs
• End-to-end traceability and auditable decisions
• Least-privilege access to tools and production systems
• Idempotent and deterministic outputs where applicable
• Source-of-truth anchored data and versioning

Agent Handoff and Collaboration Rules

• Planner hands off a validated plan to Implementer with full context and source references.
• Implementer hands off outputs to Reviewer with validation evidence.
• Reviewer approves or returns for revision; if revisions are needed, the cycle returns to Implementer.
• Researcher and Domain Specialist may inject data or constraints at planning or execution points.
• Orchestrator guarantees that each handoff carries context, memory and SOT references.

Tool Governance and Permission Rules

• Only approved tools can be invoked; secret keys are retrieved from a vault; access is ephemeral and scoped per task.
• All API calls are audited; secrets never appear in logs or outputs.
• Production changes require explicit approvals and automated safeguards.

Code Construction Rules

• Write modular, testable code; use wrappers for external calls; avoid hard-coded values.
• Follow API contracts; validations before persisting or forwarding data.
• Ensure idempotency and deterministic outputs when processing identical inputs.

Security and Production Rules

• Encrypt data at rest and in transit; rotate credentials; enforce role-based access control.
• Monitor for anomalous agent behavior; abort on detected security risks.
• Maintain auditability for all actions affecting production systems.

Testing Checklist

• Unit tests for each agent contract
• Integration tests for inter-agent handoffs
• End-to-end tests of marketplace workflows
• Canary and rollback tests for deployment paths

Common Mistakes to Avoid

• Overloading a single agent with responsibilities that belong to others
• Omitting explicit handoffs and source-of-truth references
• Bypassing tool governance or secret management
• Ignoring edge cases and failure modes

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Micro-Lenders Using Phone Usage Data Metrics To Evaluate Creditworthiness In Unbanked Regions.

FAQ

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

The template defines roles, handoffs, source-of-truth, tool governance, and escalation paths for AI coding agents operating within a marketplace, enabling both single-agent and multi-agent orchestration.

How should agent handoffs be governed in a marketplace platform?

Handoffs are explicit, with context and memory carried forward, ownership transferred to the next role, and validation checks before proceeding. Escalate on uncertainty or risk.

What are the security rules for production tool access?

Secrets are never exposed; access is least-privilege; credentials stored in a secure vault; rotate keys; audit trails; avoid hard-coded secrets.

How do you validate multi-agent orchestration in this template?

Use automated tests, integration checks, and observable metrics for end-to-end flows; cross-check outputs against source-of-truth; ensure idempotence and deterministic behavior.

How is escalation handled when agent outputs are uncertain?

Uncertain outputs trigger human review or domain specialist consultation; timeouts apply; the orchestrator logs decisions and alerts stakeholders.