From eff59ecaeade3715dbb428754445be1463c786e4 Mon Sep 17 00:00:00 2001 From: rockymadden Date: Fri, 4 Sep 2026 08:29:23 -0600 Subject: [PATCH 1/4] fix(uipath-maestro-flow): derive flow debug consent from the mandate, unmark the publish default Two defects, both consequences of rule #5 rather than gaps in it. Rule #5 classes `flow debug` as a consent gate that is never auto-answered. In the 2026-09-04 nightly, 5 of 8 `skill-flow-*` tasks therefore validated their flow, reported success, and never executed it. The checker then ran debug and found a null End-node output mapping, a faulted script, and an empty result. `flow validate` had passed on all of them. Consent for debug is not a question that needs a live user. It comes from what was asked for: a request to build something that does X is a request for it to work, and building plus validating does not discharge that. Rule #2 now says so, rule #5 defers to it, and run.md matches. Added the one guardrail debug genuinely needs: it overwrites the Studio Web solution matching the local `.uipx` SolutionId, so never debug a solution this run did not scaffold. Separately, rule #5's non-interactive fallback takes the marked recommended option, and the What's next dropdown marked "Publish to Studio Web" as the default. A headless run would auto-publish to the tenant. Dropped the marking in both greenfield and brownfield; nothing else in either table is marked, so the fallback now falls through to stop-and-report. Modifies Critical Rules 2 and 5, per CONTRIBUTING. Co-Authored-By: Claude Opus 5 (1M context) --- skills/uipath-maestro-flow/SKILL.md | 4 ++-- skills/uipath-maestro-flow/references/author/brownfield.md | 2 +- skills/uipath-maestro-flow/references/author/greenfield.md | 2 +- skills/uipath-maestro-flow/references/operate/run.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/uipath-maestro-flow/SKILL.md b/skills/uipath-maestro-flow/SKILL.md index 182d0e7959..de9aa3a23b 100644 --- a/skills/uipath-maestro-flow/SKILL.md +++ b/skills/uipath-maestro-flow/SKILL.md @@ -61,7 +61,7 @@ Guide for creating, editing, validating, debugging, publishing, diagnosing, and > **Tool vocabulary.** `Edit` means in-place replacement, `Write` a full-file write, `Read`/`Glob`/`Grep` file access, `Bash` shell, and a progress list the harness task list. Map them to equivalent tools elsewhere; preserve reviewable diffs and use shell file edits only as a last resort. 1. **Use `--output json`; prefer `--output-filter` for extraction.** Filters are global and run against the `Data` envelope, so expressions start at `Data` without a `Data.` prefix. Registry search returns a flat PascalCase array (`NodeType`, `DisplayName`, `Description`, `AvailableOnTenant`), not `Data.Nodes` or lowercase fields. Example: `uip maestro flow registry search --output json --output-filter "[*].{NodeType:NodeType,DisplayName:DisplayName,Description:Description,AvailableOnTenant:AvailableOnTenant}"`. With `--local`, omit `AvailableOnTenant`. Use `python3 -c` or `jq` only after verifying shape and when JMESPath cannot express the transform. See [cli-conventions.md §3](references/shared/cli-conventions.md#3-prefer---output-filter-for-extraction). -2. **Do not run `flow debug` without explicit user consent.** It executes the flow for real (sends emails, posts messages, calls APIs). +2. **`flow debug` consent comes from the mandate.** It executes the flow for real (sends emails, posts messages, calls APIs), so run it only when the request is for a flow that *works*: the user asked for something that does X, or said make it work, get it running, iterate until it passes. Building and validating does not discharge that, and a flow that was never executed is not finished. Ask when the request stops short of a working artifact (review this, add a node, validate only); with nobody to ask, report debug as the step not run. Debug also overwrites the Studio Web solution matching the local `.uipx` `SolutionId`, so never debug a solution this run did not scaffold. 3. **Search before creating or declaring resources absent.** For named agents, API workflows, RPA processes, and similar resources: (a) pull and search the tenant registry with `uip maestro flow registry pull --force && uip maestro flow registry search "" --output json`; pull first because the cache expires after 30 minutes, login is required, and only published resources are returned; (b) search locally with `uip maestro flow registry list --local --output json` or `search "" --local` (no login; returns sibling projects in the same `.uipx` solution); an empty keyword search does not prove absence, so confirm with `list --local`; (c) scaffold, mock, or create only when both searches find no match and the user explicitly requests embedding/creation or no published resource satisfies the need. "Coded" and "low-code" describe implementation style, not inline status. Use `uipath.agent.autonomous` only when explicitly asked to embed/inline/create an agent. Use `core.logic.mock` only when the resource is neither in the solution nor published. See [rpa](references/author/plugins/rpa/impl.md) and [agent](references/author/plugins/agent/impl.md). @@ -73,7 +73,7 @@ Guide for creating, editing, validating, debugging, publishing, diagnosing, and **Two tells that you skipped the search and took the brand-name shortcut — both are build defects, not valid manual-mode HTTP:** (a) you authored a manual-mode `core.action.http.v2` node whose `url` targets a well-known SaaS API domain that has a connector (`slack.com/api/*`, `api.github.com`, `*.salesforce.com`, `graph.microsoft.com`, …); (b) you declared an `in` variable to hold that service's API token or secret (e.g. a `slackToken` holding an `xoxb-…` bot token, an `apiKey`, a bearer token). A connector-backed flow never carries the raw credential — the IS connection does. If you find yourself writing either, **stop**: run `uip maestro flow registry search ""` and `uip is connections list "" --all-folders`, then use the connector activity (or connector-mode HTTP: `authentication:"connector"` + `targetConnector` + a bound `connectionId`/`folderKey`). Manual mode is legitimate only for a service the search proves has no connector. 4. **Never invoke other skills automatically** — when a flow needs an RPA process, agent, or app, identify the gap and provide handoff instructions. Let the user decide when to switch skills. **One exception — IXP extraction with documents in hand:** when the flow needs document extraction, the user supplied sample documents, and `registry search "uipath.ixp"` shows no extractor covering them, invoke the `uipath-ixp` skill to build and deploy the model, then resume the flow ([plugins/ixp/impl.md — If the Model Does Not Exist Yet](references/author/plugins/ixp/impl.md#if-the-model-does-not-exist-yet)). Resolve the target Orchestrator folder for the deployment before invoking — from the user's request when it names one, otherwise per rule #5 (its non-interactive fallback applies) — and pass it in the handoff; the sibling stops rather than guess a folder. There is deliberately no separate consent gate on the tenant writes this creates: the project and folder deployment fulfil the extraction request itself, and the one consequential choice — where the deployment lands (deployments have no delete API) — is exactly the folder decision rule #5 just routed. Do NOT drive `uip ixp` project or deployment commands from this skill instead of invoking it — the sibling's guides carry guardrails this skill does not. If `uipath-ixp` is unavailable in the session, fall back to `core.logic.mock` plus an Open Questions entry, exactly as when no documents were supplied. -5. **Always present finite decisions as a dropdown with a final "Something else" escape hatch.** Whenever the skill needs a decision (which solution, publish vs debug vs deploy, which connector, trigger type, or resource to bind, etc.), ask with the enumerated choices plus **"Something else"** last for free-form input; never ask open-ended in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. Non-interactively (CI/headless, no user available) → take the marked recommended option, proceed, and record the decision prominently in the final report; if none is recommended, stop and report the open decision instead of guessing. Consent gates (`flow debug`, destructive operations) are never auto-answered — in non-interactive mode, stop and report the blocked step. These fallbacks define "ask the user" / "confirm with the user" wherever this skill's references require it. +5. **Always present finite decisions as a dropdown with a final "Something else" escape hatch.** Whenever the skill needs a decision (which solution, publish vs debug vs deploy, which connector, trigger type, or resource to bind, etc.), ask with the enumerated choices plus **"Something else"** last for free-form input; never ask open-ended in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. Non-interactively (CI/headless, no user available) → take the marked recommended option, proceed, and record the decision prominently in the final report; if none is recommended, stop and report the open decision instead of guessing. Consent gates (destructive operations, tenant writes) are never auto-answered — in non-interactive mode, stop and report the blocked step. `flow debug` is not one of them; rule #2 owns it. These fallbacks define "ask the user" / "confirm with the user" wherever this skill's references require it. 6. **Discover the target solution before scaffolding.** A Flow project must use double nesting: `//.flow`. Before any new `uip solution init` or `uip maestro flow init`, run `find . -maxdepth 2 -type f -name '*.uipx' -print`. If a solution exists, stop and ask which to use: one option per solution, "Create a new solution", then "Something else". Do not silently adopt, initialize, delete, or repair an existing solution, even if a new one was requested. If creating one, ask for its name rather than defaulting to the Flow name. diff --git a/skills/uipath-maestro-flow/references/author/brownfield.md b/skills/uipath-maestro-flow/references/author/brownfield.md index 707203f2a1..8523dee50f 100644 --- a/skills/uipath-maestro-flow/references/author/brownfield.md +++ b/skills/uipath-maestro-flow/references/author/brownfield.md @@ -81,7 +81,7 @@ Authoring ends here. For any selected option, read [operate/CAPABILITY.md](../op | Option | What it does | |---|---| -| **Publish to Studio Web** (default) | Push the solution to Studio Web so the user can visualize, edit, and publish from the browser. | +| **Publish to Studio Web** | Push the solution to Studio Web so the user can visualize, edit, and publish from the browser. | | **Debug the solution** | Execute the flow end-to-end against real systems. Confirm consent first because debug has real side effects (see the consent-before-debug rule in [SKILL.md](../../SKILL.md)). | | **Deploy to Orchestrator** | Pack and publish directly to Orchestrator (bypasses Studio Web). Only when explicitly chosen; see [/uipath:uipath-platform](/uipath:uipath-platform). | | **Something else** | Last option. Accept free-form string input and act on it. | diff --git a/skills/uipath-maestro-flow/references/author/greenfield.md b/skills/uipath-maestro-flow/references/author/greenfield.md index 9f2d049dc1..769b1e89c8 100644 --- a/skills/uipath-maestro-flow/references/author/greenfield.md +++ b/skills/uipath-maestro-flow/references/author/greenfield.md @@ -373,7 +373,7 @@ Authoring terminates here. Each option below hands off to Operate — read [oper | Option | What it does | | --- | --- | -| **Publish to Studio Web** (default) | Push the solution to Studio Web so the user can visualize, edit, and publish from the browser. | +| **Publish to Studio Web** | Push the solution to Studio Web so the user can visualize, edit, and publish from the browser. | | **Debug the solution** | Execute the flow end-to-end against real systems. Confirm consent first — debug has real side effects (see the consent-before-debug rule in [SKILL.md](../../SKILL.md)). | | **Deploy to Orchestrator** | Pack and publish directly to Orchestrator (bypasses Studio Web). Only when explicitly chosen — see [/uipath:uipath-platform](/uipath:uipath-platform). | | **Something else** | Last option. Accept free-form string input and act on it (e.g., "just leave it", "pack but don't publish", "upload to a different tenant"). | diff --git a/skills/uipath-maestro-flow/references/operate/run.md b/skills/uipath-maestro-flow/references/operate/run.md index 0c808e8d61..98aa1abf0c 100644 --- a/skills/uipath-maestro-flow/references/operate/run.md +++ b/skills/uipath-maestro-flow/references/operate/run.md @@ -13,7 +13,7 @@ Execute a flow on demand and monitor progress. Three modes: **debug** (controlle ## Debug — controlled end-to-end run -> **Confirm consent first.** `flow debug` executes the flow for real — sends emails, posts messages, calls APIs. See the consent-before-debug rule in [SKILL.md](../../SKILL.md). Do not run without explicit user authorization. +> **Consent comes from the mandate.** `flow debug` executes the flow for real — sends emails, posts messages, calls APIs. Run it when the request is for a flow that works; ask when the request stops at build or validate. Never debug a solution this run did not scaffold: debug overwrites the Studio Web solution matching the local `.uipx` `SolutionId`. See rule #2 in [SKILL.md](../../SKILL.md). ```bash UIP_LOG_LEVEL=info uip maestro flow debug --output json From c0c573ae8c845d89a165e077a2611ffbd83352da Mon Sep 17 00:00:00 2001 From: rockymadden Date: Fri, 4 Sep 2026 09:07:45 -0600 Subject: [PATCH 2/4] fix(uipath-maestro-flow): make the headless behaviour a rule of its own The behaviour was the tail of rule #5, whose headline is about dropdown menus, 61% into the file and 574 characters into the rule. An agent scanning headlines for "no user, what now?" does not match on "Always present finite decisions as a dropdown". It was also wrong after this PR's own change. Rule #5 said take the marked recommended option, and dropping the two `(default)` markings left exactly one marked option in the whole skill, so every finite decision fell to stop-and-report. That is the opposite of what a headless run should do with a choice it can make. Rule #13 now covers all four cases the skill actually hits, and is self-sufficient: it states detection and behaviour, so it holds whether or not the harness ever announces the mode. Rule #5 keeps the ask mechanism and points at it. - finite choice -> best option, not only a marked one - missing value -> most defensible one, keep building - irreversible or externally visible -> do not, finish the rest first - unresolved fact -> stop on that field, never a display name or alias Also drops the two `rule #2` citations this PR had added, in SKILL.md and run.md, in favour of naming the rule. Appending #13 renumbers nothing, so the cross-references in other docs are untouched. Co-Authored-By: Claude Opus 5 (1M context) --- skills/uipath-maestro-flow/SKILL.md | 3 ++- skills/uipath-maestro-flow/references/operate/run.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/skills/uipath-maestro-flow/SKILL.md b/skills/uipath-maestro-flow/SKILL.md index de9aa3a23b..1fa3582b6a 100644 --- a/skills/uipath-maestro-flow/SKILL.md +++ b/skills/uipath-maestro-flow/SKILL.md @@ -73,7 +73,7 @@ Guide for creating, editing, validating, debugging, publishing, diagnosing, and **Two tells that you skipped the search and took the brand-name shortcut — both are build defects, not valid manual-mode HTTP:** (a) you authored a manual-mode `core.action.http.v2` node whose `url` targets a well-known SaaS API domain that has a connector (`slack.com/api/*`, `api.github.com`, `*.salesforce.com`, `graph.microsoft.com`, …); (b) you declared an `in` variable to hold that service's API token or secret (e.g. a `slackToken` holding an `xoxb-…` bot token, an `apiKey`, a bearer token). A connector-backed flow never carries the raw credential — the IS connection does. If you find yourself writing either, **stop**: run `uip maestro flow registry search ""` and `uip is connections list "" --all-folders`, then use the connector activity (or connector-mode HTTP: `authentication:"connector"` + `targetConnector` + a bound `connectionId`/`folderKey`). Manual mode is legitimate only for a service the search proves has no connector. 4. **Never invoke other skills automatically** — when a flow needs an RPA process, agent, or app, identify the gap and provide handoff instructions. Let the user decide when to switch skills. **One exception — IXP extraction with documents in hand:** when the flow needs document extraction, the user supplied sample documents, and `registry search "uipath.ixp"` shows no extractor covering them, invoke the `uipath-ixp` skill to build and deploy the model, then resume the flow ([plugins/ixp/impl.md — If the Model Does Not Exist Yet](references/author/plugins/ixp/impl.md#if-the-model-does-not-exist-yet)). Resolve the target Orchestrator folder for the deployment before invoking — from the user's request when it names one, otherwise per rule #5 (its non-interactive fallback applies) — and pass it in the handoff; the sibling stops rather than guess a folder. There is deliberately no separate consent gate on the tenant writes this creates: the project and folder deployment fulfil the extraction request itself, and the one consequential choice — where the deployment lands (deployments have no delete API) — is exactly the folder decision rule #5 just routed. Do NOT drive `uip ixp` project or deployment commands from this skill instead of invoking it — the sibling's guides carry guardrails this skill does not. If `uipath-ixp` is unavailable in the session, fall back to `core.logic.mock` plus an Open Questions entry, exactly as when no documents were supplied. -5. **Always present finite decisions as a dropdown with a final "Something else" escape hatch.** Whenever the skill needs a decision (which solution, publish vs debug vs deploy, which connector, trigger type, or resource to bind, etc.), ask with the enumerated choices plus **"Something else"** last for free-form input; never ask open-ended in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. Non-interactively (CI/headless, no user available) → take the marked recommended option, proceed, and record the decision prominently in the final report; if none is recommended, stop and report the open decision instead of guessing. Consent gates (destructive operations, tenant writes) are never auto-answered — in non-interactive mode, stop and report the blocked step. `flow debug` is not one of them; rule #2 owns it. These fallbacks define "ask the user" / "confirm with the user" wherever this skill's references require it. +5. **Always present finite decisions as a dropdown with a final "Something else" escape hatch.** Whenever the skill needs a decision (which solution, publish vs debug vs deploy, which connector, trigger type, or resource to bind, etc.), ask with the enumerated choices plus **"Something else"** last for free-form input; never ask open-ended in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. With nobody to answer, the headless rule below defines what "ask the user" / "confirm with the user" resolves to wherever this skill's references require it. 6. **Discover the target solution before scaffolding.** A Flow project must use double nesting: `//.flow`. Before any new `uip solution init` or `uip maestro flow init`, run `find . -maxdepth 2 -type f -name '*.uipx' -print`. If a solution exists, stop and ask which to use: one option per solution, "Create a new solution", then "Something else". Do not silently adopt, initialize, delete, or repair an existing solution, even if a new one was requested. If creating one, ask for its name rather than defaulting to the Flow name. @@ -85,6 +85,7 @@ Guide for creating, editing, validating, debugging, publishing, diagnosing, and 10. **Batch independent tool calls and chain dependent CLI calls.** A typical greenfield build is three turns: T1 scaffold, pull the registry, and add CLI-owned nodes in one chained `Bash`, alongside independent registry/file reads; T2 read the scaffold while editing/adding the End node and edges; T3 chain configure, validate, and format. Split only when later work depends on stdout or a mutation. See [author/greenfield.md — Three-turn execution map](references/author/greenfield.md#three-turn-execution-map). 11. **Cross-node bindings in `=js:` require `$vars.`** Use `=js:$vars..output...`; bare `=js:.output...` resolves to `undefined`. See [variables-and-expressions.md — IS Activity Inputs Require `=js:`](references/shared/variables-and-expressions.md#is-activity-inputs-require-js-critical). 12. **Node and edge IDs must begin with a letter.** Use descriptive camelCase node IDs and `edge____` edge IDs. Reserve UUIDs for the top-level flow `id` and `entryPointId`. +13. **Headless runs decide and record; they never wait.** The run is headless when the harness says so, the prompt forecloses asking, or it is CI, a scheduled job, or an eval. Then a **finite choice** → take the best option, not only a marked one; a **missing value** (a required field with no default, an output whose meaning the request never states) → supply the most defensible one and keep building; anything **irreversible or externally visible** (destructive operations, tenant writes, a browser login) → do not do it, and finish everything that does not depend on it first; a **fact you could not resolve** (a reference lookup that 401s, 403s, or returns nothing) → stop on that field, never substituting a display name, an alias, or a remembered ID, because those pass `flow validate` and fault at runtime. Put every decision, assumption, and blocked step in the final report. `flow debug` is governed by its own rule above. ## Anti-patterns (universal) diff --git a/skills/uipath-maestro-flow/references/operate/run.md b/skills/uipath-maestro-flow/references/operate/run.md index 98aa1abf0c..042450301a 100644 --- a/skills/uipath-maestro-flow/references/operate/run.md +++ b/skills/uipath-maestro-flow/references/operate/run.md @@ -13,7 +13,7 @@ Execute a flow on demand and monitor progress. Three modes: **debug** (controlle ## Debug — controlled end-to-end run -> **Consent comes from the mandate.** `flow debug` executes the flow for real — sends emails, posts messages, calls APIs. Run it when the request is for a flow that works; ask when the request stops at build or validate. Never debug a solution this run did not scaffold: debug overwrites the Studio Web solution matching the local `.uipx` `SolutionId`. See rule #2 in [SKILL.md](../../SKILL.md). +> **Consent comes from the mandate.** `flow debug` executes the flow for real — sends emails, posts messages, calls APIs. Run it when the request is for a flow that works; ask when the request stops at build or validate. Never debug a solution this run did not scaffold: debug overwrites the Studio Web solution matching the local `.uipx` `SolutionId`. See the `flow debug` consent rule in [SKILL.md](../../SKILL.md). ```bash UIP_LOG_LEVEL=info uip maestro flow debug --output json From 67cdde8881b5a398caa32f8036faeeaa259b9a50 Mon Sep 17 00:00:00 2001 From: rockymadden Date: Fri, 4 Sep 2026 09:16:03 -0600 Subject: [PATCH 3/4] fix(uipath-maestro-flow): move the headless rule above every link in the file As Critical Rule #13 it sat at line 88, past the capability list, the 13-row router, and 12 other rules. Every observed run happened to read the whole file first, so read order was not the live problem, but a rule that changes how rules 1-12 and every reference doc behave should not be stated after all of them. Working style is the right home on the merits, not just position: rules 1-12 are `.flow` mechanics (node ownership, `=js:` prefixes, ID formats), while headless is an operating mode, which is what that section is for. It now sits at line 14, fifteen lines ahead of the first link in the file, so no reference can be followed before it is read. Chose this over making it Critical Rule #1, which would renumber the list and break 29 `rule #N` citations across 7 files. Links fixed as a result: - Rule #5 pointed at "the headless rule below"; now links up to [Working style](#working-style). - The bullet said `flow debug` "is governed by its own rule above"; that rule is now below it, so it names the section instead of a direction. Co-Authored-By: Claude Opus 5 (1M context) --- skills/uipath-maestro-flow/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/uipath-maestro-flow/SKILL.md b/skills/uipath-maestro-flow/SKILL.md index 1fa3582b6a..afd0c4966e 100644 --- a/skills/uipath-maestro-flow/SKILL.md +++ b/skills/uipath-maestro-flow/SKILL.md @@ -11,6 +11,7 @@ allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion # Working style +- **Headless runs decide and record; they never wait.** The run is headless when the harness says so, the prompt forecloses asking, or it is CI, a scheduled job, or an eval. Then a **finite choice** → take the best option, not only a marked one; a **missing value** (a required field with no default, an output whose meaning the request never states) → supply the most defensible one and keep building; anything **irreversible or externally visible** (destructive operations, tenant writes, a browser login) → do not do it, and finish everything that does not depend on it first; a **fact you could not resolve** (a reference lookup that 401s, 403s, or returns nothing) → stop on that field, never substituting a display name, an alias, or a remembered ID, because those pass `flow validate` and fault at runtime. Put every decision, assumption, and blocked step in the final report. `flow debug` has its own consent rule under Critical rules. - **Understand first, then decide.** Read this file and the capability index for the work at hand, then plan against what the CLI verbs do — not a guess. `uip maestro flow --help` and `uip maestro flow registry get ` are ground truth for flags and node shapes. - **Plan the whole path up front, then chain.** Outline the sequence before running anything, batch independent steps into one turn, pipeline the rest (rule #10). Do not run turn-by-turn what could have been chained. - **Inspect an input ONCE.** To learn a shape — a node type's schema, a connector's fields, an existing `.flow`'s nodes — dump it once and search that output. Never re-read a file field-by-field or re-query the registry once per field. @@ -73,7 +74,7 @@ Guide for creating, editing, validating, debugging, publishing, diagnosing, and **Two tells that you skipped the search and took the brand-name shortcut — both are build defects, not valid manual-mode HTTP:** (a) you authored a manual-mode `core.action.http.v2` node whose `url` targets a well-known SaaS API domain that has a connector (`slack.com/api/*`, `api.github.com`, `*.salesforce.com`, `graph.microsoft.com`, …); (b) you declared an `in` variable to hold that service's API token or secret (e.g. a `slackToken` holding an `xoxb-…` bot token, an `apiKey`, a bearer token). A connector-backed flow never carries the raw credential — the IS connection does. If you find yourself writing either, **stop**: run `uip maestro flow registry search ""` and `uip is connections list "" --all-folders`, then use the connector activity (or connector-mode HTTP: `authentication:"connector"` + `targetConnector` + a bound `connectionId`/`folderKey`). Manual mode is legitimate only for a service the search proves has no connector. 4. **Never invoke other skills automatically** — when a flow needs an RPA process, agent, or app, identify the gap and provide handoff instructions. Let the user decide when to switch skills. **One exception — IXP extraction with documents in hand:** when the flow needs document extraction, the user supplied sample documents, and `registry search "uipath.ixp"` shows no extractor covering them, invoke the `uipath-ixp` skill to build and deploy the model, then resume the flow ([plugins/ixp/impl.md — If the Model Does Not Exist Yet](references/author/plugins/ixp/impl.md#if-the-model-does-not-exist-yet)). Resolve the target Orchestrator folder for the deployment before invoking — from the user's request when it names one, otherwise per rule #5 (its non-interactive fallback applies) — and pass it in the handoff; the sibling stops rather than guess a folder. There is deliberately no separate consent gate on the tenant writes this creates: the project and folder deployment fulfil the extraction request itself, and the one consequential choice — where the deployment lands (deployments have no delete API) — is exactly the folder decision rule #5 just routed. Do NOT drive `uip ixp` project or deployment commands from this skill instead of invoking it — the sibling's guides carry guardrails this skill does not. If `uipath-ixp` is unavailable in the session, fall back to `core.logic.mock` plus an Open Questions entry, exactly as when no documents were supplied. -5. **Always present finite decisions as a dropdown with a final "Something else" escape hatch.** Whenever the skill needs a decision (which solution, publish vs debug vs deploy, which connector, trigger type, or resource to bind, etc.), ask with the enumerated choices plus **"Something else"** last for free-form input; never ask open-ended in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. With nobody to answer, the headless rule below defines what "ask the user" / "confirm with the user" resolves to wherever this skill's references require it. +5. **Always present finite decisions as a dropdown with a final "Something else" escape hatch.** Whenever the skill needs a decision (which solution, publish vs debug vs deploy, which connector, trigger type, or resource to bind, etc.), ask with the enumerated choices plus **"Something else"** last for free-form input; never ask open-ended in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. With nobody to answer, the headless bullet in [Working style](#working-style) defines what "ask the user" / "confirm with the user" resolves to wherever this skill's references require it. 6. **Discover the target solution before scaffolding.** A Flow project must use double nesting: `//.flow`. Before any new `uip solution init` or `uip maestro flow init`, run `find . -maxdepth 2 -type f -name '*.uipx' -print`. If a solution exists, stop and ask which to use: one option per solution, "Create a new solution", then "Something else". Do not silently adopt, initialize, delete, or repair an existing solution, even if a new one was requested. If creating one, ask for its name rather than defaulting to the Flow name. @@ -85,7 +86,6 @@ Guide for creating, editing, validating, debugging, publishing, diagnosing, and 10. **Batch independent tool calls and chain dependent CLI calls.** A typical greenfield build is three turns: T1 scaffold, pull the registry, and add CLI-owned nodes in one chained `Bash`, alongside independent registry/file reads; T2 read the scaffold while editing/adding the End node and edges; T3 chain configure, validate, and format. Split only when later work depends on stdout or a mutation. See [author/greenfield.md — Three-turn execution map](references/author/greenfield.md#three-turn-execution-map). 11. **Cross-node bindings in `=js:` require `$vars.`** Use `=js:$vars..output...`; bare `=js:.output...` resolves to `undefined`. See [variables-and-expressions.md — IS Activity Inputs Require `=js:`](references/shared/variables-and-expressions.md#is-activity-inputs-require-js-critical). 12. **Node and edge IDs must begin with a letter.** Use descriptive camelCase node IDs and `edge____` edge IDs. Reserve UUIDs for the top-level flow `id` and `entryPointId`. -13. **Headless runs decide and record; they never wait.** The run is headless when the harness says so, the prompt forecloses asking, or it is CI, a scheduled job, or an eval. Then a **finite choice** → take the best option, not only a marked one; a **missing value** (a required field with no default, an output whose meaning the request never states) → supply the most defensible one and keep building; anything **irreversible or externally visible** (destructive operations, tenant writes, a browser login) → do not do it, and finish everything that does not depend on it first; a **fact you could not resolve** (a reference lookup that 401s, 403s, or returns nothing) → stop on that field, never substituting a display name, an alias, or a remembered ID, because those pass `flow validate` and fault at runtime. Put every decision, assumption, and blocked step in the final report. `flow debug` is governed by its own rule above. ## Anti-patterns (universal) From fb722cb6f32f346320b597a8821f31efefc74a9a Mon Sep 17 00:00:00 2001 From: rockymadden Date: Fri, 4 Sep 2026 09:33:08 -0600 Subject: [PATCH 4/4] fix(uipath-maestro-flow): drop the headless bullet; it belongs in the eval system prompt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The bullet told the skill what to do when no user is present. Three of its four branches (finite choice, missing value, irreversible action) only fire when nobody can be asked, and the fourth — never write a display name where a resolved ID belongs — already exists as an anti-pattern here and in connector/impl.md. No user only happens headless, and the only documented way to consume this skill is `uip skills install` into a developer's local Claude Code, Codex, Cursor, or Gemini. Nothing ships it to a headless surface, so the bullet was carrying eval-only behaviour in a skill that only interactive users install. It moves to the flow experiment's system prompt. What remains here has independent justification and applies with or without a user watching: `flow debug` consent comes from the mandate, and "Publish to Studio Web" is no longer marked as a default that rule #5's fallback would auto-fire. Co-Authored-By: Claude Opus 5 (1M context) --- skills/uipath-maestro-flow/SKILL.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/skills/uipath-maestro-flow/SKILL.md b/skills/uipath-maestro-flow/SKILL.md index afd0c4966e..630d6eda28 100644 --- a/skills/uipath-maestro-flow/SKILL.md +++ b/skills/uipath-maestro-flow/SKILL.md @@ -11,7 +11,6 @@ allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion # Working style -- **Headless runs decide and record; they never wait.** The run is headless when the harness says so, the prompt forecloses asking, or it is CI, a scheduled job, or an eval. Then a **finite choice** → take the best option, not only a marked one; a **missing value** (a required field with no default, an output whose meaning the request never states) → supply the most defensible one and keep building; anything **irreversible or externally visible** (destructive operations, tenant writes, a browser login) → do not do it, and finish everything that does not depend on it first; a **fact you could not resolve** (a reference lookup that 401s, 403s, or returns nothing) → stop on that field, never substituting a display name, an alias, or a remembered ID, because those pass `flow validate` and fault at runtime. Put every decision, assumption, and blocked step in the final report. `flow debug` has its own consent rule under Critical rules. - **Understand first, then decide.** Read this file and the capability index for the work at hand, then plan against what the CLI verbs do — not a guess. `uip maestro flow --help` and `uip maestro flow registry get ` are ground truth for flags and node shapes. - **Plan the whole path up front, then chain.** Outline the sequence before running anything, batch independent steps into one turn, pipeline the rest (rule #10). Do not run turn-by-turn what could have been chained. - **Inspect an input ONCE.** To learn a shape — a node type's schema, a connector's fields, an existing `.flow`'s nodes — dump it once and search that output. Never re-read a file field-by-field or re-query the registry once per field. @@ -74,7 +73,7 @@ Guide for creating, editing, validating, debugging, publishing, diagnosing, and **Two tells that you skipped the search and took the brand-name shortcut — both are build defects, not valid manual-mode HTTP:** (a) you authored a manual-mode `core.action.http.v2` node whose `url` targets a well-known SaaS API domain that has a connector (`slack.com/api/*`, `api.github.com`, `*.salesforce.com`, `graph.microsoft.com`, …); (b) you declared an `in` variable to hold that service's API token or secret (e.g. a `slackToken` holding an `xoxb-…` bot token, an `apiKey`, a bearer token). A connector-backed flow never carries the raw credential — the IS connection does. If you find yourself writing either, **stop**: run `uip maestro flow registry search ""` and `uip is connections list "" --all-folders`, then use the connector activity (or connector-mode HTTP: `authentication:"connector"` + `targetConnector` + a bound `connectionId`/`folderKey`). Manual mode is legitimate only for a service the search proves has no connector. 4. **Never invoke other skills automatically** — when a flow needs an RPA process, agent, or app, identify the gap and provide handoff instructions. Let the user decide when to switch skills. **One exception — IXP extraction with documents in hand:** when the flow needs document extraction, the user supplied sample documents, and `registry search "uipath.ixp"` shows no extractor covering them, invoke the `uipath-ixp` skill to build and deploy the model, then resume the flow ([plugins/ixp/impl.md — If the Model Does Not Exist Yet](references/author/plugins/ixp/impl.md#if-the-model-does-not-exist-yet)). Resolve the target Orchestrator folder for the deployment before invoking — from the user's request when it names one, otherwise per rule #5 (its non-interactive fallback applies) — and pass it in the handoff; the sibling stops rather than guess a folder. There is deliberately no separate consent gate on the tenant writes this creates: the project and folder deployment fulfil the extraction request itself, and the one consequential choice — where the deployment lands (deployments have no delete API) — is exactly the folder decision rule #5 just routed. Do NOT drive `uip ixp` project or deployment commands from this skill instead of invoking it — the sibling's guides carry guardrails this skill does not. If `uipath-ixp` is unavailable in the session, fall back to `core.logic.mock` plus an Open Questions entry, exactly as when no documents were supplied. -5. **Always present finite decisions as a dropdown with a final "Something else" escape hatch.** Whenever the skill needs a decision (which solution, publish vs debug vs deploy, which connector, trigger type, or resource to bind, etc.), ask with the enumerated choices plus **"Something else"** last for free-form input; never ask open-ended in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. With nobody to answer, the headless bullet in [Working style](#working-style) defines what "ask the user" / "confirm with the user" resolves to wherever this skill's references require it. +5. **Always present finite decisions as a dropdown with a final "Something else" escape hatch.** Whenever the skill needs a decision (which solution, publish vs debug vs deploy, which connector, trigger type, or resource to bind, etc.), ask with the enumerated choices plus **"Something else"** last for free-form input; never ask open-ended in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. These fallbacks define "ask the user" / "confirm with the user" wherever this skill's references require it. 6. **Discover the target solution before scaffolding.** A Flow project must use double nesting: `//.flow`. Before any new `uip solution init` or `uip maestro flow init`, run `find . -maxdepth 2 -type f -name '*.uipx' -print`. If a solution exists, stop and ask which to use: one option per solution, "Create a new solution", then "Something else". Do not silently adopt, initialize, delete, or repair an existing solution, even if a new one was requested. If creating one, ask for its name rather than defaulting to the Flow name.