ContractSpec docs

OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

workflow-system

State machine-based workflow engine with role-based approvals, delegation, and escalation

Type: feature

Version: 1.0.0

Stability: experimental

Owners: @workflow-team

Tags: workflow, approval, state-machine, automation

field.key.label: workflow-system
field.version.label: 1.0.0
field.type.label: feature
field.title.label: workflow-system
field.description.label: State machine-based workflow engine with role-based approvals, delegation, and escalation
Type: feature
Version: 1.0.0
Stability: experimental
Owners: @workflow-team
Tags: workflow, approval, state-machine, automation
field.tags.label: workflow,approval,state-machine,automation
field.owners.label: @workflow-team
field.stability.label: experimental

State machine-based workflow engine with role-based approvals, delegation, and escalation

Operations (18)

•

`workflow.definition.create` (v1.0.0)

•

`workflow.definition.update` (v1.0.0)

•

`workflow.step.add` (v1.0.0)

•

`workflow.definition.publish` (v1.0.0)

•

`workflow.definition.list` (v1.0.0)

•

`workflow.definition.get` (v1.0.0)

•

`workflow.instance.start` (v1.0.0)

•

`workflow.instance.transition` (v1.0.0)

•

`workflow.instance.pause` (v1.0.0)

•

`workflow.instance.resume` (v1.0.0)

•

`workflow.instance.cancel` (v1.0.0)

•

`workflow.instance.list` (v1.0.0)

•

`workflow.instance.get` (v1.0.0)

•

`workflow.approval.decide` (v1.0.0)

•

`workflow.approval.delegate` (v1.0.0)

•

`workflow.approval.comment.add` (v1.0.0)

•

`workflow.approval.list.mine` (v1.0.0)

•

`workflow.approval.get` (v1.0.0)

Events (17)

•

`workflow.definition.created` (v1.0.0)

•

`workflow.definition.updated` (v1.0.0)

•

`workflow.definition.published` (v1.0.0)

•

`workflow.step.added` (v1.0.0)

•

`workflow.instance.started` (v1.0.0)

•

`workflow.step.entered` (v1.0.0)

•

`workflow.step.exited` (v1.0.0)

•

`workflow.instance.completed` (v1.0.0)

•

`workflow.instance.cancelled` (v1.0.0)

•

`workflow.instance.paused` (v1.0.0)

•

`workflow.instance.resumed` (v1.0.0)

•

`workflow.instance.failed` (v1.0.0)

•

`workflow.instance.timedOut` (v1.0.0)

•

`workflow.approval.requested` (v1.0.0)

•

`workflow.approval.decided` (v1.0.0)

•

`workflow.approval.delegated` (v1.0.0)

•

`workflow.approval.escalated` (v1.0.0)

Presentations (11)

•

`workflow.designer` (v1.0.0)

•

`workflow.definition.viewList` (v1.0.0)

•

`workflow.definition.detail` (v1.0.0)

•

`workflow.instance.viewList` (v1.0.0)

•

`workflow.instance.detail` (v1.0.0)

•

`workflow.instance.progress` (v1.0.0)

•

`workflow.approval.inbox` (v1.0.0)

•

`workflow.approval.detail` (v1.0.0)

•

`workflow.approval.form` (v1.0.0)

•

`workflow.approval.badge` (v1.0.0)

•

`workflow.metrics` (v1.0.0)

Source Definition

