---
name: uipath-maestro-bpmn
description: "UiPath Maestro BPMN / Process Orchestration: author (registry-driven), validate, package, operate, and diagnose .bpmn projects. For .flow use uipath-maestro-flow; for case plans use uipath-maestro-case."
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
---

# Reasoning budget
- Match reasoning to step difficulty and bias toward acting; for mechanical / IO / format steps, if a
  provided script already covers the task, run it — don't re-derive it.
- Save deep, extended reasoning for the one genuinely hard judgment a script can't make for you.

# Working style
- **Understand first, then decide.** Read this skill's SKILL.md and understand the scripts it ships before you act. Then plan accordingly, such as run a script as-is when it fits, change a script when it's close, or write extra scripts to complement — based on what the scripts actually do, not a guess.
- **Plan the whole path up front, then chain.** Outline the full sequence of steps before running anything, batch independent steps into one turn, and pipeline the whole plan in as few turns as possible. Don't do things that can be pipelined into one call turn-by-turn.
- **Inspect an input ONCE.** To learn a file's structure (sheets/columns, pages, form fields, keys), dump it once — ideally to a file you then grep — never re-open the same file field-by-field or retry it with several libraries. A source image is the exception: look at it again whenever it is no longer visible in your context (see [Authoring from an image](#authoring-from-an-image)).
- **Don't repeat work.** Do not rerun a command when its inputs and relevant state are unchanged, and do not reread an unchanged file, script, or SKILL.md already in context. After a tool or command may modify a file, reread the affected content before relying on it.
- **Write code once and reuse.** If a step needs code, write it once as a small script (paths/params as CLI args) and call it; don't paste near-duplicate inline python across turns. Keep it terse — no comment banners or narration in inline scripts.
- **Keep outputs small.** Don't put large tool results and outputs into the context, instead write them into a file and use tools to inspect them. If there is no tool available, you should write your own scripts to inspect the file. To decide whether a row exists, filter CLI JSON by field (`jq select`), never truncate it (`head`, `sed -n`).
- **Don't do anything unnecessary.** Don't call tools, read files, or put results into context unless they're immediately needed.

# UiPath Maestro BPMN

Work with UiPath Maestro (Process Orchestration) `.bpmn` projects across their
lifecycle: author, validate, package, operate, and diagnose. **Authoring is
registry-driven for registered nodes**: their execution payloads come from
templates the registry serves. The structural BPMN and serializer-owned scaffold
metadata that hold those nodes together (process scaffold, variables, bindings,
entry points, sequence flows, gateways, events, boundary events, containers,
multi-instance markers, and the diagram) are authored from the documented spec
and canvas contract. Packaging, operating (upload, publish, run, manage), and
diagnosing are driven through the UiPath CLI, covered in the capability
references below.

## When to use

- Create a Maestro `.bpmn` from a description, or from an image of a process
  (sketch, whiteboard or sticky-note photo, screenshot of another diagram).
- Edit `.bpmn` structure: gateways, events, boundary events, subprocesses, call
  activities, multi-instance loops, sequence-flow conditions, variables.
- Add a UiPath extension node (RPA job, agent, HITL, queue, business rule, API
  workflow, Integration Service connector, internal message, timer).
- Validate a `.bpmn` against the canvas rules before import.
- Package, upload, publish, or run a project, and manage its jobs and instances.
- Diagnose a failed or misbehaving run.

### Editing an existing `.bpmn` (preserve what you did not author)

