AGENTS.md Template: File Sharing Platform Architecture

Overview

Direct answer: This AGENTS.md template defines a codified operating manual for a file sharing platform architecture, enabling both single-agent and multi-agent orchestration with explicit roles and governance.

Overview: This template provides concrete operating context for AI coding agents working on a file sharing platform. It specifies how agents interact, how decisions are made, and how handoffs occur among planners, implementers, researchers, reviewers, and security auditors. It enables multi-agent orchestration, tool governance, and human review where needed.

When to Use This AGENTS.md Template

• You're architecting an AI-driven file sharing platform with multiple services (auth, storage, metadata, permissions).
• You need explicit handoffs, traceable decisions, and auditable tool usage across agents.
• You must enforce governance, security, and deployment controls within an agent workflow.
• You require a repeatable, copyable operating manual that can be shared across teams.

Copyable AGENTS.md Template

Copy the block below into a file named AGENTS.md in your project to establish the workflow context for both single-agent and multi-agent execution.

# AGENTS.md

Project: File Sharing Platform Automation
Role: Platform Automation Engineer

Agent roster:
- Planner: defines orchestration plan and passes tasks to Implementers
- Implementer-auth: handles authentication and identity validation
- Implementer-storage: manages file storage, metadata, replication
- Implementer-permissions: handles access control and permission checks
- Researcher: sources policy constraints, threat intel
- Reviewer: validates outputs

Supervisor / Orchestrator: Central Orchestrator agent coordinates tasks, enforces governance, triggers human review when needed

Handoff rules: Planner → Implementers with explicit context; if failure, escalate to Supervisor
Context/memory/source-of-truth: Use central knowledge base; memory limited to session; all outputs reference data sources
Tool access and permission rules: Tokens with RBAC; secrets stored in secure vault; no hard-coded credentials
Architecture rules: Microservices; stateless; idempotent; event-driven; auditable
File structure rules: Top-level directories; create only necessary dirs; avoid duplication
Data, API, or integration rules when relevant: Data models: User, File, Permission; APIs: REST/GraphQL with versioning; idempotent operations
Validation rules: Validate inputs/outputs; run automated checks; health checks
Security rules: Encryption, audit logs, least privilege
Testing rules: Unit, integration, end-to-end tests; canary runs
Deployment rules: Canary or blue-green; rollback procedures
Human review and escalation rules: Define SLA for escalations; schedule human review for high-risk changes
Failure handling and rollback rules: Retries with exponential backoff; idempotent rollback
Things Agents must not do: Do not bypass authentication; Do not leak secrets; Do not skip tests; Do not perform unsupervised production changes

Recommended Agent Operating Model

The operating model defines clear roles, decision boundaries, and escalation paths to support reliable file sharing workflows.

• Planner owns the orchestration plan, acceptance criteria, and handoff contracts.
• Implementers execute tasks within defined scopes and report results to the Reviewer or Planner.
• Researchers supply policy constraints, threat intel, and risk assessments to shape decisions.
• Reviewers validate outputs against criteria and trigger human review when needed.
• Escalation paths ensure security or policy issues never go unattended.
• Decision boundaries are explicit; anything outside scope must be escalated.

Recommended Project Structure

project-root/
  agents/
    planner/
    implementer-auth/
    implementer-storage/
    implementer-permissions/
    researcher/
    reviewer/
    tester/
  orchestrator/
  services/
    auth-service/
    storage-service/
    permissions-service/
    metadata-service/
  infra/
    kubernetes/
  docs/
  templates/

Core Operating Principles

• Single source of truth for data and decisions.
• Idempotent tasks with traceable outcomes.
• Least privilege for all tools and agents.
• Explicit context propagation between agents.
• Auditable tool usage and change history.

Agent Handoff and Collaboration Rules

• Planner defines scope, context, and success criteria; passes to Implementers with boundary data.
• Implementers produce outputs with attached provenance; if uncertain, request clarification from Planner or Researcher.
• Reviewer validates results; any failure returns to Planner with remediation guidance.
• Researcher provides risk assessments before high-risk changes are deployed.
• Domain specialists review domain-critical decisions before production rollout.

Tool Governance and Permission Rules

• Commands must be scoped to agent roles and tested in staging before production.
• File edits require version control with pull-request-based approvals.
• APIs require versioning, rate limiting, and audit trails.
• Secrets must never be exposed in code or logs; use a vault with rotation policies.
• Production access requires explicit approval gates and operator handoff during releases.

Code Construction Rules

• Write modular, typed interfaces for all services.
• Use idempotent operations and clear error handling.
• Avoid duplicating logic; centralize common utilities.
• Document data contracts and API schemas in the repo.
• Do not hard-code credentials or secrets; fetch at runtime from vaults.

Security and Production Rules

• Enforce encryption at rest and in transit for all data flows.
• Maintain detailed audit logs for file access, sharing, and policy decisions.
• Apply least privilege access to services and agents; rotate keys regularly.
• Implement monitoring, anomaly detection, and alerting for production workloads.

Testing Checklist

• Unit tests for each service and utility.
• Integration tests covering auth↔storage↔permissions flows.
• End-to-end tests for typical file share and access scenarios.
• Canary or blue-green deployment checks with rollback capability.

Common Mistakes to Avoid

• Skipping explicit handoff contracts between planners and implementers.
• Embedding secrets in code or logs.
• Overlooking data privacy and policy constraints during orchestration.
• Ignoring edge cases in multi-agent coordination and failure handling.

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

How does this AGENTS.md template support multi-agent orchestration in a file sharing architecture?

It provides explicit roles, handoff rules, and governance prompts that coordinate planners, implementers, researchers, reviewers, and the orchestrator across services like auth, storage, and permissions.

What is the required handoff between Planner and Implementers?

The Planner must provide a fully scoped task with context, success criteria, required tools, data references, and acceptance criteria; Implementers return outputs with provenance and request clarification if needed.

How are secrets and tool access managed in this workflow?

Secrets are stored in a secure vault and accessed via RBAC-controlled tokens; no hard-coded credentials and all tool actions are auditable.

What constitutes a valid escalation flow to human review?

Escalation triggers include security risk, policy violations, failed critical validations, or defects that automated checks cannot resolve.

What should be included in the AGENTS.md template for file sharing architecture?

Roles, responsibilities, context propagation, architecture rules, validation, deployment and rollback strategies, plus explicit do-not-do rules for agents.