@uipath/skills 1.200.0 → 1.201.0-preview.433

package/skills/uipath-maestro-bpmn/SKILL.md

@@ -4,6 +4,20 @@ description: "UiPath Maestro BPMN / Process Orchestration: author (registry-driv
 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.
+- **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.
+- **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
@@ -35,7 +49,10 @@ 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)) round-trip
-untouched.
+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 `.flow` JSON use `uipath-maestro-flow`; for XAML/coded workflows use
 `uipath-rpa`; for Python agents use `uipath-agents`; for Case plans use
@@ -119,8 +136,8 @@ For registry-evidence-only tasks, be command-first and time-boxed:
    files** — fixture 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), then generate one
-   `BPMNShape`/`BPMNEdge` per node and flow. For local authoring prompts, use the
+   expression/error mappings, retry attributes), then run
+   `uip maestro bpmn format <file.bpmn>` to generate the diagram. If `format` reports `unknown command`, update the CLI (see [references/cli-conventions.md](references/cli-conventions.md)); if upgrading is unavailable, use the fallback DI structure in [references/structural-bpmn.md](references/structural-bpmn.md). For local authoring prompts, use the
    plain project layout `<ProjectName>/<ProjectName>.bpmn` with
    `<ProjectName>/project.uiproj`; do not create `*Solution/`, package files, or
    `.uipx` artifacts unless the user explicitly asks to package or operate the
@@ -150,11 +167,12 @@ For registry-evidence-only tasks, be command-first and time-boxed:
    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.
