BPMN workflow engine
Run a declared BPMN process as an instance: workflow_start opens one for a subject, workflow_next reports what is enabled, workflow_complete records a step or answers a decision (a DMN-computed one from facts) and REFUSES a step that is not enabled. State is committed under the work plan, so which edge was taken is a record, not a memory.
Skills it satisfies
A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.
process-state
Track where you are inside a running process — which task, in which swimlane, under which role — and recover deliberately when you find yourself outside it. Read before completing a workflow step, and whenever something unexpected interrupts one. Covers what to do about notes and stickies you re-anchored while off-process, which leave no trace in the artefact.
Source: cat-harness/skills/process/workflow/process-state.md.
Also satisfied by: workflow-complete, workflow-gate, workflow-list, workflow-next, workflow-start.
The skill declares no I/O contract (schemas/skills/process-state/{input,output}.schema.json).
Inputs and outputs
Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | process | ProcessId | yes | The process to run: a diagram’s file stem or its bpmn:process id. | string · pattern ^[a-z][a-z0-9-]*$ · A BPMN process id, e.g. crdm-requirements |
| in | node | NodeId | The step or decision to complete, as workflow_next reported it. | string · pattern ^[A-Za-z_][A-Za-z0-9_-]*$ · A node id within a BPMN process, e.g. A_Implement | |
| out | enabled | NodeId | What may be worked next, after each call. | string · pattern ^[A-Za-z_][A-Za-z0-9_-]*$ · A node id within a BPMN process, e.g. A_Implement |
Processes and tasks
No process step names a skill this Tool satisfies.
How it is deployed and reached
- MCP. Served as
workflow_*bysage(cat-harness-tools/scripts/sage-mcp.sh),google-drive(cat-harness-tools/scripts/google-drive-mcp.sh),folio-assistant(bun run cat-harness-tools/src/index.ts --stdio --repo .), the servers.mcp.jsondeclares. - In process.
src/tools/workflow.ts, registered byregisterWorkflowTools— loaded by the harness directly, with no server. - GitHub Actions. No workflow in this checkout runs its command.
The MCP tools it serves, as tools/list answers:
workflow_complete — read from its registrar.
| parameter | type | required | description |
|---|---|---|---|
instance | string | yes | |
node | string | yes | Node id from workflow_next, e.g. Task_DraftEdit |
outcome | string | For a decision a person makes — one of the outcomes workflow_next listed | |
facts | object | For a decision workflow_next reported as computed by <table>: the values it reads, e.g. { failCritical: 0, failMajor: 2 } from qa_sweep totals. The table returns the branch — do not pass outcome for these. | |
actor | string | Who you say did it, written to the history. Authorization is decided on the principal GitHub vouches for (owner or collaborator), in strict mode, before the step is recorded | |
target | string | The content the step acted on: a block id, path or bean id | |
note | string | What happened, for the instance history | |
activities | —[] | PROV-O activities a Tool returned while doing this step, verbatim (e.g. skill_update’s activity). Kept on the step’s history entry; each must name this step as its plan |
workflow_gate — read from its registrar.
| parameter | type | required | description |
|---|---|---|---|
instance | string | yes | |
activity | string | yes | Node id, e.g. Task_Commit |
actor | string | Who you say would perform it. Recorded only: strict mode authorizes the principal GitHub vouches for | |
target | string | The content it would act on: a block id, path or bean id |
workflow_list — read from its registrar.
It takes no parameters.
workflow_next — read from its registrar.
| parameter | type | required | description |
|---|---|---|---|
instance | string | yes | Instance id, from workflow_start or workflow_list |
workflow_start — read from its registrar.
| parameter | type | required | description |
|---|---|---|---|
process | string | yes | File stem, e.g. editing-hci-validation, or the bpmn:process id |
subject | string | yes | What this run is about — a block label, a release name |
bean | string | Bean id this work is tracked under | |
plan | string | Work plan this run is part of: the id of an epic or milestone whose process: tag names this process. Optional; not every process needs a plan |
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun |
| network | no |
| when to choose it | |
|---|---|
| when | Work follows a declared process and its order must be enforced and recorded: a step done out of order should be refused, not just discouraged. |
| limits | Reached over MCP; an agent without the server can walk the generated checklist (bpmn-checklist) by hand, but nothing then refuses a wrong turn. |
| cost | One diagram load per call; state is a small committed file. |
What it is made of
| role | file | |
|---|---|---|
| definition | cat-harness-tools/tools/bpmn-engine/bpmn-engine.ts | |
| in-process module | cat-harness-tools/src/tools/workflow.ts |
Its module imports, one hop:
cat-harness-tools/schemas/kg/memory-record.tscat-harness-tools/schemas/process/role-graph.tscat-harness-tools/scripts/known-skills.tscat-harness-tools/src/core/access.tscat-harness-tools/src/core/github-auth.tscat-harness-tools/src/core/handover-screen.tscat-harness-tools/src/logging/log-writer.tscat-harness-tools/src/workflow/authorize.tscat-harness-tools/src/workflow/bean-link.tscat-harness-tools/src/workflow/gate.tscat-harness-tools/src/workflow/instance.tscat-harness-tools/src/workflow/preflight.tscat-harness-tools/src/workflow/process-files.tscat-harness-tools/src/workflow/process-model.tscat-harness-tools/src/workflow/store.tscat-harness-tools/src/workflow/work-context.tscat-harness-tools/src/workflow/work-plan-store-select.tscat-harness-tools/src/workflow/work-plan-store.ts
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/cat-harness-tools/tools/bpmn-engine.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.
{
"@context": "https://litlfred.github.io/folio-assistant/cat-harness-tools/cat-harness-tools.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/cat-harness-tools/tools/bpmn-engine.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/cat-harness-tools/cat-harness-tools.jsonld",
"name": "bpmn-engine",
"title": "BPMN workflow engine",
"description": "Run a declared BPMN process as an instance: `workflow_start` opens one for a subject, `workflow_next` reports what is enabled, `workflow_complete` records a step or answers a decision (a DMN-computed one from `facts`) and REFUSES a step that is not enabled. State is committed under the work plan, so which edge was taken is a record, not a memory.",
"install": {
"none": true
},
"invoke": {
"mcp": {
"tool": "workflow_*"
},
"inProcess": {
"module": "src/tools/workflow.ts",
"register": "registerWorkflowTools"
}
},
"io": {
"inputs": [
{
"name": "process",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ProcessId",
"description": "The process to run: a diagram's file stem or its `bpmn:process` id.",
"required": true
},
{
"name": "node",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/NodeId",
"description": "The step or decision to complete, as `workflow_next` reported it.",
"required": false
}
],
"outputs": [
{
"name": "enabled",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/NodeId",
"description": "What may be worked next, after each call."
}
]
},
"satisfies": [
"process-state"
],
"requirements": {
"runtime": [
"bun"
],
"network": false
},
"selection": {
"when": "Work follows a declared process and its order must be enforced and recorded: a step done out of order should be refused, not just discouraged.",
"limits": "Reached over MCP; an agent without the server can walk the generated checklist (`bpmn-checklist`) by hand, but nothing then refuses a wrong turn.",
"cost": "One diagram load per call; state is a small committed file."
}
}