Agent instructions

These instructions teach an AI agent to read and write Instant Process code. Give them to your own agent as part of its instructions. The assistant in the Instant Process editor works from the same instructions.

The language

Instant Process describes a process as a graph. Each line declares one node and links it to the nodes that follow. The node types are START, END, END-TERMINATE, ACTIVITY, the GATEWAY keywords, the EVENT keywords, SUBPROCESS, DATA, DATABASE and TEXT. LANE and POOL lines group the nodes that follow them. The Cheatsheet lists every keyword, and the Formal specification is the authoritative grammar.

Rules for writing code

• Every START line carries NEXT. START 'Request received' on its own is a compile error. Write START 'Request received' NEXT to link to the next node in the text, or START 'Request received' NEXT '<target>'.
• A node line has at most one NEXT, one NEXT-MESSAGE and one NEXT-ASSOCIATION. For each keyword, <keyword> <target> and a bare <keyword> (a link to the next node in the text) exclude each other. More targets follow with AND, never with a repeated keyword. AND extends the <keyword> <target> it follows and never starts a new clause.
• In NEXT and AND, the target comes first and the label second: NEXT <target> '<label>'. The first token after NEXT or AND is always the target node. The optional second quoted string is always the label on the link.
  • Correct: GATEWAY 'Choice' NEXT 'Done' 'yes' AND 'Retry' 'no'. On yes the flow goes to Done, on no to Retry.
  • Wrong: GATEWAY 'Choice' NEXT 'yes' 'Done' AND 'no' 'Retry'. It links to nodes named yes and no, which do not exist.
  • Read NEXT 'Done' 'yes' as "go to Done, along the yes link": the destination comes before the name of the link, like an envelope addressed to the recipient before the note inside.
  • A target matches an existing node exactly: its description in quotes (NEXT 'Do work' 'retry') or its explicit identifier (NEXT DoWork 'retry'). A paraphrased or shortened description does not resolve. A No node with id '<label>' warning almost always means the target and the label are swapped.
• A node's description is its identifier. Add an explicit identifier only when two nodes would otherwise resolve to the same identifier: two equal descriptions, or more than one START. Never add an identifier a node does not need.
• END and END-TERMINATE carry no links.

Message flows, associations and text annotations

• A message flow is written with NEXT-MESSAGE in the place of NEXT. A message flow carries information between two parties: an order form sent to a supplier, an invoice sent back. Example: ACTIVITY 'Send invoice' NEXT-MESSAGE 'Receive invoice' 'Invoice'. Target, label and AND chain follow NEXT-MESSAGE exactly as they follow NEXT, and every target in its AND chain is a message flow. A bare NEXT-MESSAGE makes the link to the next node in the text a message flow. A node that sends both kinds carries both clauses on one line: GATEWAY 'Approved?' NEXT 'Ship order' 'Yes' NEXT-MESSAGE 'Notify customer' 'No'. A message flow is an exchange of information, never the order in which work happens. The Dutch keyword is VOLG-BERICHT.
• An association is written with NEXT-ASSOCIATION in the place of NEXT. An association ties a node to information that belongs with it, outside the flow: a policy a decision follows, a document a task refers to. Example: ACTIVITY 'Check order' NEXT 'Ship order' NEXT-ASSOCIATION 'Order policy'. An association is never the order in which work happens. The Dutch keyword is VOLG-ASSOCIATIE.
• A remark that explains a step, and is not itself work, is a TEXT line naming that step. Example: TEXT 'Orders above 500 euro need a second approval' NEXT 'Approve order'. It stands after the step it names, in that step's lane. Every link of a TEXT line is an association, written with NEXT; a TEXT line never carries NEXT-MESSAGE. The Dutch keyword is TEKST.

Pools and lanes

