AGENTS.md Template for Delayed Job Processing

Overview

TL;DR: This AGENTS.md Template defines a Delayed Job Processing workflow using a Planner, an Orchestrator, and a Worker to schedule and execute tasks after a delay, with clear handoffs, a single source of truth, and governance rules that support both single-agent and multi-agent orchestration.

The template provides concrete operating context for AI coding agents operating on delayed tasks, including how to coordinate plan creation, time-based triggering, execution, validation, and escalation. It emphasizes tool governance, human review where needed, and explicit failure handling to maintain reliability in production systems.

When to Use This AGENTS.md Template

• You need reliable delayed execution for tasks that cannot run immediately.
• You require clear planner, orchestrator, and worker roles with defined handoffs.
• You want a single source of truth for delayed tasks and auditability across agents.
• You must enforce tool governance, permission rules, and security around delayed operations.
• You expect to combine automated orchestration with human review for edge cases.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- Delayed Job Processing Project Owner: Responsible for defining the delayed task workflow, acceptance criteria, and escalation paths.
- AI Operations Lead: Oversees agent roster, memory rules, and source-of-truth policy.

Agent roster and responsibilities
- Planner: Creates delay plans, collects input, and determines scheduling windows.
- Orchestrator: Maintains the schedule, triggers handoffs, and coordinates cross-agent state.
- Worker: Executes the delayed task when the scheduled time arrives; reports results.
- Reviewer: Validates outputs, checks for accuracy and policy compliance, and approves or requests rework.
- Monitor: Watches for failures, retries, and health of all agents; emits alerts.

Supervisor or orchestrator behavior
- The Orchestrator enforces timing, sequence of handoffs, timeouts, and retries.
- It holds the canonical view of the task state and status for all agents.
- It prevents context drift by refreshing memory from the source of truth before each handoff.

Handoff rules between agents
- Planner -> Orchestrator: When a delay plan is ready and a schedule window exists.
- Orchestrator -> Worker: At the scheduled execution time.
- Worker -> Reviewer: After execution returns results.
- Reviewer -> Planner: If rework is required or if the plan changes due to new inputs.

Context, memory, and source-of-truth rules
- All tasks, states, and results live in a durable store (source of truth).
- Agents maintain ephemeral in-memory context per task; persistent memory is refreshed from the source of truth on every handoff.
- Logs, decisions, and validations are append-only and traceable.

Tool access and permission rules
- Planner can create new delayed tasks and modify plans within policy.
- Orchestrator can update scheduling, but cannot perform execution without a valid plan.
- Worker can call external services required for execution; secrets are retrieved via a secure vault.
- No agent may access production systems outside approved interfaces without approval.

Architecture rules
- Clear separation between planning, orchestration, execution, and validation layers.
- Stateless workers with idempotent operations; state is centralized in the source of truth.
- All external calls are auditable and retry-safe.

File structure rules
- All workflow definitions live under templates/ delayed-job-processing.
- Agent code is organized by role with explicit interfaces.

Data, API, or integration rules when relevant
- Delayed tasks include: id, payload, scheduledAt, status, result, and audit fields.
- All API calls use authenticated endpoints with least-privilege scopes.

Validation rules
- Each handoff must validate required fields and timing constraints.
- Delays must be non-negative and within allowed windows.

Security rules
- Secrets are never stored in code; use a secrets vault.
- Access is role-based and audited.

Testing rules
- Unit tests cover planner logic, scheduling edge cases, and idempotency of worker actions.
- Integration tests validate end-to-end delayed execution and handoffs.
- End-to-end tests simulate failure and recovery paths.

Deployment rules
- Changes go through a staged deployment with feature flags for the new workflow.
- Rollback is automatic on failure and requires a human approval gate for production releases.

Human review and escalation rules
- Human review is required for non-idempotent results and for operations outside policy.
- Escalation to on-call engineers triggers when monitors report persistent failures.

