/uipath-maestro-bpmn

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. Exception: `validate` errors on a payload with a `type` attribute or outside `<bpmn:extensionElements>`, and on an `Orchestrator.StartAgentJob` whose type version is not `v2` and whose `releaseKey` or `folderId` has no value. Rewrite those payloads per rule 6 and name each in the summary.

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`.

Critical Rules

1. **Registry owns registry-listed node payloads.** Author their execution extensions from `registry get` templates; author serializer-owned scaffold metadat