Jeffrey Smith
748da6c2b4
Custom team roles: removed CHECK constraint on team_members.role, roles stored in teams.settings, roles API, stage_config.required_role enforced on claim. Multi-party signoff: workflow_signoffs table, validation gate in advanceInternal, SubmitSignoff engine method, signoff HTTP API. Frontend: dynamic role management, stage config validation UI, signoff panel. Design docs for extension lifecycle and trigger composition. 20 store tests passing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2.4 KiB
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.completedtrigger →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.