Skip to content

ADR 003: Temporal for Workflow Orchestration

Status

Accepted

Context

Agent workflows (chained dispatch, fan-out, supervisor/worker, review loops) need durable execution with signal-based coordination, timeout handling, and retry policies.

Decision

Use Temporal.io as the workflow orchestration engine. Workflow definitions in Python using the Temporal SDK. Activities bridge to Django ORM for database operations and to the dispatch pipeline for task creation.

Consequences

  • Workflows are deterministic — no ORM calls, HTTP requests, or random numbers directly in workflow code. All side effects go through activities.
  • Signal-based coordination: task callbacks send Temporal signals, human gates wait for operator signals
  • Activities use run_in_executor to bridge synchronous Django ORM operations into async Temporal activities
  • 6 workflow patterns: TemplateExecution (generic), SingleDispatch, ChainedDispatch, FanOut, SupervisorWorker, ReviewCritiqueLoop, Advisor
  • Adding the Temporal server to docker-compose adds infrastructure complexity but provides durable execution, automatic retry, and visibility via Temporal UI
  • Worker process runs separately from Django — temporal_worker.py entry point