The skill can edit an existing file. If the edit introduces one of the shapes in
[Patterns](#patterns), use that guide — inserting a pattern into a running
process is a normal edit, not a reason to skip the shape. Make **surgical**
edits and preserve content you did not author: unknown `uipath:*` elements, `uipath:migrationVersion`,
tags, imported Integration Service payloads, and stable element IDs. Do not
regenerate the whole file or drop extension data the skill does not recognize —
preserve-only structures (see the blocklist in
[references/structural-bpmn.md](references/structural-bpmn.md#do-not-generate-for-new-authoring-preserve-on-round-trip-only)) round-trip
untouched. Never normalize existing nodes to this skill's canonical templates:
do not add missing attributes (e.g. `type="json" target="bodyField"` on an
existing `uipath:input`) to elements the edit does not target — on untouched
neighbors only wiring (`bpmn:incoming`/`bpmn:outgoing`) may change.

For an existing ScriptTask, preserve its mapping discriminator and
`uipath:scriptVersion`, and do not normalize a working brownfield node merely
because the new-node authoring contract differs. Migration requires explicit
confirmation — see
[references/structural-bpmn.md](references/structural-bpmn.md#script-tasks--jint-authoring-contract).

For `.flow` JSON use `uipath-maestro-flow`; for XAML/coded workflows use
`uipath-rpa`; for Python agents use `uipath-agents`; for Case plans use
`uipath-maestro-case`.

## The model

Two halves make a valid Maestro `.bpmn`:

1. **Registry-listed node payloads — registry-owned.** Each listed node's
   execution XML (`uipath:activity` / `uipath:event` / `uipath:mapping`, its
   `context`, `input`, `output`, and `bindingInfo`) comes from
   `uip maestro bpmn registry get <type>`'s `xmlTemplate`. **Never hand-author a
   registry-owned node payload from prose.**
2. **Structural BPMN and scaffold metadata — spec/canvas-owned.** The registry emits no
   `<bpmn:definitions>`/`<bpmn:process>`, no sequence flows, no gateway
   conditions/defaults, no event-definition payloads, no boundary-event
   attributes, no subprocess/loop structure, and no diagram. Serializer-owned
   scaffold extensions such as `uipath:variables`, `uipath:bindings`,
   `uipath:entryPointId`, and `uipath:migrationVersion` also come from this
   contract rather than a node template. Author these from
   [references/structural-bpmn.md](references/structural-bpmn.md), which is
   grounded in the registry spec, the CLI scaffold, and the canvas serializer.

## Patterns

Seven recurring process shapes, for building a new process and for extending
one that already runs. Each guide gives a worked-out topology — nodes, wiring,
gateway conditions, variables — and the reasoning behind it. Many topologies
pass validation for the same request; these are known-good shapes, not
specifications. Adapt them: add steps, drop branches, and change
counts as the process needs. Each guide's "Why it works" names the parts that
carry the shape — change those and you are building something else, so say so.
Read the guide for each pattern the process actually uses — one for a simple
process, several for a composed one — and none for a pattern you are not
building.

Every guide's shape table marks each node **Entry** (omit when inserting into a
process that already runs), **Mechanism** (changing it changes the pattern), or
**Placeholder** (bind it, or skip it if the process already does this). Author
the element the table names. A **Placeholder** whose target step 1 did not
resolve is that element with its registry payload and the identity slots left
as public placeholders, never a bare `bpmn:task` standing in for the work.

| Pattern | Reach for it when | Guide |
| --- | --- | --- |
| `ai-decision-review` | AI makes one call; act on it, or a human reviews it | [ai-decision-review-guide.md](references/patterns/ai-decision-review-guide.md) |
| `approval-chain` | A request needs sign-off from several people | [approval-chain-guide.md](references/patterns/approval-chain-guide.md) |
| `smart-triage` | Inbound work sorted into categories, each handled elsewhere | [smart-triage-guide.md](references/patterns/smart-triage-guide.md) |
| `external-wait` | The process waits on an outside party under an SLA | [external-wait-guide.md](references/patterns/external-wait-guide.md) |
| `high-volume-batch` | Many independent items processed in one run | [high-volume-batch-guide.md](references/patterns/high-volume-batch-guide.md) |
| `failure-escalation` | Unhandled failures must never disappear silently | [failure-escalation-guide.md](references/patterns/failure-escalation-guide.md) |
| `queue-distribution` | An Orchestrator queue hands work across runtimes | [queue-distribution-guide.md](references/patterns/queue-distribution-guide.md) |

**Do not reach for a pattern** when the ask is a short linear process, a single
node, or a change that does not introduce one of these shapes. A pattern is
never a wrapper to retrofit onto work that does not need one.

Using more than one pattern in one process? Read
[references/patterns/composing-guide.md](references/patterns/composing-guide.md)
first — which pattern keeps its start event, the four ways the rest join it, how
variables cross a nesting boundary, and the two placements the engine
constrains. A single pattern needs only its own guide.

## Authoring from an image

When the process comes from an image, the job is transcription: every item in the
image becomes a node and every visible connector becomes a flow. A plausible
process "inspired by" the image is not a transcription. The usual failure is
dropping and merging items while summarizing, then building from the summary.

1. **Inventory before you interpret.** Before proposing any topology, write
   down every visible item: its exact wording, its colour/shape, and its rough
   position. Then list every visible connector as source → target, with its
   label and whether it is certain or ambiguous. Mark unreadable or crossed-out
   items instead of guessing or skipping them. Keep this list in a notes file
   outside the project folder.
2. **Confirm the inventory, not a summary.** The structure you confirm under
   Rule 4 must list every node and flow from the inventory. Never offer a
   condensed or "interpreted" topology as the recommended option. Ask a
   separate question for each ambiguity, and for anything you would add that
   the image does not show (start/end events, merge gateways the canvas
   requires, a reading of an implied link).
3. **Transcribe 1:1.** One node per item, keeping the image's wording and its
   Yes/No branch labels. Add technical scaffolding only where the canvas
   requires it, and name each addition in your final report.
4. **Keep the image in view.** Earlier-turn images may leave your context:
   hosts can replace them with a text placeholder, especially after the user
   sends a new message. Before any fidelity work, including when the user says
   the result does not match, check that you can actually see the image. If
   you cannot, re-read it from its file path (the attachment path the host
   provided). If that also fails, ask the user to re-attach it. Never rebuild
   from memory of the image, from your earlier summary, or from a sub-agent's
   text description. If a sub-agent transcribed the image, check its result
   against the image yourself before editing.
5. **Verify fidelity before finishing.** After `validate` passes, look at the
   image again and compare it with the BPMN node by node and flow by flow.
   Report any remaining mismatch rather than calling the result done.
   Validation proves the file is structurally valid, not that it matches the
   image.

## Workflow

Work the six steps quickly, but keep the path matched to the user's ask. Treat
requests to discover before authoring, save raw registry JSON/evidence, or "do
not author yet" as discovery-only even if they describe an eventual BPMN. In
that mode, immediately create `registry-evidence/`, run and save `registry pull
--output json`, `registry list --output json` or `registry search ... --output
json`, and `registry get <type> --output json` for each requested type; do not
read deep authoring references or scaffold a project. For authoring asks, author
early: do not pre-read every reference before writing. Read a reference only
when you reach the structure it covers, and read only the section covering it —
[references/structural-bpmn.md](references/structural-bpmn.md) opens with a
section index naming every anchor. Get the needed templates, then write the
first complete draft before further spelunking.

For registry-evidence-only tasks, follow the command-first recipe in
[references/registry-workflow.md](references/registry-workflow.md#registry-evidence-only-tasks).

1. **Discover.** `uip maestro bpmn registry pull` **once** (cached for the
   session — do not re-pull), then `list` / `search` to map intent to extension
   types; `uip is connections list --all-folders` for live connections (always
   `--all-folders` — a folder-scoped list silently misses connections). Never
   fabricate an identifier; ask only under Rule 4, otherwise decide. Bind each
   connector node to an `Enabled` connection for its connector: the one in the
   folder the task names, else `IsDefault` `Yes`, else the first. Confirm it
   with `uip is connections ping <id> --output json` (`Data.Status` must be
   `Enabled`; the list's `State` is cached) and fall to the next candidate when
   it is not. Another owner is no reason to skip it; name each bound
   connection's Name, Owner, and Folder (never its Id) as a Rule 4 assumption.
   Use placeholders only when the user asked for a draft, a handoff, or
   placeholder, synthetic, public-safe, or sanitized values, or when no
   candidate pings `Enabled`.
   See [references/registry-workflow.md](references/registry-workflow.md).
2. **Get templates.** `uip maestro bpmn registry get <type> --output json` for
   each chosen registry-owned node only. Fetch every chosen template in **one**
   Bash call, not one command per turn — each shell round-trip is a model turn
   and dozens of them exhaust the run's time budget before authoring finishes:
   `for t in TypeA TypeB TypeC; do uip maestro bpmn registry get "$t" --output json; done`.
   Enrich `Intsvc.*` connector nodes with `--connection-id`/`--object-name`; take
   `--object-name` from the table in
   [references/registry-workflow.md](references/registry-workflow.md#picking-the-object-take-it-from-the-table-do-not-infer-it)
   — a connector exposes several objects per operation and `describe` does not
   rank them. Do not call `registry get` for structural
   gaps the registry never owns: sequence flows, gateways, events, boundary
   events, multi-instance/loop markers, `errorMapping`/retry structure, or
   diagrams. On every `bpmn:` tag you paste, opening and closing, lowercase
   the first letter after `bpmn:`: `<bpmn:UserTask>` → `<bpmn:userTask>`,
   `<bpmn:ServiceTask>` → `<bpmn:serviceTask>`. Preserve the `uipath:*`
   payload exactly.
   `BPMN.ScriptTask` is the registry lookup key, but a new node serializes
   `<uipath:type value="BPMN.Variables" version="v1" />` — never the lookup
   key. Local validation accepts the older discriminator, so a clean
   `validate` does not prove that mapping is right. For the compatibility
   fallback and its scope, see
   [references/structural-bpmn.md#script-tasks--jint-authoring-contract](references/structural-bpmn.md#script-tasks--jint-authoring-contract).
3. **Assemble.** Author directly from the complete minimal file in
   [references/structural-bpmn.md](references/structural-bpmn.md#a-complete-minimal-file-author-from-this-not-from-examples)
   plus each node's `xmlTemplate` (fill placeholders only). That skeleton shows
   a stable manual entry point, one structural task, and complete DI. **Do not
   reverse-engineer authoring patterns from task fixtures, generated package
   files, or any installed package bundle under `node_modules`** — such
   spelunking is the top reason authoring runs out of time.
   Add only the structural pieces your process needs (extra
   gateways, events, boundary events, containers, multi-instance markers,
   expression/error mappings, retry attributes). Leave the diagram to step 4;
   do not hand-author `bpmndi:*` while the source is still moving. For a new local project, initialize the
   supported scaffold with `uip maestro bpmn init <ProjectName> --output json`,
   edit at the returned `Data.Path`, and preserve its generated metadata. For a
   source-only draft the user has not asked to package or operate, pass
   `--skip-solution-registration` so no `*Solution/` wrapper or `.uipx` is
   created. `init` takes a project name, not a path, and writes under the
   current directory: `./<ProjectName>/` with that flag or inside an existing
   solution, `./<ProjectName>Solution/<ProjectName>/` otherwise.
<!--skill-flavor:named-solution-init:start-->
   When the user names a solution ("a solution of the same name" is
   `<ProjectName>`, not `<ProjectName>Solution`), create it and run `init`
   from inside it:

   ```bash
   uip solution init <SolutionName> --output json
   cd <SolutionName> && uip maestro bpmn init <ProjectName> --output json
   ```

   A `Data.AutoCreatedSolution` in the response means `init` ran outside the
   solution: re-run it from inside and report the stray directory.
<!--skill-flavor:named-solution-init:end-->
   To land a
   project at a path the user named, `mkdir -p` its parent and run `init` there
   with the leaf as the name — and either pass `--skip-solution-registration`
   or make that parent a solution first, because default `init` inserts a
   `<ProjectName>Solution/` level the requested path does not have. Check
   `Data.Path` against the requested path before editing. The
   init scaffold declares no `xsi` namespace: add
   `xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"` to
   `bpmn:definitions` before writing any `xsi:type` attribute. See
   [references/shared/local-metadata-regeneration-guide.md](references/shared/local-metadata-regeneration-guide.md).
   The runnable BPMN/start-event path belongs in lowercase `operate.json.main`,
   never `project.uiproj.main`.
   When adding draft or preserve-only case-management variants, include a real
   lowercase `<uipath:caseManagement version="v1">...</uipath:caseManagement>`
   payload with synthetic content as a separate preserve-only extension. Do not
   treat an `Orchestrator.StartCaseMgmtProcess*` typed activity shell as a
   substitute for that payload when the user asks to preserve case-management
   contract variants.
   When asked to preserve a generic unsupported `uipath:Activity`, write the
   actual capitalized element `<uipath:Activity version="v1">...</uipath:Activity>`.
   Do not write `<uipath:activity><uipath:type value="uipath:Activity" ... />`;
   that is a lowercase typed shell, not the preserve-only generic payload.
   When writing public-safe placeholders into XML attribute values, XML-escape
   angle brackets: use `&lt;TENANT_URL&gt;`, `&lt;FOLDER_KEY&gt;`, and
   `&lt;CONNECTION_NAME&gt;` in attributes. Raw `<PLACEHOLDER>` text is only safe
   in element text or CDATA; unescaped angle brackets inside attributes make the
   BPMN not well-formed.
   When routing on an Actions.HITL user task's outcome, the sequence-flow
   conditions from the exclusive gateway must reference the exact variable bound
   by the HITL template's `<uipath:output ... var="...">` (for example
   `=vars.Var_HitlResult == "approve"`), not only a copied or derived script
   variable.
   For an `Intsvc.*` activity whose `inputTarget` is `body`
   (`Intsvc.ActivityExecution` and its async, agent, and workflow variants),
   these rules override the template's `InputNotes`, `DiscoveryNotes`, and
   `ContextFieldNotes`:
   - **One body.** Exactly one `<uipath:input name="body" type="json"
     target="body">` holding the whole request object in CDATA, never one
     input per field and never a bare array. Dotted names nest
     (`fields.project.key` → `{"fields":{"project":{"key":…}}}`); `users[*]`
     is an array under `users` (`{"users":["U1","U2"]}`). See
     [Body shape](references/registry-workflow.md#body-shape-hand-authored-files-need-one-targetbody-input).
   - **Required `Parameters`.** Each `Required: true` entry (Slack `send_as`)
     is its own `uipath:input` with `target` set to its `Type`, after
     `</uipath:context>`, valued from the request, else its `DefaultValue`. See
     [Parameters](references/registry-workflow.md#required-parameters-are-separate-from-the-body--emit-every-one).
   - **`operation`** (`Intsvc.ActivityExecution` only) is the described
     `Operation.Name` (`Create`, `List`, `Retrieve`, `Update`, `Delete`,
     `Replace`), never the activity's `Name`.
   - **Data Service files** use `UploadFileToRecordField`,
     `DownloadFileFromRecordField`, and `DeleteFileFromRecordField`, never the
     `V2` objects `uip is resources list` shows. See
     [Picking the object](references/registry-workflow.md#picking-the-object-take-it-from-the-table-do-not-infer-it).
   - **`folderKey`** (`Intsvc.ActivityExecution` only). Keep the template's
     `folderKey` context input as `=bindings.<folderBindingId>` plus its
     folder binding on every node that binds a connection. Without it the run faults `102010` `Value cannot be
     null (Parameter 'Folder')`. See
     [Bindings](references/registry-workflow.md#4-bindings--from-bindinginfo-never-invented).
   - **Values.** A `Reference` field takes the looked-up id (Rule 2). A body
     value without a leading `=` is a literal: write `"=vars.<id>"`, and make
     text mixed with variables one `=js:` expression
     (`"=js:'Severity: ' + vars.Var_Severity"`).
   For an Integration Service draft or boundary handoff the user asked for (a
   request that only says to validate is not one), emit **only** the
   `.bpmn` plus the notes file — do NOT create the four generated package files
   (Rule 16); authoring them fails the boundary the task tests. The node itself
   is still authored: paste the registry's `Intsvc.*` template and keep the
   shell that template declares — `uipath:activity` for activities,
   `uipath:event` for `Intsvc.WaitForEvent` and `Intsvc.EventTrigger` (Rule 6)
   — plus its context and output, filling the resource identity slots with the
   escaped public placeholders. Event context references the connection as
   `connectionId`, activities as `connection`. A host element carrying neither
   shell, such as a bare `bpmn:sendTask` with no `uipath:activity`, is a
   missing node, not a draft. Only the resolved values are CLI-owned — see
   [references/registry-workflow.md](references/registry-workflow.md#2-get-the-template-for-each-chosen-type).
   For Integration Service draft notes, name every CLI-owned blocker literally,
   including the exact phrase `connection binding`, plus dynamic schemas,
   generated outputs, `bindings_v2.json`, and package metadata. Avoid softer
   wording such as "connection and process binding" because it hides the concrete
   artifact the CLI must supply.
   Run `uip maestro bpmn refresh <project-path>` after any edit that changes a
   start event id or adds or removes an entry point — **not only when packaging
   or operating**. Lay the diagram out first (step 4): `refresh` validates
   before it writes, so a node you just added fails it with `MISSING_DI_SHAPE`. `operate.json` and `entry-points.json` are generated once and
   do not follow source edits, so step 5's validator fails on the mismatch:
   `entry-points.json references start event "Event_start" via filePath, but no
   <bpmn:startEvent id="Event_start"> exists`. Authoring from the skeleton above
   renames the initializer's `Event_start`, so a source-only draft needs this
   too. Keep the output as written — that shape is the contract `pack` consumes.
   `refresh` requires an init-generated project: with no
   `project.uiproj` it fails `Required file is missing` / `RetryWillNotFix`.
   For a bare `.bpmn` (the shape of this repo's edit fixtures), write the
   two-key `project.uiproj` first — `{ "Name": "<ProjectName>",
   "ProjectType": "ProcessOrchestration" }` — then refresh, which writes the
   rest. Only fall back to the equivalent hand-authored shape in
   [references/shared/local-metadata-regeneration-guide.md](references/shared/local-metadata-regeneration-guide.md#source-only-fallback)
   when the CLI is unavailable. Do not copy CLI scaffold metadata shapes into a
   synthetic local project. Every root **manual** start event needs a
   `<uipath:entryPointId value="<uuid>" />` child in its `extensionElements`;
   without one `refresh` fails the whole project `RetryWillNotFix` instead of
   writing an empty entry-point list. A connector or timer start is not
   manual, so a project that runs `refresh` or `pack` keeps the initializer's
   manual start alongside it; only a source-only draft replaces it. Clearing
   the resulting stale-entry error by editing or deleting `entry-points.json`
   instead of running `refresh` passes `validate` and `pack` while shipping an
   empty `bindings_v2.json`.
   Give public inputs and outputs explicit runtime bridges, and converge routes
   returning one result on a single completion EndEvent — for the two-layer
   contract see
   [references/structural-bpmn.md](references/structural-bpmn.md#variables).
4. **Lay out the diagram.** After the last source edit, and before any
   `validate`, `refresh`, or `pack` — including the `refresh` step 3 calls for:

   ```bash
   uip maestro bpmn format <file.bpmn>
   ```

   It overwrites the file's `bpmndi:BPMNDiagram` in place, so the canvas
   renders the process arranged instead of stacked at the origin. Every
   deliverable gets this, source-only drafts included. It is also a hard
   precondition for the next two steps, not a cosmetic pass: a node with no
   `BPMNShape` or a flow with no `BPMNEdge` fails `validate` with
   `MISSING_DI_SHAPE` / `MISSING_DI_EDGE`, no diagram at all fails it with
   `BPMN_PARSE_ERROR`, and `refresh` validates before it writes, so it fails
   the same way. Edit the source again and the layout is stale — re-run this
   step before re-validating. If `format` reports `unknown command`, update the
   CLI (see [references/cli-conventions.md](references/cli-conventions.md)); if
   upgrading is unavailable, hand-author the fallback DI structure in
   [references/structural-bpmn.md](references/structural-bpmn.md).
5. **Validate.** Check well-formedness first. `validate` tokenizes with a
   tolerant parser and reports `Valid` on XML with an unbound namespace
   prefix, so a `ParseError` here is a source defect to fix before anything
   else. Then run the CLI validator, which runs the full PO.Frontend canvas
   rule set (structural rules plus variable, method-call, input-type, and
   event-object checks) offline, plus deploy-readiness checks:

   ```bash
   python3 -c "import sys, xml.etree.ElementTree as ET; ET.parse(sys.argv[1])" <file.bpmn> &&
     ! grep -nE '</?bpmn:[A-Z]' <file.bpmn> &&
     uip maestro bpmn validate <file.bpmn> --output json
   ```

   `validate` ignores tag case; a line the `grep` prints is a tag to lowercase
   (step 2).

   Exit 0 = valid. Exit 1 = a parse error, a `grep` hit, or a `validate`
   failure. Read severity from each issue's `[error]`/`[warning]` tag, not
   from the `Found N error(s)` header, which counts errors while the list under
   it prints warnings too. Fix only
   error-severity findings, then re-run step 4 and validate again; stop
   re-validating once every remaining finding is a warning or the placeholder
   pair below. `read but never assigned` is a defect no error covers: nothing
   writes a value the process reads, so a step that should produce it does not.
   `MISSING_RESOURCE` (warning) and `MISSING_BINDING` (error) are one finding
   about one unresolved node, and the binding half is a live tenant lookup.
   Bind the node to a deployed resource. When the user asked for a
   placeholder, draft, or boundary handoff, or step 1 found no `Enabled`
   candidate, no invented identifier can clear
   `MISSING_BINDING` (Rule 2): exit 1 / `RetryWillNotFix` is the
   expected result. Report the pair once and continue; `refresh` (step 6)
   succeeds with it unresolved. Fix every `VARIABLE_DOES_NOT_EXIST` warning:
   it names a reference with no declaration. A `VARIABLE_NOT_SET` warning on
   the node reading a start-event-scoped caller input is expected; see
   [references/structural-bpmn.md#validation](references/structural-bpmn.md#validation).

   `[warning] [(xml)] unknown attribute <type>` is expected noise from the
   script-task template's `<uipath:inputSchema type="jsonSchema">`. Leave it.
   `type` is required on `uipath:input`, `uipath:output`, and
   `uipath:inputOutput`; removing it there fails the load with
   `BPMN_PARSE_ERROR ... to be a string`. Do not bisect the file and do not
   read package bundles under `node_modules` to find the rule.

   Validation is structural preflight, not runtime proof — see
   [references/cli-conventions.md](references/cli-conventions.md). When
   execution is authorized, inspect runtime variables, element executions, and
   incidents before reporting behavioral success.

   If `validate` reports "unknown command" or clearly skips the
   structural rules, the installed CLI predates them — update it (see
   [references/cli-conventions.md](references/cli-conventions.md)). See
   [references/structural-bpmn.md#validation](references/structural-bpmn.md#validation).
6. **Refresh derived metadata.** Once
   step 5 leaves no fixable error, regenerate the four CLI-owned package files:

   ```bash
   uip maestro bpmn refresh <project-path> --output json
   ```

   Treat a nonzero result as a source/precondition failure: fix the BPMN or
   `project.uiproj`, re-run steps 4 and 5, and refresh again — never repair the generated
   JSON by hand. Refresh after binding a connection (step 1) and for a
   package-ready, upload, debug, publish, or deploy deliverable; a source-only
   draft needs it only for step 3's start-event edits. For the full
   contract (scope, idempotency, binding rules) see
   [references/shared/local-metadata-regeneration-guide.md](references/shared/local-metadata-regeneration-guide.md).

## Operate and diagnose

Beyond authoring, this skill packages, ships, runs, and diagnoses Maestro
projects through the UiPath CLI.

- **Package and operate** (package a project, upload to Studio Web, publish or
  deploy, run or debug instances, and manage jobs, instances, incidents, and
  lifecycle actions): see [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md).
- **Diagnose** (fetch incidents, variables, and element executions, and trace a
  failed run back to its BPMN element): see [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md).
  Runtime evidence — incidents, variables, element executions, cursors, the
  deployed asset — comes only from a `uip maestro bpmn ... --output json` read,
  one literal command per read, never a loop (rule 9 there);
  local `.bpmn` source and generated package files are read from disk as usual.
  Never substitute the files backing that CLI for the CLI itself — see rule 3
  in that reference.

Any cloud-side change (upload, publish, deploy, run, pause, resume, cancel,
retry, migrate) requires explicit user consent, and local validation should pass
first.

## Structural coverage

This skill teaches authoring of the full surface the canvas supports. What the
registry serves a template for vs. what you author by hand:

| Structure | Source |
| --- | --- |
| Node `uipath:*` payloads (RPA, agent, HITL, queue, business rule, API workflow, IS connector, internal message, timer, script) | **Registry** `xmlTemplate` |
| `<uipath:variables>` declarations (each with an `elementId`) | Authored (registry gap) |
| `<bpmn:definitions>`/`<bpmn:process>` scaffold + namespaces | Authored (registry gap) |
| Sequence flows, `conditionExpression`, gateway `default` | Authored (registry gap) |
| Gateways: exclusive, parallel, inclusive, event-based (complex is preserve-only) | Authored (registry gap) |
| Events + event-definition matrix: message, timer, error, terminate (end-only). Signal/escalation/conditional/link/compensate/cancel/multiple are preserve-only | Authored (registry gap); payload per canvas serializer |
| Boundary events: `attachedToRef`, interrupting/non-interrupting (`cancelActivity`) | Authored (registry gap) |
| Subprocess, event subprocess (`triggeredByEvent`), call activity | Authored (registry gap); call-activity payloads from registry |
| Multi-instance / loop characteristics | Authored from canvas contract — **registry exposes no template (registry gap)** |
| `bpmndi:BPMNDiagram` (shape per node, edge per flow) | Generated via `uip maestro bpmn format <file.bpmn>` — **registry emits none (registry gap)** |

Flagged registry gaps: the registry serves no template for structural BPMN,
sequence-flow conditions, event-definition payloads, boundary-event attributes,
multi-instance markers, or the diagram. These are authored from the spec +
canvas contract in [references/structural-bpmn.md](references/structural-bpmn.md)
and honestly surfaced to the user as gaps when asked.

## Rules

1. **Registry owns registry-listed node payloads.** Author their execution
   extensions from `registry get` templates; author serializer-owned scaffold
   metadata only from the structural/canvas contract. Never invent either from
   prose.
2. **Never fabricate an identifier.** Connection IDs, process/queue/connector
   keys, app IDs, folder ids/paths come from discovery or the user. A connector
   field whose `describe` entry carries `Reference` takes the `LookupValue` a
   live lookup returned, never the name the user wrote. See
   [references/registry-workflow.md](references/registry-workflow.md#a-reference-entry-takes-a-looked-up-value-never-the-display-name).
3. **Structural BPMN is authored, not invented.** Follow the spec/canvas
   contract in [references/structural-bpmn.md](references/structural-bpmn.md);
   flag honestly what the registry does not expose.
4. **One clarifying round, then author.** Ask (AskUserQuestion) only for a
   choice that the request and the CLI evidence leave undecidable and whose
   wrong answer is unrecoverable or forces an invented identifier; batch those
   into one round before authoring and never open a second. Decide everything
   else, author, and name each assumption and what tied in your summary. When
   the request says not to pause for approval or confirmation, ask nothing.
   When the source is an image, confirm the full inventory, not a summary —
   see [Authoring from an image](#authoring-from-an-image).
5. **The diagram is mandatory.** Import is diagram-driven — every node needs a
   `BPMNShape`, every flow a `BPMNEdge`, or it will not appear on the canvas.
   `uip maestro bpmn format <file.bpmn>` generates the whole diagram; run it as
   the last write to the `.bpmn` and before `validate` or `refresh`, both of
   which error on a node with no shape.
6. **Preserve the registry's node-type shape.** Most `uipath:activity` /
   `uipath:event` / `uipath:mapping` templates declare their type as a nested
   `<uipath:type value="<Type>" version="v1" />`. Some runtime-authored
   templates use the payload's `type` attribute instead; notably,
   `Orchestrator.StartAgentJob` is a direct child of `bpmn:ServiceTask` with
   `<uipath:activity type="Orchestrator.StartAgentJob" version="v1">`. Both
   declarations are supported. Paste the selected registry template literally
   and do not normalize one form into the other.
   Event extension types (`Intsvc.WaitForEvent`, `Intsvc.EventTrigger`,
   `Maestro.ReceiveMessageEvent`, `Maestro.SendMessageEvent`) must use
   `<uipath:event>`, including when the BPMN host is task-like such as
   `<bpmn:receiveTask>`.
7. **No `--` in XML comments.** XML forbids `--` (double-hyphen) inside
   `<!-- … -->`, so never paste CLI commands or flags (`--output`,
   `--connection-id`, `--object-name`) into a comment — it makes the file
   unparseable. Keep comments minimal.
8. **Use `--output json` for parsed CLI calls.**
9. **Public-safe always.** No customer XML, tenant URLs, real IDs, or private
   names — see [references/public-safety.md](references/public-safety.md).
   Exception: in the user's local project (the `.bpmn` and the CLI-generated
   `bindings_v2.json`), a connection binding and its folder key take the real
   IDs step 1 bound (step 1 names when placeholders apply). Notes, and examples
   or fixtures added to this skills repository, stay sanitized.
10. **Confirm before any cloud change.** Upload, publish, deploy, run, pause,
   resume, cancel, retry, and migrate require explicit user consent; validate
   locally first.
11. **Retry is node configuration, never canvas.** Handle transient failures
   with `uipath:retry` on the activity. Never draw a retry loop from gateways
   and timer events. See
   [references/structural-bpmn.md](references/structural-bpmn.md#choosing-an-error-handling-construct).
12. **Task SLA is task configuration, never canvas.** Approval timers,
   reassignment, and escalation-on-breach live on the user task. Do not model
   them as boundary timers around it.
13. **An error event subprocess is interrupting and terminal.** When it fires,
   the normal path stops and the instance records **Completed**, not Faulted.
   Every path through it must end in an explicitly named outcome, or a handled
   failure is indistinguishable from success. For recover-and-continue, attach
   an error boundary event instead.
14. **A different target system is not, by itself, a different shape.** Swapping
   Document Understanding for a UiPath agent, or Outlook for Gmail, changes a
   binding. Reshape when the process genuinely differs — not merely because the
   target system did.
15. **You author the process; you are never a participant in it.** Where a shape
   calls for reasoning, classification, or extraction at runtime, place and bind
   the node that will perform it — a UiPath agent, Document Understanding, a
   business rule task. Never do that work at authoring time or hardcode its
   result. Bare "agent" in any process description means a UiPath agent, never
   you.
16. **Generated package files are CLI-owned.** Never hand-author
   `bindings_v2.json`, `entry-points.json`, `operate.json`, or
   `package-descriptor.json`. Run `uip maestro bpmn refresh <project-path>` to
   generate them — never the deprecated `update-metadata`. An
   Integration Service draft or boundary handoff the user asked for (step 3)
   asks for none of those — emit
   only the `.bpmn` plus a `.md` notes file naming the CLI-owned blockers.
17. **Incorporating a resource delegated to a sibling skill (RPA workflow, API
   workflow, agent, business rule) is a five-step sequence, in this order.
   Stopping after the owning skill hands the resource back is not done.**
   (A business rule skips step 4, and step 3's release and folder keys do
   not apply: it binds by `name` and `folderPath`, keyed `<folderPath>.<name>`, per
   [registry-workflow.md](references/registry-workflow.md) § Business rule bindings.)
<!--skill-flavor:delegated-resource-solution-first:start-->
   (1) Create or open the solution **first** (`uip solution init`; on
   `unknown command`, the older `uip solution new`), and
   author the resource's project **inside** it, so it registers in the
   `.uipx`: run the resource's `init` and `uip maestro bpmn init` from the
   directory holding the `.uipx`, as in **Assemble**. A project created
   outside any solution has no path to deployment.
<!--skill-flavor:delegated-resource-solution-first:end-->
<!--skill-flavor:delegated-resource-author-deploy:start-->
   (2) Delegate authoring to the resource's owning skill (e.g.
   `uipath-api-workflow`, `uipath-rpa`) with an explicit argument contract:
   declared inputs and outputs, not an unauthored scaffold. (3) Deploy the
   resource (pack, publish, `solution deploy run`) **before** binding it into
   the BPMN node; its release key and folder key exist only once deployed.
   To redeploy, follow `uipath-solution`'s upgrade path.
<!--skill-flavor:delegated-resource-author-deploy:end-->
   (4) Pick the wrapper by `ProcessType`, read from
   `uip or processes list --folder-path <path> --all-fields --output json`
   ([registry-workflow.md](references/registry-workflow.md#agent-wrapper-selection--pick-by-processtype-not-the-label));
   a low-code agent uses `Orchestrator.StartAgentJob`, whose template (rule
   6) binds `name` and `folderPath`, not rule 18. For a rule-18 wrapper, read
   the same response's `Key` and `FolderKey` (PascalCase, like the default
   list; the default list without `--all-fields` omits `ProcessType`) and
   bind per rule 18, never a fabricated or placeholder key. Re-read both
   after every deploy: `deploy run` creates a new folder, so a literal
   `folderKey` from an earlier deploy points at the old one. (5) Unless the task forbids
   live runs or asks for a draft or handoff, run the process
   (`uip maestro bpmn debug`) and read the node's output in
   `debug-instance variables-all`. Map `=result.<key>` to the key that output
   used; a scalar can surface under a generic key instead of the schema
   property name. Without a run, use the schema name and report the mapping
   as unverified. A business rule maps its whole result as one `output` from
   `=result`, never one output per decision or column.
18. **Job-wrapper registry templates (`Orchestrator.StartJob`,
   `ExecuteApiWorkflowAsync`, `StartAgenticProcess[Async]`,
   `StartCaseMgmtProcess[Async]`) serve an unresolved `releaseKey` that
   validates but faults at runtime. This is the one exception to rule 6's
   paste-literally.** For all of them, bind `releaseKey` via
   `=bindings.<id>` to the resource's `Key`. For `ExecuteApiWorkflowAsync`
   only, also add a literal `folderKey` with the folder's `FolderKey` and
   drop `folderId`, `folderPath`, and `name`. For the others, keep the
   template's remaining fields and make that swap only after a live run
   faults with `key:FolderKey`; without a run, report the node unverified. Details:
   [references/registry-workflow.md](references/registry-workflow.md#job-wrapper-v1-trap--releasekey-templates-are-unrunnable).

## References

| Topic | Read |
| --- | --- |
| Discover → template → bind → assemble loop | [references/registry-workflow.md](references/registry-workflow.md) |
| Structural BPMN, event matrix, boundary events, containers, multi-instance, diagram, validation | [references/structural-bpmn.md](references/structural-bpmn.md) |
| Worked-out topology for a recurring process shape, and how shapes compose | Patterns table above → `references/patterns/*-guide.md` |
| Runtime expressions, `vars.`/`bindings.`/`iterator.`, `=js:` (Jint) syntax | [references/expression-authoring.md](references/expression-authoring.md) |
| CLI conventions and the side-effect boundary | [references/cli-conventions.md](references/cli-conventions.md) |
| Keeping content public-safe | [references/public-safety.md](references/public-safety.md) |
| Package, upload, publish, run, or manage instances | [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md) |
| Diagnose a failed or misbehaving run | [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md) |
| Project layout and generated package files | [references/shared/project-layout.md](references/shared/project-layout.md) |