Agent instruction:

Model the unhappy path. Use `flows_to` edge props with `kind: "exception"` or `kind: "timer"` to route failures, rejections, and timeouts to a recovery step or an explicitly cancelled terminal State, so the process documents what happens when the happy path does not hold.

Agent instruction:

Rework and retry loops are allowed: a `flows_to` edge may target an earlier flow node to send work back (revise-and-resubmit, fix-and-recheck). Route the loop back through a gateway Decision so the cycle has an explicit exit and can't spin forever. A single edge still renders source -> target — a loop is about where the edge points, not reversing its direction.

Agent instruction:

A node belongs in process when it describes a workflow — a sequence of steps with actors and an outcome — or a policy/guard for one. Workflows can be commercial, operational, or personal; what matters is that the work is repeatable and the steps can be named. Pass when the candidate describes a step, gateway, milestone, validation, reference, or policy for such a workflow. Fail only when the candidate is a one-off incident with no repeatable structure, a UI-specific user journey, or a pure state machine without a workflow outcome.

when node type

action, decision, eval, reference

on violation

warn

Allowed node types

node types

action, decision, state, eval, reference, rule, principal

on violation

block

Allowed edge types

edge types

flows_to, has_parent, supports, attributed_to, constrained_by, replaces, derived_from

on violation

block

Agent instruction:

Check the candidate's visible user-facing text fields, including name, action, decision, question, chosen, state, rule, and eval text. PASS when the text reads as business-process language for an operator or process reader, and any BPMN/source/import/code-evidence details are absent from visible prose or kept only in structured metadata, References, or audit/history. FAIL when visible text contains raw import scaffolding or implementation/source metadata, including phrases or patterns like "BPMN gateway", "BPMN task", "Gateway_...", "Implementation status", "Code evidence", "Source type", "exclusiveGateway", "user asks:", raw BPMN ids, generated object ids, or notes about code evidence discovered during import. Do not fail merely because a real business term happens to mention a job type, gateway, source, or implementation in ordinary process language; fail only when the prose exposes importer/debug/source metadata instead of the process meaning.

when node type

action, decision, state, eval, rule, principal

fires on lifecycle

queued, active

on violation

block

Agent instruction:

Check the Principal's `prose`. PASS when it clearly names a process actor — a role, team, external party, or system — and explains what responsibility or boundary it owns in this process. FAIL if it reads like an uncontextualized org-chart person, a vague label (`user`, `team`, `system`) with no process responsibility, or an empty shell with only a bare name.

when node type

principal

on violation

warn

Agent instruction:

Model a process as an Action that names the whole repeatable activity (a verb + object, e.g. `publish a job`) and give it member flow nodes via `has_parent` edges pointing at it. A step that is itself a whole process becomes a subprocess automatically — it is a member Action that also has its own `has_parent` children; do not create a separate purpose node for it.

Requires edge

edge type

attributed_to

target

principal

when node type

action, decision

fires on lifecycle

queued, active

on violation

block

Limits edge

edge type

attributed_to

target

principal

max count

1

when node type

action, decision

fires on lifecycle

queued, active

on violation

block

Requires edge

edge type

has_parent

target

action

direction

outgoing

exempt when field set

top_level

when node type

action, decision, state

fires on lifecycle

queued, active

on violation

block

Limits edge

edge type

has_parent

target

action

max count

1

when node type

action, decision, state

fires on lifecycle

queued, active

on violation

block

Requires edge

edge type

flows_to

direction

incoming

exempt when field set

entry_point, top_level

when node type

action, decision, state

fires on lifecycle

queued, active

on violation

block

Requires edge

edge type

flows_to

direction

outgoing

exempt when field set

exit_point, top_level

when node type

action, decision, state

fires on lifecycle

queued, active

on violation

block

Agent instruction:

