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.

porttyperequireddescriptionconstraint
inprocessProcessIdyesThe 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
innodeNodeIdThe 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
outenabledNodeIdWhat 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_* by sage (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.json declares.
  • In process. src/tools/workflow.ts, registered by registerWorkflowTools — 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.

workflow_complete [1..1]bpmn-engine«tool»bpmn-engineworkflow_complete : WorkflowCompleteInput [1..1]WorkflowCompleteInput«json-schema»WorkflowCompleteInputinstance : string [1..1]node : string [1..1]outcome : string [0..1]facts : object [0..1]actor : string [0..1]target : string [0..1]note : string [0..1]activities : unknown[] [0..*]
parametertyperequireddescription
instancestringyes
nodestringyesNode id from workflow_next, e.g. Task_DraftEdit
outcomestringFor a decision a person makes — one of the outcomes workflow_next listed
factsobjectFor 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.
actorstringWho 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
targetstringThe content the step acted on: a block id, path or bean id
notestringWhat 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.

workflow_gate [1..1]bpmn-engine«tool»bpmn-engineworkflow_gate : WorkflowGateInput [1..1]WorkflowGateInput«json-schema»WorkflowGateInputinstance : string [1..1]activity : string [1..1]actor : string [0..1]target : string [0..1]
parametertyperequireddescription
instancestringyes
activitystringyesNode id, e.g. Task_Commit
actorstringWho you say would perform it. Recorded only: strict mode authorizes the principal GitHub vouches for
targetstringThe 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.

workflow_next [1..1]bpmn-engine«tool»bpmn-engineworkflow_next : WorkflowNextInput [1..1]WorkflowNextInput«json-schema»WorkflowNextInputinstance : string [1..1]
parametertyperequireddescription
instancestringyesInstance id, from workflow_start or workflow_list

workflow_start — read from its registrar.

workflow_start [1..1]bpmn-engine«tool»bpmn-engineworkflow_start : WorkflowStartInput [1..1]WorkflowStartInput«json-schema»WorkflowStartInputprocess : string [1..1]subject : string [1..1]bean : string [0..1]plan : string [0..1]
parametertyperequireddescription
processstringyesFile stem, e.g. editing-hci-validation, or the bpmn:process id
subjectstringyesWhat this run is about — a block label, a release name
beanstringBean id this work is tracked under
planstringWork 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.

installnone
runtimebun
networkno
when to choose it
whenWork follows a declared process and its order must be enforced and recorded: a step done out of order should be refused, not just discouraged.
limitsReached over MCP; an agent without the server can walk the generated checklist (bpmn-checklist) by hand, but nothing then refuses a wrong turn.
costOne diagram load per call; state is a small committed file.

What it is made of

Its module imports, one hop:

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."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev