core/docs/DESIGN-TRIGGER-COMPOSITION.md

Trigger Composition: Triggers, Schedules, and Workflows

Overview

Three automation primitives exist in the platform: triggers (event-driven), schedules (time-driven), and workflows (multi-step state machines). This document defines how they compose without creating circular dependencies.

Composition Rules

Triggers can start workflows

A trigger's Starlark handler may call workflow.start(workflow_id, data) to create a new workflow instance. This is the primary entry point for event-driven workflow initiation.

Example: a ticket.created trigger fires and starts an approval workflow.

Schedules can start workflows

A schedule's Starlark handler may also call workflow.start(...). This enables time-based batch processing workflows.

Example: a daily 9am schedule starts a standup collection workflow.

Workflows emit events that triggers listen to

Workflow lifecycle events (workflow.started, workflow.advanced, workflow.completed, workflow.signoff, etc.) are published on the event bus. Triggers may subscribe to these events to perform side effects (notifications, external API calls, audit logging).

Workflows cannot start triggers or schedules

Workflows do not directly invoke triggers or create schedules. Workflow Starlark hooks operate within the workflow's own context and do not have access to trigger/schedule management APIs. This prevents uncontrolled fan-out.

Circular Invocation Guard

The automated stage cycle guard (max 10 consecutive automated stages) already prevents infinite loops within a single workflow. Cross-workflow cycles are prevented by this rule:

A workflow event handler (trigger) may start a new workflow instance, but the new instance is not processed synchronously. It enters the work queue as a separate execution context. The bus does not re-enter the originating workflow's advance call.

This means:

• workflow.completed trigger → workflow.start(B) is allowed (async).
• Workflow A automated stage → workflow.start(B) where B immediately completes and triggers A again → allowed but rate-limited by the cycle guard on each individual workflow.

Not Supported (by design)

• Triggers cannot modify a running workflow instance (read-only access via Starlark builtins).
• Schedules cannot advance or cancel workflow instances directly.
• Workflows cannot create, modify, or delete triggers or schedules.

These restrictions keep the composition model simple and auditable.