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>
58 lines
2.4 KiB
Markdown
58 lines
2.4 KiB
Markdown
# 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.
|