@uipath/skills 1.195.0

package/skills/uipath-mcp-servers/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: uipath-mcp-servers
+description: "UiPath AgentHub MCP server registration + tool authoring via `uip agenthub mcp` (six server types: uipath / coded / command / remote / platform / swagger) and `uip agenthub mcp-tools` (three tool kinds: is-activity / resource / raw on `uipath`-type servers). For Integration Service activity authoring→load `references/is-activity-workflow.md`. For Python MCP servers / coded-agent integration→uipath-agents. For raw IS CLI→uipath-platform."
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+# UiPath AgentHub MCP Servers
+
+Register AgentHub MCP servers via `uip agenthub mcp`. Author tools on `uipath`-type servers via `uip agenthub mcp-tools`.
+
+> **`mcp` here means an AgentHub MCP-server resource, not the MCP wire protocol.** Slugs like `inbox-mcp` / `team-helper` name AgentHub server registrations, not local repos. `uipath-mcp-python` (`@uipath/mcp`) is a separate server-implementation SDK — different task, see `uipath-agents`.
+
+## When to Use This Skill
+
+- Create / update / delete / refresh / list / get an AgentHub MCP server (any of: `uipath`, `coded`, `command`, `remote`, `swagger`, `platform`).
+- Author / list / get / enable / disable / delete tools on a `uipath`-type server (`is-activity`, `resource`, `raw`).
+- **For `is-activity` tools (Integration Service connector activities), load [references/is-activity-workflow.md](references/is-activity-workflow.md) end-to-end before authoring.** It owns the Pre-flight, cascade, `designTimeLookups`, `ActivityMetadata` schema, and connector-specific troubleshooting.
+- Skip: Python MCP server implementation (FastMCP / `@uipath/mcp`) → `uipath-agents`. Raw IS CLI outside MCP tooling → `uipath-platform`.
+
+## Trust the CLI
+
+The CLI is the source of truth for shapes and flags. Use it instead of guessing:
+
+- `uip agenthub mcp create <type> --print-schema --output json` — payload shape for any server type.
+- `uip agenthub mcp template <type> --output json` — ready-to-edit `--file` skeleton.
+- `uip agenthub mcp-tools template <kind> --output json` — tool payload skeleton (is-activity / resource / raw).
+- `uip agenthub mcp-tools candidates --category <kind> --output json` — discover bindable targets. `<kind>` ∈ `automation | agent | agentic-process | api-workflow | is-activity`.
+- `--output-filter <JMESPath>` on every command — extract specific fields without walking JSON by hand (e.g. `--output-filter "Data.items[].slug" --output plain`).
+- `--dry-run` on every mutating call — resolve and inspect the body before POST. Note: `--dry-run` skips some server-side validation, so a clean dry-run is not a guaranteed real POST.
+
+## Critical Rules
+
+These are the things the CLI does not advertise in `--help`.
+
+1. **Slug regex.** Backend enforces `^[a-z0-9-]+$`, length 3-50. Lowercase, digits, hyphens — no underscores, dots, or uppercase. CLI validates client-side before POST.
+
+2. **Folder context is required on every AgentHub call.** Pass `--folder-path <name>` OR `--folder-key <guid>`, never both. `--folder-path` resolves via Orchestrator SDK. Personal workspace folders (`<user>@<tenant>'s workspace`) do NOT resolve by name — use `--folder-key <guid>`. Common names (`Shared`) can be ambiguous across nested folders; the CLI returns the candidate list with GUIDs — pick one and re-run with `--folder-key`. Discover GUIDs via `uip or folders list --output json`. **`refresh-tools` always requires `--folder-key` specifically** (endpoint is `/mcp/{folderKey}/{slug}/refresh-tools`).
+
+3. **Verify after every mutation.** After `create` / `update` / `delete` / `refresh-tools`, re-list (`mcp list`, `mcp-tools list --mcp <slug>`) or `mcp get <slug>` and confirm the expected state.
+
+4. **`refresh-tools` behavior depends on server type.**
+   - `coded` / `command` — async, returns HTTP 202 + runtime id. Surface the runtime id; never claim refreshed before a follow-up `mcp-tools list --mcp <slug>` confirms.
+   - `remote` / `platform` / `swagger` — sync, returns 200 after a synchronous fetch+upsert.
+   - `uipath` / `selfhosted` — rejected locally; tools are manually authored via `mcp-tools create-*`. CLI emits a `NextCommand` hint to author instead.
+
+5. **`mcp delete` looks up by slug, not GUID.** Passing a GUID returns 404.
+
+6. **For any `is-activity` tool, read [references/is-activity-workflow.md](references/is-activity-workflow.md) end-to-end before any CLI call.** It owns the cascade-asking gate, the action-triggered platform-IS reads, the `ActivityMetadata` schema, and the `inputSchema` / `designTimeLookups` rules. IS metadata authored from memory passes `--dry-run` but fails at runtime — do not skip the reference.
+
+## Server Types
+
+`uip agenthub mcp create` takes six type subcommands. All share `--name <display>`, `--slug <kebab>`, `--description`, `--version`, `--file`/`--body`/`--print-schema`, `--dry-run`, `--folder-path`/`--folder-key`, `--tenant`, `--login-validity`. The differentiating flag picks the integration shape:
+
+| Type | Differentiating flag | When to use | Tool surface |
+|------|---------------------|-------------|--------------|
+| `uipath`   | _(none)_              | AgentHub-hosted server you'll fill with `mcp-tools create-*`. | Authored via `uip agenthub mcp-tools create-*`. `refresh-tools` rejected. <!-- uip-check-skip --> |
+| `coded`    | `--process-key <key>` (+ `--folder-key` for the process) | Wrap an existing coded-agent process (published to Orchestrator) as an MCP server. | Discovered via `refresh-tools` (async 202). |
+| `command`  | `--command <cmd>` + `--arg <arg>` (repeatable) + `--env <k=v>` (repeatable) | Spawn a local subprocess as an MCP server. | Discovered via `refresh-tools` (async 202). |
+| `remote`   | `--uri <url>` + `--header <k=v>` (repeatable) + `--use-relay` | Point at an existing HTTP MCP server. Bearer/header values can be Orchestrator asset references; `AssetReferenceSubstitutor` resolves them at runtime via the caller's token + folder context. Do NOT invent a credential-store syntax. | Discovered via `refresh-tools` (sync 200). |
+| `platform` | `--service <name>` (lowercase service id, e.g. `orchestrator` — the CLI `--help` example's capitalized `Orchestrator` is rejected with HTTP 400) + `--tool <name>` (repeatable; selects exposed platform tools) | Bind to a first-party UiPath service. | Discovered via `refresh-tools` (sync 200). |
+| `swagger`  | `--spec-url <url>` (+ `--use-relay`)   | Register an OpenAPI/Swagger spec as MCP tools. Same asset substitution as `remote`. | Discovered from the spec via `refresh-tools` (sync 200). |
+
+Headers/auth on `remote` and `swagger` are payload fields, not scalar flags. Read the shape from `--print-schema` (or `template <type>`), submit via `--file <payload.json>` or `--body '<json>'`.
+
+`mcp update <slug>` dispatches by existing server type — flag shape mirrors `create <type>`. Verify with `mcp get <slug> --output json`.
+
+`mcp template <type>` also accepts `process-assistant` and `selfhosted` — these have templates but NO `create` subcommand (backend enum only; skip).
+
+## Tool Kinds (`uipath`-type servers only)
+
+`uip agenthub mcp-tools create-{is-activity | resource | raw}`. Shared flags: `--mcp <slug>` (parent server), `--name`, `--description`, `--target-identifier <guid>` / `--target-name <name>` (resolve target via RCS — only for non-`activity` categories), `--folder-key <guid>` / `--folder-path <name>` (folder context; the CLI derives the target's folder from `--target-identifier`, so there is **no** `--target-folder-key` flag — do not invent one), `--category`, `--input-schema`, `--output-schema`, `--metadata`, `--continue-on-error` (default) / `--fail-fast`, `--file`/`--body`, `--dry-run`. Differ in metadata shape, discovery path, and validation strictness.
+
+| Kind | Discovery | Validation | When to use |
+|------|-----------|------------|-------------|
+| `is-activity` | `mcp-tools candidates --category is-activity` + `is resources describe` | Connector schema | Wrap an Integration Service connector activity as an MCP tool. **Load [references/is-activity-workflow.md](references/is-activity-workflow.md) end-to-end** — extra Critical Rules, Pre-flight, `ActivityMetadata` schema, and IS-specific troubleshooting apply. |
+| `resource`    | `mcp-tools candidates --category <kind>` (kind ∈ `automation` / `agent` / `agentic-process` / `api-workflow`) | Resource schema | Bind an Orchestrator resource. Pass `--target-identifier <resource-id>`. Read metadata shape from `mcp-tools template resource --output json`. |
+| `raw`         | None | None | Free-form JSON tool — caller owns correctness end-to-end. No discovery, no schema validation, no reference-value labeling. Read the skeleton from `mcp-tools template raw --output json`. |
+
+Stringify `--metadata` / `--input-schema` / `--output-schema` as scalars (not `--file`). Build each JSON in a file and pass it as `--metadata "$(jq -c . metadata.json)"` (likewise input/output schema) — do **not** assemble multi-KB JSON inline in the command. Pass `--output-schema "{}"` when the underlying target has no response fields — empty string is rejected with `Unexpected end of JSON input`.
+
+Other `mcp-tools` verbs (`list --mcp <slug>`, `get`, `enable`, `disable`, `delete`, `update`) are self-documenting via `--help`. Use them for the Critical Rule 3 verify step.
+
+## Troubleshooting (generic)
+
+- **HTTP 400 with no detail** — re-run with `--dry-run` to inspect the resolved body. CLI surfaces ASP.NET ProblemDetails as an `Errors` field listing per-field validation failures.
+- **`InvalidFolderKey: "--folder-key requires a GUID; use --folder-path for folder names"`** — switch to `--folder-path <name>`.
+- **`No folder named '<personal workspace>' was found. Did you mean: Shared?`** — personal workspaces are unresolvable by name; pass `--folder-key <guid>` (Critical Rule 2).
+- **`ConflictingInput: "Pass either --folder-path or --folder-key, not both."`** — drop one.
+- **Slug rejected with validation error** — backend enforces `^[a-z0-9-]+$`, length 3-50 (Critical Rule 1).
+- **`mcp delete <guid>` returns 404** — `mcp delete` looks up by slug, not GUID (Critical Rule 5).
+- **`refresh-tools` returns 202 with a runtime id** — `coded` / `command` refreshes are async (Critical Rule 4). Surface the runtime id; verify via follow-up `mcp-tools list --mcp <slug>`.
+
+Tool-kind-specific troubleshooting lives with the workflow that owns it — IS-activity troubleshooting is in [references/is-activity-workflow.md](references/is-activity-workflow.md).

package/skills/uipath-mcp-servers/references/is-activity-workflow.md

@@ -0,0 +1,158 @@
+# IS-Activity Tool Authoring
+
+Wrap an Integration Service connector activity as an MCP tool via `uip agenthub mcp-tools create-is-activity`. Discovery verb is `uip is resources run` / `describe` (pre-rename `execute` → use `run`).
+
+**Division of labor.** The metadata-*discovery* workflow — `describe`, reference resolution, cascade (`-f`), scope filtering, static-value labeling — lives in the platform IS references below; this file does not restate it. This file owns the MCP-tool layer: turning discovered metadata into the `create-is-activity` payload (`ActivityMetadata`, `inputSchema`, `outputSchema`). **Do not author IS metadata from memory** — a `designTimeLookups` / `-f` / `reference` shape that "looks right from a rule" still gets the wrong shape per connector and fails at runtime after passing `--dry-run`. Read the platform section at the action-trigger below even when confident.
+
+## Platform IS references — read by action
+
+In `../../uipath-platform/references/integration-service/`. Each is small. Do NOT read all upfront — before performing each action, read the named section first. The blind spots are unknown-unknowns, so the trigger is the action, not your sense of certainty.
+
+| Before this action | First read |
+|---|---|
+| `uip is connections list <key>` for the first time | `connections.md` §`Folder Scoping` (pass `--folder <name-or-key>`) |
+| `is resources describe ... -f <parent>=<value>` (any cascade re-run) | `resources.md` §`Parent-Field-Driven Custom Fields` (`-f` shape, `--operation` requirement, `--action` rule, merge semantics) |
+| A `staticValues.<bucket>.<field>` whose describe field has a `.reference` block | `reference-resolution.md` §`Static Reference-Value Labeling` (`designTimeLookups` format + cascade-scope edge cases) |
+| An `inputSchema.properties.<field>` whose `.reference.path` contains `{otherField}` | `reference-resolution.md` §`Field Dependency Chains` (resolve parent first) |
+| An `inputSchema.properties.<field>` whose `.reference.filterPattern` contains `{filter}` | `reference-resolution.md` §`Search References` |
+| Resolving a reference where `run list` returns `scope: null` AND `scope.type: "PROJECT"` rows | `reference-resolution.md` §`Scope Filtering` |
+| Diagnosing a `describe` server-side failure | `resources.md` §`Describe Failures` |
+| Final gate before `create-is-activity --dry-run` | `reference-resolution.md` §`Validate Required Fields Before Executing` |
+
+## Critical rules (extend SKILL.md)
+
+1. **Discover before authoring.** `candidates --category is-activity` resolves connector + activity; `is resources describe` pulls field metadata. Compose `metadata` / `inputSchema` / `outputSchema` from the describe response, never from memory — every connector + operation has its own shape.
+2. **Connection is folder-scoped.** `uip is connections list <connector> --folder <name-or-key> --output json` (the unfiltered form silently filters to the current context and may return empty). Pass `--target-identifier <connection-guid>`; the CLI derives `targetFolderKey` — there is **no** `--target-folder-key` for IS-activity tools. `Reason: CrossFolderConnection` → pick from `Data.candidates`. (`connections.md` §`Folder Scoping` / §`Selecting a Connection`)
+3. **Cascade api-type ObjectActions.** `describe <key> <objectName> --connection-id <id> --operation <op>`; if `requestFields` is short for the operation, re-run with `-f <parent>=<value>` (repeatable). Omit `--action` for Jira `curated_create_issue` Create (passing it → `No api-type ObjectAction matched`); pass `--action` only when describe reports multiple matches. Cascade examples: Jira `curated_create_issue`, Salesforce `query_records`, Dataservice V3. (`resources.md` §`Parent-Field-Driven Custom Fields`)
+4. **Baked static reference values need `designTimeLookups`.** Every `staticValues.<bucket>.<field>` (any bucket — `field` / `query` / `header` / `path`) whose describe field has a `.reference` block MUST emit `designTimeMetadata.designTimeLookups[<dotted-field>] = "<displayName> - <value>"`. Applies to `requestFields[]` and `parameters[]`; NOT to runtime / enum fields — labeling renders only for baked values. (`reference-resolution.md` §`Static Reference-Value Labeling`)
+5. **Stringify `metadata` / `inputSchema` / `outputSchema` as scalars** — SDK types them `string | null`. Build each in a file and pass `--metadata "$(jq -c . metadata.json)"`; do not assemble multi-KB JSON inline, and do not mix `--file` with scalar options (`ConflictingInput`). `--output-schema "{}"` when the activity has no `responseFields` (empty string → `Unexpected end of JSON input`).
+6. **Ask — don't guess — when a value drives discovery.** Cascade `-f` parents, a search-reference `{filter}`, a dependency-chain parent, or a required reference with no user hint: STOP and ask, even in autonomous mode. **No autonomous fallback exists.** If the user defers ("Other" / "you decide" / silence), re-ask in plain text — do NOT fall back to free runtime, a guessed default, or silently skipping the tool. Bounded set (2–4 candidates) → `AskUserQuestion` (do not add "Other"; it is auto-appended; <2 options errors). Unbounded set (dozens+) → plain text showing the top 5–10 candidates by a real attribute plus the exact format you need (`"<project key> + <issue type>"`). Never filter an unbounded `run list` with a guessed `JMESPath` name — a miss returns `[]` with no signal.
+
+## Reference fields — the 3-way choice
+
+For every `requestFields[name].reference` or `parameters[name].reference` (`reference-resolution.md` §`Reference Fields`), run `uip is resources run list <connector> <reference.objectName> --connection-id <id> --output json`, then pick per field:
+
+- **(a) Bake** — `staticValues.<bucket>.<field> = <value>` + a `designTimeLookups` entry (Rule 4). When one value applies to every call (user named it).
+- **(b) Constrained runtime** — `inputSchema.properties.<field> = {type: string, enum: [<discovered values>]}`. When the set is bounded (≤ 20–50), stable, known now. No lookup needed.
+- **(c) Free runtime** (default) — `inputSchema.properties.<field> = {type: string}`, no enum. When the set is large / volatile (IDs, free text, search inputs). The `description` is the prompt the consuming LLM reads: noun phrase + format (e.g. `"IANA timezone like 'UTC'"`) + omission behavior + constraints.
+
+Cascade roots and search references with no user-supplied filter = **hard ask** (Rule 6) — no "pick first" / "most-recent" default. Non-cascade required references default to (c) in autonomous mode; use (b) only when the set is genuinely small and stable.
+
+## Pre-flight (walk before drafting `--metadata`)
+
+0. **Scope.** Restate server slug, folder, exact tool list (one bullet per `<connector> · <activity> · <op>`), baked statics. Folder: if unnamed, `uip or folders list --output json` → `Shared` (org-default) or `<email>'s workspace` (personal needs `--folder-key <guid>`). Run `mcp-tools list --mcp <slug> --folder-path <name>` first — same name + connector + objectName exists → ask update vs add-new.
+1. **Connection** — Rule 2. Confirm even on a single match (present name / owner / folder, never UUIDs, per `connections.md` §`Selecting a Connection`). N>1 → ASK. Zero → retry `--refresh`, then surface a create-connection hint and STOP.
+2. **Activity disambiguation.** `candidates --category is-activity --connector <key>` returns ≥2 overlapping entries (`send_message_to_channel` vs `_to_user`) → ASK. GET tie-break: `Get…` / `Find…` without an id → `List`; `Get … by …` or path `{id}`/`{key}` → `Retrieve`; unsure → describe without `--operation`, present `Data.availableOperations[]`.
+3. **Reference fields** — the 3-way choice above, per field.
+4. **Required scalar with no enum / reference / description** → STOP, ask (e.g. Slack `UsersByEmail.By`). Do not bake a guess.
+
+Multi-tool builds ("server with tools for X and Y"): re-walk Pre-flight + the command steps per tool — by tool 3 you drift toward tool 1's model.
+
+## `ActivityMetadata` (the object to stringify into `--metadata`)
+
+```jsonc
+{
+  "connector":   { "key": "<connector-key>" },              // from candidates
+  "object": {
+    "path":        "<availableOperations[chosen].path — e.g. /issue/{issueKey}/comment/{commentId}>",
+    "objectName":  "<the describe argument, e.g. issue_comment>",
+    "method":      "<GET|POST|PATCH|PUT|DELETE — from availableOperations[chosen].method>",
+    "contentType": "application/json"
+  },
+  "mapping": {
+    "path":   ["issueKey", "commentId"],   // property names filling {placeholder} tokens in object.path
+    "query":  ["maxResults", "startAt"],   // parameters[i] where .type === "query"
+    "header": [],                           // parameters[i] where .type === "header"
+    "field":  []                            // body fields (typically requestFields[])
+  },
+  "staticValues": {
+    "query":  { /* field-name: literal value the LLM cannot override */ },
+    "header": { },
+    "path":   { },
+    "field":  { /* body fields the LLM cannot override */ }
+  },
+  "designTimeMetadata": {
+    "designTimeLookups": {
+      // one entry per staticValues.* field whose describe field has .reference
+      // value format: "<displayName> - <baked-value>"  e.g. "fields.project.key": "Orchestrator - OR"
+      // see Critical Rule 4
+    },
+    "manageProperties": []
+  },
+  "metadataVersion": 1
+}
+```
+
+`staticValues` holds only values the LLM cannot override (`processType`, baked enum choices, baked reference IDs); runtime values belong in `inputSchema.properties`. Emit flat dotted keys (`"fields.project.key": "OR"`); the FE may persist them nested on save — both round-trip through `ParameterMappingService`'s four-bucket iteration (`Query` / `Path` / `Header` / `Field`).
+
+`inputSchema.properties` = `requestFields ∪ parameters` not covered by `staticValues`. Per entry: name = `parameters[i].name` / `requestFields[j].name`; `title` = `displayName ?? name`; `description`; `type` from `dataType` / field shape; add to `required[]` when `.required === true`; honor `enum` / `.reference` (the 3-way choice). Curated activities often have empty `requestFields[]` before cascade — `parameters` is then the input source. Set `additionalProperties: false`. `mapping.path` must list every `{token}` in `object.path` by property name (CLI validates client-side).
+
+`outputSchema` is a real JSON Schema built from `Data.responseFields` (walk like `inputSchema.properties`). Do not ship `{"type":"object","additionalProperties":true}`. `"{}"` only when the activity genuinely has no response body.
+
+## Workflow (commands)
+
+```bash
+# 0 — folders (once per machine); personal workspace needs --folder-key, not --folder-path
+uip or folders list --output json
+
+# 1 — confirm / create the `uipath`-type server (slug ^[a-z0-9-]+$, len 3-50)
+uip agenthub mcp list --folder-path <folder> --output-filter "Data.items[].slug" --output json
+uip agenthub mcp create uipath --name "<display>" --slug <slug> --folder-path <folder> --output json
+
+# 2 — connector key + activity (vendor name ≠ connector key; e.g. Slack → uipath-salesforce-slack)
+uip agenthub mcp-tools candidates --category is-activity --name <vendor> --output json
+uip agenthub mcp-tools candidates --category is-activity --connector <key> --output json
+# Read Data.items[].{connectorKey, objectName, methodName, displayName}. Multi-candidate → Pre-flight 2.
+
+# 3 — describe: operations, then field metadata  (cascade/reference mechanics → platform refs)
+uip is resources describe <key> <objectName> --connection-id <id> --output json            # Data.availableOperations[]
+uip is resources describe <key> <objectName> --connection-id <id> --operation <op> --output json
+# requestFields[] (body), parameters[] (path/query/header), responseFields[] (output).
+# Short requestFields → curated: cascade with -f per resources.md §Parent-Field-Driven Custom Fields.
+
+# 4 — connection in the server's folder        [READ: connections.md §Selecting a Connection + §Folder Scoping]
+uip is connections list <connector-key> --folder <server-folder-name-or-key> --output json
+
+# 5 — label every baked static reference value  [READ: reference-resolution.md §Static Reference-Value Labeling]
+uip is resources run list <connector> <reference.objectName> --connection-id <id> --output json
+
+# 6 — dry-run preview (skips some server-side checks; can pass while the real POST fails)
+uip agenthub mcp-tools create-is-activity ... --dry-run --output json   # inspect Data.resolved.{metadata,inputSchema,outputSchema}
+
+# 7 — create
+uip agenthub mcp-tools create-is-activity \
+  --mcp <slug> --name "<tool name>" --description "<1-4000 chars; shown in AgentHub UI>" \
+  --folder-path "<server folder>" --target-identifier <connection-guid> \
+  --metadata "$(jq -c . metadata.json)" --input-schema "$(jq -c . input-schema.json)" \
+  --output-schema "$(jq -c . output-schema.json)" --output json   # Data.id = created tool ID
+
+# 8 — verify (do NOT claim done before this passes)
+uip agenthub mcp-tools list --mcp <slug> --folder-path <folder> --output json
+# Confirm id/name/description/mcpName. High-value tools: smoke-test via `uip is resources run <verb>`.
+```
+
+Update (metadata/schemas changed) — scalars only, `--output-schema "{}"` for no response body:
+
+```bash
+uip agenthub mcp-tools update <tool-id> --mcp <slug> --folder-path "<folder>" \
+  --metadata "$(jq -c . metadata.json)" --input-schema "$(jq -c . input-schema.json)" \
+  --output-schema "$(jq -c . output-schema.json)" --output json
+```
+
+Delete: `uip agenthub mcp-tools delete <tool-id> --mcp <slug> --folder-key <guid> --output json`.
+Skeleton for `--file`: `uip agenthub mcp-tools template is-activity --output json`.
+
+## IS-Activity Troubleshooting
+
+- **HTTP 400, no detail** — re-run `--dry-run`; CLI surfaces ASP.NET ProblemDetails as an `Errors` field of per-field failures.
+- **404 at runtime** — `metadata.mapping.path` missing a `{token}` from `object.path`. List every placeholder and retry.
+- **`Reason: CrossFolderConnection`** — connection in a different folder than the server. Pick a `Data.candidates` entry via `--target-identifier <guid>`, or move the connection / server.
+- **`Operation 'X' not found. Available: <Y>`** — curated activity exposes only `Y`. Re-run `describe` without `--operation`, pick from `Data.availableOperations[]`.
+- **`No api-type ObjectAction matched for fields [...]`** — `-f` set matches no registered action, or `--action` was passed when it should be omitted (Jira `curated_create_issue` Create). Drop `--action` first; else inspect `connectorMethodInfo.design.actions[]` / `objectActions[]` for required `-f` shapes.
+- **Form renders raw scalar (`OR`, `3`) instead of a labeled value** — `designTimeLookups[<field>]` missing (Rule 4 / Step 5), then `mcp-tools update <tool-id>`.
+- **`ConflictingInput: Use exactly one of --file, --body, or scalar options.`** — pass schemas as scalars, not `--file`.
+- **`Unexpected end of JSON input` on `--output-schema`** — pass `"{}"` for no-response-body activities.
+- **`connections list <key>` empty in one folder, connection exists elsewhere** — folder-scoped; re-run with `--folder <name-or-key>` of the server's folder (`connections.md` §`Folder Scoping`).
+- **403 Forbidden at runtime** — connection scope mismatch; re-authorize via `uip is connections edit <id>` with broader scopes (`connections.md` §`Scope-Related Errors`).
+
+For generic AgentHub-MCP issues (slug regex, folder context, refresh-tools async/sync, `mcp delete` lookup), see SKILL.md §Troubleshooting.

package/skills/uipath-planner/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: uipath-planner
+description: "UiPath task planner — reads SDDs from uipath-solution or elicits non-PDD requests, derives multi-skill task lists, emits live TaskCreate calls. Detects project type (.cs, .xaml, .flow, .bpmn, .py). For PDDs→uipath-solution first."
+when_to_use: "User makes a non-trivial UiPath request that spans SEPARATE buildable projects — e.g. 'build a UiPath solution for X', 'set up a process from scratch', a Flow that orchestrates standalone RPA processes or agents — OR provides an SDD path. Skip when the request targets a SINGLE project, even a Flow/Agent/RPA project with inline HITL, script, or connector nodes wrapped in its own solution (e.g. a Flow with an inline approval step is one uipath-maestro-flow task, not a plan) — invoke that specialist directly."
+allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion, EnterPlanMode, ExitPlanMode, TaskCreate, TaskUpdate, TaskList
+---
+
+# UiPath Task Planner
+
+Your job is to **derive task lists, route to specialists, and emit live tasks** — never execute the work yourself.
+
+The planner has two lanes:
+
+- **Lane A — PDD-driven.** Triggered when the input is an SDD with a `## Planner Handoff` header. Reads the SDD, derives tasks per the project list, writes `<process>-tasks.md`, emits live `TaskCreate` calls. Zero or one user prompt. See [pdd-driven-lane-guide.md](references/pdd-driven-lane-guide.md).
+- **Lane B — Non-PDD.** Triggered when there's no SDD. Elicits preferences via a batched `AskUserQuestion`, detects project type, multi-skill patterns or filesystem signals, writes `<feature>.md`, emits live tasks. Typically 0–3 user prompts (5-call hard cap). See [non-pdd-lane-guide.md](references/non-pdd-lane-guide.md).
+
+The lane is decided by the **Entry Guard** below.
+
+## When to Use This Skill
+
+- The request is **non-trivial** — spans **separate buildable projects** that each need their own specialist (e.g. a Flow orchestrating standalone RPA processes or agents), or UI automation with unclear scope
+- The request is **ambiguous** — no single specialist skill clearly matches
+- The user asks "what can I build?" or needs help choosing a project type
+- The user provides an SDD path — Lane A runs
+
+Skip this planner for single-project tasks — load the specialist directly. A request is **single-project** (one specialist owns it end-to-end) even when it bundles several things *inside one project*: a Flow with script nodes plus an inline HITL approval step plus its own solution wrapper is **one** `uipath-maestro-flow` task. Inline nodes (HITL QuickForm, script, connector, inline agent) and the solution scaffolding are author sub-steps the specialist performs itself — they are **not** separate skills to orchestrate. Counting them as distinct skills ("solution + flow + human-in-the-loop") and emitting a plan is the most common mis-trigger. The planner is only for requests spanning **separate buildable projects** — distinct `.uipx` projects (a Flow consuming standalone RPA processes, an Agent using published processes as tools).
+
+## Critical Rules
+
+1. **Plan only — never execute the work yourself.** Do NOT write automation code (XAML, C#, Python, JSON) or create project files. Plan / tasks files and live `TaskCreate` calls are the only outputs you produce.
+2. **For PDDs, hard-block and redirect to `uipath-solution`.** A PDD (PDF, docx, or markdown describing process steps + applications + exceptions) does NOT belong in this skill. The dedicated PDD→SDD skill produces a much better deliverable. The only escape is the user explicitly saying "skip SDD".
+3. **Never exceed 5 `AskUserQuestion` calls in any planning session.** Each call is one user-facing prompt; batch related questions (e.g., the Step 4 UI elicitation in Lane B batches App type, Targeting approach, App state into one call). If you cannot fit the elicitation in 5 calls, plan with best available info and note the assumption. Lane A typically uses 0–2 calls.
+4. **Always include a mandatory Testing task per generation skill** in the plan. Testing is non-negotiable — happy path + edge cases + error scenarios + e2e for Master Projects. The Testing task routes to the specialist's testing references and does NOT describe the testing procedure inline.
+5. **Route — do not redescribe.** The plan says WHICH skill to load and IN WHAT ORDER. It does NOT describe specialist-internal flows (target configuration, OR registration, XAML authoring pipelines, **HITL field/outcome schema design**, auth flows, testing procedures). Each specialist's docs own those details. **For a HITL step, pass the business intent only** ("manager approves or rejects an expense; can add a reason if rejected") — never a field-level spec (do not prescribe field names, types like `approved: boolean`, `required` flags, or outcome lists). The HITL specialist chooses the schema shape (boolean decision field vs Approve/Reject outcomes) from the intent; a field-level prescription forces one shape and defeats that choice.
+
+## Entry Guard
+
+When the planner is invoked, run this guard before anything else.
+
+```
+1. Did the user reference a document path?
+   - No → Lane B (non-PDD elicitation)
+
+2. The path resolves to a file. Read its first ~50 lines.
+   - File contains the heading `## Planner Handoff` OR the HTML-comment marker `<!-- planner-handoff:v1 -->` → Lane A (read SDD, derive tasks). Either signal is sufficient — they are redundant on purpose so a renamed heading does not silently break detection.
+
+3. Otherwise (no marker, or unparseable / binary file like .pdf / .docx):
+   ask via AskUserQuestion:
+
+   > What is the document at <path>?
+   > 1. Solution Design Document (SDD) — proceed with task generation (Lane A, hand-written SDD)
+   > 2. Process Design Document (PDD) — load uipath-solution first
+   > 3. Other context — note its existence; proceed with non-PDD elicitation (Lane B)
+
+4. Based on user's choice:
+   - SDD → Lane A. Try to find the Planner Handoff header; if missing, proceed with safe defaults
+     (interactive autonomy, single-product scope) and log a one-line warning.
+   - PDD → HARD BLOCK with this message:
+
+     > The document at <path> is a Process Design Document. UiPath has a dedicated skill
+     > for PDD→SDD generation that produces a much better deliverable: uipath-solution.
+     > Load it with this PDD path; it will produce an SDD that I can then use to generate
+     > the task list.
+     >
+     > If you've already considered the SDD path and want a lightweight plan from this PDD
+     > anyway, tell me "skip SDD" and I'll proceed with degraded inline reading (Lane B + PDD
+     > as context).
+
+   - Other context → Lane B, with the document path noted in plan header.
+```
+
+The `## Planner Handoff` heading **and** the `<!-- planner-handoff:v1 -->` marker are the load-bearing detection contract — `uipath-solution` writes both deterministically, this skill detects either. Templates ship with both; either alone is enough to take Lane A. Do not pattern-match on filename or extension; those are unreliable.
+
+## Lane A — PDD-driven (summary)
+
+When triggered: SDD detected at entry guard.
+
+1. Read the SDD's `## Planner Handoff` header (6 fields: Execution autonomy, SDD scope, Project list section, Tasks file, Generated by, Generation date).
+2. If `<process>-tasks.md` already exists, ask `continue / regenerate` (1 prompt). Regenerate preserves completed work via task identity matching — see [plan-and-tasks-format.md → Regenerate logic](references/plan-and-tasks-format.md#regenerate-logic-pdd-driven-lane-only).
+3. Parse the SDD project list section. Pick the multi-skill pattern.
+4. Ask the Step 4 UI batch (3 questions, 1 call) only if the SDD's Application Inventory section lists UI applications and the answers aren't already resolved from context.
+5. Derive tasks. Write `<process>-tasks.md`.
+6. If `Execution autonomy: interactive` → `EnterPlanMode` for review. If `autonomous` → emit live tasks directly.
+7. Emit `TaskCreate` calls + `addBlockedBy` edges. Hand off.
+
+Full procedure: [pdd-driven-lane-guide.md](references/pdd-driven-lane-guide.md).
+
+## Lane B — Non-PDD (summary)
+
+When triggered: no SDD; user described a task or asked for help planning one.
+
+1. Step 1 — batched elicitation: bundle Q1 (generation approach) + Q2 (execution autonomy) + Q3 (project-type fallback, only when project type is vague) + Q5 (Solution scope, only when plan loads `uipath-maestro-flow`) into **one** `AskUserQuestion` call. Drop any question already resolved from context; if all resolve, skip the call entirely.
+2. Step 2 — detect multi-skill patterns; emit multi-skill plan if applicable. See [multi-skill-patterns-guide.md](references/multi-skill-patterns-guide.md).
+3. Step 3 — filesystem detection for single-skill plans.
+4. Step 4 UI batch — only when plan includes UI automation in `uipath-rpa` (one batched `AskUserQuestion` for App type / Targeting approach / App state).
+5. Write `YYYY-MM-DD-<feature>.md` to `docs/plans/` (project) or `./plans/` (no project).
+6. If explore-first → `EnterPlanMode`. If simultaneous → emit plan as text + live tasks.
+
+Full procedure: [non-pdd-lane-guide.md](references/non-pdd-lane-guide.md).
+
+## Skill capability map
+
+High-level view of what each specialist owns. **Do not describe internal flows of any specialist in your plan** — each skill documents its own procedures and will drift out of sync if duplicated here.
+
+| Skill | What it owns | Handles auth? | Handles deploy? |
+|---|---|---|---|
+| `uipath-rpa` | RPA workflows (XAML and C# coded): create, edit, build, run, debug. Owns **all** UI automation authoring end-to-end, including live-app exploration and probing. | No (relies on Studio) | **No** — defer to `uipath-solution` for `.uipx` multi-project, `uipath-platform` for single non-solution packages |
+| `uipath-agents` | AI agents — code-based (LangGraph / LlamaIndex / OpenAI Agents) and low-code (`agent.json`) | Yes (`uip login`) | **Yes** — end-to-end |
+| `uipath-coded-apps` | Web apps (`.uipath/` dir): build, sync, package, publish, deploy | Yes (`uip login`) | **Yes** — end-to-end |
+| `uipath-maestro-flow` | `.flow` files orchestrating RPA, agents, apps | Yes (`uip login`) | **Partial** — follows plan `Solution scope` (SW or local); `uipath-platform` for Orchestrator |
+| `uipath-platform` | Auth (`uip login`), Orchestrator (folders, processes, jobs, machines, users, roles), resources (assets, queues, storage buckets + bucket files, libraries, webhooks, triggers), Integration Service (connectors, connections, activities, IS triggers), traces, licensing | Yes (auth hub) | **Yes** — for non-solution single packages and Orchestrator-side post-deploy ops |
+| `uipath-mcp-servers` | UiPath AgentHub MCP server registration (6 types: `uipath`, `coded`, `command`, `remote`, `swagger`, `platform`) and tool authoring on `uipath`-type servers (3 kinds: `is-activity`, `resource`, `raw`). Wraps IS connector activities (Jira, Slack, Outlook, Salesforce, ...), Orchestrator resources (process / agent / api-workflow), external HTTP MCP endpoints, OpenAPI specs, published coded agents (as Orchestrator processes), local subprocess commands, or first-party UiPath services as MCP tools agents can consume. NOT for FastMCP / Python `mcp` SDK / `uipath-mcp-python` server-implementation work. | Yes (`uip login`) | **Yes** — registration is deployment (posts directly to AgentHub) |
+| `uipath-solution` | PDD→SDD architecture authoring AND `uip solution` lifecycle (init, pack, publish, deploy, activate). Runs in PDD-driven flows as the first skill (design) and again as the final skill (deploy of `.uipx` solutions). | Yes (`uip login` for ops half) | **Yes** — for multi-project Solution (`.uipx`) deploys |
+
+## Reference Navigation
+
+| File | Purpose |
+|------|---------|
+| [PDD-driven Lane Guide](references/pdd-driven-lane-guide.md) | Lane A end-to-end — read SDD header, parse project list, derive tasks, write tasks.md, emit live tasks |
+| [Non-PDD Lane Guide](references/non-pdd-lane-guide.md) | Lane B end-to-end — elicitation, project-type inference, filesystem detection, UI batch, write plan.md |
+| [Multi-skill Patterns Guide](references/multi-skill-patterns-guide.md) | The named multi-skill patterns (RPA build+deploy, Flow with local/deployed resources, Agent with RPA tools, etc.). Used by both lanes. |
+| [Plan and Tasks Format](references/plan-and-tasks-format.md) | Header schema, task row schema, identity tuple, status states, regenerate-with-preservation algorithm, TaskCreate mapping, anti-hallucination rule, quality rules |
+
+## Anti-patterns
+
+1. **Skipping the entry guard.** Always inspect the input first. A PDD silently treated as a generic doc produces a degraded plan and skips the dedicated SDD skill.
+2. **Writing automation code or modifying the project.** Plans only. In explore-first Lane B mode, non-mutating `uip` discovery is allowed; that's the upper limit.
+3. **Exceeding 5 `AskUserQuestion` calls.** If the elicitation can't fit, plan with best available info and note the assumption.
+4. **Recommending a skill that contradicts filesystem signals.** `.flow` files → `uipath-maestro-flow`, not `uipath-rpa`.
+5. **Asking the UI-targeting batch when the plan has no UI automation.** Pure data processing, API calls, agent-only, flow-only plans skip Step 4 entirely.
+6. **Describing specialist-internal flows in the plan.** Target-configuration procedures, OR registration, scaffolding pipelines, auth steps, pack/publish details, testing procedures — all owned by the specialist's own docs. Inlining creates drift.
+7. **Saving a plan with placeholders** (TBD, TODO, as needed, similar to Task N).
+8. **Asking the user to choose between XAML and C#.** Project type is inferred from the request; RPA workflows are XAML by default. Coded mode is set only when the user independently says "coded workflow", "C# workflow", or ".cs file".
+9. **Surfacing C# as recommended for routine UI automation.** Form-fill, Type Into, Click, dropdown selection, Excel / email / file work — all bread-and-butter XAML. C# coded fallback is an internal `uipath-rpa` decision for individual subtasks, never a top-level recommendation from the planner.
+10. **Adding a third option to the UI-targeting question.** Only two options exist: "I build it, you review it" (default) and "You indicate each element". Never invent a third "build it manually" option — a developer choosing manual authoring wouldn't be using a coding agent.
+11. **Leaking internal jargon or implementation details into user-facing questions.** Never mention "snapshot", "hand-wire", "AutomationId", "selector candidate", "autonomous capture", "target configuration". Speak in plain developer language: "the live app", "Studio", "elements", "selectors", "inspect", "discover".
+12. **Injecting domain or app names into question text.** Ask "What kind of application are we automating?" — not "What kind of HR application…". Domain lives in the plan header, not the questions.
+13. **Omitting the mandatory Testing task per generation skill.** Every generation skill in the plan gets a `Testing (MANDATORY)` task that routes to that skill's testing references. Never replace it with a `Validate:` sub-step. Never describe test-case authoring / data-driven testing / mock testing in the plan.
+14. **Asking about test coverage depth.** Testing is always thorough. The implementation specialist can scope down at execution time if the user wants a quick MVP; the planner does not offer the option.
+15. **Omitting `Execution autonomy` from the plan header, or leaving `Stop conditions` empty when autonomy is `autonomous`.** Downstream specialists rely on both to decide whether to interrupt. Populate `Stop conditions` with the hard blockers realistic for this specific plan (auth, app state, element-capture limits, missing resources) — do not leave a generic placeholder.
+16. **Generating an SDD or copying SDD content into the plan.** SDD is owned by `uipath-solution`. The plan references SDD section paths in skill prompts but does not duplicate architecture content.
+17. **Asking the user what the planner / library / filesystem can already answer.** Project type is resolved by explicit naming, keyword signals, and filesystem detection before any prompt fires. Skill capability is fixed in the capability map — never ask "which skill should I use". Existence of a `project.json`, `.flow`, `.uipath/`, or `pyproject.toml` is observable. Default first; ask only when no safe default applies. A user prompt is the most expensive resource the planner has — spend it on decisions only the user can make.

package/skills/uipath-planner/references/multi-skill-patterns-guide.md

@@ -0,0 +1,143 @@
+# Multi-skill Patterns Guide
+
+Common request shapes that span more than one specialist skill. Use this guide when deciding whether a request is single-skill (load one specialist directly) or multi-skill (emit a plan).
+
+## When to emit a multi-skill plan
+
+Emit a multi-skill plan when the request clearly spans more than one specialist. Single-skill tasks (e.g., "create a workflow that sends an email") go directly to the specialist — no plan needed.
+
+A request is **multi-skill** when at least one of the following is true:
+
+- Build + deploy crosses skill boundaries (RPA build → platform deploy)
+- A target product cannot exist without other products built first (Flow needs RPA processes that don't exist yet)
+- The user wants the result of one skill to be consumed by another (Agent uses RPA processes as tools)
+
+A request is **single-skill** when:
+
+- The deliverable is owned end-to-end by one skill (e.g., "create a UiPath RPA workflow that fills a form" — one project, one app, one workflow)
+- The user is modifying an existing automation in a single project
+- The request is read-only / diagnostic / exploration only
+
+> **Important:** Single-app UI automation (one project, one live app, one workflow) is **not** a multi-skill pattern — it's a single-skill `uipath-rpa` task. `uipath-rpa` owns UI automation authoring end-to-end, including live-app exploration and probing.
+
+> **Important — inline nodes are not components.** A Flow whose only "components" are **inline nodes** (HITL QuickForm, script, connector activity, inline agent) is a **single-skill** `uipath-maestro-flow` task, **not** a multi-skill plan. The flow author journey scaffolds the solution and authors every inline node itself — it reads the HITL plugin reference inline; it does not hand off to `uipath-human-in-the-loop` as a separate task. Counting inline pieces as separate skills ("solution + flow + human-in-the-loop") is a mis-classification. A flow only becomes **multi-skill** (Pattern 2/3) when it orchestrates **separate buildable projects** — distinct `.uipx` projects such as a standalone RPA process, a coded agent, or a coded app, each of which needs its own specialist.
+
+## Pattern 1 — RPA build + deploy to Orchestrator
+
+**When it applies:** user wants to build an RPA workflow and deploy it to Orchestrator (most common production flow).
+
+```
+1. uipath-rpa      → create / edit, validate, build the workflow
+2. uipath-rpa      → testing (mandatory)
+3. uipath-solution → pack, publish, deploy to Orchestrator (`uip solution` lifecycle)
+```
+
+`uipath-rpa` does not deploy. Deploy to Orchestrator for solution-bundled RPA goes through `uipath-solution` (`uip solution pack/publish/deploy`). For raw single-package Orchestrator ops not wrapped in a `.uipx`, defer to `uipath-platform`.
+
+## Pattern 2 — Flow with local resources
+
+**When it applies:** Flow and the components it orchestrates are peer sibling projects under one `.uipx` solution at the current working directory. **Components here means separate buildable projects** (a standalone RPA `.xaml`/`.cs` process, a coded agent, a coded app) — each scaffolded as a distinct project routed to its own specialist. Inline flow nodes are **not** components (see the blockquote above); `uipath-maestro-flow` authors them itself in steps 1/4. Each component is scaffolded as part of this plan (or replaced by a placeholder contract when not built here). The flow runs locally / publishes to Studio Web per the plan's `Solution scope`.
+
+```
+1. uipath-maestro-flow   → create solution, init flow project
+2. <skill per component> → fan out: one task per component, routed by type
+                           (rpa → uipath-rpa; agent → uipath-agents; app → uipath-coded-apps)
+3. <skill per component> → testing for each component (mandatory)
+4. uipath-maestro-flow   → wire all components, validate, finalize per `Solution scope`
+5. uipath-maestro-flow   → testing for the flow (mandatory)
+```
+
+`<component skill>` is `uipath-rpa`, `uipath-agents`, or `uipath-coded-apps` depending on the component type.
+
+## Pattern 3 — Flow with deployed resources
+
+**When it applies:** Flow references components that exist as standalone Orchestrator tenant resources — already published, or to be published as part of this session. The flow consumes them by tenant identity, not as peer sibling projects under a local solution.
+
+```
+1. <component skill>   → scaffold any unbuilt component
+2. <component skill>   → testing for the component (mandatory)
+3. uipath-solution     → deploy the component to Orchestrator via `uip solution` (RPA always needs uipath-solution; agents / coded-apps self-deploy)
+4. uipath-maestro-flow → design and wire the flow against the published components, validate, finalize per `Solution scope`
+5. uipath-maestro-flow → testing for the flow (mandatory)
+```
+
+## Pattern 4 — Flow deploy to Orchestrator
+
+**When it applies:** the flow exists; user wants it deployed to Orchestrator (not Studio Web).
+
+```
+1. uipath-maestro-flow → validate, `uip maestro flow pack`
+2. uipath-maestro-flow → testing (mandatory)
+3. uipath-solution     → publish and deploy to Orchestrator via `uip solution`
+```
+
+`uipath-maestro-flow` follows the plan's `Solution scope` (SW or local); Orchestrator deploy of the wrapping solution requires `uipath-solution`.
+
+## Pattern 5 — Agent that uses RPA processes as tools
+
+**When it applies:** the request is for an agent whose tools are RPA processes that need to be created and published.
+
+```
+1. uipath-rpa      → create and validate the RPA process(es) the agent will call
+2. uipath-rpa      → testing for the RPA processes (mandatory)
+3. uipath-solution → deploy the RPA process(es) to Orchestrator via `uip solution`
+4. uipath-agents   → create the agent, bind the published processes as tools
+5. uipath-agents   → testing for the agent (mandatory)
+6. uipath-agents   → deploy
+```
+
+## Pattern 8 — Build an AgentHub MCP server
+
+**When it applies:** the request is to register an AgentHub MCP server that wraps a coded agent or uses Orchestrator-asset-backed auth that does not exist yet. Pure `uipath-mcp-servers` work — `uipath` / `command` / `platform` servers, `remote`/`swagger` with auth assets already in place, or any `is-activity` tool authoring against existing IS connections — is single-skill; go straight to `uipath-mcp-servers`.
+
+Wrapping a not-yet-built coded agent (server type `coded`):
+
+```
+1. uipath-agents      → develop and publish the coded agent (deploys end-to-end as an Orchestrator process)
+2. uipath-mcp-servers → register the coded MCP server against the published process key
+```
+
+Orchestrator assets needed for `remote` / `swagger` Bearer / header substitution that don't exist yet:
+
+```
+1. uipath-platform    → create the Orchestrator asset(s) holding the auth values
+2. uipath-mcp-servers → register the server with asset-substituted headers
+```
+
+Missing IS connections are **not** a `uipath-platform` prereq — IS connections are created interactively in the Integration Service UI via OAuth, not by the CLI.
+
+## Pattern routing for PDD-driven lane
+
+When deriving tasks from an SDD, the planner picks a pattern based on the SDD's project list:
+
+| SDD shape | Pattern(s) used |
+|---|---|
+| Single RPA project, no deploy mention | Pattern: simple `uipath-rpa` build + testing |
+| Single RPA project, deploy to Orchestrator | Pattern 1 |
+| RPA Master Project (multiple sub-projects, queue-connected) | Pattern 1 applied per sub-project, then cross-project deploy via `uipath-solution` (single `.uipx`) |
+| Solution with Flow + RPA + Agents, components built fresh in this session | Pattern 2 expanded across all included products |
+| Solution with Flow consuming pre-published Orchestrator resources | Pattern 3 |
+| Solution overview SDD | Compose multiple patterns; respect cross-product integration order from §Cross-Project Data Flow |
+| API Workflow (single product) | API Workflow specialist + `uipath-solution` for deploy + testing |
+| Agent with RPA tools in §3 Tools | Pattern 5 |
+
+Cross-project integration order (general rule): **dependencies before dependents**. Build callable resources (RPA processes, API Workflows, agents-as-tools) before the products that consume them (Flows, Cases, parent agents).
+
+## Pattern composition for Solutions
+
+Solution-scope SDDs produce a unified project list. The planner walks the list and emits one pattern segment per project, then sequences them so that integrated components are built before their consumers:
+
+1. Build all leaf resources (libraries, callable API Workflows, RPA processes used as agent tools).
+2. Run testing for each leaf.
+3. Deploy leaf resources to Orchestrator.
+4. Build orchestrators (Flows, parent agents, Cases) using the published leaf references.
+5. Run testing for each orchestrator.
+6. Deploy orchestrators.
+7. End-to-end validation.
+
+## Anti-patterns
+
+1. **Splitting a single-app UI automation into a "discovery" task plus an "authoring" task.** `uipath-rpa` owns end-to-end authoring including target configuration and live-app exploration. One task, one skill.
+2. **Skipping the dedicated Testing task per generation skill.** Testing is mandatory and lives at the patterns level — every generation step in every pattern is followed by a testing step.
+3. **Deploying via `uipath-rpa` or `uipath-maestro-flow`.** Deployment of `.uipx`-wrapped solutions to Orchestrator goes through `uipath-solution` (`uip solution pack/publish/deploy`); for non-solution single-package Orchestrator ops, defer to `uipath-platform`. The build skills do not deploy.
+4. **Building Flow nodes that reference resources before the resources exist.** Use Pattern 2 (local resources, mocked then wired) or Pattern 3 (build and deploy components first, then reference). Never reference an unpublished resource by ID.