uipath-maestro-bpmn

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).
• 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, 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) 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.

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 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.
3. Structural BPMN is authored, not invented. Follow the spec/canvas contract in 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. In draft mode, structure questions wait for the 3c gate.
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. Declare the node type as a <uipath:type> child. Every uipath:activity / uipath:event / uipath:mapping sits inside <bpmn:extensionElements> and carries <uipath:type value="<Type>" version="<version>" />. For a template with type on the wrapper, remove the attribute, add the child, leave the wrapper's own version, and wrap the payload in <bpmn:extensionElements> if it has none; this overrides paste-as-is in 4b and 4c. Take <version> from the template's uipath:type, else from uip maestro bpmn registry get <Type>. Orchestrator.StartAgentJob takes v2, binds name/folderPath, and drops releaseKey/folderId. 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. 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 4a bound (4a names when placeholders apply). Notes, and examples or fixtures added to this skills repository, stay sanitized.
10. Confirm before any cloud change. Publish, deploy, run, pause, resume, cancel, retry, and migrate require explicit user consent; validate locally first. solution upload is the exception: unless the request forbids it, a request to build the process authorizes the upload that shows it, so upload without asking. Confirm only when the project was not created in this run — adopted at 2a, or edited in place (brownfield) — because upload overwrites the cloud solution matching the local .uipx SolutionId. Confirm it where that solution is chosen (2a); when 2a did not run, confirm before the 4g upload.
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.
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 (4c) 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 § Business rule bindings.)

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

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

(4) Pick the wrapper by ProcessType, read from uip or processes list --folder-path <path> --all-fields --output json (registry-workflow.md); a low-code agent uses Orchestrator.StartAgentJob (type v2, rule 6), which 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 overrides paste-as-is in 4b and 4c. 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.

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, 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 4a 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. That applies to phase 4, where nodes are real. In a phase 2 skeleton every activity is deliberately a bare bpmn:task — see references/phase-2-skeleton-guide.md.

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
approval-chain	A request needs sign-off from several people	approval-chain-guide.md
smart-triage	Inbound work sorted into categories, each handled elsewhere	smart-triage-guide.md
external-wait	The process waits on an outside party under an SLA	external-wait-guide.md
high-volume-batch	Many independent items processed in one run	high-volume-batch-guide.md
failure-escalation	Unhandled failures must never disappear silently	failure-escalation-guide.md
queue-distribution	An Orchestrator queue hands work across runtimes	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 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

Authoring runs five phases in order. The mode decides which steps run; it never changes what a step does.

Phase	Steps	What happens	Reference
0 — Surface	—	Nothing to do yet; surface detection is future work.	Below
1 — Preflight	1a–1c	Check login, scan for an existing solution and project, start from its cloud copy. Changes nothing in the project, so it runs in every mode.	Below
2 — Skeleton	2a–2f	Scaffold the project, author blank boxes with real control flow, format, validate, show the shape. Makes no registry calls. Draft mode only, except 2a.	references/phase-2-skeleton-guide.md
3 — Iterate	3a–3c	Adjust the shape, re-format, show it, hold the approval gate. Draft mode only.	references/phase-2-skeleton-guide.md
4 — Wire it up	4a–4g	Discover, fetch templates, paste real payloads into the existing boxes, lay out, validate, refresh, show.	Below

The skeleton (2b–2f) and iteration (phase 3) exist to show the user a shape before it is wired. Auto mode skips both: it runs 2a to scaffold the project, then authors real nodes directly in phase 4. Every other step is identical.

Modes

Check the modes top to bottom and take the first that matches. Draft and auto are internal names: never ask which mode, and never block on the choice.

Mode	Take it when	Phases
Brownfield	A .bpmn the request targets already exists. Do not run init; if the file is bare (no project.uiproj), bootstrap it with the two-key project.uiproj + refresh path in 4c.	0–1, then 4
Discovery-only	The request asks to discover before authoring, save raw registry JSON/evidence, or explicitly "do not author yet", even if it describes an eventual BPMN. Immediately create registry-evidence/, 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 scaffold a project and do not read deep authoring references. Recipe: references/registry-workflow.md.	0–1, then terminate
Draft	The session is in plan mode, or the user wants to see or approve the shape before it is built: draft it first, plan it, sketch, design, what would it look like, show me first. Judge the intent, not the word: a "draft project" or "draft handoff" asking for a source-only deliverable (Rule 16) is auto mode.	0–3, stop at the gate
Auto	Anything else. This is the default.	0–1, 2a, 4, no stop

Say which mode was taken in the final report.

In plan mode, writes wait for plan approval: put the skeleton outline (boxes, gateways, conditions) in the plan, then build 2a–2f once the plan is approved.