-   If a local-only prompt asks for `operate.json`, `entry-points.json`,
-   `bindings_v2.json`, or `package-descriptor.json`, follow the minimal local
-   metadata shape in
-   [references/shared/local-metadata-regeneration-guide.md](references/shared/local-metadata-regeneration-guide.md#minimal-local-metadata-shape).
-   Do not copy CLI scaffold metadata shapes into a synthetic local project.
+   If the user asks to package or operate, run
+   `uip maestro bpmn update-metadata <file.bpmn>` to generate the five package
+   metadata files. Only fall back to the minimal local metadata shape in
+   [references/shared/local-metadata-regeneration-guide.md](references/shared/local-metadata-regeneration-guide.md#minimal-local-metadata-shape)
+   when the CLI is unavailable. Do not copy CLI scaffold metadata shapes into a
+   synthetic local project.
 4. **Validate.** Run the CLI validator — it 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:
@@ -201,7 +219,7 @@ registry serves a template for vs. what you author by hand:
 | 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) | Always generated — **registry emits none (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,

package/skills/uipath-maestro-bpmn/references/diagnose/references/failure-modes.md

@@ -3,7 +3,8 @@
 ## Missing diagram
 
 Studio Web import rejects BPMN without a valid diagram and plane.
-Add `bpmndi:BPMNDiagram`, `bpmndi:BPMNPlane`, shapes for nodes, and edges for sequence flows.
+Run `uip maestro bpmn format <file.bpmn>` to generate the full diagram.
+If CLI unavailable: add `bpmndi:BPMNDiagram`, `bpmndi:BPMNPlane`, shapes for nodes, and edges for sequence flows manually.
 
 ## Orphaned diagram plane
 
@@ -12,7 +13,9 @@ Point the plane to a valid element or remove the orphaned diagram.
 
 ## Missing shape or waypoint
 
-Rendered elements without BPMN DI may parse but fail to render correctly. Add bounds for nodes and waypoints for edges.
+Rendered elements without BPMN DI may parse but fail to render correctly.
+Run `uip maestro bpmn format <file.bpmn>` to regenerate all shapes and waypoints.
+If CLI unavailable: add bounds for nodes and waypoints for edges manually.
 
 ## Entry point mismatch
 
@@ -45,7 +48,7 @@ The model may adjust BPMN structure around the connector but must not invent con
 ## Stale generated package files
 
 Generated JSON no longer reflects the BPMN source.
-Regenerate package metadata and verify package descriptor content before upload or deploy.
+Run `uip maestro bpmn update-metadata <file.bpmn> --dry-run` to identify drift, then `uip maestro bpmn update-metadata <file.bpmn>` to regenerate before upload or deploy.
 
 Signs:
 

package/skills/uipath-maestro-bpmn/references/operate/CAPABILITY.md

@@ -32,7 +32,7 @@ These actions may contact UiPath services or external systems.
    migrate, and cursor movement require a clear user decision for that action.
 3. **Validate before operate** - do not upload, publish, debug, or run until Author validation is complete or the user
    explicitly accepts known draft warnings.
-4. **Refresh or regenerate package metadata before cloud actions** - stale `bindings_v2.json`, `entry-points.json`,
+4. **Refresh or regenerate package metadata before cloud actions** - run `uip maestro bpmn update-metadata <file.bpmn> --dry-run` to check drift, then `uip maestro bpmn update-metadata <file.bpmn>` to regenerate. Stale `bindings_v2.json`, `entry-points.json`,
    `operate.json`, or `package-descriptor.json` can break import or runtime even when the BPMN source is correct.
 5. **Keep source and package ownership clear** - fix process structure, variables, mappings, events, and documented non-IS
    extensions in `.bpmn`; rerun CLI generation/enrichment for generated package JSON and Integration Service metadata.

package/skills/uipath-maestro-bpmn/references/operate/references/ship.md

@@ -16,10 +16,16 @@ Before upload, publish, deploy, or debug:
    and package consistency.
 3. Confirm Integration Service enrichment is complete for executable connector elements.
    If enrichment tooling is unavailable, keep the project as a draft and do not operate it as executable.
-4. Regenerate or refresh package metadata with the supported CLI path.
+4. Regenerate or refresh package metadata:
+
+   ```bash
+   uip maestro bpmn update-metadata <file.bpmn> --dry-run   # check drift
+   uip maestro bpmn update-metadata <file.bpmn>             # regenerate
+   ```
+
    Treat `bindings_v2.json`, `entry-points.json`, `operate.json`, and `package-descriptor.json` as derived unless a
-   CLI contract says otherwise. Use
-   [local-metadata-regeneration-guide.md](../../shared/local-metadata-regeneration-guide.md) for the local drift
+   CLI contract says otherwise. See
+   [local-metadata-regeneration-guide.md](../../shared/local-metadata-regeneration-guide.md) for drift
    checks that connect BPMN source, entry points, bindings, and `Intsvc.*` payload enrichment.
    When the BPMN references external Orchestrator processes, `uip solution
    resource refresh` expects a versioned `bindings_v2.json` object with a

package/skills/uipath-maestro-bpmn/references/registry-workflow.md

@@ -180,7 +180,7 @@ auth, schema, or enrichment decision is missing).
 4. Author the structural BPMN the registry does not emit: sequence flows,
    gateway conditions/defaults, event definitions, boundary events,
    subprocess/call-activity containers, multi-instance markers.
-5. Generate the `bpmndi:BPMNDiagram` (shape per node, edge per flow).
+5. Generate the `bpmndi:BPMNDiagram`: `uip maestro bpmn format <file.bpmn>`
 6. Validate (see [structural-bpmn.md#validation](structural-bpmn.md#validation)).
 
 ## OOTB extension types (29, login-free)

package/skills/uipath-maestro-bpmn/references/shared/local-metadata-regeneration-guide.md

@@ -41,26 +41,33 @@ Do not derive metadata from stale package files first. Use existing generated fi
 
 1. Edit `.bpmn` first.
 2. Run local validation for XML, diagrams, entry point IDs, variables, mappings, binding references, and package metadata drift.
-3. Before running `pack`, verify the project directory contains the full local
-   metadata set: `project.uiproj`, `operate.json`, `entry-points.json`,
-   `bindings_v2.json`, and `package-descriptor.json`. The pack command
-   consumes these files; it does not synthesize a missing package descriptor.
-4. If generated package JSON is stale, regenerate it with the supported local
-   CLI path. If no generator is available for a local-only synthetic project,
-   write the minimal placeholder-safe shape below before packing. For
-   package-shape verification, use the local pack command and request JSON
-   output when parsing command results:
+3. Regenerate package metadata from the BPMN source:
+
+   ```bash
+   uip maestro bpmn update-metadata <file.bpmn> --dry-run   # check drift
+   uip maestro bpmn update-metadata <file.bpmn>             # regenerate
+   ```
+
+   If CLI unavailable for a local-only synthetic project, write the minimal
+   placeholder-safe shape (see below) before continuing.
+
+4. Verify the project directory now contains the full metadata set:
+   `project.uiproj`, `operate.json`, `entry-points.json`, `bindings_v2.json`,
+   and `package-descriptor.json`. The pack command consumes these files; it does
+   not synthesize a missing package descriptor.
+
+5. For package-shape verification, use the local pack command:
 
    ```bash
    uip maestro bpmn pack <project-path> <OutputDir> --output json
    ```
 
-5. Inspect the package or generated content for:
+6. Inspect the package or generated content for:
    - `entry-points.json` entries matching root start events and schemas.
    - `bindings_v2.json` resources matching root bindings and enriched connector metadata.
    - `operate.json` pointing at the intended BPMN file with `ProcessOrchestration` content type.
    - `package-descriptor.json` entries for the BPMN file and generated JSON under `content/`.
-6. If the installed CLI cannot regenerate a needed file in place, keep the generated file stale only as a known blocker and report the exact unsupported step.
+7. If the installed CLI cannot regenerate a needed file in place, keep the generated file stale only as a known blocker and report the exact unsupported step.
 
 Packaging is local and authoring-safe. Upload, publish, deploy, debug, and run are cloud or runtime actions and still require explicit user consent.
 

package/skills/uipath-maestro-bpmn/references/structural-bpmn.md

@@ -164,7 +164,11 @@ template, but the runtime contract is fixed:
   with `type="json"` and `target="bodyField"`, and maps each field by variable
   id (`=vars.Var_Amount`). Include `<uipath:input name="args" type="json"
   target="bodyField"><![CDATA[{}]]></uipath:input>` even when there are no
-  inputs; this is part of the `BPMN.ScriptTask` registry template.
+  inputs; this is part of the `BPMN.ScriptTask` registry template. This rule
+  applies to nodes you author and to mappings an edit explicitly targets;
+  never retrofit these attributes onto an untouched node's mapping — a
+  pre-existing `<uipath:input name="args">` outside the edit's target stays
+  byte-identical.
 - Map the returned object's property back through `source="=result.response"`
   (the conventional scalar property) or `source="=result.response.<field>"`
   (another object field); `var` points at a declared variable id (do not put the
@@ -453,7 +457,7 @@ unsupported for generation until current tooling confirms them.
 The registry emits no diagram. Import is **diagram-driven**: the canvas builds
 nodes from `BPMNShape`s and edges from `BPMNEdge`s, not by walking
 `flowElements`. **A node with no shape is invisible; a flow with no edge is
-dropped.** You must generate the full `BPMNDiagram` yourself.
+dropped.** Generate the full `BPMNDiagram` with `uip maestro bpmn format <file.bpmn>`.
 
 - One `<bpmndi:BPMNShape id="S_<nodeId>" bpmnElement="<nodeId>">` per node, with
   `<dc:Bounds x= y= width= height= />`. SubProcess shapes carry `isExpanded`.
@@ -481,13 +485,15 @@ Safe, surgical edits on an existing `.bpmn` (preserve content you did not author
 
 - **Add / delete / reconnect a node**: add the element with a stable id and its
   `<bpmn:incoming>`/`<bpmn:outgoing>` refs, add the sequence-flow elements in the
-  owning scope, and add/update its `BPMNShape` and edge waypoints. On delete,
-  remove orphaned flows and DI edges and recheck entry-point variables, output
-  mappings, and binding references.
+  owning scope. On delete, remove orphaned flows and recheck entry-point variables,
+  output mappings, and binding references. Then regenerate the diagram:
+  `uip maestro bpmn format <file.bpmn>`. If CLI unavailable: add/update `BPMNShape`
+  and edge waypoints manually.
 - **Insert a gateway**: split the existing sequence flow into an incoming and an
   outgoing flow, add conditions to the outgoing flows plus one `default`, add a
-  matching join only if branches actually need synchronization, then re-waypoint
-  the diagram (gateway shape + all edges).
+  matching join only if branches actually need synchronization. Then regenerate the
+  diagram: `uip maestro bpmn format <file.bpmn>`. If CLI unavailable: re-waypoint
+  manually (gateway shape + all edges).
 - **Move logic into a subprocess**: move only elements that share a valid scope,
   re-scope their variables, recreate legal subprocess flow boundaries, and add a
   second diagram plane for the subprocess so nested content renders.