Check the Action's `prose` and `verb`. PASS when the text names a single business activity the named actor performs — an ordinary single-verb step like `review the legal terms`, `approve the invoice`, or `pack the order` PASSES. FAIL with reason only if the text (a) is a vague umbrella phase covering many steps (e.g. `handle request`, `do the thing`, `process order`), (b) bundles two distinct activities joined by `and` (e.g. `examine and treat the patient`), or (c) is an implementation chore divorced from business meaning (e.g. `call API`, `update row`, `write to DB`).

when node type

action

fires on lifecycle

queued, active

on violation

warn

Agent instruction:

Check the node's `prose` — the process canvas renders it as this flow node's box label. PASS when it reads as a concise label: a verb+object (`publish a job`), a noun phrase, or a milestone phrase (`invoice approved`). FAIL with reason when it is a run-on sentence that strings several steps or conditions together (e.g. `all steps from asking to post a job through to the published job post being confirmed`) or stuffs a paragraph of detail into the name; suggest leading with a short headline and moving the detail into a supporting field or Reference.

when node type

action, decision, state

on violation

warn

Requires edge

edge type

flows_to

min count

2

when node type

decision

fires on lifecycle

queued, active

on violation

block

Agent instruction:

Check the Decision's `question`, `alternatives`, and any outgoing `flows_to` branch labels/conditions. PASS when the question reads as yes/no or an enumeration, AND the alternatives / outgoing branches either include an explicit default/else branch or name every enumerated value. FAIL with reason if the question has uncovered cases or if a default/else is missing where enum coverage isn't visibly complete.

when node type

decision

fires on lifecycle

queued, active

on violation

block

Unique field

field

state

case-insensitive

yes

when node type

state

fires on lifecycle

queued, active

on violation

block

Agent instruction:

Check ONLY the State's `state`. PASS when the text reads as a milestone or entry/exit condition — a noun or past-participle (`invoice approved`, `payment captured`, `cart`, `awaiting-review`). FAIL with reason if it reads as an imperative verb naming an Action (`Approve invoice`, `Process the order`).

when node type

state

fires on lifecycle

queued, active

on violation

block

Requires edge

edge type

supports

when node type

eval

fires on lifecycle

queued, active

on violation

block

Agent instruction:

BPMN vocabulary — an edge's meaning comes from its type plus the node types it connects, not from any role tag: `flows_to` is process order and renders source -> target with no reversal; a `has_parent` edge from a flow node to a process Action places it in that process's pool (and makes the parent Action a process, or a subprocess if it has a parent of its own); an `attributed_to` edge to a Principal drives actor lanes (from an Action), gateway deciders (from a Decision), and process ownership (from the process Action); a `constrained_by` edge to a Rule links a policy guard; a `supports` edge from an Eval tests the node it points at, and `supports` edges from other nodes carry rationale and evidence.

Agent instruction:

For parallel work, give one flow node multiple unconditional `flows_to` outgoing edges — an AND-split needs no gateway Decision. Reserve gateway Decisions for exclusive or conditional (XOR/inclusive) branching, and reconverge parallel branches on a shared downstream node.

Agent instruction:

Relationships in a process Doco are first-class edges with lifecycle and history. Use `flows_to` for process order and the canonical families (`supports`, `attributed_to`, `constrained_by`, `has_parent`, `derived_from`, `replaces`, `relates_to`); an edge's specialized meaning comes from its type plus the node types it connects, not from a role tag. Re-point by retiring the old edge and adding the new one; endpoints are immutable.

Agent instruction:

Use `queued` for a process — or a single step, gateway, or milestone — that is fully wired and ready but not yet in force: a redesign awaiting sign-off, a step pending a scheduled go-live, or an approved-but-not-yet-rolled-out change. A `queued` node asserts readiness, so it must already satisfy the same actor attribution, `has_parent` process membership, and forward-flow wiring an `active` node does. If it is still being sketched and that wiring is incomplete, leave it `drafting` instead of queuing it.

Agent instruction:

Process *instances* (recorded runs) live in a separate Doco as Logs; surface them here only via References. This template describes the design of the process, not the history of its executions.

Agent instruction:

Don't model every click, method call, or DB mutation — only the steps that mean something to a business operator. Implementation detail belongs in `apis` or code Docos, not here.