AGENTS.md Template for resumable upload design

Overview

Direct answer: This AGENTS.md Template for resumable upload design provides a practical operating manual for AI coding agents to coordinate a multi agent workflow around chunked uploads. It governs the resumable upload design, including agent rosters, handoffs, and governance so single agents and multi agent orchestration share a common operating context.

This template covers the workflow memory source of truth and tool access necessary to maintain robust state across chunks restarts and failures.

When to Use This AGENTS.md Template

When building a resumable or chunked upload service that must survive restarts and network interruptions
When you want a clearly defined agent roster and escalation path
When you need strict tool governance and memory sharing across agents
When the design requires explicit handoffs between planner implementer reviewer tester researcher and domain specialist

Copyable AGENTS.md Template

# AGENTS.md
Project Role
- Resumable Upload Engine

Agent roster and responsibilities
- Planner
- Implementer
- Reviewer
- Tester
- Researcher
- Domain Specialist

Supervisor or orchestrator behavior
- The orchestrator coordinates all agents and maintains the single source of truth and triggers handoffs

Handoff rules
- On chunk ready, assign to Implementer
- If error, escalate to Planner and log for review

Context memory and source of truth
- Central state store with chunk metadata upload id offset and checksum
- All agents read from and write to this store

Tool access and permission rules
- Access to storage bucket chunking service and API endpoints
- Secrets stored in vault logs redacted

Architecture rules
- Stateless plan execution per chunk and state persisted in store

File structure rules
- Each module in dedicated folder under project

Data API rules
- Include chunk id offset length checksum content

Validation rules
- Checksum validation offset consistency id monotonic

Security rules
- Do not log secrets encryption in transit and at rest

Testing rules
- Unit tests for chunk validation integration tests for orchestrator agent flow

Deployment rules
- CI gate blue green or canary for schema changes

Human review and escalation rules
- Flag anomalies for human review require explicit approval for production change

Failure handling and rollback rules
- Retry with backoff on transient errors rollback to last stable chunk

Things Agents must not do
- Do not run without a plan do not bypass orchestrator do not duplicate work

Recommended Agent Operating Model

Outline the roles decision boundaries and escalation paths for the resumable upload workflow. The planner defines chunk boundaries plus strategy; the implementer performs chunk writes; the reviewer validates results; the tester ensures end to end correctness; the researcher gathers API requirements; the domain specialist resolves storage and API constraints. The orchestrator coordinates and enforces memory consistency and tool governance across all agents.

Recommended Project Structure

resumable-upload-design/
  orchestrator/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  services/
    storage/
    chunker/
    api/
  config/
  models/
  tests/
  docs/

Core Operating Principles

Single source of truth for upload state
Idempotent operations across retries
Clear ownership and escalation paths
Explicit tool governance and auditability
Stricter security and access control

Agent Handoff and Collaboration Rules

Planner to Implementer handoffs occur when chunk metadata is available and validation passes
Implementer to Reviewer handoffs occur after a chunk write completes
Researcher informs Domain Specialist when new API requirements arise
Domain Specialist to Planner escalates if constraints change
Orchestrator ensures memory consistency across hands

Tool Governance and Permission Rules

Commands must be authorized by orchestrator
File edits require version control and review
API calls limited to allowed endpoints with scope
Secrets stored in vault; secrets not logged
Production systems require approval gates

Code Construction Rules

Write modular, testable code
Validate all chunk metadata before persistence
Never reuse stale handles
Maintain deterministic behavior for retries
Do not bypass orchestrator for production actions

Security and Production Rules

Encrypt data at rest and in transit
Audit logs for all state-changing operations
Limit blast radius with scoped credentials
Use feature flags for risky changes

Testing Checklist

Unit tests for chunk validation and state updates
Integration tests for orchestrator-agent interactions
End-to-end tests simulating network failures and rollbacks
Security and access control tests
Performance tests for chunk handling

Common Mistakes to Avoid

Ambiguous ownership or missing escalation paths
Skipping state persistence requirements
Unvetted tool access or secrets handling
Bypassing the orchestrator for production changes
Unclear failure handling or rollback procedures

FAQ

What is the purpose of this AGENTS.md Template for resumable upload design?

Provides a copyable operating manual for single and multi agent orchestration of resumable uploads, with clear rules and governance.

How do agents hand off work in this template?

Planners assign tasks to Implementers with explicit handoff triggers and context sharing to maintain continuity.

How is state persisted across chunks and restarts?

A central single source of truth stores chunk metadata, offsets, and progress; each action validates and updates this state.

What security measures are required?

Secrets are kept in a vault, logs redact secrets, and production actions go through approval gates with audit trails.

How is testing performed for the resumable upload workflow?

Unit tests, integration tests for orchestrator-agent interactions, and end to end tests simulating failure and rollback.

Target User

Use Cases