1/**
2 * Workflow System Feature Module Specification
3 *
4 * Defines the feature module for workflow and approval capabilities.
5 */
6import { defineFeature } from '@lssm-tech/lib.contracts-spec';
7import { WorkflowVisualizationRefs } from './visualizations';
8
9/**
10 * Workflow System feature module that bundles workflow definition,
11 * instance management, and approval handling into an installable feature.
12 */
13export const WorkflowSystemFeature = defineFeature({
14	meta: {
15		key: 'workflow-system',
16		title: 'Workflow & Approval System',
17		description:
18			'State machine-based workflow engine with role-based approvals, delegation, and escalation',
19		domain: 'workflow',
20		owners: ['@workflow-team'],
21		tags: ['workflow', 'approval', 'state-machine', 'automation'],
22		stability: 'experimental',
23		version: '1.0.0',
24	},
25
26	// All contract operations included in this feature
27	operations: [
28		// Workflow definition operations
29		{ key: 'workflow.definition.create', version: '1.0.0' },
30		{ key: 'workflow.definition.update', version: '1.0.0' },
31		{ key: 'workflow.step.add', version: '1.0.0' },
32		{ key: 'workflow.definition.publish', version: '1.0.0' },
33		{ key: 'workflow.definition.list', version: '1.0.0' },
34		{ key: 'workflow.definition.get', version: '1.0.0' },
35
36		// Workflow instance operations
37		{ key: 'workflow.instance.start', version: '1.0.0' },
38		{ key: 'workflow.instance.transition', version: '1.0.0' },
39		{ key: 'workflow.instance.pause', version: '1.0.0' },
40		{ key: 'workflow.instance.resume', version: '1.0.0' },
41		{ key: 'workflow.instance.cancel', version: '1.0.0' },
42		{ key: 'workflow.instance.list', version: '1.0.0' },
43		{ key: 'workflow.instance.get', version: '1.0.0' },
44
45		// Approval operations
46		{ key: 'workflow.approval.decide', version: '1.0.0' },
47		{ key: 'workflow.approval.delegate', version: '1.0.0' },
48		{ key: 'workflow.approval.comment.add', version: '1.0.0' },
49		{ key: 'workflow.approval.list.mine', version: '1.0.0' },
50		{ key: 'workflow.approval.get', version: '1.0.0' },
51	],
52
53	// Events emitted by this feature
54	events: [
55		// Definition events
56		{ key: 'workflow.definition.created', version: '1.0.0' },
57		{ key: 'workflow.definition.updated', version: '1.0.0' },
58		{ key: 'workflow.definition.published', version: '1.0.0' },
59		{ key: 'workflow.step.added', version: '1.0.0' },
60
61		// Instance events
62		{ key: 'workflow.instance.started', version: '1.0.0' },
63		{ key: 'workflow.step.entered', version: '1.0.0' },
64		{ key: 'workflow.step.exited', version: '1.0.0' },
65		{ key: 'workflow.instance.completed', version: '1.0.0' },
66		{ key: 'workflow.instance.cancelled', version: '1.0.0' },
67		{ key: 'workflow.instance.paused', version: '1.0.0' },
68		{ key: 'workflow.instance.resumed', version: '1.0.0' },
69		{ key: 'workflow.instance.failed', version: '1.0.0' },
70		{ key: 'workflow.instance.timedOut', version: '1.0.0' },
71
72		// Approval events
73		{ key: 'workflow.approval.requested', version: '1.0.0' },
74		{ key: 'workflow.approval.decided', version: '1.0.0' },
75		{ key: 'workflow.approval.delegated', version: '1.0.0' },
76		{ key: 'workflow.approval.escalated', version: '1.0.0' },
77	],
78
79	// Presentations associated with this feature
80	presentations: [
81		// Definition
82		{ key: 'workflow.designer', version: '1.0.0' },
83		{ key: 'workflow.definition.viewList', version: '1.0.0' },
84		{ key: 'workflow.definition.detail', version: '1.0.0' },
85
86		// Instance
87		{ key: 'workflow.instance.viewList', version: '1.0.0' },
88		{ key: 'workflow.instance.detail', version: '1.0.0' },
89		{ key: 'workflow.instance.progress', version: '1.0.0' },
90
91		// Approval
92		{ key: 'workflow.approval.inbox', version: '1.0.0' },
93		{ key: 'workflow.approval.detail', version: '1.0.0' },
94		{ key: 'workflow.approval.form', version: '1.0.0' },
95		{ key: 'workflow.approval.badge', version: '1.0.0' },
96
97		// Dashboard
98		{ key: 'workflow.metrics', version: '1.0.0' },
99	],
100
101	// Link operations to their primary presentations
102	opToPresentation: [
103		{
104			op: { key: 'workflow.definition.list', version: '1.0.0' },
105			pres: { key: 'workflow.definition.viewList', version: '1.0.0' },
106		},
107		{
108			op: { key: 'workflow.instance.list', version: '1.0.0' },
109			pres: { key: 'workflow.instance.viewList', version: '1.0.0' },
110		},
111		{
112			op: { key: 'workflow.approval.list.mine', version: '1.0.0' },
113			pres: { key: 'workflow.approval.inbox', version: '1.0.0' },
114		},
115		{
116			op: { key: 'workflow.approval.decide', version: '1.0.0' },
117			pres: { key: 'workflow.approval.form', version: '1.0.0' },
118		},
119	],
120
121	// Target requirements for multi-surface rendering
122	presentationsTargets: [
123		{ key: 'workflow.designer', version: '1.0.0', targets: ['react'] },
124		{
125			key: 'workflow.definition.viewList',
126			version: '1.0.0',
127			targets: ['react', 'markdown'],
128		},
129		{
130			key: 'workflow.definition.detail',
131			version: '1.0.0',
132			targets: ['react', 'markdown'],
133		},
134		{
135			key: 'workflow.instance.viewList',
136			version: '1.0.0',
137			targets: ['react', 'markdown'],
138		},
139		{
140			key: 'workflow.instance.detail',
141			version: '1.0.0',
142			targets: ['react', 'markdown'],
143		},
144		{ key: 'workflow.instance.progress', version: '1.0.0', targets: ['react'] },
145		{
146			key: 'workflow.approval.inbox',
147			version: '1.0.0',
148			targets: ['react', 'markdown'],
149		},
150		{
151			key: 'workflow.approval.detail',
152			version: '1.0.0',
153			targets: ['react', 'markdown'],
154		},
155		{
156			key: 'workflow.metrics',
157			version: '1.0.0',
158			targets: ['react', 'markdown'],
159		},
160	],
161
162	visualizations: WorkflowVisualizationRefs,
163
164	// Capability requirements
165	capabilities: {
166		requires: [
167			{ key: 'identity', version: '1.0.0' },
168			{ key: 'audit-trail', version: '1.0.0' },
169			{ key: 'notifications', version: '1.0.0' },
170			{ key: 'feature-flags', version: '1.0.0' },
171		],
172		provides: [
173			{ key: 'workflow', version: '1.0.0' },
174			{ key: 'approval', version: '1.0.0' },
175			{ key: 'state-machine', version: '1.0.0' },
176		],
177	},
178
179	workflows: [
180		{ key: 'workflow-system.workflow.approval-chain', version: '1.0.0' },
181	],
182
183	telemetry: [{ key: 'workflow-system.telemetry', version: '1.0.0' }],
184
185	jobs: [
186		{ key: 'workflow-system.job.instance-timeout', version: '1.0.0' },
187		{ key: 'workflow-system.job.escalation', version: '1.0.0' },
188	],
189
190	docs: [
191		'docs.examples.workflow-system',
192		'docs.examples.workflow-system.goal',
193		'docs.examples.workflow-system.usage',
194		'docs.examples.workflow-system.constraints',
195	],
196});
197

Open system docs

workflow-system

Operations (18)

Events (17)

Presentations (11)

Source Definition