• Pools are the participants, lanes are the roles inside one participant. A pool is an organisation or an independent party: the customer, the shop, a carrier. A lane is a role or department inside one pool: sales, the warehouse, a manager.
• A new process for two or more independent parties uses one POOL per party, with lanes inside a pool for its roles. A new process inside one person or one organisation uses lanes for its roles, or no lanes at all, and no POOL.
• A process either starts with POOL or contains no POOL at all. Existing code without POOL stays without pools unless the user asks for them, and its lanes are edited as they are.
• Every node and lane after a POOL line belongs to that pool until the next POOL line. A pool either declares lanes or holds its nodes directly. Declaring a lane again returns the flow to it.
• Inside a pool, steps link with NEXT. Every link between two pools is a message flow, written with NEXT-MESSAGE. A step that sends a message and continues its own work carries both clauses: NEXT '<own next step>' NEXT-MESSAGE '<step in the other pool>' '<message>'.
• A party whose own steps are unknown is an empty pool, and a link names it directly: ACTIVITY 'Ship order' NEXT-MESSAGE 'Carrier' 'Parcel' with POOL 'Carrier' declared. A pool sends a message with its own clause: POOL 'Carrier' NEXT-MESSAGE 'Confirm delivery'. A pool never carries a bare NEXT-MESSAGE.

Subprocesses

SUBPROCESS 'Label' PROCESS '<process id>' references another process. The process id comes from the user, from the current process code, or from a search of the user's processes. Never invent a process id. When several processes match the name the user gave equally well, ask which one is meant. When none matches, say so and write no SUBPROCESS line.

Writing a complete process

Plan a new process before writing it:

1. Decide the scope: the trigger that starts the process, the outcomes that end it, the pools (the parties that take part) and the lanes (the roles inside each pool).
2. List every step in order, per lane. For each step, ask what can go differently: a choice the party makes, a check that can fail, a condition that changes what comes next. Each of those is a decision; list its outcomes and where each outcome leads.
3. List the message flows between pools.
4. Check that every NEXT and AND target in the plan is a node the plan declares, spelled exactly as declared.

A complete process models the flow as it runs in practice: every step the parties take, and a decision wherever the real flow branches, each outcome leading somewhere. Each activity is one action one party performs. A complete process is never a minimal example of a start, one or two steps and an end, unless the user asks for exactly that.

Write the whole process at once, not as a skeleton filled in later.

Editing an existing process

• Change only what the request asks for. Add or suggest other changes only when the user asks for improvements.
• A process the user provides is followed exactly, even where it could be modelled differently.
• The lanes, pools and steps the user names are the ones the process uses, over any default above.
• Moving steps into another lane inserts a LANE line before them and declares the original lane again after them, so the steps that follow stay where they were.
• A renamed node is renamed in every link that targets it.

Examples

Each example compiles.

A complete small process

Two lanes, a database, a decision and two outcomes.

LANE Customer
START 'Order placed' NEXT
ACTIVITY 'Pay order' NEXT
LANE Shop
DATABASE 'Stock' NEXT 'Check stock'
ACTIVITY 'Check stock' NEXT
GATEWAY-EXCLUSIVE 'In stock?' NEXT 'Ship order' 'Yes' AND 'Refund order' 'No'
ACTIVITY 'Ship order' NEXT
END 'Order delivered'
ACTIVITY 'Refund order' NEXT
END 'Order refunded'

Lanes

A lane declared again returns the flow to it.

LANE Customer
START 'Need a quote' NEXT
ACTIVITY 'Request quote' NEXT
LANE Sales
ACTIVITY 'Prepare quote' NEXT
ACTIVITY 'Send quote' NEXT
LANE Customer
END 'Quote received'

Pools with a message flow

Two participants. The order form travels between them as a message flow.

POOL Customer
START 'Wants a product' NEXT
ACTIVITY 'Place order' NEXT-MESSAGE 'Process order' 'Order form' NEXT
END 'Order placed'
POOL Shop
START 'Order arrives' NEXT
ACTIVITY 'Process order' NEXT
END 'Order processed'

A parallel split and join

Two paths run at the same time and join before the end.

START 'Order confirmed' NEXT
GATEWAY-PARALLEL 'Split' NEXT 'Pack goods' AND 'Send invoice'
ACTIVITY 'Pack goods' NEXT 'Join'
ACTIVITY 'Send invoice' NEXT 'Join'
GATEWAY-PARALLEL 'Join' NEXT
END 'Order complete'

A text annotation

A remark that explains a step.

START 'Claim filed' NEXT
ACTIVITY 'Assess claim' NEXT
END 'Claim settled'
TEXT 'Within five working days' NEXT 'Assess claim'