Only Build it at 3c authorizes phase 4. When the user keeps the outline, or has not answered, report the skeleton as an outline, not as a finished process. Draft mode shows the shape by upload when the request allows one (2f); when it forbids upload, show the laid-out local .bpmn path and a short text outline instead.

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 opens with a section index naming every anchor. Get the needed templates, then write the first complete version before further spelunking.

Phase 0 — Surface

Nothing to do yet. Surface detection is future work.

Phase 1 — Preflight

• 1a Check login. uip login status --output json, chained in the same Bash call as 1b's scan — not a turn of its own. Without login, registry pull returns only the built-in (OOTB) extension types, so connector and process discovery comes back silently incomplete: tell the user rather than discovering against a half-registry. Local authoring and validate still work offline — see references/cli-conventions.md.

• 1b Scan for a solution and project. Look for any *.uipx file up to two levels below the working directory, with whatever file search the host provides — for example:

  find . -maxdepth 2 -type f -name '*.uipx' -print
  

  The result decides whether 2a creates or adopts. Record it; do not scan again in phase 2.

• 1c Start from the cloud copy. When 1b found a solution (skip this for discovery-only), download it by the SolutionId in its .uipx into a separate directory:

  uip solution download <SOLUTION_ID> --extract -d <DOWNLOAD_DIR> --output json
  

  init writes a SolutionId before any upload, so a failure whose Instructions say "Studio Web API returned 404" just means there is no cloud copy yet: skip the rest of 1c. If the download fails for another reason (offline, not logged in), skip 1c and say so in the final report. Otherwise compare each project's .bpmn in the download with the local one; Studio Web reformats the .uipx and project.uiproj and adds SolutionStorage.json, so only the .bpmn files tell real edits apart. If they match, carry on. If they differ, ask the user which copy to keep before authoring, because a later upload replaces the cloud copy with the local one and would erase edits made in Studio Web.

Phase 2 — Skeleton

Draft mode only, except 2a. Steps 2b to 2f — author blank boxes, format, validate, refresh, show the skeleton — are specified in references/phase-2-skeleton-guide.md. Only 2a is below, because it is the one step that depends on phase 1's scan.

• 2a Create or adopt the project (greenfield only). Skip this step for discovery-only, for brownfield/bare-.bpmn edits, and for an Integration Service draft or boundary handoff the user asked for (Rule 16). Otherwise chain it after 1b in the same turn. Step 1b already answered whether a solution exists; adopt what it found rather than scanning again. When the user named a project path (A/B/B.bpmn names project directory A/B), mkdir -p that directory's parent, cd into it, and run uip maestro bpmn init <B> --skip-solution-registration --output json there; leave out the flag only when that parent is already a solution. Without it, init adds a <B>Solution/ level the path does not have. Either way, author only into the .bpmn at the returned Data.Path; never write a second .bpmn elsewhere.

  If one is found, stop and ask the user which to use, as a pick list if the host has one: one option per solution found, plus "Create a new solution". Never silently adopt, initialize, or repair an existing solution. Say in that question that adopting one means a later upload overwrites its cloud copy, because this is the only point where that is still the user's choice to make. If it found nothing, run init now, by the rules in Assemble (4c); 2b (draft) or 4c (auto) authors into the .bpmn it generates.

Phase 3 — Iterate

Adjust the shape, re-format, show the change, and hold the approval gate until the user agrees it: see references/phase-2-skeleton-guide.md. Draft mode only.

Phase 4 — Wire it up

• 4a 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 source-only draft (Rule 16), a handoff, or placeholder, synthetic, public-safe, or sanitized values, or when no candidate pings Enabled. See references/registry-workflow.md.
• 4b 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 — 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, except per rules 6 and 18. 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.
• 4c Assemble. If this run uploaded the shape, download it first (as in 1c); when its .bpmn differs from the local one, build on the downloaded one (4g says so). For greenfield, edit the .bpmn that 2a's init generated in place; never replace the whole file. Editing in place preserves the four generated JSON files, the initializer's Event_start id, and its uipath:entryPointId. Author from the complete minimal file in references/structural-bpmn.md 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 4d; 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.

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:

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.

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. Older init scaffolds declare 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. 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 <TENANT_URL>, <FOLDER_KEY>, and <CONNECTION_NAME> 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. Every new connector node is V2, in every workflow, HTTP requests (Intsvc.UnifiedHttpRequest) and external agents included: build it with registry get --input-details and paste Data.V2 as it is. In an existing workflow without <uipath:intsvcActivityConfig version="v2" /> never add the marker, and leave its V1 nodes alone unless the task asks (a V1 trigger or wait faults at run time, so rebuild one as V2 when the task touches it). If registry get fails unknown option '--input-details', the CLI predates V2 nodes: stop on a trigger, wait, HTTP request or external agent and tell the user to update uip; only a plain activity falls back to the V1 template. See references/v2-connector-nodes.md.