Failure handling and rollback rules
- If a task fails, retries follow a backoff policy; after max attempts, trigger escalation.
- Rollback returns the system to the last known good state in the source of truth.

Things Agents must not do
- Do not execute tasks outside the approved delay window.
- Do not bypass the Orchestrator or source of truth.
- Do not modify production state without a validated plan and approval.

Recommended Agent Operating Model

The Delayed Job Processing model defines clear roles with bounded decision rights. The Planner defines the plan and inputs, the Orchestrator makes timing decisions and sequence, and the Worker executes with idempotent behavior. The Reviewer and Monitor provide guardrails and human-in-the-loop safety. Escalation paths route issues to on-call engineers and product owners when thresholds are exceeded.

Recommended Project Structure

project-root/
  agents/
    planner/
    orchestrator/
    worker/
    reviewer/
    monitor/
  memory/
  data/
  configs/
  integrations/
  tests/
  deployments/

Core Operating Principles

• Single source of truth for delayed tasks; memory is refreshed from the source on every handoff.
• Idempotent worker actions to ensure safe retries.
• Deterministic handoffs and time-bound execution windows.
• Observability with end-to-end tracing and audit trails.
• Strict tool governance and least-privilege access.

Agent Handoff and Collaboration Rules

• Planner communicates a complete delay plan to the Orchestrator with required inputs and constraints.
• Orchestrator validates the plan, schedules, and issues a handoff to the Worker at the correct time.
• Worker executes and returns results to the Reviewer, while updating the source of truth.
• Reviewer validates results, updates plans if necessary, and notifies Planner for adjustments.
• Researcher or Domain Specialist can be consulted for complex domain-specific data or validations.

Tool Governance and Permission Rules

• Commands and API calls must originate from authenticated agents with scoped permissions.
• All file edits require a lock and audit trail; no direct production edits without approval.
• Secrets must be retrieved from a secure vault; never hard-coded.
• Production changes require approval gates and verification by the Orchestrator.
• External services are accessed through defined contracts with versioned interfaces.

Code Construction Rules

• All delays are expressed as non-negative durations with explicit units.
• All state transitions must be idempotent and reversible if possible.
• Validation is performed before any side-effect; failures should not mutate state.
• Inputs are validated against schemas; outputs must meet interface contracts.

Security and Production Rules

• Enforce least privilege for all agents; rotate credentials regularly.
• Audit all handoffs, executions, and approvals; store immutable logs.
• Implement circuit breakers for dependency failures; escalate when thresholds are breached.

Testing Checklist

• Unit tests for planner logic and scheduling edge cases.
• Integration tests for end-to-end delayed task execution and handoffs.
• Retry and backoff tests; idempotency verification for Worker actions.
• Security tests including secret access and approval gate behavior.
• Disaster recovery tests to verify rollback to last known good state.

Common Mistakes to Avoid

• Skipping the Orchestrator or bypassing the source of truth during handoffs.
• Treating delays as free-form; lacking strict timing constraints and retries.
• Allowing uncontrolled side effects during failures or rollbacks.
• Neglecting human review for edge cases or non-idempotent outcomes.

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

What is the purpose of this AGENTS.md Template for Delayed Job Processing?

To provide a complete operating manual for a delayed task workflow, outlining roles, handoffs, governance, and safety rules for single-agent and multi-agent orchestration.

Who should use this template?

Engineering leaders, AI operators, and product teams responsible for reliable delayed execution and multi-agent coordination.

How does handoff work between Planner, Orchestrator, and Worker?

The Planner generates a plan, the Orchestrator schedules and triggers the handoff, and the Worker executes at the assigned time with results returned to the Reviewer.

How are delays persisted and retried?

Delays are stored in a durable source of truth with defined retry/backoff policies; the Orchestrator handles retries and escalation on persistent failures.

How is security enforced in this workflow?

Access is role-based, secrets are vault-stored, and all interactions are audited and versioned.