After bpmn refresh, run uip solution resources refresh so the connections become solution resources.

When filling the V1 template (an older CLI, or reading an existing V1 node) 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"]}). Place it, and every Parameters input, inside <uipath:activity>, between </uipath:context> and the template's <uipath:output>. An input after </uipath:activity> is never sent, and validate does not catch it. See Body shape.

• Required Parameters. Each Required: true entry (Slack send_as) is its own uipath:input with target set to its Type, after </uipath:context> and still inside <uipath:activity>, valued from the request, else its DefaultValue. See Parameters.

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

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

• 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. 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; a trigger-start draft (below) is the exception. Lay the diagram out first (4d): 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 4e's validator fails on the mismatch: entry-points.json references start event "Event_start" via filePath, but no <bpmn:startEvent id="Event_start"> exists. Writing a full-file replacement from the minimal file above renames the initializer's Event_start, so a source-only draft needs this too; editing in place avoids it. 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 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. When the request names a trigger as the start and asks for no package-ready, upload, debug, publish, or deploy deliverable, it is a trigger-start draft. For a timer or V1 connector start, turn the initializer's Event_start into the trigger in place, keeping its id and its uipath:entryPointId child, add no second start, and skip refresh (a timer or V1 start alone has no entry point, so it fails), even after binding a connection; entry-points.json stays valid. Any of those deliverables, including a later one on such a draft, keeps the manual Event_start, gives the trigger its own start id, joins the two per Gateways, and runs refresh. A V2 connector trigger start is the exception, and the usual case, since every new trigger is V2: it carries its own uipath:entryPointId and is an entry point. In a draft, paste its Data.V2 element with {{ID}} = Event_start in place of the manual start, add no second start, and run refresh; skipping it leaves entry-points.json on the old id and validate fails. A deliverable may do the same, or keep the manual Event_start beside it, joined as above, to debug from either start. A recurring timer is a timeCycle with an R/ repeat (R/P1D), not the template's timeDuration. Clearing a 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.

• 4d Lay out the diagram. After the last source edit, and before any validate, refresh, or pack — including the refresh 4c calls for:

  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); if upgrading is unavailable, hand-author the fallback DI structure in references/structural-bpmn.md.

• 4e 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:

  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 (4b).

  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 4d 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, a source-only draft (Rule 16), or a boundary handoff, or 4a 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 (4f) 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.

  [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. 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). See references/structural-bpmn.md#validation.

• 4f Refresh derived metadata. Once 4e leaves no fixable error, regenerate the four CLI-owned package files:

  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 4d and 4e, and refresh again — never repair the generated JSON by hand. Refresh after binding a connection (4a) and for a package-ready, upload, debug, publish, or deploy deliverable; a source-only draft needs it only for 4c's start-event edits, and a trigger-start draft (4c) skips it. For the full contract (scope, idempotency, binding rules) see references/shared/local-metadata-regeneration-guide.md.

• 4g Show the finished process. When the request allows an upload and the project has a solution (.uipx), uip solution upload <SolutionDir> --output json returns the Data.DesignerUrl. When the project was not created in this run (brownfield, or adopted at 2a without a confirmation), confirm before uploading (Rule 10). When the request forbids upload, or there is no solution, skip it. Then reply in this shape, dropping lines that do not apply:

  <Name>: built, validated<, uploaded><, run>. <One sentence if you kept the user's online changes.>
  <DesignerUrl as a link on its own line, or the local .bpmn path>
  
  - <what changed, one line each, up to 5>
  
  Assumed: <...>  Unverified: <...>
  

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.
• Diagnose (fetch incidents, variables, and element executions, and trace a failed run back to its BPMN element): see 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 (publish, deploy, run, pause, resume, cancel, retry, migrate) requires explicit user consent, and local validation should pass first. solution upload is the exception — see Rule 10.

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 and honestly surfaced to the user as gaps when asked.

References

Topic	Read
Phase 2 skeleton — blank boxes, real control flow, no registry calls	references/phase-2-skeleton-guide.md
Discover → template → bind → assemble loop	references/registry-workflow.md
Structural BPMN, event matrix, boundary events, containers, multi-instance, diagram, validation	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
CLI conventions and the side-effect boundary	references/cli-conventions.md
Keeping content public-safe	references/public-safety.md
Package, upload, publish, run, or manage instances	references/operate/CAPABILITY.md
Diagnose a failed or misbehaving run	references/diagnose/CAPABILITY.md
Project layout and generated package files	references/shared/project-layout.md